企业官网建设流程全解析

• 移动开发
• UI组件

导读

在 Litho 中，组件树（Component Tree）上的每个节点都通过一个唯一标识——组件键（key）——来确立身份。Litho 依赖 key 在两次布局之间追踪组件身份，并在状态更新时准确找到目标组件、为其写入新的状态值。本文以 keys-and-identity.md 为主线，结合 litho-core 的底层实现与 sample 中的完整示例，系统讲解 key 的自动生成规则、动态层级下自动 key 失效的原因，以及如何在 Kotlin API 与 Spec API 中手动设置稳定 key，帮助你在列表增删、条件渲染等场景中避免状态错位与 UI 异常。

一、什么是组件 key：组件树中的身份 ID

Key 帮助 Litho 为组件树中代表某个节点的组件设置唯一身份。Litho 使用 key 达成两个核心目标：

1. 在布局变化之间保持组件身份可追踪——同一个组件节点在两次渲染中是否仍是"同一个组件"，由 key 判定；
2. 正确识别状态更新的目标——当调用一次状态更新（state update）时，Litho 需要依据 key 在遍历组件树的过程中找到对应节点，并把新的状态值写入正确的位置。

从源码实现看，key 是全局的、跨层级的。以状态存储为例，StateId.kt 定义的状态标识由treeId + globalKey + index三元组构成，其中globalKey正是从组件树上计算出的全局键，可见 key 直接参与状态值的定位与检索。

默认情况下，Litho 会基于组件类型 + 父组件 key自动为每个组件生成 key。但在实际 UI 中，我们常常需要动态增删组件、调整兄弟节点顺序或按条件渲染某些组件，此时自动生成的 key 可能无法满足"跨更新稳定"的要求。本页后续内容将解释自动 key 的生成机制，以及何时、如何手动指定 key。

一个需要牢记的前提：只要组件渲染在组件树的同一节点上，它就会被分配相同的 key。如果该节点改变了位置（例如被移动到另一个父节点下，或因为其他兄弟节点被删除/插入而改变了自身的位置），那么它的 key 在两次 UI 更新之间不保证一致。

注意：这一点非常关键——Litho 在状态更新时会用 key 来判断该更新哪个组件，并在遍历树、写入新状态值时靠 key 正确识别组件。key 一旦漂移，状态就会"认错门"。

二、自动生成 key：类型 + 父 key + 去重序号

Litho 根据组件的类型以及它相对父组件的位置来生成 key，如下图所示的基础组件树：

2.1 key 的拼接构成

一个组件的 key 由以下三部分拼接而成：

下图展示了同一个组件树在加上 key 之后的样子：

为降低意外碰撞（key collision）的概率，实际 key 计算中还包含了其他分隔符，上图出于简化目的未展示。

2.2 源码级的 key 生成实现

自动 key 的生成逻辑集中在 ComponentKeyUtils.kt 中，核心方法是generateGlobalKey(parentContext, parentComponent, childComponent)，其流程可以归纳为：

• 判断是否手动 key：通过childComponent.hasManualKey()判断；若为手动 key，则 key 以$前缀标记（PREFIX_FOR_MANUAL_KEY = "$"）；
• 拼接父链：若存在父组件，则调用getKeyWithSeparator(parentGlobalKey, key)，以,作为分隔符把父 key 与子 key 连接，形成层级链；
• 同类型去重：对于没有手动 key 的子组件，调用getChildCountAndIncrement(childComponent)按类型计数，再通过getKeyForChildPosition(currentKey, index)在序号非 0 时以!index后缀追加去重 ID。

因此自动 key 的形态大致是父key,类型key!序号的层级拼接，这与文档中"父 key + 组件 key + 去重 ID"的简化描述一一对应。

2.3 为什么自动 key 不稳定

在 ComponentTree 中检测到 key 碰撞时——典型场景是父组件创建了多个同类型的子组件——Litho 会根据它们的排列顺序为这些兄弟组件分配唯一 key。这带来的直接后果是：自动生成的 key 不随组件移动而保持稳定。

三、典型问题：删除一个子组件，key 发生漂移

