开始接入

Hippy 已经提供了完整的前终端范例,可以直接基于我们现有的范例开始 App 开发。

如果要在已有的 App 里整合 Hippy,那就请继续阅读下面的终端集成章节。需要提醒的是,在 Hippy 体系下,终端开发转变为平台开发,前端开发变成业务开发平台开发提供通用的能力,供业务开发完成实际交互,因此还要注意以后续的自定义章节,这都需要进入起步菜单下对应的终端章节。

终端集成

如果要接入 Hippy 到现有项目,请查看 iOSAndroid 集成教程。

前端接入

Hippy 同时支持 React 和 Vue 两种语法,通过 @hippy/react@hippy/vue 两个包提供实现。

但是从工程上我们依然称呼它们为 hippy-reacthippy-vue

hippy-react

[hippy-react 介绍] [范例工程]

hippy-react 工程暂时只能通过手工配置初始化(后期会提供基于 yeoman 的脚手架),建议直接 clone 范例工程并基于它进行修改。

当然,也可以从头开始进行配置。

准备 hippy-react 运行时依赖

请使用 npm i 安装以下 npm 包,保证运行时正常。

包名说明
@hippy/reacthippy-react 运行时和渲染层
reactreact 本体
regenerator-runtimeasync/await 转换运行时

hippy-react 编译时依赖

以官方提供的 范例工程 范例工程为例,需要使用 npm i -D 准备好以下依赖,当然开发者可以根据需要自行选择:

必须的:

包名说明
@babel/plugin-proposal-class-propertiesBabel 插件 - 支持仍在草案的 Class Properties
@babel/preset-envBabel 插件 - 根据所设置的环境选择 polyfill
@babel/preset-reactBabel 插件 - 转译 JSX 到 JS
@hippy/debug-serverHippy 前终端调试服务
babel/coreBabel - 高版本 ES 转换为 ES6 和 ES5 的转译程序
babel-loaderWebpack 插件 - 加载 Babel 转译后的代码
unicode-loaderWebpack 插件 - Hippy 只支持 unicode 的代码
webpackWebpack 打包程序
webpack-cliWebpack 命令行

可选的:

包名说明
case-sensitive-paths-webpack-pluginWebpack 插件,对 import 文件进行大小写检查
file-loader静态文件加载
url-loader静态文件以 Base64 形式加载

hippy-react 编译配置

当前 hippy-react 采用 Webpack 4构建(暂时不建议升级到Webpack 5),配置全部放置于 scripts 目录下,其实只是 webpack 的配置文件,建议先阅读 webpack 官网内容,具备一定基础后再进行修改。

hippy-react 终端开发调试用编译配置

该配置展示了将 Hippy 运行于终端的最小化配置。

配置文件说明
hippy-webpack.dev.js调试用配置

终端线上包配置

线上包和开发调试用包主要有两个区别:

  1. 开启了 production 模式,去掉调试信息,关闭了 watch(watch 模式下会监听文件变动并重新打包)。
  2. 终端内很可能不止运行一个 Hippy 业务,所以将共享的部分单独拆出来做成了 vendor 包,这样可以有效减少业务包体积,这里使用了 DllPluginDllReferencePlugin 来实现。需要说明的是生成的 vendor 包正常情况下是不需要特别更新的,但是如果更新了也要注意一下向上兼容性,不要因为分包导致业务崩溃。
配置文件说明
vendor.jsvendor 包中需要包含的共享部分
hippy-webpack.ios.jsiOS 业务包配置
hippy-webpack.ios-vendor.jsiOS Vendor 包配置
hippy-webpack.android.jsAndroid 业务包配置
hippy-webpack.android-vendor.jsAndroid Vendor 包配置

如果仔细观察 webpack 配置,可以看出 iOS 和 Android 配置差不多,但因为 iOS 上受苹果政策影响只能使用 JavaScriptCore(以下简称 JSC)作为运行环境,而 JSC 是跟随 iOS 操作系统的,无法进行独立升级,低版本 iOS 带的 JSC 甚至无法完整支持 ES6,所以需要输出一份 ES5 版本的 JS 代码。而 Android 下可以使用可以独立升级的 X5 中的 V8 作为运行环境,就可以直接使用 ES6 代码了。ES6 代码不但运行更快,体积还会更小一些。

特别说明:JS 方面可以使用的功能其实受到 iOS 覆盖最低版本的影响,绝大多数功能可以通过 @babel/preset-env自动安装 polyfill,但是部分特性不行,例如要使用 Proxy,就无法覆盖 iOS 10 以下版本。

hippy-react 入口文件

