94 lines
6.4 KiB
Markdown
94 lines
6.4 KiB
Markdown
# 区块编辑器中的JavaScript开发
|
||
|
||
为区块编辑器开发区块通常涉及使用现代JavaScript（ESNext和JSX），本手册中的大多数示例都采用这些语法编写。
|
||
|
||
然而，这种形式的JavaScript必须转换为浏览器兼容的格式，因此需要构建步骤。这个过程会将JavaScript源代码及相关资源进行转换、打包和优化，最终生成适用于生产环境的格式。
|
||
|
||
## 使用构建流程的JavaScript开发
|
||
|
||
采用构建流程进行区块开发能充分发挥现代JavaScript的潜力，便于使用ESNext和JSX。
|
||
|
||
[ESNext](https://developer.mozilla.org/en-US/docs/Web/JavaScript/JavaScript_technologies_overview#standardization_process) 指的是JavaScript的最新语法和特性。[JSX](https://react.dev/learn/writing-markup-with-jsx) 是React项目开发的语法扩展，允许您编写类似HTML的JavaScript代码。
|
||
|
||
由于浏览器无法直接执行ESNext和JSX，这些语法必须转换为浏览器兼容的JavaScript。
|
||
|
||
[webpack](https://webpack.js.org/concepts/why-webpack/) 是一个可插拔工具，用于处理和打包JavaScript以实现浏览器兼容性。[Babel](https://babeljs.io/) 作为webpack的插件，能够将ESNext和JSX转换为标准JavaScript。
|
||
|
||
配置webpack和Babel可能具有挑战性，因此建议使用 [`@wordpress/scripts`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/) 工具包。该工具通过预配置两者来简化开发，您通常无需编写自定义的webpack或Babel配置。
|
||
|
||
入门指南请参阅 [wp-scripts入门指南](/docs/getting-started/devenv/get-started-with-wp-scripts.md)。
|
||
|
||
### `wp-scripts`概览
|
||
|
||
下图概述了使用`wp-scripts`工具包时的构建流程。该工具专为开发和生产环境的[标准配置](/docs/getting-started/devenv/get-started-with-wp-scripts.md#basic-usage)设计，开箱即用。
|
||
|
||
[](https://developer.wordpress.org/files/2023/11/build-process.png "打开构建流程图")
|
||
|
||
- **生产模式 (`npm run build`):** 在此模式下，`wp-scripts`会编译JavaScript并对输出进行压缩，以减小文件大小并提升浏览器加载速度。这非常适合将代码部署至生产环境。
|
||
|
||
- **开发模式 (`npm start`):** 此模式专为活跃开发定制。它会跳过压缩以便于调试，生成源码映射以优化错误追踪，并监听源文件变更。当检测到更改时，会自动重建受影响文件，让您可以实时查看更新。
|
||
|
||
`wp-scripts`工具包还支持使用JavaScript模块，允许代码分布在多个文件中，并在构建流程后生成精简的打包文件。[block-development-example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/data-basics-59c8f8) GitHub代码库提供了一些优秀示例。
|
||
|
||
<div class="callout callout-tip">
|
||
大多数情况下无需自定义配置，但您可以在使用<code>wp-scripts</code>时提供<a href="https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/#provide-your-own-webpack-config"><code>webpack.config.js</code></a>文件来调整构建流程以满足需求。
|
||
</div>
|
||
|
||
## 无构建流程的JavaScript开发
|
||
|
||
在某些特定场景下，无需构建流程即可将JavaScript集成到WordPress项目中可能是最直接的方法。这对于不涉及JSX或其他需要编译的高级JavaScript特性的项目尤为适用。
|
||
|
||
当您选择不使用构建流程时，需通过全局`wp`对象直接与WordPress的[JavaScript API](/docs/reference-guides/packages.md)进行交互。这意味着WordPress提供的所有方法和工具包都立即可用，但需要注意：您必须手动管理脚本依赖关系。这需要将每个对应工具包的[句柄](/docs/contributors/code/scripts.md)添加到您入队JavaScript文件的依赖数组中。
|
||
|
||
例如，假设您正在创建一个使用[`blocks`](/packages/blocks/README.md)工具包中的`registerBlockVariation`函数来注册新[区块变体](/docs/reference-guides/block-api/block-variations.md)的脚本。您必须在脚本的依赖数组中包含`wp-blocks`。这能确保在脚本执行时，`wp.blocks.registerBlockVariation`方法可用且已定义。
|
||
|
||
以下示例展示了在入队`variations.js`文件时定义`wp-blocks`依赖项：
|
||
|
||
```php
|
||
function example_enqueue_block_variations() {
|
||
wp_enqueue_script(
|
||
'example-enqueue-block-variations',
|
||
get_template_directory_uri() . '/assets/js/variations.js',
|
||
array( 'wp-blocks' ),
|
||
wp_get_theme()->get( 'Version' ),
|
||
false
|
||
);
|
||
}
|
||
add_action( 'enqueue_block_editor_assets', 'example_enqueue_block_variations' );
|
||
```
|
||
|
||
然后在`variations.js`文件中，您可以像这样为"媒体与文本"区块注册新变体：
|
||
|
||
```js
|
||
wp.blocks.registerBlockVariation(
|
||
'core/media-text',
|
||
{
|
||
name: 'media-text-custom',
|
||
title: '自定义媒体与文本',
|
||
attributes: {
|
||
align: 'wide',
|
||
backgroundColor: 'tertiary'
|
||
},
|
||
}
|
||
);
|
||
```
|
||
|
||
对于需要在区块编辑器中运行的脚本，请确保使用[`enqueue_block_editor_assets`](https://developer.wordpress.org/reference/hooks/enqueue_block_editor_assets/)钩子配合标准的[`wp_enqueue_script`](https://developer.wordpress.org/reference/functions/wp_enqueue_script/)函数。
|
||
|
||
更多信息请参阅[在编辑器中加载资源](/docs/how-to-guides/enqueueing-assets-in-the-editor.md)。
|
||
|
||
<div class="callout callout-tip">
|
||
在编辑文章或使用站点编辑器时，打开浏览器开发者工具并在控制台中尝试运行<code>wp.data.select('core/editor').getBlocks()</code>。此命令将返回所有可用区块。
|
||
</div>
|
||
|
||
## 扩展资源
|
||
|
||
- [工具包参考](/docs/reference-guides/packages.md)
|
||
- [wp-scripts入门指南](/docs/getting-started/devenv/get-started-with-wp-scripts.md)
|
||
- [在编辑器中加载资源](/docs/how-to-guides/enqueueing-assets-in-the-editor.md)
|
||
- [WordPress工具包句柄](/docs/contributors/code/scripts.md)
|
||
- [JavaScript参考](https://developer.mozilla.org/en-US/docs/Web/JavaScript) | MDN Web文档
|
||
- [block-development-examples](https://github.com/WordPress/block-development-examples) | GitHub代码库
|
||
- [block-theme-examples](https://github.com/wptrainingteam/block-theme-examples) | GitHub代码库
|
||
- [webpack与WordPress工具包的交互原理](https://developer.wordpress.org/news/2023/04/how-webpack-and-wordpress-packages-interact/) | 开发者博客
|
||
- [构建流程图](https://excalidraw.com/#json=4aNG9JUti3pMnsfoga35b,ihEAI8p5dwkpjWr6gQmjuw) |