openharmonyinsight/ohos-dev-arkui-v1-v2-migration

V1 → V2 State Management Migration Skill

Migrate OpenHarmony ArkUI @Component (V1) components to @ComponentV2 (V2).

When to Use

Activate this skill when the user expresses any of the following intents:

• 迁移 V1 组件到 V2 / V1V2 迁移 / 状态管理迁移 (migrate V1 components to V2 / state management migration)
• Change @Component to @ComponentV2
• Migrate decorators such as @State/@Prop/@Link to their V2 equivalents
• Analyze whether a component can be migrated to V2 / assess migration risk

---

Overall Workflow

0. Confirm target → 1. Analyze → 2. Plan → 3. Execute → 4. Verify

Each phase is detailed below. Always proceed in this order; never skip analysis and jump straight to execution.

---

Step 0: Confirm the Migration Target

Before any analysis, confirm the migration target in the following order.

Case 1: The user only says "V1V2 migration" without a project path

You must first ask the user for the project path, e.g.:

Please provide the HarmonyOS/OpenHarmony project path to migrate.

After receiving the path, proceed to Case 2. Do not assume or guess the project path.

Case 2: The user provides a project path but no specific component

Run the scan script:

python3 {{SKILL_DIR}}/scripts/component_analyzer.py <project-path> --scan-v1

The script outputs the list of all V1 components in the project, plus an instruction field. You must present the V1 component list to the user and ask which component to migrate. Do not skip this step.

If the list is empty, inform the user that the project contains no V1 components and no migration is needed.

Case 3: The user provides both a project path and a component name

Proceed directly to Step 1 (Analysis).

---

Step 1: Analyze

1.1 Detect the API version

python3 {{SKILL_DIR}}/scripts/api_version_checker.py <project-dir> --json

Key output fields:

• mixingRules: "strict" (API < 19) or "relaxed" (API >= 19)
• compatibleApiVersion: the minimum compatible API version
• availableApis: list of available compatibility APIs

Decision points:

• strict → complex types cannot cross the V1/V2 boundary during migration; a bridge pattern may be required
• relaxed → UIUtils.enableV2Compatibility() and UIUtils.makeV1Observed() can relax the constraints

1.2 Analyze the target component

python3 {{SKILL_DIR}}/scripts/component_analyzer.py <target-file-or-dir> --json

Output includes:

• Component version (V1/V2), decorator list, state variable types
• Child component references, rendering mode (ForEach/LazyForEach/Repeat)
• App-level state usage (LocalStorage/AppStorage/PersistentStorage/Environment/animateTo)

1.3 Trace the dependency chain

python3 {{SKILL_DIR}}/scripts/dependency_tracer.py <component-name> <project-dir> --json

Output:

• mustMigrate: list of components that must be migrated together due to data interaction
• State passing types between components (state_variable_ref / two_way_binding / callback / literal)
• Dependency graph (parent → child data flow)

Decision points:

• If mustMigrate contains only one component → it can be migrated independently
• If there are multiple components → evaluate whether to migrate them all or use a bridge pattern

1.4 Mixing validation (run once before and once after migration)

python3 {{SKILL_DIR}}/scripts/mixing_validator.py <project-dir> --json [--target <component-name>]

Output:

• violations: mixing issues that will cause compile/runtime errors
• warnings: mixing scenarios that may be risky
• suggestions: available compatibility API suggestions
• summary.isCompliant: whether all checks pass

---

Step 2: Plan

Based on the analysis, report the migration scope and strategy to the user:

Independent migration (preferred)

The target component has no external data interaction (hasInput: false, hasOutput: false), or all interactions use simple types.

Joint migration

The target component exchanges complex types with its parent/child components. All components in mustMigrate must be migrated together.

Bridge pattern (use when API < 19)

When V1 must pass an @Observed-decorated class to a V2 component:

V1Comp → V1BridgeComponent(@Component) → V2Comp(@ComponentV2)

