Android 跨端不一致问题：解法清单

核实日期：2026-10-13

材料是内网学城《99.不一致性问题》目录下的 45 篇子文档里与 Android 相关的 32 篇（读取日期 2026-10-13，逐篇读简化版正文），加上挂在其中 6 篇问题下、由本人撰写的 8 份排查文档。

怎么用：第 1 章用三个问题判断你手上的问题落在哪条通道，第 2 章按通道找对应解法，第 3 章是能直接抄的写法，第 4 章解释为什么这么修。全文讲「怎么解」，不做篇数分布统计。

阅读约定：问题一律用简称；版本号、机型、代码照抄原文未复算；「通道」与「六层」是本文的分析结构，不是文档原文。45 篇的标题都带状态标签（【已解决】/【待解决】/【Hack】），本文一律按正文实际内容判断，不采信标题 —— 其中 3 篇标着【已解决】而正文的「原因 / 解决 / Hack」三节全空。

一、先判断：三个问题，四条通道

三个判断按顺序问，不要跳：

1. 换一份同一版本引擎的原生 demo 还能复现吗？ 能复现 → 通道 1，别在属性映射里绕。
2. 框架侧是不是已经写了「不改」？ 写了 → 通道 2，找替代写法，不要等。
3. 根因写出来了吗？ 没写 → 通道 4，先补定位；写了但没有落点 → 通道 3。

一条能带走的判断：升级版本是唯一能一次解掉一批问题的杠杆。 1.31 与 1.32 两次跟 Yoga，一次消化掉 absolute 无法隐藏、三边 borderWidth 撑不起视图、display:none 与 absolute 共存的性能问题；1.32 同一轮又修掉 AlignSelf 相反、ResizeMode 系列、visible_area_change 数据异常。这些收益来自引擎本身，不是某一个属性。

二、解法清单

同一批问题按现象归类，能更快找到该怎么解：

2.1 到 2.4 是四组解法，按「谁动手」排，从最省事的开始；2.5 是还没有解法的，写清楚缺哪一步。

2.1 升级版本就解掉，业务代码不用改（11 条）

三篇标题标【已解决】但正文三节全空的（label 的 EllipsizeMode::Tail 截断末尾省略号、图片重载用例闪白、Image ResizeMode 三端不一致），给不出解法，实际修复版本见第六章。

2.2 要在框架的 Java 层动刀，每条都有代价（3 条）

这三条是本人排查产出，方案各给了两条路，取舍一并列出。

2.3 框架的结论是「不改」，换业务侧写法（3 条）

2.4 已定位，但还没有版本落点，先按 hack 做（4 条）

2.5 只有现象，缺的是「补一次定位」（8 条）

这 8 条不是难度大，而是没走到「复现 → 读源码 → 给两条路」这一步。缺的动作写清楚，谁都能接着做。

三、可以直接抄的写法

九段从原文档抄来的写法。每段都标注了什么时候可以撤掉。

3.1 隐藏 scroll_view 又不丢滚动位置

不用 visible 完全隐藏，改成「高度归零 + 全透明」，位置就不会被布局重置带走：

styles! {
  fake_invisible { Height::number(0.)  Opacity::number(0.) }
  fake_visible   { Height::auto()     Opacity::number(1.) }
}

隐藏的是父布局时绕不过去，要用共享态存位置：隐藏前把当时的 offset 存下来，on_layout 里判断宽度从 0 变成正数时再恢复（用 animated: false 直接跳，不要放动画）：

on_layout: move |e| {
  if let Ok(d) = e {
    let w = frame.get().as_ref().width;
    set_frame(d.layout.clone());
    // 宽度从 0 恢复到大于 0，判定为「隐藏 → 显示」
    if w == 0. && d.layout.width > 0. { restore_scroll(); }
  }
}

撤掉条件：ScrollView 的位置保存逻辑随版本发出后。

3.2 图片 ResizeMode 不生效

在 on_load 里强制刷新一次高度，逼它重新按 ResizeMode 计算边界：

let height = use_state(cx, || Height::number(0.));
image {
  style: { ResizeMode::Stretch  {height} },
  source: "...",
  on_load: move |_| { height.set(Height::auto()) },
}

图片本来就是异步加载、从无到有，所以额外刷一次高度没有副作用。撤掉条件：升到 1.32。

3.3 MaxWidth/MaxHeight 用了 undefined

不要用 undefined，Android 会把它的值 0 当成最大宽高。需要「不限宽」时给一个极大值：

MaxWidth::number(200.)  Height::number(500.)  Width::auto()

{toggle}.map(|v| match *v {
  true  => MaxWidth::number(99999.),   // 等价于「不限」，不要写 undefined
  false => MaxWidth::number(200.),
})

适配所有版本，代价是不美观。撤掉条件：所在 App 版本的 Native 解析了 undefined 类型之后。

3.4 部分机型 Label 裁最后一个字

显式指定字体，不再依赖机型默认字体：

label {
  style: { FontSize::number(14.), FontWeight::N500, FontFamily::new("system") },
  text: "+ 添加新卡",
}

