企业官网建设流程全解析

• 跨平台
• 移动开发
• 前端

本文围绕 Hippy 3.0 前端 SDK 的升级指引展开，覆盖 hippy-react、hippy-vue（Vue 2.x）、hippy-vue-next（Vue 3.x）三类框架的依赖升级步骤、组件与接口变更点、升级后的验证关注点，以及 3.0 带来的 Performance API 与 Layout 引擎切换等新特性。读完后，你可以按版本组合完成业务工程的依赖升级、重编 JS common 包，并对 Move 操作、事件冒泡/捕获、动画表现等重点场景做回归验证。

升级依赖项变更

升级 3.0 的第一件事是核对业务工程中各@hippy/*包与react/vue的版本组合。下面按框架分别给出官方指引中的完整升级清单。

hippy-react

如果业务目前使用 React 来开发 Hippy，需先确认两个前置条件：当前@hippy/react的版本，以及工程中react的版本（16 还是 17）。

场景一：@hippy/react版本小于 2.12.0，且 React 使用的是 16 的版本，需要升级如下版本：

（1）删除 react-reconciler 依赖 （2）@hippy/react 升级到 3.3.0 及以上 （3）新增 @hippy/react-reconciler 依赖，使用react17的tag，即 @hippy/react-reconciler: "react17" （4）React 版本升级到 17，即 react: "^17.0.2" （5）如果使用了 @hippy/react-web 包做h5同构，则需要升级 @hippy/react-web 到 3.3.0 及以上

场景二：@hippy/react版本大于 2.12.0，且 React 使用的是 17 的版本，需要升级如下版本：

（1）@hippy/react 升级到 3.3.0 及以上 （2）升级 @hippy/react-reconciler 依赖，使用react17的tag，即 @hippy/react-reconciler: "react17" （3）如果使用了 @hippy/react-web 包做h5同构，则需要升级 @hippy/react-web 到 3.3.0 及以上

需要业务使用新的 hippy-react 重编 js common包。

这一点可以直接从仓库源码得到印证：hippy-react 的 package.json 中，dependencies已经固定为"@hippy/react-reconciler": "react17"与"react": "^17.0.2"，且不再包含旧的react-reconciler依赖，与上述升级清单完全一致。

hippy-vue

如果业务目前使用 Vue 2.x 来开发 Hippy，需要升级如下版本依赖：

（1）@hippy/vue 升级到 3.3.1-rc.1 及以上 （2）@hippy/vue-native-components 升级到 3.3.0 及以上 （3）@hippy/vue-router 升级到 3.3.0 及以上 （4）@hippy/vue-css-loader 升级到 3.3.0 及以上 （5）@hippy/vue-loader 升级到 3.3.0 及以上 （6）vue 和 vue-router 等vue相关依赖无需升级

需要业务使用新的 hippy-vue 重编 js common包。

hippy-vue-next

如果业务目前使用 Vue 3.x 来开发 Hippy，需要升级如下版本依赖：

（1）@hippy/vue-next 升级到 3.3.0 及以上 （2）@hippy/vue-css-loader 升级到 3.3.0 及以上 （3）@hippy/vue-router-next-history 升级到 0.0.1 （4）vue 和 vue-router 等vue相关依赖无需升级

需要业务使用新的 hippy-vue-next 重编 js common包。

可以对照仓库确认这几个包均已包含在 monorepo 中：hippy-vue、hippy-vue-next、hippy-vue-native-components、hippy-vue-css-loader、hippy-vue-loader，其中@hippy/vue-next声明了对@vue/runtime-core@3.4.32、@vue/shared@3.4.32的 peerDependencies，这也呼应了"vue 相关依赖无需升级"的前提——3.0 SDK 是与现有 Vue 3.x 运行时对齐的，升级压力集中在@hippy/*一层。

接入与使用方式变更

接入 Hippy-React、Hippy-Vue、Hippy-Vue-Next SDK 的代码方式无变化，可参考 前端集成指引。

具体变化点如下：

1. iOS 新增节点层级优化算法，Android 优化了现有的层级优化算法。 该算法会将仅参与布局的 View 节点优化去除，从而提升渲染效率。请注意：由于该算法的存在，可能导致依赖特定 UI 层级结构的 native 组件发生"找不到特定 View"的异常。 此时，可以通过前端代码中给特定 View 增加collapsable: 'false'属性来禁止该节点被优化算法去除。

从源码结构看，collapsable是一个跨端落地的节点属性，而不仅仅存在于前端 SDK：Android 端的 NodeProps.java、HarmonyOS 端的 hr_node_props.h 均定义了对应的属性解析；前端侧 view.tsx 等基础组件也透传了该属性。也就是说，当某个自定义 native 组件（如需要按层级查找子 View 的容器）在 3.0 下报错时，第一步排查就应是：给被"拍平"掉的中间 View 补上collapsable: 'false'。

组件变更

以下 5 个组件级变更是升级时最容易踩坑的地方，需逐条自查：

1. dialog 组件：第一个子元素不能设置{ position: absolute }样式。如果想将 dialog 内容铺满全屏，可以给第一个子元素设置{ flex: 1 }样式，或者显式设置 width 和 height 数值。

2. Image 组件：废弃了source、sources、srcs字段，建议使用src字段代表图片 url。

3. iOS Image 组件：默认没有实现图片缓存（由于实现机制的变化），需要业务 iOS 端自行实现缓存管理，详细可参考 iOS 升级指引。

4. hippy-vue scoped 样式隔离：2.15 以前的版本不支持 scoped 样式隔离；2.15–2.17 的版本，如果没有开启Vue.config.scoped = true;也不支持 scoped 样式隔离。Vue 3.0 默认开启 scoped，无需设置开关。

5. hippy-vue 布局属性书写方式：height、width等布局属性在 3.0 的版本将不支持放在自定义属性里，如：

<div :height="36" :width="36" >

需要放在style属性中，如：

<div :style={height: 36, width: 36} >

第 5 点的背景可以从 C++ DOM 侧得到解释：3.0 中节点属性统一走 DOM 层的属性解析（见 node_props.h），height/width这类布局语义被归入 style 通道处理，而不再作为节点属性透传，因此旧写法在 3.0 下会静默失效，必须迁移到:style中。

接口定义变更

3.0 对前端接口面做了收敛，以下是 5 个明确的变更点：

1. hippy-react 不再导出RNfqb、RNfqbRegister、RNfqbEventEmitter、RNfqbEventListener方法。业务侧如有引用需要移除或替换。

2. hippy-react animation 模块建议统一使用destroy()；仍兼容历史错误写法destory()（已标记废弃，后续可能移除）。

3. hippy-react animation 事件监听不再支持onRNfqbAnimationXX兼容写法，统一用onHippyAnimationXX或者onAnimationXX。

4. 动画对象的初始化时机：

   • hippy-react 初始化动画对象（new Animation），需要在根节点渲染之后，否则会因为 Dom Manager 未创建提示报错；
   • hippy-vue/hippy-vue-next 初始化动画对象（new Animation），需要在Vue.start 回调之后，否则会因为 Dom Manager 未创建提示报错。

5. 颜色渐变动画需显式指定 valueType：hippy-react/hippy-vue/hippy-vue-next 如果使用了颜色属性的渐变动画，需要显式指定 color 单位，添加valueType: 'color'字段，例如：

animation: new Animation({ startValue: 'red', toValue: 'yellow', valueType: 'color', // 颜色动画需显式指定color单位 duration: 1000, delay: 0, mode: 'timing', timingFunction: 'linear', }),

从源码结构看，第 4、5 点的变化与 3.0 的实现迁移方向一致：动画不再走 JS bridge 模块，而是下沉到 C++ DOM 模块实现，仓库中 animation.h、animation_manager.h、cubic_bezier_animation.h 等头文件对应了这一层 C++ 实现。由于 C++ 侧需要依据valueType区分颜色插值与数值插值，颜色动画才必须显式标注单位；而"Dom Manager 未创建"的报错则直接对应动画管理器挂载在 DOM 场景之上的生命周期约束。

验证关注点

Hippy 3.0 前端架构的四大改动点

Hippy 3.0 前端架构升级主要有如下改动点：

1. JS 驱动上屏的方式由UIManagerModule变为了SceneBuilder。
2. Node API 重新实现了 Move 计算逻辑。
3. Event 由前端分发变为 DOM 分发。
4. 动画由 bridge 模块变为 C++ DOM 模块实现。

这四点都能在仓库中找到落点：旧的上屏通道 UIManagerModule.js 仍然存在，但 3.0 的节点上屏走 scene_builder.h / scene_builder.cc 这条 C++ 链路；Move 重算与事件分发则落在 DOM 层的节点与 diff 逻辑（如 diff_utils.h）中。

回归验证的三个重点

升级后需要验证关注：

1. 界面的 UI 视图渲染正常（UI 结构、样式属性等），特别关注 Hippy-React/Vue 中因为条件渲染语句产生的节点Move操作，表现是否正常——由于 Move 计算逻辑重新实现，v-if/条件渲染导致的列表项增删移动是回归重点；
2. UI 事件（点击、滑动等）表现正常，特别关注事件冒泡、捕获等表现是否正常——事件分发主体从前端换成了 DOM 层，事件链路的顺序与终止行为需要重点验证；
3. 关注动画表现是否正常——动画实现主体迁移到 C++ DOM 模块，timing 函数、颜色渐变、延迟与循环等参数表现需要逐一核对。

新特性

Performance API

Hippy 3.0 实现了基于前端规范设计的性能 API，接入方式可参考 Performance。

Layout 引擎支持切换

Hippy 3.0 支持了 Layout 引擎的无缝切换，项目可保持Yoga引擎，也可以选择 Hippy 自研的Taitank引擎。详情可参考 Layout。

从源码结构看，两种引擎以"布局节点"的策略类形式共存于 DOM 层：yoga_layout_node.h 与 taitank_layout_node.h 分别对接 Yoga 与 Taitank，上层的 layout_node.h 负责统一抽象，这正是"无缝切换"能够成立的结构基础——业务侧无需感知布局引擎差异。

小结

3.0 的前端升级可以概括为三步：一是按框架版本组合完成@hippy/*依赖升级并重编 JS common 包；二是处理组件与接口层面的 5+5 个变更点（dialog 子元素布局、Image 字段与缓存、scoped 开关、:style布局属性、RNfqb 系列 API 移除、destroy 拼写、动画初始化时机与valueType: 'color'）；三是围绕 Move 操作、事件冒泡/捕获、动画表现三条主线做回归，必要时用collapsable: 'false'修复层级优化导致的 native 组件查找异常。升级的接入代码本身无需变化，成本主要集中在依赖版本核对与行为回归上。

• 跨平台
• 移动开发
• 前端