# 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)。