3.5 foreground 回调触发不稳定

先判断当前 Native 版本有没有这个能力（recce_ui 0.13.6+ 提供 can_i_use），没有就绕到 MSI 的广播上：

if env().os == OS::ANDROID && !can_i_use::android_foreground() {
  use_future!(scope_id, async move {
    // 先随意调一次 MSI 桥，触发 MSI 挂载
    let _ = MSI::subscribe("onAppStatusChange", None, |_, _| {}).await;
    add_app_listeners(AppEventListener::new(
      "onAppStatusChange".to_string(),
      move |event: &AppEvent| { /* app_status 为 Foreground 时做事 */ },
    ));
  });
}

更省事的替代：直接用 appear 事件代替 foreground。

3.6 env 取不到 window 尺寸

Android 的 display_width/height 实际给的是 window 值，而 window 尺寸双端都没传。业务侧用 MSI 桥自己取（MSI 接口 id 1504）。

3.7 1.32 以下的 visible_area_change

两个 rect 各坏一个，业务侧可以互补计算；老版本返回 px，记得除 pixel_ratio 换成 dp：

if env().os == OS::ANDROID && !can_i_use::android_visible_area_change_data() {
  let ratio = env().pixel_ratio.unwrap_or(1.);
  // Android 用 interactionClientRect + ScrollView 相对原点偏移；iOS 用 boundingClientRect 减偏移
  let right = env().display_width as f32 - (rect.x as f32 + rect.width as f32) / ratio;
  let top   = rect.y as f32 / ratio + rem(10.) - panel_top;
}

3.8 input placeholder 折行

像 web 一样自实现一层 placeholder：input 外面套相对定位容器，再叠一个绝对定位的 label，文本为空时显示占位文案：

view {
  style: { Position::Relative }
  input {
    style: { Width::number(100.), IncludeFontPadding::bool(false), NumberOfLines::s32(1), TextAlignVertical::Center }
    on_change_text: move |t| text.set(t),
  }
  view {
    style: { Position::Absolute, Top::number(0.), Bottom::number(0.), Left::number(5.), AlignItems::Center }
    label { style: { NumberOfLines::s32(1), Color::rgb(0xcccccc) }, text: {is_visible}.map(...) }
  }
}

3.9 父级整体透明

Android 无法整体变浅，用与背景同色的遮罩层模拟：在最外层加一个 absolute、四边贴合、与背景同色的视图，把 Opacity 设在遮罩上。

四、为什么这么修：六层的判断

解法分六层，层与层的分界不是「哪个平台」，而是「这一层做错之后，要在哪一层才能修」。

前 3 层的问题会随引擎与协议升级整批消失，后 3 层一次只能修一个。1 到 3 层的解法就是 2.1 表里的版本号；4 到 6 层的解法是 2.2 到 2.4 表里的写法与 hack。

4.1 布局引擎：先怀疑版本，再怀疑属性

判断：布局结果不符合预期时，第一动作是在「同一版本引擎的原生 demo」上复现一遍；能复现就是引擎的事，不要在属性映射里绕。

• absolute 定位无法隐藏，就是这么定下来的：同一段代码在 Yoga 1.18 以下与 3.2.1 上对照，前者黑块仍有宽高、后者没有，结论从「属性没生效」改成「引擎有 bug，升级」。
• 边框宽度撑不起视图，是另一半：Android 侧设置 borderWidth 时漏掉了 left/right/bottom 三个维度对 Yoga 节点的写入 —— 不是引擎算错，是「属性写进节点」这一步漏了。所以修法是补写入，不是换引擎。
• 反向的例子同样有用：小米机型 1px 像素差确认 Android 在原生 Yoga 算完之后又做了一次 round 作差，而 RN 最新版用同一套算法 —— 这里「和 RN 对齐」等于「一起错」，所以结论是给业务 hack 并向 RN 提 issue。

4.2 视图树与隐藏语义：Android 的「隐藏」是一次真实的布局塌缩

判断：Android 把 display:none 表达成「自身与所有子视图置 0×0」，iOS 只改当前视图。所有从尺寸派生的量（可滚动最大距离、自适应高度、传给宿主的组件尺寸）都会被这个 0 污染。

• 滚动位置重置：ScrollView 给内容布局挂了 onLayoutChange，回调里发现内容高为 0、maxScrollY 也就是 0，于是判定「当前位置越界」并把它写回 0 —— 位置不是没保存，是被自己清掉了。修法是在回调里判断内容尺寸是否为 0，而不是换一种隐藏方式。
• 同层组件白屏与抖动：宿主宽度被置 0 后 Recce 按 0 渲染，内部自适应让高度撑大，与宿主来回触发布局成死循环。三条 hack 的差别在于绕过哪一段：缓存上一次宽度（只改 Recce）、跟随宿主同步宽度（会闪）、通过总线把宿主尺寸直接给 Recce（兼容性最好，但两边都要改）。
• 凡是「隐藏再显示后状态丢失」或「被隐藏的组件显示异常」，先查这条链上有没有尺寸派生量被 0 污染，不要先怀疑隐藏属性的实现差异。