以文档中的组件树为例：父组件下并排渲染了两个Row子组件，各自带有一个有状态的组件。初始时，第一个Row的 key 为...Row!0（序号 0），第二个Row的 key 为...Row!1（序号 1）。

当第一个Row被移除后，组件树变成下图：

更新之后，初始树中的第二个 Row 变成了第一个类型为 Row 的子节点，因此它的 key 从...Row!1变成了...Row!0——key 变了！

这会带来两重后果：

1. 原状态丢失：Litho 此前把该 Row 的状态映射在旧 key 上，key 变化后，旧 key 对应的状态值全部被重置，UI 回到初始状态；
2. 状态错位：更严重的是，旧 key 关联的状态会落到新获得该 key 的下一个 Row 组件头上，即"状态串台"。

可以想象，这会引发令人头疼的 UI 缺陷：计数值、开关状态、输入内容等莫名跳变到另一个组件上。

一句话总结：Litho 的自动 key 生成是"尽力而为"（best-effort）的，在运行时实现下无法做到完全确定性（deterministic）——因为去重 ID 依赖运行时兄弟节点的排列与增删情况。

四、手动指定 key：稳定身份的解法

对于组件位置可能动态变化的 UI 层级，必须在组件上手动指定跨 UI 更新保持稳定的 key。手动 key 会始终优先于自动生成的 key（从 generateGlobalKey 中if (hasManualKey) "$${childComponent.key}"的分支可见，手动 key 直接使用用户提供的值，不再走类型计数去重）。

4.1 Kotlin API：内置全局key()方法

在 Kotlin API 中，可以通过内置的全局key()方法为组件设置手动 key，完整示例见 IdentityRootComponent.kt：

class IdentityRootComponent : KComponent() { override fun ComponentScope.render(): Component { val isFirstCounterEnabled = useState { true } val isSecondCounterEnabled = useState { true } return Column(style = Style.onVisible { ... }) { if (isFirstCounterEnabled.value) { child( key("first_row") { Row { child(CounterComponent()) child( Text( text = "X", textSize = 30.dp, style = Style.margin(all = 30.dp).onClick { isFirstCounterEnabled.update(false) })) } }) } if (isSecondCounterEnabled.value) { child( key("second_row") { Row { child(CounterComponent()) child( Text( text = "X", textSize = 30.dp, style = Style.margin(all = 30.dp).onClick { isSecondCounterEnabled.update(false) })) } }) } } } }

这里的CounterComponent是一个持有计数值状态（useState { 0 }）的组件，完整定义见 CounterComponent.kt。两个 Row 分别被手动 key 为"first_row"与"second_row"：

• 点击X时对应行的isFirstCounterEnabled/isSecondCounterEnabled被置为false，该 Row 从树中被移除；
• 由于手动 key 不参与"同类型去重"，剩余 Row 的 key 始终保持不变，其内部的计数器状态不会丢失或串台。

key()的底层实现位于 KComponent.kt：它是一个内联函数，先执行组件 lambda 拿到组件实例，再调用setKeyForComponentInternal(component, key)把手动 key 写入该组件。源码注释给出了典型用法：

key("my_key") { Text(...) }

4.2 Spec API：通用key组件属性

在基于注解的 Spec API（Java）中，可以使用通用的key组件属性在创建组件时手动设置 key，完整示例见 IdentityRootComponentSpec.java：

