# 交互性 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>