diff --git a/docs/assets/img/3.0-demo-create.png b/docs/assets/img/3.0-demo-create.png new file mode 100644 index 00000000000..23585f0848d Binary files /dev/null and b/docs/assets/img/3.0-demo-create.png differ diff --git a/docs/assets/img/3.0-demo-helloworld.png b/docs/assets/img/3.0-demo-helloworld.png new file mode 100644 index 00000000000..14dbe00df10 Binary files /dev/null and b/docs/assets/img/3.0-demo-helloworld.png differ diff --git a/docs/assets/img/3.0-demo-home.png b/docs/assets/img/3.0-demo-home.png new file mode 100644 index 00000000000..42637ec7454 Binary files /dev/null and b/docs/assets/img/3.0-demo-home.png differ diff --git a/docs/assets/img/3.0-demo-page-management.png b/docs/assets/img/3.0-demo-page-management.png new file mode 100644 index 00000000000..3df9604515e Binary files /dev/null and b/docs/assets/img/3.0-demo-page-management.png differ diff --git a/docs/assets/img/3.0-demo.png b/docs/assets/img/3.0-demo.png new file mode 100644 index 00000000000..f2be10f8bfe Binary files /dev/null and b/docs/assets/img/3.0-demo.png differ diff --git a/docs/development/demo.md b/docs/development/demo.md index 34e6f4ab70d..a8c0c4de6b8 100644 --- a/docs/development/demo.md +++ b/docs/development/demo.md @@ -2,7 +2,12 @@ Hippy 采用 `monorepo` 进行代码管理，多仓库 SDK 统一版本，前端可以直接引入对应的 NPM 包，终端可通过发布分支源码接入或通过对应的包管理仓库引入。 -Hippy 已经提供了完整的[前端和终端范例](//github.com/Tencent/Hippy/tree/master/examples)，可直接基于我们现有的范例开始 App 开发。若想快速体验 Hippy，可按照本文档的步骤将 DEMO 运行起来 。 如果要在已有的 App 里整合 Hippy，请继续阅读下面的 `终端环境搭建` 等章节。 +Demo的Native工程代码位于framework/examples目录，前端工程代码位于driver/js/examples目录，如果你对阅读代码更感兴趣，可直接进入github查看 + +- [Demo Native 工程代码](https://github.com/Tencent/Hippy/tree/main/framework/examples) +- [Demo 前端工程代码](https://github.com/Tencent/Hippy/tree/main/driver/js/examples) + +如果已经已经了解Hippy，可跳过Demo体验，参考[Native工程集成章节](development/native-integration?)把Hippy集成到工程。 --- @@ -10,103 +15,217 @@ Hippy 已经提供了完整的[前端和终端范例](//github.com/Tencent/Hippy ## 环境准备 -请确保本地已安装 [git](https://git-scm.com/) 、[nodejs](https://nodejs.org/en/) 和 [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)。 +### macOS开发环境 + +可以在macOS上开发iOS，Android应用，请求根据需要进行环境配置。 -!> npm 最低要求 v7 版本, nodejs 最低要求 v16 版本 +首先，通过Homebrew包管理工具安装git, git-lfs, node(v16) and npm(v7) -Hippy 仓库根目录运行 `git clone https://github.com/Tencent/Hippy.git` 和 `npm install` 命令。 +```shell +brew install git git-lfs node@16 xcodegen cmake +``` -!> Hippy 仓库应用了 [git-lfs](https://git-lfs.github.com/) 来管理 so、gz、otf 文件， 请确保你已安装 [git-lfs](https://git-lfs.github.com/)。 +#### 编译iOS Demo环境准备 -对于 macOS 开发者： +1. Xcode -* [Xcode](https://developer.apple.com/xcode/) 和 iOS SDK： 用于构建 iOS App。 -* [Cocoapods](https://cocoapods.org/): 用于管理iOS工程文件。 -* [Android Studio](https://developer.android.com/studio) 和 NDK: 用于构建 Android App。 + 通过Apple App Store安装[Xcode](https://apps.apple.com/cn/app/xcode/id497799835?l=en-GB&mt=12) -对 Windows 开发者： +2. 通过gem命令安装Cocoapods -* [Android Studio](https://developer.android.com/studio) 和 NDK： 用于构建 Android App。 + `sudo gem install cocoapods` -## 使用 js demo 构建 iOS App -对于首次进行 iOS 开发，我们推荐优先采用 iOS 模拟器。然而你也可以修改 Xcode 配置将 app 安装到 iPhone 上。 +#### 编译Android Demo环境准备 -1. 在Hippy driver/js目录执行命令 +1. Android Studio - ```bash - npm run init + 通过android开发者平台下载安装[Android Studio](https://developer.android.com/studio) - # 该命令由 `npm install && npx lerna bootstrap && npm run build` 组成，你也可以分别执行这几个命令。 - # - # npm install: 安装项目所需的脚本依赖。 - # - # `npx lerna bootstrap`: 安装每一个 JS 包的依赖。（Hippy 使用 [Lerna](https://lerna.js.org/) 管理多个 js 包） - # - # `npm run build`: 构建每一个 JS SDK 包。 - ``` - -2. 选择一个你想体验的 JS Demo，在 Hippy 项目 driver/js目录执行 - - ```bash - npm run buildexample [hippy-react-demo|hippy-vue-demo|hippy-vue-next-demo] +2. Android NDK + + 通过android开发者平台下载安装[NDK](https://developer.android.com/ndk?hl=en) + +### Windows开发环境 + +可以Windows上开发Android应用，请安装以下依赖。 + +1. Android Studio + + 通过android开发者平台下载安装[Android Studio](https://developer.android.com/studio) - # 方括号内选择你想构建的 JS Demo，执行后会将对应的 JS 相关资源文件生成到终端 Demo 目录下。 +2. Android NDK + + 通过android开发者平台下载安装[NDK](https://developer.android.com/ndk?hl=en) + +3. Git for Windows + + 通过(https://gitforwindows.org)下载安装Git for Windows + +4. Node和NPM + + 通过指引安装[nodejs和npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)，建议使用Node v16，NPM v7版本 + + +## 代码拉取 + +```shell +git clone https://github.com/Tencent/Hippy.git +``` + +## 编译运行Demo + +以下基于macOS平台，分别说明如何编译Android和iOS Demo。 + +### 编译运行iOS Demo + +```shell +# 进入Hippy源码目录 +cd ./framework/examples/ios-demo +# 执行xcodegen生成工程 +xcodegen +# 打开workspace，编译运行即可 +open HippyDemo.xcworkspace +``` + +### 编译运行Android Demo + +1. 使用 Android Studio 打开根目录 `Android Project` 项目。 +2. 使用 USB 线连接 Android 设备，并确保设备 USB 调试模式已经开启（电脑 Terminal 执行 `adb devices` 检查手机连接状态）。 +3. Android Studio 执行项目构建，并安装 APK运行。 + +### 效果预览 + +Demo运行起来后，可见Demo首页类似 + +Demo效果 + +点击"New Page"，进入页面管理 + +Demo效果 + +点击"+"号创建新的Hippy页面 + +Demo效果 + +点击Create按钮后，显示出了Hippy渲染的页面 + +Demo效果 + + +## 动手尝试 + +如果你不满足于简单把Demo跑起来，还可以动手尝试修改前端代码，可以按照以下指引进行。 + +### 了解Demo项目代码 + +Demo项目Native代码位于framework/examples/，前端代码位于driver/js/examples目录 + +```shell +steven@STEVEN-MC Hippy % ls driver/js/examples +total 0 +drwxr-xr-x 8 steven staff 256 Oct 30 14:53 hippy-react-demo +drwxr-xr-x 9 steven staff 288 Oct 30 14:53 hippy-vue-demo +drwxr-xr-x 11 steven staff 352 Oct 30 14:53 hippy-vue-next-demo - # 如果该步骤出现异常，你也可以 `cd` 到 `examples` 下的任意一个 JS Demo 目录，执行 `npm install --legacy-peer-deps` 去安装 Demo 的依赖。 - ``` +``` -3. 打开`examples/ios-demo`目录, 使用`Cocoapods`生成工程项目文件 +其中前端hippy-react-demo、hippy-vue-demo、hippy-vue-next-demo这3者为前端项目Demo，分别演示基于hippy-react、hippy-vue、hippy-vue-next开发项目。 - ```bash - cd examples/ios-demo - pod install - ``` +### 修改前端工程 -4. 用`Xcode`打开上一步Cocoapods生成的 `HippyDemo.xcworkspace`工程文件，进行 iOS App 构建。 +以hippy-react-demo为例，打开hippy-react-demo/src/app.jsx，将内容替换为以下代码片段 -> 更多细节请参考 [iOS 集成章节](development/native-integration?id=ios). +```jsx +import React, { Component } from 'react'; +import { + View, + Text +} from '@hippy/react'; -## 使用 js demo 构建 Android App +export default class App extends Component { + render() { + return ( + + Hello World! + + ); + } +} +``` -1. Hippy driver/js 目录执行 `npm run init`。 +### 编译修改后的前端工程 - > 该命令由 `npm install && npx lerna bootstrap && npm run build` 组成，你也可以分别执行这几个命令。 - > - > `npm install`: 安装项目所需的脚本依赖。 - > - > `npx lerna bootstrap`: 安装每一个 JS 包的依赖。（Hippy 使用 [Lerna](https://lerna.js.org/) 管理多个 js 包） - > - > `npm run build`: 构建每一个 JS SDK 包。 +先在Hippy**根目录**执行命令 -2. 选择一个你想体验的 JS Demo，在 Hippy driver/js目录执行 `npm run buildexample [hippy-react-demo|hippy-vue-demo|hippy-vue-next-demo]`（方括号内选择你想构建的 JS Demo），执行后会将对应的 JS 相关资源文件生成到终端 Demo 目录下。 -3. 使用 Android Studio 打开根目录 `Android Project` 项目。 -4. 使用 USB 线连接 Android 设备，并确保设备 USB 调试模式已经开启（电脑 Terminal 执行 `adb devices` 检查手机连接状态）。 -5. Android Studio 执行项目构建，并安装 APK。 +```shell +npm install +``` -> 如果 `步骤二` 出现异常，你也可以 `cd` 到 `examples` 下的任意一个 JS Demo 目录，执行 `npm install --legacy-peer-deps` 去安装 Demo 的依赖。 -> -> 更多细节请参考 [Android 集成章节](development/native-integration?id=android)。 +以hippy-react-demo为例说明编译流程 -## 调试 js demo +```shell +cd driver/js/ +npm run init -1. 按照 `使用 js demo 构建 iOS App` 或 `使用 js demo 构建 Android App` 步骤构建 App。 -2. Hippy 项目driver/js目录执行 `npm run init:example [hippy-react-demo|hippy-vue-demo|hippy-vue-next-demo]`。 -3. Hippy 项目driver/js目录执行 `npm run debugexample [hippy-react-demo|hippy-vue-demo|hippy-vue-next-demo] dev`。 +# 该命令由 `npm install && npx lerna bootstrap && npm run build` 组成，你也可以分别执行这几个命令。 +# +# npm install: 安装项目所需的脚本依赖。 +# +# `npx lerna bootstrap`: 安装每一个 JS 包的依赖。（Hippy 使用 [Lerna](https://lerna.js.org/) 管理多个 js 包） +# +# `npm run build`: 构建每一个 JS SDK 包。 -> 或者你也可以 `cd` 到 `driver/js/examples` 下不同的 DEMO 目录执行 `npm run hippy:dev` 开启 JS Bundle 调试. -> -> 为了在 Demo 调试模式下便于修改SDK源码进行调试，@hippy/react、 @hippy/vue,、@hippy/vue-next 等 npm 包会链接到 `packages` > `[different package]` > `dist` 的生产文件下，所以一旦你修改了 JS SDK的源码并想要在目标 JS DEMO 里立即生效，请再次在 Hippy 项目driver/js目录执行 `npm run build`。 -> -> 更多调试细节请参考 [Hippy 调试文档](development/debug)。 +# 编译hippy-react-demo +npm run buildexample hippy-react-demo -## 构建生产环境 JS demo +# 如果上一条命令有异常，可以执行以下命令 +cd examples/hippy-react-demo +npm install --legacy-peer-deps +cd ../.. +npm run buildexample hippy-react-demo +``` -1. 按照 `使用 js demo 构建 iOS App` 或 `使用 js demo 构建 Android App` 步骤构建 App。 -2. `cd` 到 `examples` 下不同的 DEMO 目录（hippy-react-demo/hippy-vue-demo/hippy-vue-next-demo）。 -3. 执行 `npm install` 安装不同 DEMO 的依赖包。 -4. 执行 `npm run hippy:vendor` 和 `npm run hippy:build` 构建出生产环境所需的 `vendor.[android|ios].js` 和 `index.[android|ios].js`。 +执行完后，构建产物将会被打包放到examples/hippy-react-demo/dist目录中，目录内容类似 -> Hippy demo 使用 Webpack DllPlugin 分离出公共的 js common 包和业务包，以便多个业务能够复用 common 代码。 +```shell +driver/js/examples/hippy-react-demo/dist +├── android +│ ├── assets +│ │ ├── defaultSource.jpg +│ │ └── hippyLogoWhite.png +│ ├── asyncComponentFromHttp.android.js +│ ├── asyncComponentFromLocal.android.js +│ ├── index.android.js +│ ├── vendor-manifest.json +│ └── vendor.android.js +└── ios + ├── assets + │ ├── defaultSource.jpg + │ └── hippyLogoWhite.png + ├── asyncComponentFromHttp.ios.js + ├── asyncComponentFromLocal.ios.js + ├── index.ios.js + ├── vendor-manifest.json + └── vendor.ios.js +5 directories, 14 files +``` +### 运行前端编译产物 + +正常构建后产物会被拷贝到Android和iOS的res目录，如果发现未拷贝，可以手动执行。 +把examples/hippy-react-demo/dist/ios目录内容整体拷贝到ios demo的res/react目录，当用Android来跑时，注意拷贝到Android对应的目录。 + +```shell +cp -R driver/js/examples/hippy-react-demo/dist/ios/* framework/examples/ios-demo/res/react +cp -R driver/js/examples/hippy-react-demo/dist/android/* framework/examples/android-demo/res/react/ +``` + +接下来，按照[编译运行Demo](#编译运行demo)一节运行Demo。 +效果如图所示 + + +Demo效果 + +恭喜你完成了Hippy的初步体验，下一步参考[Native工程集成章节](development/native-integration)将Hippy接入到你现有的工程吧。