The bridge is a pure V1 component: it destructures the @Observed class into simple-type fields and passes them to the V2 child's @Param (complex types cannot cross the V1→V2 boundary when API < 19). It must NOT hold an @ObservedV2 object via a V1 decorator. For multi-component sharing, use a standalone @ObservedV2/@Trace singleton written by V1 and read by V2. See the bridge section in references/mixing-rules.md.

Confirm the strategy with the user before proceeding to execution.

---

Step 3: Execute the Migration

Rewrite the code item by item in the following order. Each item maps to a reference document.

3.1 Component decorator

@Component  →  @ComponentV2

If the component has @Entry, leave it unchanged (@Entry works in both V1 and V2). If the component has @Reusable, change it to @ReusableV2.

3.2 State variable decorator mapping

For the full mapping table, see references/decorator-mapping.md. Quick reference:

| V1 | V2 | Key points | |----|-----|--------| | @State simple type | @Local | Direct replacement | | @State complex type | @Local + @ObservedV2/@Trace on the class | V2 @Local observes only itself, not its properties | | @State needing external init | @Param @Once | @Local forbids external initialization | | @Prop | @Param | @Param is passed by reference (not a deep copy); @Param is read-only | | @Link | @Param + @Event | Replace two-way binding with a callback pattern | | @Provide/@Consume | @Provider/@Consumer | V2 requires the () syntax; the alias is the unique match key | | @Watch | @Monitor | V2 is asynchronous; supports multiple variables; provides before/after | | @Observed/@ObjectLink | @ObservedV2/@Trace | Deep observation; no longer needs child-component decomposition | | $$ binding | !! binding | Direct replacement |

3.3 Data object migration

Change @Observed classes to @ObservedV2 and add @Trace to the properties.

// V1
@Observed
class Model {
  @Track public name: string = '';
  @Track public count: number = 0;
}

// V2
@ObservedV2
class Model {
  @Trace public name: string = '';
  @Trace public count: number = 0;
}

Note: @Observed and @ObservedV2 cannot coexist on the same class. If the class is referenced by other V1 components, resolve those dependencies first.

For detailed rules, see references/class-migration.md.

3.4 Rendering control migration

| V1 | V2 | |----|-----| | ForEach | Repeat(...).each(...).key(...) | | LazyForEach + IDataSource | Repeat(...).each(...).key(...).virtualScroll() + @Local array |

In V2 the data source is a plain @Local array; modifying the array triggers updates — no need to call notifyDataAdd and friends manually.

Use .templateId() + .template() for template rendering instead of manual if checks.

For detailed rules and code examples, see references/rendering-migration.md.

3.5 App-level state migration

| V1 | V2 | |----|-----| | LocalStorage | @ObservedV2/@Trace singleton | | AppStorage | AppStorageV2.connect() | | @StorageProp/@StorageLink | AppStorageV2.connect() + @Local + @Monitor | | PersistentStorage | PersistenceV2.globalConnect() | | Environment | Read directly from UIAbilityContext.config |

Important: keep V1 API calls; only add V2 API calls. During incremental migration, a single .ts file may contain V1 API calls for multiple keys. When migrating a component, add the corresponding V2 API (e.g. AppStorageV2.connect()) only for the keys that component uses, and do not remove the original V1 API calls (e.g. AppStorage.setOrCreate()), because other not-yet-migrated V1 components may still be using other keys in the same file. Only when stateApiByKey shows that all decoratorUsage for a key have been migrated to V2 may the V1 API calls for that key be removed.

For detailed rules, see references/app-state-migration.md.

3.6 Built-in objects and animateTo

• Wrap framework built-in objects (ChildrenMainSize/WaterFlowSections/attributeModifier) with UIUtils.makeObserved().
• animateTo is incompatible with V2's asynchronous update mechanism; force a synchronous flush first with animateToImmediately (API < 22) or UIUtils.applySync() (API >= 22).

For detailed rules, see references/advanced-topics.md.

3.7 New V2 capabilities

After migration, consider adopting new V2 capabilities:

