arkui-x-dev

开发、审查、打包 ArkUI-X 跨平台应用（一套 ArkTS 主代码构建 OpenHarmony/HarmonyOS + Android + iOS 三端应用）。核心方法：先核对"ArkUI-X 跨平台与原生鸿蒙应用的差异红线"，确认需求在跨平台能力边界内，再按场景加载离线参考文档执行。ArkUI-X 只支持 Stage 模型 + ArkTS，API 仅限官方跨平台支持清单，清单外 API 编译期拦截（'xxx' can't support crossplatform application.）——清单外的平台能力只能走平台差异化 + 平台桥接（Bridge）/平台视图两条通道，这些红线直接决定技术方案能否成立，必须先核对再动手。

When to Use

• 用户明确提出用 ArkUI-X / 跨平台框架开发，一套代码同时出鸿蒙、Android、iOS 应用
• 判断某个需求或系统能力（服务卡片、分布式流转、推送、后台任务等）能否在 ArkUI-X 三端实现
• ArkUI-X 工程创建（DevEco [ArkUI-X] Empty Ability 模板）、.arkui-x 目录、arkui-x-config.json5 模块级跨平台配置
• 编译报错 'xxx' can't support crossplatform application、ignoreCrossPlatform 配置取舍
• 判断某个 @ohos.* API / 三方库是否在「跨平台支持列表」内
• ArkTS 与 Android Java / iOS Objective-C 互调：平台桥接 @arkui-x.bridge / BridgePlugin（异步/同步/回调/消息监听）
• 在 ArkUI 页面内嵌原生 View（地图、WebView 等，平台视图 IPlatformView）
• Android/iOS 工程集成：StageApplication/StageActivity/StageViewController 生命周期映射、instanceName 命名规则、WantParams 参数传递、startAbility 拉起原生页面、Fragment 跨平台
• 跨平台 N-API/FFI（ArkTS ↔ C/C++）、框架/特性动态化
• 三端构建（ace build apk/hap/ios、DevEco Build APP(s)）、rom size 包体积分析、AAR/Framework 产物复用
• ArkUI-X vs 纯鸿蒙应用 vs 元服务 vs 原生双端的技术路线选型

不适用：纯鸿蒙单端工程脚手架（create-hmos-project）、鸿蒙单端 NDK/Node-API（arkts-ndk-dev）、hvigorw/签名等鸿蒙工具链操作（arkts-build）、元服务/万能卡片（atomic-service-dev）、通用 ArkTS 语法与编译错误（arkts-helper/arkts-debug）、运行期崩溃诊断（arkts-crash-diagnosis）、轻量穿戴仿真（lite-simulator-debug）。

Boundary with Other Skills

Workflow (Follow Strictly)

1. 读入口索引与速查表

先读 references/INDEX.md（唯一入口），第一站读 references/17-arkuix-vs-harmonyos-matrix.md（能力清单、技术路线决策、差异红线速查，逐条标注官方来源）。

2. 确认技术路线与能力边界

核对 17 号第 2、3 节，确认用户目标是 ArkUI-X 跨平台、纯鸿蒙单端、元服务还是原生双端。若需求踩红线（清单外 API 且无桥接替代、服务卡片/分布式等鸿蒙独有能力要带到 Android/iOS、元服务形态误用等），明确告知限制并给出替代方案（平台差异化 + Bridge、或转纯鸿蒙/原生双端路线），不要硬做。

3. 工程与环境任务

搭环境/SDK 版本按 references/03-dev-environment.md（平台配套：Android 8+/iOS 10+/OpenHarmony API 10+，详见 14）；新建工程按 references/04-create-project-deveco.md（必须用 [ArkUI-X] Empty Ability 模板）与 references/05-first-app-stage.md；工程目录与跨平台模块配置（arkui-x-config.json5）按 references/07-package-structure.md。

4. 写码前核对 API 跨平台支持

按 references/13-api-support-list.md（官方跨平台支持列表）逐个确认所写 @ohos.* API 可用。清单外 API：先查有无跨平台等价 API；没有则按 references/08-platform-differences.md 做平台差异化（deviceInfo.osFullName 分支 + 鸿蒙侧直调），Android/iOS 侧按 references/09-platform-bridge.md（Bridge 机制与 API、数据类型与大小限制）、references/15-bridge-tutorial-android.md / references/16-bridge-tutorial-ios.md（十场景实操）桥接到原生实现；内嵌原生 View 按 references/10-platform-view.md。不要用 ignoreCrossPlatform: true 一关了之（只屏蔽告警，运行仍失败）。Android/iOS 工程集成、生命周期映射与参数传递按 references/06-ability-integration-android-ios.md。

5. 构建与体积