入口文件非常简单,只是从 hippy-react 里初始化一个 Hippy 实例。注意,入口文件组件需要通过单节点包裹,如下:

  1. import { Hippy } from '@hippy/react';
  2. import App from './app';
  3. new Hippy({
  4. appName: 'Demo', // 终端分配的业务名称
  5. entryPage: App, // 对应业务启动时的组件
  6. silent: false, // 设置为 true 可以关闭框架日志输出
  7. }).start();
  8. // P.S. entryPage需要通过单节点包裹,不能用数组的形式,例如
  9. import React from 'react';
  10. import {
  11. View,
  12. Text,
  13. } from '@hippy/react';
  14. export default function app() {
  15. // 入口文件不要使用这种形式,非入口文件可以使用
  16. return [
  17. <View key="root_blk" />,
  18. <Text key="root_txt">test test</Text>
  19. ];
  20. // 修改成通过单节点包裹
  21. return (<View>
  22. <View key="root_blk" />,
  23. <Text key="root_txt">test test</Text>
  24. </View>);
  25. }

hippy-react npm script

最后在 package.json 中补上几个快速的 npm 脚本就可以了,这里以 hippy:开头做好了范例,这里顺道做了一个到 hippy-debug-server 的快速启动命令。

  1. "scripts": {
  2. "hippy:debug": "hippy-debug",
  3. "hippy:dev": "webpack --config ./scripts/hippy-webpack.dev.js",
  4. "hippy:vendor": "webpack --config ./scripts/hippy-webpack.ios-vendor.js --config ./scripts/hippy-webpack.android-vendor.js",
  5. "hippy:build": "webpack --config ./scripts/hippy-webpack.ios.js --config ./scripts/hippy-webpack.android.js"
  6. }

hippy-react 转 Web

请参考专门的 hippy-react 转 Web 章节

hippy-vue

[hippy-vue 介绍] [范例工程]

hippy-vue 相对简单很多,hippy-vue 只是 Vue 在终端上的渲染层,组件也基本和浏览器保持一致。可以通过 vue-cli创建一个 Web 项目,然后加上一些 hippy-vue 的内容就可以直接将网页渲染到终端了。

准备 hippy-vue 运行时依赖

请使用 npm i 安装以下 npm 包,保证运行时正常。

包名说明
@hippy/vuehippy-vue 运行时核心
@hippy/vue-native-componentshippy-vue 的扩展终端组件
@hippy/vue-routervue-router 在 hippy-vue 上的移植

hippy-vue 编译时依赖

以官方提供的 范例工程 范例工程为例,需要使用 npm i -D 准备好以下依赖,当然开发者可以根据需要自行选择:

必须的:

包名说明
@hippy/debug-serverHippy 前终端调试服务
@hippy/vue-css-loaderhippy-vue 的 CSS 文本到 JS 语法树转换
unicode-loaderWebpack 插件 - Hippy 只支持 unicode 字符集

可选的:

包名说明
case-sensitive-paths-webpack-pluginWebpack 插件,对 import 文件进行大小写检查

hippy-vue 编译配置

当前 hippy-vue 采用 Webpack 4构建(暂时不建议升级到Weppack 5),配置全部放置于 scripts 目录下,其实只是 webpack 的配置文件,建议先阅读 webpack 官网内容,具备一定基础后再进行修改。

hippy-vue 终端开发调试用编译配置

该配置展示了将 Hippy 运行于终端的最小化配置。

配置文件说明
hippy-webpack.dev.js调试用配置

hippy-vue 终端线上包配置

线上包和开发调试用包主要有两个区别:

  1. 开启了 production 模式,去掉调试信息,关闭了 watch(watch 模式下会监听文件变动并重新打包)。
  2. 终端内很可能不止运行一个 Hippy 业务,所以将共享的部分单独拆出来做成了 vendor 包,这样可以有效减少业务包体积,这里使用了 DllPluginDllReferencePlugin 来实现。需要说明的是生成的 vendor 包正常情况下是不需要特别更新的,但是如果更新了也要注意一下向上兼容性,不要因为分包导致业务崩溃。
配置文件说明
vendor.jsvendor 包中需要包含的共享部分
hippy-webpack.ios.jsiOS 业务包配置
hippy-webpack.ios-vendor.jsiOS Vendor 包配置
hippy-webpack.android.jsAndroid 业务包配置
hippy-webpack.android-vendor.jsAndroid Vendor 包配置

如果仔细观察 webpack 配置,可以看出 iOS 和 Android 配置差不多,但因为 iOS 上受苹果政策影响只能使用 JavaScriptCore(以下简称 JSC)作为运行环境,而 JSC 是跟随 iOS 操作系统的,无法进行独立升级,低版本 iOS 带的 JSC 甚至无法完整支持 ES6,所以需要输出一份 ES5 版本的 JS 代码。而 Android 下可以使用可以独立升级的 X5 中的 V8 作为运行环境,就可以直接使用 ES6 代码了。ES6 代码不但运行更快,体积还会更小一些。

