95 lines
5.1 KiB
Markdown
95 lines
5.1 KiB
Markdown
# 使用 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/)（官方文档） |