输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
文档管理中心

HarmonyOS

输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
API参考
高级筛选
API version全部版本
设备全部
元服务API集不筛选
您当前正在浏览HarmonyOS最新文档，覆盖已发布的所有API版本，可在API参考中筛选您使用的API版本。详细的版本配套关系请参考版本说明。
API参考应用框架ArkUI（方舟UI框架）ArkTS组件通用属性基础属性分布式迁移标识

分布式迁移标识

Phone12+PC/2in113+Tablet12+TV19+Wearable18+
更新时间: 2026-08-29 09:41
本文导读

组件的分布式迁移标识，用于在分布式迁移场景下标识组件，将组件的特定状态恢复到对端设备，帮助用户在设备切换后保持原有的组件位置或滚动状态，提升跨设备使用的连续性。

说明

从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

restoreId

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

restoreId(value: number): T

标记支持分布式迁移的组件Id，系统通过该Id匹配两端设备上的对应组件，并据此恢复组件的特定状态。不同组件的迁移效果和限制有所不同：Grid的ScrollBar位置无法迁移；Scroll在两端设备显示规格不同或布局参数差异导致布局不一致时会影响迁移效果；WaterFlow还会迁移顶部FlowItem相对WaterFlow的主轴偏移值（单位为vp）。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

展开
参数名 类型 必填 说明
value number 是 标记支持分布式迁移的组件Id，用于两端设备组件的配对。取值为整数，具体范围以接口实现约束为准。同一个应用中各个支持分布式迁移组件的Id必须不同；否则可能导致两端设备组件无法正确配对，影响分布式迁移时的状态恢复。

返回值：

展开
类型 说明
T 返回当前组件。

支持的组件

展开
组件名称 起始版本 迁移状态
List 8 迁移当前设备顶部显示的ListItem索引值，迁移后在对端设备上，将该索引值对应的ListItem在List中置顶显示。
Grid 9 迁移当前设备顶部显示的GridItem索引值，迁移后在对端设备上，将该索引值对应的GridItem在Grid中置顶显示。ScrollBar位置无法迁移。
Scroll 9 迁移滚动位置距顶部的绝对距离（vp单位）。两端设备显示规格不同等原因导致布局不一致，会影响迁移效果。
WaterFlow 11 迁移当前设备顶部显示的FlowItem索引值，迁移后在对端设备上，将该索引值对应的FlowItem在WaterFlow顶部显示。同时迁移顶部FlowItem相对WaterFlow的主轴偏移值（vp单位）。

示例

该示例通过restoreId设置了List组件的分布式迁移标识。

// xxx.ets
@Entry
@Component
struct RestoreIdExample {
  private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
  build() {
    Column() {
      List({ space: 20 }) {
        ForEach(this.arr, (item:number) => {
          ListItem() {
            Text('' + item)
              .width('100%')
              .height(100)
              .fontSize(16)
              .textAlign(TextAlign.Center)
              .borderRadius(10)
              .backgroundColor(Color.Pink)
          }
        }, (item:number) => (item.toString()))
      }
      .restoreId(1);
    }
  }
}
组件标识
显隐控制
相关推荐
文档复用标识
文档组件标识
文档组件可见区域变化事件
文档GridObjectSortComponent
文档组件区域变化事件
文档应用接续数据迁移
文档共享元素转场 (sharedTransition)
文档位置设置
文档挂载卸载事件
文档复用选项
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明
在 API参考 中进行搜索
请输入您想要搜索的关键词