• @Computed: derived state with automatic result caching
• Repeat template rendering + virtualScroll: replaces ForEach/LazyForEach

---

Step 4: Verify

4.1 Mixing validation

python3 {{SKILL_DIR}}/scripts/mixing_validator.py <project-dir> --json --target <component-name>

Ensure summary.isCompliant is true and all violations are empty.

4.2 Item-by-item checklist

• [ ] Component decorator: @Component → @ComponentV2
• [ ] All V1 state decorators replaced with their V2 equivalents
• [ ] Classes with complex types now have @ObservedV2 + @Trace
• [ ] @Link two-way binding changed to @Param + @Event callback pattern
• [ ] $$ replaced with !!
• [ ] ForEach/LazyForEach replaced with Repeat
• [ ] App-level state (if any) has V2 APIs added, and V1 API calls still used by other components were not removed
• [ ] animateTo (if any) has a synchronous-flush prefix added
• [ ] No V1/V2 decorators mixed within the same component
• [ ] No @Observed and @ObservedV2 coexisting on the same class
• [ ] Data passing across V1/V2 component boundaries follows the mixing rules

---

Reference document index

| File | Contents | When to consult | |------|------|----------| | references/decorator-mapping.md | Full decorator mapping table, migration rules for @State/@Prop/@Link/@Provide/@Watch | When rewriting state variables | | references/class-migration.md | @Observed/@ObjectLink/@Track → @ObservedV2/@Trace, nested object observation, precise updates | When migrating data object classes | | references/mixing-rules.md | V1/V2 mixing rules, API < 19 vs >= 19 differences, bridge pattern, enableV2Compatibility | When components coexist during migration | | references/rendering-migration.md | ForEach/LazyForEach → Repeat, virtualScroll, template rendering, @Reusable → @ReusableV2 | When rewriting rendering logic | | references/app-state-migration.md | LocalStorage/AppStorage/PersistentStorage/Environment → V2 alternatives | When migrating app-level state | | references/advanced-topics.md | Built-in objects (makeObserved), animateTo migration, V1/V2 update mechanism differences | When handling special cases | | references/architecture.md | Overall skill architecture, five-phase workflow, script responsibilities and import relationships | Maintainer reference: understanding script collaboration and data flow | | references/migration-overview.md | Design overview, detailed JSON output fields of each script, Storage key tracing mechanism, end-to-end example walkthrough | Maintainer reference: interpreting script output and migration decisions |

Example index

| Directory | Scenario | Migration points covered | |------|------|-----------| | examples/simple-component/ | Simple component | @State→@Local, @Prop→@Param | | examples/component-with-props/ | Complex parent-child interaction | @Link→@Param+@Event, @Provide→@Provider, @Watch→@Monitor, $$→!! | | examples/observed-class/ | Data object | @Observed→@ObservedV2, @ObjectLink→@Trace, nested observation | | examples/localstorage/ | App-level state | LocalStorage→singleton, AppStorage→AppStorageV2, PersistentStorage→PersistenceV2 | | examples/partial-migration/ | Partial migration and coexistence | V1/V2 coexistence, bridge pattern, API version checks |

Each example directory contains before.ets (V1 code) and after.ets (V2 code) for side-by-side reference.

---

Notes / Caveats

1. Never mix V1/V2 decorators within the same component — compile error.
2. Never decorate the same class with both @Observed and @ObservedV2 — compile error.
3. @Local forbids external initialization — when a value must come from outside, use @Param @Once.
4. @Param is read-only — when the child needs to modify it, keep a local copy and sync via @Monitor.
5. @Monitor is asynchronous — different from the synchronous behavior of V1's @Watch.
6. V2 deep observation — @ObservedV2/@Trace can directly observe nested properties; you no longer need to decompose child components layer by layer.
7. animateTo compatibility — V2's async mechanism is incompatible with animateTo; a synchronous-flush prefix is mandatory.
8. Migration is incremental — partial migration is allowed, but the mixing rules must be followed (see references/mixing-rules.md).