4.3 属性协议：跨端 bug 会互相抵消，不能用「二选一」定位

判断：差异不一定表现为「一端对一端错」，可能是两次错误叠加后的结果，所以必须拿 RN 的行为当第三参照。

• AlignSelf 是最典型的：Recce 解析时把 FlexEnd 与 Center 设置反了，iOS 端又反了一次，两次抵消后 iOS 是对的、Android 是错的。只看两端结果会得出「iOS 对、Android 错」，根因却在共享的那次解析上加 iOS 的补偿。
• 属性协议要写清四件事，这批问题里四件各出过一次：默认值（双端 ResizeMode 默认值不一致）、取值域（Android 侧 ResizeMode 只支持四个值，fit_start/fit_end 没有）、单位（1.32 以下 interactionClientRect 返回 px 而不是 dp）、参照系（同一次曝光，Android 相对屏幕、iOS 相对 scroll_view；env 的 display 在 Android 上其实是 window 值）。
• 类型没被解析会把「未定义」变成「0」：MaxWidth::undefined() 发出的类型是 Undefined、值是 0，Android 不解析这个类型，0 就成了最大宽度。兜底思路值得记住 —— 在 recce_ui 侧把该类型的值改成 NaN，让下游无法把 0 当有效值用，这样不用等旧版本流量退完。

4.4 事件分发：先分清「谁来决定命中」

判断：原生命中受 View 层级与边界裁剪约束；框架层命中可以自定义规则，代价是要一并接管原生本来免费给的那些能力。

• 原生命中带来的两处限制都有文档：触点落在绝对定位溢出父容器的子元素上时，中间那层容器判定子树不含触点，事件就不再下发；ScrollView 把手势识别成滑动、不响应 click，父级的 click-outside 因此实现不了。
• 绕开的方向也一致：用 on_touch_end 这类由框架自己做的事件，touch 不走原生分发，因此不受原生手势识别限制。1.35 的触摸新架构是同一思路的彻底版本 —— root 统一观察 touch 流、递归命中，把 hitSlop / overflow / clipChildren / transform 都算进去。
• 代价那一侧同样有记录：接管命中之后，多指、无障碍、焦点这些原来由原生隐式提供的能力，变成必须自己补的欠账。
• 反方向的差异别忘：鸿蒙的 touch 默认穿透，同一份代码在那边要「显式拦截」而不是「避免拦截」。

4.5 渲染与合成：差异多在「谁在什么时候算尺寸」

判断：行高、尺寸类的跨端差异，先把这个尺寸在每端分几步算出来；多数差异出在步数不同，不是画法不同。

• 父级 opacity：iOS 用 CALayer.opacity 在合成时整体应用，Android 用 View.alpha 让每个子视图先各自渲染（含透明度）再合并，父子都设半透明就会叠加变深。这也解释了为什么结论是「不改」—— Android 的行为与 RN 一致。
• 文本内嵌图片的行高是三段式差异：iOS 走 NSTextAttachment（占位符 U+FFFC），图片底边坐在基线上向上占 12pt，而字体 ascender 只有 9.5pt，TextKit 发现这一行需要更多上行空间就把 line fragment 撑高；Android 走 ReplacementSpan.getSize()，直接替换字体度量（是替换不是叠加）；鸿蒙的 ImageSpan 是文本节点的一等子节点，同一轮排版里统算所有 span，没有二次修正。
• 图片绘制边界是「在别人的决策点上二次覆盖」：系统已在 updateDrawable 里算好 bounds，Recce 又按图片原始尺寸覆盖了一遍，Stretch 因此失效；配套的第二个坑是设置 ResizeMode 时没把图片标脏，所以动态改属性不重载。

4.6 环境与设备：把机型名单换成结构性条件

判断：这一层的共同形态是「同一份代码在特定机型或特定像素密度下失效」；文档给的 hack 全是「显式声明」，修的时候要把「依赖某个机型默认值」换成结构性条件，否则换机型就复发。

• 分辨率变更：Android 的 DisplayMetricsHolder 缓存了 DisplayMetrics，margin / width / height 的像素换算全走这份缓存，屏幕参数变了仍按旧值换算 —— 修法是 RecceRootView 销毁时清缓存。
• 像素密度小数：布局结果的宽高是两次 round 作差，遇到小数宽高或小数像素密度就会差 1px，表现为红框与倒三角之间一条缝，只有小数机型上能看见。
• 字体 fallback：部分机型（如小米 MAX）Label 最后一个字被裁，hack 是显式指定 FontFamily。
• 无障碍：聚焦响应区域与点击区域不一致（努比亚偏左、红米正常），且 accessible 的默认值双端不一致（iOS 必须显式传 true 才播报）。

五、八份排查文档补上的东西

这 8 份挂在 6 个问题下，价值集中在「定位到方法名」这一层 —— 表格里是每份文档补上的定位与顺带产出的东西，解法本身见 2.1 与 2.2。

这 8 份的共同点：都给了最小复现与具体到方法名的定位，方案都列了两条并写明取舍，其中两处直接改写了父文档已有的结论。

六、待核实