特别说明:JS 方面可以使用的功能其实受到 iOS 覆盖最低版本的影响,绝大多数功能可以通过 @babel/preset-env自动安装 polyfill,但是部分特性不行,例如要使用 Proxy,就无法覆盖 iOS 10 以下版本。

hippy-vue 入口文件

hippy-cli 初始化的项目自带了一个Web 端入口文件,可以保留着用来启动 Web 端网页,但是因为 hippy-vue 的启动参数不一样,需要专门的终端入口文件来加载一些终端上用到的模块。

  1. import Vue from 'vue';
  2. import VueRouter from 'vue-router';
  3. import HippyVueNativeComponents from '@hippy/vue-native-components';
  4. import App from './app.vue';
  5. import routes from './routes';
  6. import { setApp } from './util';
  7. // 禁止框架调试信息输出,取消注释即可使用。
  8. // Vue.config.silent = true;
  9. Vue.config.productionTip = false;
  10. // Hippy 终端组件扩展中间件,可以使用 modal、view-pager、tab-host、ul-refresh 等终端扩展组件了。
  11. Vue.use(HippyVueNativeComponents);
  12. Vue.use(VueRouter);
  13. const router = new VueRouter(routes);
  14. /**
  15. * 声明一个 app,这是同步生成的
  16. */
  17. const app = new Vue({
  18. // 终端指定的 App 名称
  19. appName: 'Demo',
  20. // 根节点,必须是 Id,当根节点挂载时才会触发上屏
  21. rootView: '#root',
  22. // 渲染自己
  23. render: h => h(App),
  24. // iPhone 下的状态栏配置
  25. iPhone: {
  26. // 状态栏配置
  27. statusBar: {
  28. // 禁用状态栏自动填充
  29. // disabled: true,
  30. // 状态栏背景色,如果不配的话,会用 4282431619,也就是 #40b883 - Vue 的绿色
  31. // 因为运行时只支持样式和属性的实际转换,所以需要用下面的转换器将颜色值提前转换,可以在 Node 中直接运行。
  32. // hippy-vue-css-loader/src/compiler/style/color-parser.js
  33. backgroundColor: 4283416717,
  34. // 状态栏背景图,要注意这个会根据容器尺寸拉伸。
  35. // backgroundImage: '//mat1.gtimg.com/www/qq2018/imgs/qq_logo_2018x2.png',
  36. },
  37. },
  38. // 路由
  39. router,
  40. });
  41. /**
  42. * $start 是 Hippy 启动完以后触发的回调
  43. * Vue 会在 Hippy 启动之前完成首屏 VDOM 的渲染,所以首屏性能非常高
  44. * 在 $start 里可以通知终端说已经启动完成,可以开始给前端发消息了。
  45. */
  46. app.$start((/* app */) => {
  47. // 这里干一点 Hippy 启动后的需要干的事情,比如通知终端前端已经准备完毕,可以开始发消息了。
  48. // setApp(app);
  49. });
  50. /**
  51. * 保存 app 供后面通过 app 接受来自终端的事件。
  52. *
  53. * 之前是放到 $start 里的,但是有个问题时因为 $start 执行太慢,如果首页就 getApp() 的话可能会
  54. * 导致获得了 undefined,然后监听失败。所以挪出来了。
  55. *
  56. * 但是终端事件依然要等到 $start 也就是 Hippy 启动之后再发,因为之前桥尚未建立,终端发消息前端也
  57. * 接受不到。
  58. */
  59. setApp(app);

hippy-vue npm script

最后在 package.json 中补上几个快速的 npm 脚本就可以了,这里以 hippy:开头做好了范例,这里顺道做了一个到 hippy-debug-server 的快速启动命令。

  1. "scripts": {
  2. "hippy:debug": "hippy-debug",
  3. "hippy:dev": "webpack --config ./scripts/hippy-webpack.dev.js",
  4. "hippy:vendor": "webpack --config ./scripts/hippy-webpack.ios-vendor.js --config ./scripts/hippy-webpack.android-vendor.js",
  5. "hippy:build": "webpack --config ./scripts/hippy-webpack.ios.js --config ./scripts/hippy-webpack.android.js"
  6. },

路由

@hippy/vue-router 完整支持 vue-router 中的跳转功能,具体请参考 hippy-vue-router 文档。

hippy-vue 转 Web

hippy-vue 项目基于 vue-cli 生成的 Web 项目,之前的 Web 能力可以直接使用,对于使用 vue-cli 生产的项目,可以参考官方文档