title: "关于交互性 API" post_status: publish comment_status: open taxonomy: category: - gutenberg-docs post_tag: - Interactivity Api - Reference Guides - Repos

关于交互性 API

交互性 API 是一套基于声明式代码的指令标准系统，用于为区块添加前端交互功能。

指令通过特殊属性扩展 HTML，告知交互性 API 将指定行为附加到 DOM 元素甚至对其进行转换。对于熟悉 Alpine.js 的用户来说，这是类似的方法，但明确设计为与 WordPress 无缝协作。

API 目标

Interactivity API 的主要目标是为 Gutenberg 区块的前端交互提供一种标准且简单的处理方式。

标准化使开发者能够更轻松地创建丰富的交互式用户体验，从简单的计数器或弹窗，到更复杂的功能，如即时页面导航、即时搜索或购物车和结账流程。

目前，即使没有 Interactivity API，所有这些用户体验在技术上都是可以实现的。然而，用户体验越复杂，区块之间的交互越多，开发者构建和维护网站的难度就越大。他们必须自行解决许多挑战。该 API 旨在为支持这类交互提供开箱即用的方法。

为解决这一挑战，Interactivity API 定义了以下要求/目标：

区块优先和 PHP 优先：该 API 必须与 PHP 和当前区块系统（包括在 WordPress 中广泛扩展的动态区块）良好协作。它必须支持服务器端渲染。服务器渲染的 HTML 与客户端水合的 HTML 必须完全相同。这对 SEO 和用户体验至关重要。
向后兼容：该 API 必须与 WordPress 钩子兼容，例如，这些钩子可能会修改服务器渲染的 HTML。它还必须与国际化和站点上现有的 JS 库（如 jQuery）兼容。
可选且可逐步采用：与上一点相关，该 API 必须保持可选。应该能够逐步采用它，这意味着不使用此 API 的交互式区块可以与使用它的区块共存。
声明式和响应式：该 API 必须使用声明式代码，监听数据变化，并仅更新依赖于该数据的 DOM 部分。
高性能：运行时必须快速且轻量，以确保最佳用户体验。
可扩展：与 WordPress 注重可扩展性一样，这个新系统必须提供可扩展模式以覆盖大多数用例。
原子化和可组合：需要拥有可重用的微小部分，这些部分可以组合起来创建更复杂的系统，以构建灵活且可扩展的解决方案。
与现有区块开发工具兼容：该 API 必须与现有的区块构建工具集成，无需开发者进行额外的工具配置或设置。

除了所有这些要求之外，在任何解决方案之上集成客户端导航都应该简单且高效。客户端导航是在网站页面之间导航而不重新加载整个页面的过程，这是 Web 开发者最需要的令人印象深刻的用户体验之一。因此，此功能应与这个新系统兼容。

为何选择指令？

指令是经过对不同可能性与实现方案的深入研究后得出的成果。我们发现这一设计能最高效地满足各项需求。

区块优先且 PHP 友好

该 API 专为区块世界设计，并秉承 WordPress 紧密遵循 Web 标准的历史传统。

由于指令是 HTML 属性，它们非常适合动态区块和 PHP。

动态区块示例

<div
  data-wp-interactive='wpmovies'
  <?php echo wp_interactivity_data_wp_context( array( 'isOpen' => false ) ); ?>
  data-wp-watch="callbacks.logIsOpen"
>
  <button
    data-wp-on--click="actions.toggle"
    data-wp-bind--aria-expanded="context.isOpen"
    aria-controls="p-1"
  >
    Toggle
  </button>

  <p id="p-1" data-wp-bind--hidden="!context.isOpen">
    This element is now visible!
  </p>
</div>

如您所见，像 data-wp-on--click 或 data-wp-bind--hidden 这样的指令是作为自定义 HTML 属性添加的。WordPress 可以在服务器上处理此 HTML，执行指令逻辑并生成相应的标记。

向后兼容

由于交互性 API 与服务器端渲染完美配合，您可以使用所有 WordPress API，包括：

WordPress 过滤器和操作：您可以继续使用 WordPress 钩子来修改 HTML，甚至修改指令。此外，现有钩子将按预期继续工作。
核心翻译 API：例如 __() 和 _e()。您可以用它来翻译 HTML 中的文本（像往常一样），甚至可以在指令的服务器端使用这些 API。

可选与渐进式采用

Interactivity API 管道基于 WordPress 的坚实基础和模式构建，提倡渐进式增强。

