JS API v2 与 v7 的核心分水岭在于能力边界重划：v2 是早期简单响应式框架，v7 是 ArkUI 全面落地后的重构版本，二者不兼容，需迁移 ForEach→Repeat、CustomDialogController→bindsheet/bingpopup、animateto→animateTo+AnimationOptions。
JS API v2 和 v7 的核心分水岭在哪
不是“功能更多”，而是“能力边界彻底重划”：v2 是 HarmonyOS 早期 JS UI 框架的初始形态，仅支持简单组件绑定与基础状态响应；v7 则是 ArkUI 开发框架全面落地后的稳定版本，引入了 @ObservedV2、Repeat、bindsheet 等语义化更强的状态驱动机制。两者不兼容，不能混用——v2 的 ForEach 在 v7 工程中会直接报错 ReferenceError: ForEach is not defined。
v7 必须迁移的三个高频断点
实际升级时，90% 的编译失败集中在这三处：
-
ForEach必须替换成Repeat，且Repeat要求数据源必须是被@ObservedV2装饰的类实例，普通数组不行 -
CustomDialogController在 v7 中已废弃，改用bindsheet或bindpopup配合@Builder函数定义弹窗内容 - 动画控制从
animateto（v2）变为统一由animateTo（注意大小写）+AnimationOptions对象驱动，旧参数如duration必须包进对象里
HTML5 文件里调用 JS 插件，v2/v7 差异真的影响 DOM 吗
不影响。HTML5 本身是运行在 Webview 或 web 组件中的标准环境，它调用的 JS 插件（比如通过 window.postMessage 通信）属于纯前端逻辑，和 ArkTS/JS UI 的 API 版本无关。真正受影响的是：你在 module.json5 里声明的 abilities 类型、build-profile.json5 中指定的 apiVersion，以及所有写在 .ets 文件里的 UI 构建代码。
怎么一眼判断项目用的是 v2 还是 v7
看三处关键配置和语法：
立即学习“前端免费学习笔记（深入）”；
- 打开
module.json5，检查module.apiVersion字段：值为2是 v2；7或更高（如8、9）即 v7+ - 打开任意
.ets页面文件，搜@Component—— 若后面跟着V2（如@ComponentV2），说明还在用 v2 兼容层；若只有@Component且搭配@ObservedV2，基本就是 v7 原生写法 - 查
build-profile.json5中apiType是否为stage：v7 要求必须是stage模型，fa（Feature Ability）模型只支持到 v2
v7 的迁移不是加新功能，是换引擎——很多看似“只是换个函数名”的改动，背后是整个响应式系统重建。最容易漏掉的是 RelativeContainer 里子组件的 layoutWeight 行为变化，v2 中它影响 flex 分布，v7 中已被弃用，得改用 Flex + weight 属性。这种隐性断裂，往往要到真机调试时才暴露。
