148 lines
6.5 KiB
Markdown
148 lines
6.5 KiB
Markdown
# React Native 版移动端 Gutenberg 入门指南
|
||
|
||
欢迎阅读！本文档是针对 Android 和 iOS 设备的区块编辑器原生移动端移植版的入门指南。总体而言，这是一个可在全新项目或现有项目中使用的 React Native 库。请继续阅读了解如何构建、测试和运行。
|
||
|
||
## 环境准备
|
||
|
||
为了获得与项目维护者相近的开发体验，请确保安装以下工具：
|
||
|
||
- git
|
||
- [nvm](https://github.com/nvm-sh/nvm)
|
||
- Node.js 和 npm（使用 nvm 安装）
|
||
- [Android Studio](https://developer.android.com/studio/)（用于编译 Android 版应用）
|
||
- [Xcode](https://developer.apple.com/xcode/)（用于编译 iOS 应用）
|
||
- CocoaPods（通过 `sudo gem install cocoapods` 安装）用于获取 React 及第三方依赖
|
||
|
||
请注意，维护者使用的操作系统平台是 macOS，但相关工具和设置也应适用于其他平台。
|
||
|
||
## 克隆项目
|
||
|
||
```sh
|
||
git clone https://github.com/WordPress/gutenberg.git
|
||
```
|
||
|
||
## 环境设置
|
||
|
||
请注意，此处描述的命令应在克隆项目的顶层目录中运行。在运行演示应用之前，需要下载并安装项目依赖。通过以下命令完成：
|
||
|
||
```sh
|
||
nvm install
|
||
npm ci
|
||
npm run native preios
|
||
```
|
||
|
||
## 运行项目
|
||
|
||
```sh
|
||
npm run native start:reset
|
||
```
|
||
|
||
该命令将在开发模式下运行打包程序（Metro）。打包程序会持续运行，向请求的客户端提供应用包。
|
||
|
||
在打包程序运行的同时，打开另一个终端窗口，使用以下命令编译并运行 Android 应用：
|
||
|
||
```sh
|
||
npm run native android
|
||
```
|
||
|
||
此时应用应在连接的设备或运行的模拟器中打开，并从正在运行的打包程序获取 JavaScript 代码。
|
||
|
||
要使用默认模拟器设备编译并运行 iOS 版本的应用，请使用：
|
||
|
||
```sh
|
||
npm run native ios
|
||
```
|
||
|
||
如果您使用的是 Mac 并已安装相关环境，该命令将尝试在 iOS 模拟器中打开您的应用。
|
||
|
||
### 在其他 iOS 设备模拟器上运行
|
||
|
||
要使用其他设备模拟器编译并运行应用，请使用以下命令。注意使用双 `--` 将模拟器选项传递给 `react-native` CLI：
|
||
|
||
```sh
|
||
npm run native ios -- -- --simulator="设备名称"
|
||
```
|
||
|
||
例如，如果要在 iPhone Xs Max 上运行，请尝试：
|
||
|
||
```sh
|
||
npm run native ios -- -- --simulator="iPhone Xs Max"
|
||
```
|
||
|
||
要查看所有可用 iOS 设备列表，请使用 `xcrun simctl list devices`。
|
||
|
||
### 自定义演示编辑器
|
||
|
||
默认情况下，演示编辑器会渲染大多数受支持的核心区块。这有助于展示编辑器的功能，但在专注于特定区块或功能时可能会分散注意力。可以通过在 `packages/react-native-editor/src/setup-local.js` 文件中使用 `native.block_editor_props` 钩子来自定义编辑器的初始状态。
|
||
|
||
<details><summary>setup-local.js 示例</summary>
|
||
|
||
```js
|
||
/**
|
||
* WordPress 依赖
|
||
*/
|
||
import { addFilter } from '@wordpress/hooks';
|
||
|
||
export default () => {
|
||
addFilter(
|
||
'native.block_editor_props',
|
||
'core/react-native-editor',
|
||
( props ) => {
|
||
return {
|
||
...props,
|
||
initialHtml,
|
||
};
|
||
}
|
||
);
|
||
};
|
||
|
||
const initialHtml = `
|
||
<!-- wp:heading -->
|
||
<h2 class="wp-block-heading">仅一个标题</h2>
|
||
<!-- /wp:heading -->
|
||
`;
|
||
```
|
||
|
||
</details>
|
||
|
||
### 故障排除
|
||
|
||
如果 Android 模拟器无法正常启动，或编译失败并显示 `Could not initialize class org.codehaus.groovy.runtime.InvokerHelper` 或类似错误，建议根据 [React Native 文档](https://reactnative.dev/docs/environment-setup)中的最新要求仔细检查开发环境设置。例如，使用 Android Studio 时，需要配置 `ANDROID_HOME` 环境变量并确保 JDK 版本符合最新要求。
|
||
|
||
有时，特别是在调整 `package.json`、Babel 配置（`.babelrc`）或 Jest 配置（`jest.config.js`）中的任何内容时，您的更改可能似乎未按预期生效。此时，可能需要停止 Metro 打包进程并使用 `npm run native start:reset` 重新启动。其他时候，您可能需要重新安装 NPM 包，这时 `npm run native clean:install` 脚本会很有用。
|
||
|
||
## 使用 Visual Studio Code 进行开发
|
||
|
||
虽然不要求必须使用 Visual Studio Code 来开发 gutenberg-mobile，但它是推荐的 IDE，我们为其提供了一些配置。
|
||
|
||
首次在 Visual Studio 中打开项目时，系统会提示安装一些推荐的扩展。这将有助于类型检查和调试等工作。
|
||
|
||
我们使用的扩展之一是 [React Native Tools](https://marketplace.visualstudio.com/items?itemName=vsmobile.vscode-react-native)。它允许您从 VSCode 运行打包程序，或在 iOS 或 Android 上启动应用程序。它还添加了一些调试配置，以便您可以直接在 VSCode 中设置断点和调试应用程序。有关更多详细信息，请参阅[扩展文档](https://marketplace.visualstudio.com/items?itemName=vsmobile.vscode-react-native)。
|
||
|
||
## 单元测试
|
||
|
||
使用以下命令运行测试套件：
|
||
|
||
```sh
|
||
npm run test:native
|
||
```
|
||
|
||
该命令将在您的测试上运行 [jest](https://github.com/facebook/jest) 测试运行器。测试在桌面上针对 Node.js 运行。
|
||
|
||
要在调试器支持下运行测试，请使用以下 CLI 命令启动：
|
||
|
||
```sh
|
||
npm run test:native:debug
|
||
```
|
||
|
||
然后，在 Chrome 中打开 `chrome://inspect` 以附加调试器（查看“远程目标”部分）。在测试/开发过程中，可以随意在代码中的任何位置添加 `debugger` 语句，以便在调试器中中断。
|
||
|
||
## 编写和运行单元测试
|
||
|
||
本项目配置使用 [jest](https://jestjs.io/) 进行测试。您可以配置任何喜欢的测试策略，但 jest 可以开箱即用。在名为 `__tests__` 的目录中创建测试文件，或使用 `.test.js` 扩展名，以便 jest 加载这些文件。请参阅[此处的示例测试](https://github.com/WordPress/gutenberg/blob/HEAD/packages/react-native-editor/src/test/api-fetch-setup.test.js)。[jest 文档](https://jestjs.io/docs/getting-started)和 [React Native 测试教程](https://jestjs.io/docs/tutorial-react-native)也是极好的资源。
|
||
|
||
## 端到端测试
|
||
|
||
除了单元测试之外，Mobile Gutenberg（MG）项目还依赖端到端（E2E）测试，在类似于最终用户的环境中自动化测试关键流程。我们通常更倾向于单元测试，因为它们速度快且易于维护。但是，对于需要操作系统级功能（例如复杂手势、文本选择）或视觉回归测试（例如深色模式、对比度级别）的断言，我们使用 E2E 测试。
|
||
|
||
E2E 测试位于 [`packages/react-native-editor/__device-tests__`](/packages/react-native-editor/__device-tests__) 目录中。有关运行和贡献这些测试的其他文档，请参阅[测试目录](/packages/react-native-editor/__device-tests__#readme)。 |