273 lines
9.9 KiB
Markdown
273 lines
9.9 KiB
Markdown
### 运行演示应用
|
||
|
||
启动 Metro 打包工具：
|
||
|
||
```
|
||
npm run native start:reset
|
||
```
|
||
|
||
在另一个终端中运行以下命令，在 Android 模拟器中启动演示应用（如果模拟器尚未运行，此命令也会自动启动模拟器）：
|
||
|
||
```
|
||
npm run native android
|
||
```
|
||
|
||
稍等片刻后，我们将看到类似以下界面：
|
||
|
||
<img src="https://developer.wordpress.org/files/2021/10/android-simulator.png" width="700px" alt="Android模拟器中区块编辑器的截图">
|
||
|
||
## 单元测试
|
||
|
||
```sh
|
||
npm run test:native
|
||
```
|
||
|
||
## 集成测试
|
||
|
||
[Appium](https://appium.io/) 自带诊断工具。通过以下命令运行：
|
||
|
||
```sh
|
||
npx appium-doctor
|
||
```
|
||
|
||
<img src="https://developer.wordpress.org/files/2021/10/CleanShot-2021-10-27-at-15.20.16.png" width="700px" alt="终端中运行的appium-doctor工具截图">
|
||
|
||
请解决所有必需的依赖项。
|
||
|
||
### iOS 集成测试
|
||
|
||
若能确保 iOS 本地环境正常运行，iOS 端到端测试将十分简单。首先停止所有正在运行的 Metro 进程（之前通过 `npm run native start:reset` 启动）。
|
||
|
||
然后在终端中输入：
|
||
|
||
```sh
|
||
npm run native test:e2e:ios:local
|
||
```
|
||
|
||
通过指定文件名可运行部分测试用例：
|
||
|
||
```sh
|
||
npm run native test:e2e:ios:local gutenberg-editor-paragraph.test.js
|
||
```
|
||
|
||
若一切顺利，将呈现如下效果：
|
||
|
||
<video src="https://user-images.githubusercontent.com/1270189/137403353-2a8ded47-5c7c-4f99-b2cc-fa6def4b4990.mp4" data-canonical-src="https://user-images.githubusercontent.com/1270189/137403353-2a8ded47-5c7c-4f99-b2cc-fa6def4b4990.mp4" controls="controls" muted="muted" class="d-block rounded-bottom-2 width-fit" style="max-height:640px;" alt="iOS模拟器中区块编辑器集成测试演示视频"></video>
|
||
|
||
### Android 集成测试
|
||
|
||
**创建新的虚拟设备**，需与 [packages/react-native-editor/**device-tests**/helpers/caps.js](https://github.com/WordPress/gutenberg/blob/trunk/packages/react-native-editor/__device-tests__/helpers/caps.js#L30) 中指定的设备参数匹配。截至本文撰写时，需使用 Pixel 3 XL 镜像配合 Android 9（API 28）系统。
|
||
|
||
首先启动虚拟设备：点击手机图标进入 AVD 管理器，然后点击绿色启动按钮。
|
||
|
||
<img src="https://developer.wordpress.org/files/2021/10/adv-integration.png" width="700px" alt="启动Android模拟器的操作截图">
|
||
|
||
确保没有 Metro 进程正在运行（之前通过 `npm run native start:reset` 启动）。
|
||
|
||
然后在终端中运行：
|
||
|
||
```sh
|
||
npm run native test:e2e:android:local
|
||
```
|
||
|
||
通过指定文件名可运行部分测试用例：
|
||
|
||
```
|
||
npm run native test:e2e:android:local gutenberg-editor-paragraph.test.js
|
||
```
|
||
|
||
稍等片刻后应显示：
|
||
|
||
<img src="https://developer.wordpress.org/files/2021/10/CleanShot-2021-10-27-at-15.28.22.png" width="700px" alt="Android模拟器中区块编辑器集成测试截图">
|
||
|
||
# React Native 开发环境配置指南（macOS 版）
|
||
|
||
是否对移动端原生编辑器开发感兴趣？本指南将手把手带您完成开发环境配置！
|
||
|
||
请注意，本文说明主要针对 macOS 环境。若需配置其他环境，请参考 [React Native 快速入门文档](https://reactnative.dev/docs/environment-setup) 获取相关指引和步骤。
|
||
|
||
## 克隆 Gutenberg 项目
|
||
|
||
```sh
|
||
git clone git@github.com:WordPress/gutenberg.git
|
||
```
|
||
|
||
### 安装 node 与 npm
|
||
|
||
若您同时参与多个 JS 项目，建议使用 node 版本管理器。管理器可让您自由切换不同的 node 和 npm 版本。
|
||
|
||
我们推荐使用 [nvm](https://github.com/nvm-sh/nvm)。
|
||
|
||
安装 nvm 后，在克隆项目的根目录下执行：
|
||
|
||
```sh
|
||
nvm install 'lts/*'
|
||
nvm alias default 'lts/*' # 设置为新终端打开时的默认版本
|
||
nvm use # 切换至项目配置版本
|
||
```
|
||
|
||
随后安装依赖：
|
||
|
||
```
|
||
npm ci
|
||
```
|
||
|
||
### 已有旧版 Gutenberg 代码？
|
||
|
||
若您已持有 Gutenberg 代码，请务必彻底清理 `node_modules` 并重新安装依赖。
|
||
这将有助于避免后续出现错误。
|
||
|
||
```sh
|
||
npm run distclean
|
||
npm ci
|
||
```
|
||
|
||
## iOS 环境配置
|
||
|
||
### CocoaPods 依赖管理
|
||
|
||
需要安装 [CocoaPods](https://guides.cocoapods.org/using/getting-started.html) 来获取 React 及第三方依赖。安装步骤因 Ruby 管理方式而异。
|
||
|
||
#### 系统自带 Ruby
|
||
|
||
若使用 MacOS 默认 Ruby，需通过 `sudo` 命令安装 Cocoapods：
|
||
|
||
```
|
||
sudo gem install cocoapods
|
||
```
|
||
|
||
注意：Mac M1 芯片与 Cocoapods 存在兼容性问题。若遇安装问题，可尝试执行以下命令安装 ffi 包（确保以正确架构安装 pods）：
|
||
|
||
```
|
||
sudo arch -x86_64 gem install ffi
|
||
arch -x86_64 pod install
|
||
```
|
||
|
||
#### Ruby 版本管理器
|
||
|
||
若使用 Ruby 版本管理器，可能无需手动安装 Cocoapods 或 `ffi` 包。请参照所选管理器的文档进行操作。
|
||
|
||
若需在 [WordPress iOS 应用](https://github.com/wordpress-mobile/WordPress-iOS) 中运行 Gutenberg（而非仅演示应用），推荐使用 [`rbenv`](https://github.com/rbenv/rbenv) 管理器。
|
||
|
||
### 配置 Xcode
|
||
|
||
通过 App Store 安装 [Xcode](https://developer.apple.com/xcode/) 后启动：
|
||
|
||
- 接受许可协议
|
||
- 确认 `Xcode > 偏好设置 > 位置 > 命令行工具` 指向当前 Xcode 版本
|
||
|
||
<img src="https://developer.wordpress.org/files/2021/10/xcode-command-line-tools.png" width="700px" alt="Xcode 命令行工具设置界面截图">
|
||
|
||
### 环境诊断工具
|
||
|
||
可通过 [react-native doctor](https://reactnative.dev/blog/2019/11/18/react-native-doctor) 检测开发环境缺失项。在 Gutenberg 项目根目录或 `/packages/react-native-editor` 文件夹内运行：
|
||
|
||
```sh
|
||
npx @react-native-community/cli doctor
|
||
```
|
||
|
||
<img src="https://developer.wordpress.org/files/2021/10/react-native-doctor.png" width="700px" alt="终端中运行的 react-native-community/cli doctor 工具截图">
|
||
|
||
尝试让 `doctor` 工具修复所有“通用”和“iOS”问题（此时“Android”项显示❌无需担心，后续会处理！）
|
||
|
||
### 运行演示应用
|
||
|
||
当所有通用和 iOS 问题解决后，尝试运行：
|
||
|
||
```
|
||
npm run native start:reset # 启动 metro 打包器
|
||
```
|
||
|
||
另开终端窗口执行：
|
||
|
||
```
|
||
npm run native ios
|
||
```
|
||
|
||
等待构建完成后，演示应用将在 iOS 模拟器中运行：
|
||
|
||
<img src="https://developer.wordpress.org/files/2021/10/iOS-Simulator.png" width="700px" alt="iOS 模拟器中的区块编辑器运行截图" />
|
||
|
||
## Android 环境配置
|
||
|
||
### Java开发工具包（JDK）
|
||
|
||
[React Native文档](https://reactnative.dev/docs/environment-setup)推荐的JDK名为Azul Zulu。可通过[Homebrew](https://brew.sh/)安装。安装Homebrew后，在终端执行以下命令：
|
||
|
||
```
|
||
brew tap homebrew/cask-versions
|
||
brew install --cask zulu11
|
||
```
|
||
|
||
若系统已安装JDK，需确保版本为JDK 11或更高。
|
||
|
||
### 配置Android Studio
|
||
|
||
编译Android应用需先[下载Android Studio](https://developer.android.com/studio)。
|
||
|
||
打开现有项目，选择已克隆的Gutenberg文件夹。
|
||
|
||
点击下图高亮的立方体图标进入SDK管理器，也可通过`工具 > SDK管理器`进入：
|
||
|
||
<img src="https://developer.wordpress.org/files/2021/10/react-native-package-manager.png" width="700px" alt="Android Studio中包管理器按钮位置示意图">
|
||
|
||
在此界面可下载SDK平台、软件包及其他工具。需勾选“显示包详细信息”查看特定版本，因为构建过程对E2E测试和开发环境有特定版本要求：
|
||
|
||
<img src="https://developer.wordpress.org/files/2021/10/react-native-show-package-details.png" width="700px" alt="Android Studio包管理器界面，突出显示包详细信息复选框">
|
||
|
||
根据[build.gradle](https://github.com/WordPress/gutenberg/blob/trunk/packages/react-native-editor/android/build.gradle)勾选所有相关软件包，点击“应用”开始下载。node_modules中的build.gradle文件可能包含其他依赖项。
|
||
|
||
若不想逐行查阅文件，系统会在堆栈跟踪中提示缺失包，但此方法需多次尝试。
|
||
|
||
<img src="https://developer.wordpress.org/files/2021/10/react-native-editor-build-gradle.png" width="700px" alt="build.gradle配置文件截图">
|
||
|
||
<img src="https://developer.wordpress.org/files/2021/10/react-native-sdk.png" width="700px" alt="包管理器显示SDK平台界面">
|
||
|
||
<img src="https://developer.wordpress.org/files/2021/10/react-native-sdk-tools.png" width="700px" alt="包管理器显示SDK工具界面">
|
||
|
||
### 更新路径配置
|
||
|
||
导出以下环境变量并更新$PATH。若终端使用zsh可添加到`~/.zshrc`文件，若使用bash则添加到`~/.bash_profile`：
|
||
|
||
```sh
|
||
### Android Studio自带的Java：
|
||
export JAVA_HOME=/Applications/Android\ Studio.app/Contents/jre/Contents/Home
|
||
### Android Home可在Android Studio中配置：偏好设置 > 系统设置 > Android SDK
|
||
export ANDROID_HOME=$HOME/Library/Android/sdk
|
||
export PATH=$PATH:$ANDROID_HOME/emulator
|
||
export PATH=$PATH:$ANDROID_HOME/tools
|
||
export PATH=$PATH:$ANDROID_HOME/tools/bin
|
||
export PATH=$PATH:$ANDROID_HOME/platform-tools
|
||
```
|
||
|
||
保存后执行source命令或重启终端使配置生效：
|
||
|
||
```sh
|
||
source ~/.zshrc
|
||
```
|
||
|
||
或
|
||
|
||
```sh
|
||
source ~/.bash_profile
|
||
```
|
||
|
||
若找不到SDK路径，可通过Android Studio > 偏好设置 > 系统设置 > Android SDK验证位置：
|
||
|
||
<img src="https://developer.wordpress.org/files/2021/10/sdk-path.png" width="700px" alt="Android Studio中SDK路径定位示意图">
|
||
|
||
### 创建设备镜像
|
||
|
||
点击右下角带Android标识的手机图标创建虚拟设备镜像：
|
||
|
||
<img src="https://developer.wordpress.org/files/2021/10/react-native-android-device-manager-button.png" width="700px" alt="Android设备管理器按钮位置示意图">
|
||
|
||
进入“Android虚拟设备管理器(AVD)”，点击“创建虚拟设备”，选择手机类型：
|
||
|
||
<img src="https://developer.wordpress.org/files/2021/10/react-native-android-select-hardware.png" width="700px" alt="虚拟设备配置界面截图">
|
||
|
||
选择目标SDK版本（对应[build.gradle](https://github.com/WordPress/gutenberg/blob/trunk/packages/react-native-editor/android/build.gradle)中的targetSdkVersion设置）：
|
||
|
||
<img src="https://developer.wordpress.org/files/2021/10/react-native-adv-system-image.png" width="700px" alt="设备管理器中选择系统镜像界面">
|
||
|
||
可根据需要调整高级设置（可选），最后点击完成。 |