# 使用 create-block 快速入门

WordPress 区块编辑器的自定义区块通常通过插件注册，并由特定文件集合定义。[`@wordpress/create-block`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/) 是官方支持的脚手架工具，可快速生成创建和注册区块所需的文件结构。它能生成项目初始代码，并集成现代化的 JavaScript 构建环境（使用 [`wp-scripts`](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-scripts/)），无需额外配置。

该工具包旨在帮助开发者遵循 WordPress 最佳实践快速搭建区块开发环境。

## 快速开始

### 安装配置

请先确保计算机已安装 Node.js 和 `npm`。若未安装，请查阅 [Node.js 开发环境](https://developer.wordpress.org/block-editor/getting-started/devenv/nodejs-development-environment/)指南。

您可以在任意目录使用 `create-block` 创建区块脚手架，然后在生成的插件文件夹内[使用 `wp-env`](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-env/) 创建本地 WordPress 开发环境，该环境会自动安装并激活您的新区块插件。

若已搭建[本地 WordPress 开发环境](https://developer.wordpress.org/block-editor/getting-started/devenv/#local-wordpress-environment)，请通过终端进入 `plugins/` 目录。

执行以下命令创建示例区块插件：

```bash
npx @wordpress/create-block@latest todo-list
cd todo-list
```

其中提供的 `slug` 参数（`todo-list`）将作为插件文件夹名称和内部区块标识。

进入本地 WordPress 的插件管理页面，激活 "Todo List" 插件后，即可在编辑器中找到该示例区块。

### 基础使用

`create-block` 默认采用现代 JavaScript（ESNext 与 JSX）构建区块，这需要构建步骤将代码编译为浏览器可识别的格式。幸运的是，`wp-scripts` 工具包已自动处理此过程。关于该工具的详细介绍请参阅 [wp-scripts 入门指南](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-scripts)。

当 `create-block` 生成区块脚手架时，会自动安装 `wp-scripts` 并将常用脚本添加到区块的 `package.json` 文件中，默认包含：

```json
{
    "scripts": {
		"build": "wp-scripts build",
		"format": "wp-scripts format",
		"lint:css": "wp-scripts lint-style",
		"lint:js": "wp-scripts lint-js",
		"packages-update": "wp-scripts packages-update",
		"plugin-zip": "wp-scripts plugin-zip",
		"start": "wp-scripts start"
	}
}
```

这些脚本可通过 `npm run {脚本名称}` 命令运行。最常使用的两个脚本是 `start` 和 `build`，它们负责构建流程。

开发区块时请运行 `npm run start` 命令，这将启动开发服务器并在检测到代码变更时自动重新构建。

准备部署区块时请运行 `npm run build` 命令，该命令会对代码进行优化并生成生产环境版本。

各脚本的详细说明请参阅 `wp-scripts` 的[工具包文档](https://developer.wordpress.org/block-editor/packages/packages-scripts/)。

## 其他实现方式

### 交互模式

为偏好引导式操作的开发者，`create-block` 提供了交互模式。此模式会逐步提示输入配置参数，无需像前文示例那样手动预先指定 `slug` 等所有选项。

运行以下命令启用此模式：

```bash
npx @wordpress/create-block@latest
```

根据提示逐步完成区块设置即可。

### 快速启动模式（选项参数）

若您已熟悉 `create-block` 的[选项参数](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/#options)并希望快速完成配置，可使用快速启动模式。通过命令行直接传递特定参数，省去交互提示步骤。

例如，要快速创建命名空间为 "my-plugin"、区块标识为 "my-block" 的动态区块，可使用：

```bash
npx @wordpress/create-block@latest --namespace="my-plugin" --slug="my-block" --variant="dynamic"
```

### 使用模板

`create-block` 支持模板功能，允许基于预定义配置和结构创建区块。当您有特定区块结构偏好，或需构建多个相似配置的区块时，此功能尤为实用。

使用模板时，需通过 `--template` 选项指定模板名称或路径：
```bash
npx @wordpress/create-block --template="my-custom-template"
```

模板需预先设置以确保 `create-block` 能正确识别。更多细节请参阅 `create-block` 的[模板文档](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/#template)，并查阅[外部项目模板指南](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/packages-create-block-external-template/)。

## 扩展资源

- [使用 create-block 工具](https://learn.wordpress.org/tutorial/using-the-create-block-tool/)（Learn WordPress 教程）
- [@wordpress/create-block](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/)（官方文档）
- [@wordpress/scripts](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/)（官方文档）