150 lines
8.3 KiB
Markdown
150 lines
8.3 KiB
Markdown
### 高级配置
|
||
|
||
虽然 `wp-scripts` 提供了可靠的默认配置，但在某些情况下可能需要更专业的设置。好消息是 `wp-scripts` 具有高度适应性。例如，您可以扩展和覆盖默认的 webpack 配置，从而能够添加加载器和插件，或修改构建流程的几乎所有环节。这种灵活性确保当项目规模扩大或需求变化时，`wp-scripts` 能够根据您不断变化的需求进行定制。
|
||
|
||
有关所有配置选项，请参阅 `wp-scripts` 的[包文档](https://developer.wordpress.org/block-editor/packages/packages-scripts/)。
|
||
|
||
## 扩展资源
|
||
|
||
- [@wordpress/scripts](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/)（官方文档）
|
||
- [webpack 与 WordPress 包的交互机制](https://developer.wordpress.org/news/2023/04/how-webpack-and-wordpress-packages-interact/)（WordPress 开发者博客）
|
||
|
||
# 开始使用 wp-scripts
|
||
|
||
[`@wordpress/scripts`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/) 包（通常简称为 `wp-scripts`）是一组配置文件和脚本，主要旨在标准化和简化需要 JavaScript 构建步骤的 WordPress 项目的开发流程。
|
||
|
||
JavaScript 构建步骤指的是将 JavaScript 源代码和相关资源转换、打包并优化为适合生产环境格式的过程。这些构建步骤通常会将现代 JavaScript（ESNext 和 JSX）转换为与大多数浏览器兼容的版本，还可以将多个文件打包成一个，通过代码压缩减小文件大小，并执行各种其他任务来优化代码。
|
||
|
||
在为区块编辑器开发时，您通常会使用 ESNext 和 JSX，区块编辑器手册中的所有示例都采用这些语法。学习如何设置构建步骤至关重要，但配置 [webpack](https://webpack.js.org/)、[Babel](https://babeljs.io/) 和 [ESLint](https://eslint.org/) 等必要工具可能变得复杂。这正是 `wp-scripts` 的用武之地。
|
||
|
||
以下是 `wp-scripts` 能够实现的功能：
|
||
|
||
- **代码编译：** 使用 Babel 将现代 JavaScript（ESNext 和 JSX）转换为与大多数浏览器兼容的代码
|
||
- **资源打包：** 使用 webpack 将多个 JavaScript 文件合并为单一包以提升性能
|
||
- **代码检查：** 提供 ESLint 配置，帮助确保代码质量并符合编码规范
|
||
- **代码格式化：** 集成 Prettier 实现自动化代码风格统一，保持项目间代码格式一致性
|
||
- **Sass 编译：** 将 Sass（.scss 或 .sass）文件转换为标准 CSS
|
||
- **代码压缩：** 为生产环境缩减 JavaScript 代码体积，确保更快的页面加载速度
|
||
|
||
该软件包封装了现代 WordPress JavaScript 开发中大量初始设置、配置和样板代码，让您可以专注于构建区块和区块编辑器扩展功能。
|
||
|
||
## 快速开始
|
||
|
||
<div class="callout callout-tip">
|
||
如果您使用 <a href="https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-create-block/"><code>@wordpress/create-block</code></a> 包来搭建创建和注册区块所需的文件结构，您将同时获得现代化的 JavaScript 构建设置（使用 <code>wp-scripts</code>）且无需任何配置，因此无需担心安装 <code>wp-scripts</code> 或注册资源。详细信息请参阅<a href="https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-create-block/">开始使用 <code>create-block</code></a>。
|
||
</div>
|
||
|
||
### 安装步骤
|
||
|
||
请确保计算机已安装 Node.js 和 `npm`。若未安装，请查阅 [Node.js 开发环境](https://developer.wordpress.org/block-editor/getting-started/devenv/nodejs-development-environment/)指南。
|
||
|
||
接着创建项目文件夹，确保其中包含 `package.json` 文件、`build` 文件夹和 `src` 文件夹。`src` 文件夹内还需包含 `index.js` 文件。
|
||
|
||
如果尚未创建 `package.json` 文件，请在终端中进入项目文件夹并运行 `npm init` 命令。交互式提示将引导您完成设置步骤。您可以按需配置，但当询问 "entry point"（入口点）时，请输入 `build/index.js`。
|
||
|
||
当然，使用 `wp-scripts` 设置项目有多种方式，但这是区块编辑器手册全程推荐的实践方案。
|
||
|
||
最后，通过以下命令将 `wp-scripts` 包安装为开发依赖项：
|
||
|
||
```bash
|
||
npm install @wordpress/scripts --save-dev
|
||
```
|
||
|
||
安装完成后，您的项目文件夹结构应如下所示：
|
||
|
||
```bash
|
||
示例项目文件夹/
|
||
├── build/
|
||
├── node_modules/ (自动生成)
|
||
├── src/
|
||
│ └── index.js
|
||
├── package-lock.json (自动生成)
|
||
└── package.json
|
||
```
|
||
|
||
### 基础用法
|
||
|
||
安装完成后，您可以通过在 `package.json` 文件的脚本部分引用 `wp-scripts` 提供的预定义脚本来运行它们。以下是一个示例：
|
||
|
||
```json
|
||
{
|
||
"scripts": {
|
||
"start": "wp-scripts start",
|
||
"build": "wp-scripts build"
|
||
}
|
||
}
|
||
```
|
||
|
||
随后可以使用 `npm run {脚本名称}` 命令来运行这些脚本。
|
||
|
||
### 使用 `wp-scripts` 的构建流程
|
||
|
||
您最常使用的两个脚本是 `start` 和 `build`，因为它们负责构建步骤。有关所有选项，请参阅[包文档](https://developer.wordpress.org/block-editor/packages/packages-scripts/)。
|
||
|
||
在开发项目时，使用 `npm run start` 命令。这将启动开发服务器，并在检测到任何更改时自动重新构建项目。请注意，`build/index.js` 中的编译代码不会被优化。
|
||
|
||
当您准备部署项目时，使用 `npm run build` 命令。这会优化您的代码，使其适合生产环境。
|
||
|
||
构建完成后，您将看到在 `build/index.js` 中创建的编译后的 JavaScript 文件。
|
||
|
||
构建过程中还会生成一个 `build/index.asset.php` 文件，其中包含依赖项数组和一个版本号（用于缓存清除）。请注意，如果没有使用 `wp-scripts` 构建流程注册块，您需要手动创建 `*.asset.php` 依赖文件（参见[示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/minimal-block-no-build-e621a6)）。
|
||
|
||
### 加载资源
|
||
|
||
如果您通过 `register_block_type` 注册块，`block.json` 中定义的脚本将自动加载（参见[示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/minimal-block-ca6eda)）。
|
||
|
||
要在编辑器或其他上下文中手动加载文件，可以参考[在编辑器中加载资源](https://developer.wordpress.org/block-editor/how-to-guides/enqueueing-assets-in-the-editor/)指南获取更多信息。以下是一个典型的实现示例：
|
||
|
||
```php
|
||
/**
|
||
* 加载编辑器资源。
|
||
*/
|
||
function example_project_enqueue_editor_assets() {
|
||
$asset_file = include( plugin_dir_path( __FILE__ ) . 'build/index.asset.php');
|
||
|
||
wp_enqueue_script(
|
||
'example-editor-scripts',
|
||
plugins_url( 'build/index.js', __FILE__ ),
|
||
$asset_file['dependencies'],
|
||
$asset_file['version']
|
||
);
|
||
}
|
||
add_action( 'enqueue_block_editor_assets', 'example_project_enqueue_editor_assets' );
|
||
```
|
||
|
||
这里有一个在编辑器中手动加载文件的[示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/data-basics-59c8f8)。
|
||
|
||
## 后续步骤
|
||
|
||
虽然 `start` 和 `build` 是两个最常用的脚本，但 `wp-scripts` 还提供了其他几个有用的工具，值得探索。以下是一些示例。
|
||
|
||
### 保持代码质量
|
||
|
||
为了帮助开发者提高代码质量，`wp-scripts` 预配置了 ESLint 和 Prettier 等工具。ESLint 确保您的 JavaScript 遵循最佳实践和 [WordPress 编码标准](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/)，而 Prettier 会自动格式化您的代码。可用的脚本包括：
|
||
|
||
```json
|
||
{
|
||
"scripts": {
|
||
"format": "wp-scripts format",
|
||
"lint:css": "wp-scripts lint-style",
|
||
"lint:js": "wp-scripts lint-js",
|
||
}
|
||
}
|
||
```
|
||
|
||
定期对代码进行格式化和检查可以确保代码功能正常、清晰且易于维护，无论是您自己还是其他开发者都能受益。
|
||
|
||
### 运行测试
|
||
|
||
除了编写代码，验证其功能也至关重要。`wp-scripts` 包含了 [Jest](https://jestjs.io/)（一个 JavaScript 测试框架）以及端到端测试和单元测试脚本：
|
||
|
||
```json
|
||
{
|
||
"scripts": {
|
||
"test:e2e": "wp-scripts test-e2e",
|
||
"test:unit": "wp-scripts test-unit-js"
|
||
}
|
||
}
|
||
```
|
||
|
||
单元测试验证代码的独立单元（例如函数）是否按预期工作，而端到端测试通过模拟真实用户场景来评估整个项目，确保系统的所有部分无缝协作。 |