例如，包含指令的区块可以与其他（交互式或非交互式）区块共存。这意味着如果页面上有其他使用 jQuery 等框架的区块，所有功能仍将按预期工作。

使用 Interactivity API 进行全页面客户端导航时，与其他库的兼容性规则将存在例外。详见客户端导航部分。

Declarative and reactive

The Interactivity API follows an approach similar to other popular JS frameworks by separating state, actions, and callbacks and defining them declaratively. Why declaratively?

Declarative code describes what a program should do, while imperative code describes how the program should do it. Using a declarative approach, the UI automatically updates in response to changes in the underlying data. With an imperative approach, you must manually update the UI whenever the data changes. Compare the two code examples:

Imperative code

<button id="toggle-button">Toggle Element</button>
<p>This element is now visible!</p>
<script>
  const button = document.getElementById("toggle-button");

  button.addEventListener("click", () => {
    const element = document.getElementById("element");
    if(element) {
      element.remove();
    } else {
      const newElement = document.createElement("p");
      newElement.textContent = "This element is visible";
      document.body.appendChild(newElement);
    }
});
</script>

Declarative code

This is the same use case shared above but serves as an example of declarative code using this new system. The JavaScript logic is defined in the view.js file of the block, and add the directives to the markup in the render.php.

// view.js file

import { store, getContext } from "@wordpress/interactivity";

store( 'wpmovies', {
  actions: {
    toggle: () => {
      const context = getContext();
      context.isOpen = !context.isOpen;
    },
  },
});

<!-- Render.php file -->

<div
  data-wp-interactive='wpmovies'
  <?php echo wp_interactivity_data_wp_context( array( 'isOpen' => true ) ); ?>
>
  <button
    data-wp-on--click="actions.toggle"
    data-wp-bind--aria-expanded="context.isOpen"
    aria-controls="p-1"
  >
    Toggle
  </button>

  <p id="p-1" data-wp-bind--hidden="!context.isOpen">
    This element is now visible!
  </p>
</div>

Using imperative code may be easier when creating simple user experiences, but it becomes much more difficult as applications become more complex. The Interactivity API must cover all use cases, from the simplest to the most challenging. That’s why a declarative approach using directives better fits the Interactivity API.

高性能

该 API 的设计旨在实现最佳性能：

指令所需的运行时代码仅约 10 KB，且所有区块只需加载一次。
脚本加载不会阻塞页面渲染。

可扩展性

指令可以直接在 HTML 中添加、移除或修改。例如，用户可以使用 render_block 过滤器来修改 HTML 及其行为。

原子化与可组合性

每个指令控制 DOM 的一小部分，您可以组合多个指令来创建丰富、交互式的用户体验。

兼容现有区块开发工具链

该 API 可与标准区块构建工具（如 wp-scripts）开箱即用。要让 wp-scripts 正确构建使用交互性 API 的脚本模块，唯一要求是在 build 和 start 脚本中使用 --experimental-modules 标志。

客户端导航

Interactivity API 内置了为网站添加客户端导航的基础功能。此功能完全可选，但它提供了在不脱离 WordPress 渲染系统的前提下创建此类用户体验的可能性。

请访问客户端导航指南，了解更多关于如何使用 Interactivity Router 并在您的区块中实现客户端导航的信息。

Why a standard?

Blocks using the Interactivity API and interactive blocks using other approaches like jQuery can coexist, and everything will work as expected. However, the Interactivity API comes with some benefits for your interactive blocks:

Blocks can communicate with each other easily. With a standard, this communication is handled by default. When different blocks use different approaches to frontend interactivity, inter-block communication becomes more complex and almost impossible when different developers create blocks.
Composability and compatibility: You can combine interactive blocks, and nest them in structures with defined behaviors. Thanks to following the same standard, they are fully cross-compatible. If each block used a different approach to interactivity, they would likely break.
Fewer KBs will be sent to the browser. If each plugin author uses a different JS framework, more code will be loaded in the front end. If all the blocks use the same one, the code is reused.
If all the blocks on a page use this standard, site-wide features like client-side navigation can be enabled.

Additionally, with a standard, WordPress can absorb the maximum amount of complexity from the developer because it will handle most of what’s needed to create an interactive block.

Complexities absorbed by the standard

With this absorption, less knowledge is required to create interactive blocks, and developers have fewer decisions to worry about.

By adopting a standard, learning from other interactive blocks is simpler, and fosters collaboration and code reusability. As a result, the development process is leanier and friendlier to less experienced developers.

← 返回文档中心