@LayoutSpec class IdentityRootComponentSpec { @OnCreateInitialState static void onCreateInitialState( ComponentContext c, StateValue<Boolean> isFirstCounterEnabled, StateValue<Boolean> isSecondCounterEnabled) { isFirstCounterEnabled.set(true); isSecondCounterEnabled.set(true); } @OnCreateLayout static Component onCreateLayout( ComponentContext c, @State boolean isFirstCounterEnabled, @State boolean isSecondCounterEnabled) { return Column.create(c) .child( isFirstCounterEnabled ? Row.create(c) .key("first_row") .child(CounterComponent.create(c)) .child( Text.create(c) .text("X") .paddingPx(YogaEdge.START, 16) .clickHandler(IdentityRootComponent.onClickRemoveFirstChild(c))) .build() : null) .child( isSecondCounterEnabled ? Row.create(c) .key("second_row") .child(CounterComponent.create(c)) .child( Text.create(c) .text("X") .paddingPx(YogaEdge.START, 16) .clickHandler(IdentityRootComponent.onClickRemoveSecondChild(c))) .build() : null) .build(); } @OnEvent(ClickEvent.class) static void onClickRemoveFirstChild(ComponentContext c) { IdentityRootComponent.onRemoveFirstChild(c); } @OnEvent(ClickEvent.class) static void onClickRemoveSecondChild(ComponentContext c) { IdentityRootComponent.onRemoveSecondChild(c); } @OnUpdateState static void onRemoveFirstChild(StateValue<Boolean> isFirstCounterEnabled) { isFirstCounterEnabled.set(false); } @OnUpdateState static void onRemoveSecondChild(StateValue<Boolean> isSecondCounterEnabled) { isSecondCounterEnabled.set(false); } }

同样地，通过.key("first_row")与.key("second_row")为两个 Row 指定了稳定身份。Builder 上的key(@Nullable String key)方法在 Component.java 中实现，它会拒绝 null key 并给出明确的报错提示。

4.3 手动 key 的注意事项

从 ComponentKeyUtils.generateGlobalKey 的实现可以看到，手动 key 同样会经过"父 key 拼接"和"同 key 去重"两个环节：

• 手动 key 会拼接在父组件全局 key 之后，形成父key,$子key的形式（SEPARATOR_FOR_MANUAL_KEY = ",$"），因此手动 key 只需要在兄弟节点之间保持唯一，无需刻意全局唯一；
• 若同一父组件下出现重复的手动 key，Litho 会通过getManualKeyUsagesCountAndIncrement(key)检测，并对重复 key 追加序号使其唯一，同时发出ComponentKeyUtils:DuplicateManualKey警告（见 logDuplicateManualKeyWarning）。重复 key 被改写会导致"行为不符合预期"，因此务必保证手动 key 在兄弟间不重复。

五、进阶技巧：用 key 强制重置组件状态

除了维持身份稳定，手动 key 还有一个巧妙的用途：强制组件状态基于某些 props 重新初始化。

当手动 key 是某些 props 的函数时，只要这些 props 发生变化，key 就会随之变化；由于 Litho 用 key 定位状态，key 一变，旧状态便不再与之匹配，组件就会被当作"新组件"处理，状态值自然回到初始值。

这一模式非常适合以下场景：

• 同一组件复用在不同数据上：例如一个详情卡片组件，当展示的 item id 变化时需要清空内部编辑状态、滚动位置等；
• 条件性重置：希望某个标志位从false变回true时组件重新走初始化逻辑；
• key 作为 props 的函数：key("detail_${item.id}") { DetailCard(item = item) }，item 变化即状态重置。

提示：这是手动 key 的"额外红利"——用 key 表达"身份"与"数据版本"的双重语义，让状态生命周期与数据生命周期对齐。

六、总结与实践建议

回到核心结论，可以总结为一张决策表：

手动设置 key 的要点回顾：

1. Kotlin API使用全局内联函数key("xxx") { ... }，见 KComponent.kt；
2. Spec API使用 Builder 的.key("xxx")属性，见 Component.java；
3. 手动 key优先于自动 key，生成规则与自动 key 相同（父 key 拼接 + 同 key 去重），见 ComponentKeyUtils.kt；
4. 兄弟节点之间避免重复 key，否则会触发DuplicateManualKey警告并被改写；
5. 需要重置状态的场景，可让 key 成为相关 props 的函数。

完整的可运行示例位于 sample 工程中：Kotlin 版本 IdentityRootComponent.kt、Java 版本 IdentityRootComponentSpec.java 及配套的 CounterComponent.kt。想进一步理解 key 在状态协调中的作用，可继续阅读同目录下的 communicating-between-components.md、hoisting-state.md 与 componenttree.md。

• 移动开发
• UI组件