三端构建：DevEco Build > Build Hap(s)/APP(s) > Build APP(s)（04）或 ACE Tools ace build apk/hap/ios（07）；Android/iOS 端安装运行调试用 Android Studio / Xcode（DevEco 仅支持 ArkUI-X 源码侧，见 03）。包体积分析与优化按 references/07-package-structure.md 的 rom size 章节（ace build <target> --analyze）。

6. 引用来源

回答中引用所依据的参考文档，例如：

依据 references/08-platform-differences.md（上游《跨平台框架规格说明》规格 1）：当前支持 Stage 模型，FA 模型及类 Web 范式已不再支持。

7. 升级路径

本技能离线文档未覆盖的内容（平台视图/N-API/AAR/Framework/Fragment/联动编译/接口扩展插件等 tutorial 实操、新增版本说明），从 ArkUI-X 官方文档仓库在线获取——ArkUI-X 文档不在华为开发者门户与知识 MCP 语料内，GitCode raw 直链可用：

# 用法：把 <repo-path> 换成文档路径（去掉 zh-cn/ 前缀时的完整路径见各快照头部的上游 URL）
curl -sL "https://raw.gitcode.com/arkui-x/docs/raw/master/zh-cn/application-dev/tutorial/how-to-use-platformview-on-android.md"

文档树索引见 https://gitcode.com/arkui-x/docs/tree/master/zh-cn/application-dev ，抓取后按仓库规范补来源头使用，并引用来源。

Directory Structure

arkui-x-dev/
├── SKILL.md                                   # 本文件
├── references/
│   ├── INDEX.md                               # 唯一入口，必读
│   ├── 01-arkuix-overview.md                  # 官方：ArkUI-X 概览（定位/特征/架构）
│   ├── 02-start-overview.md                   # 官方：应用开发导读 + 开发准备（聚合）
│   ├── 03-dev-environment.md                  # 官方：配置开发环境 + ArkUI-X SDK 介绍（聚合）
│   ├── 04-create-project-deveco.md            # 官方：ArkUI-X 之初体验 + DevEco 使用（聚合）
│   ├── 05-first-app-stage.md                  # 官方：使用 ArkTS 语言开发（Stage 模型）
│   ├── 06-ability-integration-android-ios.md  # 官方：Stage 模型开发 Android/iOS 端指南（聚合）
│   ├── 07-package-structure.md                # 官方：应用工程结构说明 + rom size（聚合）
│   ├── 08-platform-differences.md             # 官方：平台差异化 + 跨平台框架规格说明 10 条（聚合）
│   ├── 09-platform-bridge.md                  # 官方：平台桥接介绍 + @arkui-x.bridge API（聚合）
│   ├── 10-platform-view.md                    # 官方：平台视图（原生 View 混合显示）
│   ├── 11-dynamic-and-ffi.md                  # 官方：动态化介绍 + FFI 能力(N-API)（聚合）
│   ├── 12-resources-cross-platform.md         # 官方：资源分类与访问
│   ├── 13-api-support-list.md                 # 官方：OpenHarmony 接口定义跨平台支持列表
│   ├── 14-release-notes-v5.0.1.md             # 官方：5.0.1 Release 版本说明 + 版本策略（聚合）
│   ├── 15-bridge-tutorial-android.md          # 官方：平台桥接开发指南（Android，十场景）
│   ├── 16-bridge-tutorial-ios.md              # 官方：平台桥接开发指南（iOS，十场景）
│   └── 17-arkuix-vs-harmonyos-matrix.md       # 原创：能力边界与开发限制速查
├── assets/
│   ├── arkui-x-config.json5                   # 跨平台模块与 ignoreCrossPlatform 配置示例
│   ├── platform-difference.ets                # 平台差异化 BAD/GOOD 示例
│   └── bridge-usage.ets                       # 平台桥接 BAD/GOOD 示例
└── evals/
    └── evals.json                             # 触发/行为评测用例

Documentation Source & Maintenance

• 官方快照（01–16）抓取自 ArkUI-X 官方文档仓库 https://gitcode.com/arkui-x/docs （master 分支，ArkUI 主库组织 https://gitcode.com/arkui-x ），抓取/核实于 2026-09-01，来源头见各文档头部。17 号为原创整理，逐条标注上游链接，修订时须同步核对对应官方页面。
• 注意：华为开发者门户 documentPortal（arkuix-* 等 catalog 均不存在）与 HarmonyOS 知识 MCP 语料都不含 ArkUI-X 文档，harmony-fetch 的两条常规通道对 ArkUI-X 无效；在线补充一律走 GitCode raw 直链（Workflow 第 7 步）。
• 更新方式：curl -sL "https://raw.gitcode.com/arkui-x/docs/raw/master/<zh-cn 路径>" 覆盖对应快照并更新来源头核实时间；「API 跨平台支持列表」（13）与版本配套关系（14）属于易变约束，定期（建议每月）核对上游是否更新。