124 lines
8.2 KiB
Markdown
124 lines
8.2 KiB
Markdown
# 交互性 API 参考
|
||
|
||
交互性 API [随 WordPress 6.5 版本推出](https://make.wordpress.org/core/2024/02/19/merge-announcement-interactivity-api/)，为开发者提供了一种标准化的方式，用于为区块前端添加交互功能。该 API 已被应用于多个 WordPress 核心区块，包括搜索、查询、导航和文件区块。
|
||
|
||
这一标准让开发者能够更轻松地创建丰富的交互式用户体验——从简单的计数器或弹窗，到即时页面导航、即时搜索、购物车或结算等复杂功能。
|
||
|
||
区块之间可以共享数据、操作和回调函数，这使得区块间的通信更加简便且不易出错。例如：点击“加入购物车”区块时，可以无缝更新独立的“购物车”区块。
|
||
|
||
如需了解交互性 API 的诞生背景，请查阅[原始提案](https://make.wordpress.org/core/2023/03/30/proposal-the-interactivity-api-a-better-developer-experience-in-building-interactive-blocks/)。您也可以查看[合并公告](https://make.wordpress.org/core/2024/02/19/merge-announcement-interactivity-api/)、[状态更新日志](https://make.wordpress.org/core/2023/08/15/status-update-on-the-interactivity-api/)及官方 [Trac 工单](https://core.trac.wordpress.org/ticket/60356)。
|
||
|
||
<div class="callout callout-info">
|
||
交互性 API 由 <a href="https://developer.wordpress.org/block-editor/reference-guides/packages/packages-interactivity/"><code>@wordpress/interactivity</code></a> 软件包提供支持，该包已从 WordPress 6.5 开始内置核心
|
||
</div>
|
||
|
||
## 交互性 API 文档导航
|
||
|
||
通过以下链接快速定位您感兴趣的内容。若初次接触交互性 API，建议按顺序阅读以下资源：
|
||
|
||
- **[环境要求](#交互性-api-的环境要求)**：开始使用交互性 API 创建交互区块前请查阅本节
|
||
- **[快速入门指南](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/iapi-quick-start-guide/)**：一分钟内快速创建使用交互性 API 的自定义区块
|
||
- **[教程：初探交互性 API](https://developer.wordpress.org/news/2024/04/11/a-first-look-at-the-interactivity-api/)**：通过 [WordPress 开发者博客](https://developer.wordpress.org/news/)的这篇文章快速入门
|
||
- **[核心概念](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/core-concepts/)**：深入理解交互性 API 开发的相关概念与思维模型
|
||
- **[API 参考](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/api-reference/)**：深入探索 API 内部机制、指令列表及状态存储工作原理
|
||
- **[文档与示例](#文档与示例)**：了解更多交互性 API 的延伸资源
|
||
|
||
如需深入理解交互性 API 或解答相关疑问，请查阅：
|
||
|
||
- **[关于交互性 API](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/iapi-about/)**：了解 API 设计目标及采用标准化方案实现区块交互性的核心理念
|
||
- **[常见问题解答](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/iapi-faq/)**：获取技术原理及替代方案的相关解答
|
||
|
||
## 交互性 API 的环境要求
|
||
|
||
交互性 API 已集成至 WordPress 6.5 核心版本。对于更低版本，需安装并启用 Gutenberg 17.5 或更高版本。
|
||
|
||
需要特别说明的是，区块创建工作流程保持不变，所有[环境准备要求](https://developer.wordpress.org/block-editor/getting-started/devenv/)依然适用，包括：
|
||
|
||
- [代码编辑器](https://developer.wordpress.org/block-editor/getting-started/devenv/#code-editor)
|
||
- [Node.js 开发工具](https://developer.wordpress.org/block-editor/getting-started/devenv/#node-js-development-tools)
|
||
- [本地 WordPress 环境](https://developer.wordpress.org/block-editor/getting-started/devenv/#local-wordpress-environment)
|
||
|
||
当您完成区块开发环境配置并运行 WordPress 6.5+（或 Gutenberg 17.5+）后，即可开始创建交互功能。
|
||
|
||
### 代码要求
|
||
|
||
#### 为项目添加交互功能
|
||
|
||
通过以下命令将交互性 API 安装到项目中：
|
||
|
||
```bash
|
||
npm install @wordpress/interactivity --save
|
||
```
|
||
|
||
将存储库导入到 `view.js` 中。更多信息请参阅[存储库文档](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/api-reference/#the-store)。
|
||
|
||
```js
|
||
import { store } from '@wordpress/interactivity';
|
||
```
|
||
|
||
#### 为 `block.json` 添加交互功能支持
|
||
|
||
为了表明区块[支持](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/)交互性 API 功能，请在区块的 `block.json` 文件的 `supports` 属性中添加 `"interactivity": true`。
|
||
|
||
```json
|
||
// block.json
|
||
"supports": {
|
||
"interactivity": true
|
||
},
|
||
```
|
||
|
||
有关此属性的详细说明，请参阅[交互性支持属性文档](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#interactivity)。
|
||
|
||
#### 使用 `viewScriptModule` 加载交互性 API JavaScript 代码
|
||
|
||
交互性 API 提供了 `@wordpress/interactivity` 脚本模块。使用交互性 API 的 JavaScript 应实现为脚本模块，以便它们可以依赖于 `@wordpress/interactivity`。[自 WordPress 6.5 起，脚本模块已可用](https://make.wordpress.org/core/2024/03/04/script-modules-in-6-5/)。区块可以使用 [`viewScriptModule` 区块元数据](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#view-script-module)轻松排队加载其脚本模块：
|
||
|
||
```json
|
||
// block.json
|
||
{
|
||
...
|
||
"viewScriptModule": "file:./view.js"
|
||
}
|
||
```
|
||
|
||
使用 `viewScriptModule` 还需要在 `wp-scripts` 的 [`build`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/#build) 和 [`start`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/#start) 脚本中添加 `--experimental-modules` 标志，以确保脚本模块正确构建。
|
||
|
||
```json
|
||
// 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`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-interactivity/packages-interactivity-api-reference/#wp-interactive) 指令。
|
||
|
||
```html
|
||
<div data-wp-interactive="myPlugin">
|
||
<!-- 交互性 API 区域 -->
|
||
</div>
|
||
```
|
||
|
||
有关此指令的详细说明，请参阅 [`wp-interactive` 文档](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/api-reference/#wp-interactive)。
|
||
|
||
## 文档与示例
|
||
|
||
以下是一些关于交互性 API 的更多学习资源：
|
||
|
||
- [WordPress 6.5 开发说明](https://make.wordpress.org/core/2024/03/04/interactivity-api-dev-note/)
|
||
- [合并公告](https://make.wordpress.org/core/2024/02/19/merge-announcement-interactivity-api/)
|
||
- [提案：交互性 API——构建交互式区块的更好开发体验](https://make.wordpress.org/core/2023/03/30/proposal-the-interactivity-api-a-better-developer-experience-in-building-interactive-blocks/)
|
||
- [交互性 API 讨论](https://github.com/WordPress/gutenberg/discussions/52882)，特别是[展示](https://github.com/WordPress/gutenberg/discussions/55642#discussioncomment-9667164)讨论。
|
||
- [wpmovies.dev](https://wpmovies.dev/) 演示及其 [wp-movies-demo](https://github.com/WordPress/wp-movies-demo) 仓库
|
||
- 在 [block-development-examples](https://github.com/WordPress/block-development-examples) 中使用交互性 API 的示例：
|
||
- [`my-first-interactive-block`](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/my-first-interactive-block)
|
||
- [`interactivity-api-countdown-3cd73e`](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/interactivity-api-countdown-3cd73e)
|
||
- [`interactivity-api-quiz-1835fa`](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/interactivity-api-quiz-1835fa)
|
||
|
||
<div class="callout">
|
||
已开启一个跟踪问题，以便协调与交互性 API 文档相关的工作：<a href="https://github.com/WordPress/gutenberg/issues/53296">交互性 API 文档 - 跟踪问题 #53296</a>
|
||
</div> |