8.2 KiB
交互性 API 参考
交互性 API 随 WordPress 6.5 版本推出，为开发者提供了一种标准化的方式，用于为区块前端添加交互功能。该 API 已被应用于多个 WordPress 核心区块，包括搜索、查询、导航和文件区块。
这一标准让开发者能够更轻松地创建丰富的交互式用户体验——从简单的计数器或弹窗，到即时页面导航、即时搜索、购物车或结算等复杂功能。
区块之间可以共享数据、操作和回调函数，这使得区块间的通信更加简便且不易出错。例如：点击“加入购物车”区块时，可以无缝更新独立的“购物车”区块。
如需了解交互性 API 的诞生背景，请查阅原始提案。您也可以查看合并公告、状态更新日志及官方 Trac 工单。
@wordpress/interactivity 软件包提供支持，该包已从 WordPress 6.5 开始内置核心
交互性 API 文档导航
通过以下链接快速定位您感兴趣的内容。若初次接触交互性 API，建议按顺序阅读以下资源：
- 环境要求：开始使用交互性 API 创建交互区块前请查阅本节
- 快速入门指南：一分钟内快速创建使用交互性 API 的自定义区块
- 教程：初探交互性 API：通过 WordPress 开发者博客的这篇文章快速入门
- 核心概念：深入理解交互性 API 开发的相关概念与思维模型
- API 参考：深入探索 API 内部机制、指令列表及状态存储工作原理
- 文档与示例：了解更多交互性 API 的延伸资源
如需深入理解交互性 API 或解答相关疑问，请查阅：
交互性 API 的环境要求
交互性 API 已集成至 WordPress 6.5 核心版本。对于更低版本，需安装并启用 Gutenberg 17.5 或更高版本。
需要特别说明的是，区块创建工作流程保持不变，所有环境准备要求依然适用，包括：
当您完成区块开发环境配置并运行 WordPress 6.5+（或 Gutenberg 17.5+）后，即可开始创建交互功能。
代码要求
为项目添加交互功能
通过以下命令将交互性 API 安装到项目中：
npm install @wordpress/interactivity --save
将存储库导入到 view.js 中。更多信息请参阅存储库文档。
import { store } from '@wordpress/interactivity';
为 block.json 添加交互功能支持
为了表明区块支持交互性 API 功能，请在区块的 block.json 文件的 supports 属性中添加 "interactivity": true。
// block.json
"supports": {
"interactivity": true
},
有关此属性的详细说明，请参阅交互性支持属性文档。
使用 viewScriptModule 加载交互性 API JavaScript 代码
交互性 API 提供了 @wordpress/interactivity 脚本模块。使用交互性 API 的 JavaScript 应实现为脚本模块，以便它们可以依赖于 @wordpress/interactivity。自 WordPress 6.5 起，脚本模块已可用。区块可以使用 viewScriptModule 区块元数据轻松排队加载其脚本模块：
// block.json
{
...
"viewScriptModule": "file:./view.js"
}
使用 viewScriptModule 还需要在 wp-scripts 的 build 和 start 脚本中添加 --experimental-modules 标志，以确保脚本模块正确构建。
// package.json
{
"scripts": {
...
"build": "wp-scripts build --experimental-modules",
"start": "wp-scripts start --experimental-modules"
}
向 DOM 元素添加 wp-interactive 指令
要在 DOM 元素（及其子元素）中“激活”交互性 API，请在区块的 render.php 或 save.js 文件中向 DOM 元素添加 wp-interactive 指令。
<div data-wp-interactive="myPlugin">
<!-- 交互性 API 区域 -->
</div>
有关此指令的详细说明，请参阅 wp-interactive 文档。
文档与示例
以下是一些关于交互性 API 的更多学习资源：
- WordPress 6.5 开发说明
- 合并公告
- 提案：交互性 API——构建交互式区块的更好开发体验
- 交互性 API 讨论，特别是展示讨论。
- wpmovies.dev 演示及其 wp-movies-demo 仓库
- 在 block-development-examples 中使用交互性 API 的示例：