# 交互性 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)。
## 交互性 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
```
有关此指令的详细说明，请参阅 [`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)