指南版本：v0.6
概述
Hippy 和 Weex 都是用于构建高性能原生应用的框架，它们允许开发者使用 Web 开发语言（如 JavaScript 和前端框架如 Vue.js）来构建跨平台应用。尽管两者在概念上相似，但它们之间仍存在一些差异，包括 API、组件库、模块系统以及一些开发细节。本指南将帮助你理解从 Hippy 迁移到 Weex 的关键步骤和注意事项。
1. 环境准备
Hippy所需的最低版本：Node.js v16 或更高版本。
项目地址：gitlab
正在不断完善的平移分支：vue2-vod
升级或安装 Node.js
nvm安装、切换当前node版本： nvm教程
sh
# 如果你当前的 Node.js 版本低于 v16
nvm install 16.1.0
nvm use 16.1.0安装完成后，通过 node -v 命令检查你的 Node.js 版本是否已更新至所需的版本。
运行项目
进入项目根目录
js
npm i
// 开发调试项目
npm run hippy:dev
// 打包
npm run hippy:build开发调试时启动WEB同构调试
js
// npm run hippy:dev 执行成功👇
webpack-util info paste the following bundleUrl in app to open hippy page
webpack-util info bundleUrl: http://192.168.80.33:38989/2dfba76d47dc6c946af5e9c5eed2dd8d/index.bundle?debugUrl=ws%3A%2F%2F192.168.80.33%3A38989%2Fdebugger-proxy
webpack-util info find debug page on: http://192.168.80.33:38989/extensions/home.html?hash=2dfba76d47dc6c946af5e9c5eed2dd8d- 执行成功后，命令行里会提供两个url，同时浏览器会打开同构页面；
- 第一个url是调试的bundleUrl文件链接
- 第二个url是调试页面的地址，浏览器打开该链接即可进入到调试页面
- 前端先在main-native.js指定输出页面，就可直接在浏览器的console里看前端日志
- WEB同构调试界面👇
项目结构
arduino
│ main-native.js // 原生环境的入口文件,适配多种分辨率的全屏样式预处理
│ main-web.js // Web环境的入口文件
│ util.js // 存放eventbus相关的工具
│
├─animation // 动画相关文件的目录
│
├─assets // 资源文件的目录，如图片、音频等
│
├─components // 子组件相关文件的目录
│
├─config // 配置文件的目录
│ config.js // 配置接口/开发环境
│
├─module // 模块相关文件的目录
│ vod_module.js // vod原生能力调用模块
│
└─net // 网络请求相关文件的目录
│ Http. // HTTP请求工具
│ NewYearModel.js // 新年模型文件，用于处理新年相关的网络请求
│
├─pages // 页面相关文件的目录
│
├─store // Vuex状态管理相关文件的目录
│
└─utils // 实用工具文件的目录
│ kaEvent.js // 事件处理工具文件
│ navigator.js // 导航相关工具文件
│ storage.js // 存储相关工具文件
│ utils.js // 通用工具函数文件 开发时如何新增页面？
- @/pages路径下新建.vue文件
- 在main-native.js指定当前调试页面，比如指定->
vMoveDemo_v4.6_opacity.vue
js
// import App from './pages/vMoveDemo_v4.4_autoActionConf.vue';
// import App from './pages/vMoveDemo_v4.5.vue';
import App from './pages/vMoveDemo_v4.6_opacity.vue';注意 ❗
- 只有pages路径下的页面才会被打包至dist文件；
- 为了高效打包，不要在此目录放置任何不必要的页面或子组件。
2. 业务迁移
迁移代码到Hippy涉及对DOM、JS和CSS层面的调整，以确保低成本的迁移的兼容性和性能。
DOM迁移
直接将原有的dom代码平行拷贝
DOM结构差异处理
DOM结构差异归纳为五类核心元素：文本节点、图像标签、终端自定义组件、前端自定义组件、动画组件。
📃 文本节点：text
注意 ❗
- hippy中要求所有文本元素必须包裹在
<text>或其他文本类标签中 - 倘若直接写在
<div>中则文本不渲染
js
✔<text>我是文本组件:text</text>
✔<span>我是文本组件:span</span>
✔<p>我是文本组件:p</p>
✔<label>我是文本组件:label</label>
❗ × <div>我是文本组件:div</div>异常处理方案：
- 未显示文字内容？ 排查是否用正确的文本标签包裹
🖼 图像标签：image
js
✔<img :src="hippyLogoImage">
✔<image :src="hippyLogoImage"> 注意 ❗
- 引入前端本地图片资源需要用import的方式
- 倘若直接
src='./logo.png'会报vfs错误
js
// dom
<img :src="hippyLogoImage">
// js
import hippyLogoImage from '../../assets/hippyLogoImage.png';异常处理方案：
- 不显示图片？ 排查路径是否正确；图片资源是否存在；
- 报vfs错误？ 排查本地图片资源是否用了相对路径引用
🕹 终端自定义组件
// todo
🔮 前端自定义组件
注册全局公共组件
- 请将组件添加至@/components/...
- 再在@/components/index.js中统一暴露
js
// @/components/index.js
install(Vue) {
Vue.component('adb', adb)
...
}- main-native.js 会统一注册步骤2中暴露的组件，后续全局可直接使用 <adb> （无需操作）
- 切勿在main入口文件直接引用，避免代码冗余
🎆 动画组件
倘若组件需要展示动画效果，你需要包裹需展示动效的元素在<vAnimation>标签中，才能应用动画。
html
<vAnimation actionName="hippyAniAction">
<div class="comment-area" id="commentArea" ref="commentArea">
....
</div>
</VAnimation>JavaScript迁移
JS迁移可概括为3大步骤：冗余代码消除、vod终端功能���用、动画效果调试。
一、冗余代码消除
由于已经在beforeLoadStyle阶段 就对多分辨率适配 做了统一优化
所以js迁移至hippy的第一件事就是去除👇这块代码！
js
//以下代码块需要在vue文件的<javascript>块的最开始就执行
var vodWidth = weex.config.env.deviceWidth;
var tvWidth = weex.config.env.tvWidth;
var uiBaseWidth = 1280; //这边表示当前css的数值是基于1280的宽度进行标注的
var viewportWidth = vodWidth / (tvWidth / uiBaseWidth);
var meta = weex.requireModule("meta");
meta.setViewport({
width: viewportWidth,
});二、vod终端能力调用 （待与终端联调验证）
双边终端能力的调用存在差异,所以已将vod调用方法封装在@/module/vod_module.js中👇
js
// weex
var vod = weex.requireModule("kmvod");
// hippy
import { vod } from "../module/vod_module.js"三、动画效果调试
首先完整复制现有的动画代码
我的目标是在 Weex 和 Hippy 框架间建立兼容层，因此具体调整和兼容性问题需要通过你的调试来解决。在移植过程中，注重代码的适应性，确保动画效果在新环境中同样流畅。
CSS样式
直接将原有的CSS样式平行拷贝
CSS 做到开箱即用，无需修改即可在hippy适配，极大减少了工作量。
⛳动画迁移
动画迁移需要JS和DOM配合迁移 所以另开一章讲解
-
目前支持平行迁移的动效有：
缩放（scale）、opacity（透明度）、平移（translate）、水平平移（translateX）和垂直平移（translateY）。 -
不支持的动效：color（字体颜色）
一、DOM操作
全局动画自定义组件vAnimation的引入
你需要包裹需展示动效的元素在<vAnimation>标签中，才能应用动画。actionName（必传）属性是用来定义动画行为的名称，在此基础上才可以在js中定义具体的动画逻辑。
html
<vAnimation actionName="hippyAniAction">
<div class="comment-area" id="commentArea" ref="commentArea">
....
</div>
</VAnimation>二、JS调整
① 混入动画调用模组：mixinSetAni
混入：当一个类或组件"混合"了某个混入后，它就会获得混入中定义的所有成员。这种机制使得多个组件可以共享相同的代码片段，而无需通过继承来实现，从而减少了代码的耦合度。
javascript
// 引入混入组件
import mixinSetAni from '@/components/mixinSetAni';
export default {
// 在组件的mixins数组中注册混入
mixins: [mixinSetAni],
// 组件的其他配置...
};② 无差别的weex调用法
这是迁移后的缩略代码，可保持原有回调地狱不变。
js
showCommentAni(type) {
let el = this.$refs["commentArea"]
this.setAni(//向下
el, {
transform: "translateY(" + translateY + "px)",
},
() => {
this.setAni(//消失
el, {
transform: "translateY(" + translateY + "px)"
},
() => {//下一个
setTimeout(() => {
this.showCommentAni("循环")
}, 100)
},
1000
);
},
1000,
);
}注意 ❗
需循环调用 且动画的起始点位为0 的时候需要调用_loopHook，调用方法见👇
_loopHook
-
参数：
{Object} el{Array} resetTarget：translateY|translateX|scale|translate|rotate|opacity...
-
限制 ：el只接受和setAni传入的相同的
el -
详细： 重置传入的resetTarget的动画起始值为0/1(当传入scale/opacity时重置为1)
-
示例：
js
var el = this.$refs["commentArea"]
setTimeout(() => {
// 在递归showCommentAni之前调用这个hook👇
this._loopHook(el,["translateY","opacity"])
this.showCommentAni("循环")
}, 100)异常处理方案：
- Weex时期设置的字体颜色动效不生效？
- 如果业务需求仅涉及降低字体的颜色饱和度以达到视觉上的淡化效果，建议采用调整元素的
opacity属性来进行动画处理，这是一种更为高效且直观的实现方式。
- 动画循环异常排查？
- 如果在初始动画播放之后，后续的动画效果未能正常展现，请检查
_loopHook钩子函数是否已被正确调用并执行。
疑难杂症
全局事件eventbus
由于官方文档对于vue2的用法说的不清不楚，这里额外补充
js
// 引入getApp()
import { getApp } from '@/util';
// 发送方 a.js
this.app = getApp();
this.app.$emit(actionName, hippyAniAction);
// 接收方 b.vue
mounted() { // 挂载时订阅
getApp().$on(actionName, (e) => {
this.busActions = e
});
},
beforeDestroy() { // 销毁前取消订阅❗
getApp().$off(actionName);
},注意 ❗
👆演示的util存放于src目录下，不是src/utils/下的工具类
常用的官方API 官方文档
获取设备属性
获取到的都是主屏参数，对于TV屏界面开发没有什么用，作为了解便可
- 屏幕参数（只能获取到主屏的）：Vue.Native.Dimensions.screen
- 主屏像素比：Vue.Native.PixelRatio
- ......
迁移示例-新年祝福
- 原weex代码：
@/pages/happ-newyear/index.vue - 迁移效果：👇
步骤
....