`
### `wp-class` 指令
该指令根据布尔值为 HTML 元素添加或移除类名。其语法格式为 `data-wp-class--classname`。
```html
选项 1
选项 2
```
查看与上述指令配合使用的存储模块
```js
store( 'myPlugin', {
actions: {
toggleSelection: () => {
const context = getContext();
context.isSelected = ! context.isSelected;
},
},
} );
```
`wp-class` 指令在以下情况执行：
- 元素创建时
- 每当影响指令最终值的 `state` 或 `context` 属性发生变化时（在回调函数或传递的引用表达式中）
指令接收的布尔值用于切换 `class` 属性中的关联类名（值为 `true` 时添加，值为 `false` 时移除）。
需要注意：使用 `wp-class` 指令时，推荐使用短横线命名法而非驼峰命名法。因为 HTML 属性不区分大小写，`data-wp-class--isDark`、`data-wp-class--isdark` 和 `DATA-WP-CLASS--ISDARK` 在 HTML 中会被视为相同属性。
因此，建议使用 `is-dark` 替代 `isDark`，使用 `data-wp-class--is-dark` 替代 `data-wp-class--isDark`：
```html
```
```css
/* 推荐用法 */
.is-dark {
/* ... */
}
/* 不推荐用法 */
.isDark {
/* ... */
}
```
### `wp-style` 指令
该指令根据值为 HTML 元素添加或移除内联样式。其语法格式为 `data-wp-style--css-property`。
```html
```
查看与上述指令配合使用的存储模块
```js
store( 'myPlugin', {
actions: {
toggleContextColor: () => {
const context = getContext();
context.color = context.color === 'red' ? 'blue' : 'red';
},
},
} );
```
`wp-style` 指令在以下情况执行：
- 元素创建时
- 每当影响指令最终值的 `state` 或 `context` 属性发生变化时（在回调函数或传递的引用表达式中）
指令接收的值用于添加或移除包含对应 CSS 属性的样式属性：
- 值为 `false` 时移除样式属性：`
`
- 值为字符串时添加样式属性并赋值：`
`
### `wp-run` 指令
该指令会在**节点渲染执行期间**运行传入的回调函数。
您可以在传入的回调中使用并组合诸如 `useState`、`useWatch` 或 `useEffect` 之类的钩子，创建自己的逻辑，相比之前的指令提供了更大的灵活性。
您可以通过 `data-wp-run--[唯一标识符]` 语法在同一个 DOM 元素上附加多个 `wp-run` 指令。
`唯一标识符` 不需要全局唯一，只需与该 DOM 元素上其他 `wp-run` 指令的唯一标识符不同即可。
```html
```
查看与上述指令配合使用的存储
```js
import {
getElement,
store,
useState,
useEffect,
} from '@wordpress/interactivity';
// 与 `data-wp-init` 和 `data-wp-watch` 不同，您可以在 `data-wp-run` 回调中使用任何钩子。
const useInView = () => {
const [ inView, setInView ] = useState( false );
useEffect( () => {
const { ref } = getElement();
const observer = new IntersectionObserver( ( [ entry ] ) => {
setInView( entry.isIntersecting );
} );
observer.observe( ref );
return () => ref && observer.unobserve( ref );
}, [] );
return inView;
};
store( 'myPlugin', {
callbacks: {
logInView: () => {
const isInView = useInView();
useEffect( () => {
if ( isInView ) {
console.log( '在视口内' );
} else {
console.log( '在视口外' );
}
} );
},
},
} );
```
需要注意的是，与 (P)React 组件类似，在首次渲染期间，`getElement()` 返回的 `ref` 为 `null`。要正确访问 DOM 元素引用，通常需要使用类似效果的钩子，如 `useEffect`、`useInit` 或 `useWatch`。这确保了 `getElement()` 在组件挂载后运行，并且 `ref` 可用。
### `wp-key` 指令
`wp-key` 指令为元素分配一个唯一键，以帮助交互式 API 在遍历元素数组时识别它。如果您的数组元素可能移动（例如，由于排序）、插入或删除，这一点就变得很重要。选择恰当的键值有助于交互式 API 推断数组中具体发生了哪些变化，从而使其能够正确更新 DOM。
键应是一个字符串，用于在兄弟元素中唯一标识该元素。通常，它用于重复元素，如列表项。例如：
```html
```
但它也可以用于其他元素：
```html
```
当列表重新渲染时，交互式 API 将通过元素的键进行匹配，以确定是否添加/删除/重新排序了项目。没有键的元素可能会不必要地重新创建。
### `wp-each` 指令
`wp-each` 指令用于渲染元素列表。该指令可以在 `
` 标签中使用，其值是存储在全局状态或上下文中的数组的路径。`` 标签内的内容是用于渲染每个项目的模板。
默认情况下，每个项目都包含在上下文中的 `item` 名称下，因此模板内的指令可以访问当前项目。
例如，考虑以下 HTML。
```html
```
它将生成以下输出：
```html
```
可以通过向指令名称添加后缀来更改上下文中保存项目的属性。在以下示例中，默认属性从 `item` 更改为 `greeting`。
```html
```
默认情况下，它使用每个元素作为渲染节点的键，但如果需要，您也可以指定一个路径来检索键，例如当列表包含对象时。
为此，您必须在 `` 标签中使用 `data-wp-each-key`，而不是在模板内容中使用 `data-wp-key`。这是因为 `data-wp-each` 会为每个渲染的项目创建一个上下文提供者包装器，而这些包装器需要 `key` 属性。
```html
```
### `wp-each-child`
针对服务端渲染的列表，另一项名为 `data-wp-each-child` 的指令可确保水合过程按预期工作。该指令在服务器端处理指令时会自动添加。
```html
```
## 指令的值是对存储属性的引用
分配给指令的值是一个指向特定状态、操作或副作用的字符串。
在以下示例中，使用 getter 定义了派生值 `state.isPlaying`。
```js
const { state } = store( 'myPlugin', {
state: {
currentVideo: '',
get isPlaying() {
return state.currentVideo !== '';
},
},
} );
```
然后，字符串值 `"state.isPlaying"` 用于将此选择器的结果分配给 `data-wp-bind--hidden`。
```html
```
分配给指令的这些值是存储中特定属性的**引用**。它们会自动与指令关联，使每个指令“知道”其引用的存储元素，无需任何额外配置。
请注意，默认情况下，引用指向当前命名空间中的属性，该命名空间由具有 `data-wp-interactive` 属性的最近祖先指定。如果需要访问不同命名空间中的属性，可以显式设置属性所在的命名空间。语法为 `namespace::reference`，将 `namespace` 替换为适当的值。
以下示例从 `otherPlugin` 获取 `state.isPlaying`，而不是 `myPlugin`：
```html
```
## 存储
存储用于创建与指令关联的逻辑（操作、副作用等）以及该逻辑中使用的数据（状态、派生状态等）。
**存储通常在每个块的 `view.js` 文件中创建**，但状态可以从块的 `render.php` 文件初始化。
### 存储的组成部分
#### 状态
它定义了页面 HTML 节点可用的数据。重要的是区分两种定义数据的方式：
- **全局状态**：使用带有 `state` 属性的 `store()` 函数定义，数据可供页面的所有 HTML 节点使用。
- **上下文/局部状态**：使用 HTML 节点中的 `data-wp-context` 指令定义，数据可供该 HTML 节点及其子节点使用。可以在操作、派生状态或副作用中使用 `getContext` 函数访问它。
```html
```
```js
const { state } = store( 'myPlugin', {
state: {
someText: 'Hello Universe!',
},
actions: {
someAction: () => {
state.someText; // 访问或修改全局状态 - "Hello Universe!"
const context = getContext();
context.someText; // 访问或修改局部状态（上下文） - "Hello World!"
},
},
} );
```
#### 操作
操作只是普通的 JavaScript 函数。通常由 `data-wp-on` 指令（使用事件监听器）或其他操作触发。
```ts
const { state, actions } = store( 'myPlugin', {
actions: {
selectItem: ( id ) => {
const context = getContext();
// `id` 在此处是可选的，因此该操作可以在指令中使用。
state.selected = id || context.id;
},
otherAction: () => {
// 但它也可以从其他操作中调用。
actions.selectItem( 123 ); // 可以正常工作且类型正确
},
},
} );
```
异步操作
异步操作应使用生成器而不是 async/await。
在异步函数中，控制权交给函数本身。函数的调用者无法知道函数是否在等待，更重要的是，等待是否已解决以及函数是否已恢复执行。我们需要这些信息才能恢复作用域。
假设一个块有两个按钮。一个位于 `isOpen: true` 的上下文中，另一个位于 `isOpen: false` 的上下文中：
```html
```
如果操作是异步的并且需要等待较长时间：
- 用户点击第一个按钮。
- 作用域指向第一个上下文，其中 `isOpen: true`。
- 第一次访问 `state.isOpen` 是正确的，因为 `getContext` 返回当前作用域。
- 操作开始等待较长时间。
- 在操作恢复之前，用户点击第二个按钮。
- 作用域切换到第二个上下文，其中 `isOpen: false`。
- 第一次访问 `state.isOpen` 是正确的，因为 `getContext` 返回当前作用域。
- 第二个操作开始等待较长时间。
- 第一个操作完成等待并恢复执行。
- 第一个操作的第二次访问 `state.isOpen` 是错误的，因为 `getContext` 现在返回了错误的作用域。
我们需要能够知道异步操作何时开始等待和恢复操作，以便恢复正确的作用域，这正是生成器的作用。
如果存储按以下方式编写，它将正常工作：
```js
const { state } = store( 'myPlugin', {
state: {
get isOpen() {
return getContext().isOpen;
},
},
actions: {
someAction: function* () {
state.isOpen; // 此上下文是正确的，因为它是同步的。
yield longDelay(); // 使用生成器，调用者控制何时恢复此函数。
state.isOpen; // 此上下文是正确的，因为我们在恢复函数之前恢复了正确的作用域。
},
},
} );
```
如果操作需要处理大量工作，您可能需要在操作中添加多个这样的 `yield` 点。
如上文关于 [`wp-on`](#wp-on)、[`wp-on-window`](#wp-on-window) 和 [`wp-on-document`](#wp-on-document) 所述，当由于操作需要同步访问 `event` 对象而无法使用上述指令的 `async` 版本时，应使用异步操作。当操作需要调用 `event.preventDefault()`、`event.stopPropagation()` 或 `event.stopImmediatePropagation()` 时，需要同步访问。
为确保操作代码不会导致长任务，您可以在调用同步事件 API 后手动让出主线程。Interactivity API 为此提供了 `splitTask()` 函数，它以跨浏览器兼容的方式实现让出。以下是一个示例：
```js
import { splitTask } from '@wordpress/interactivity';
store( 'myPlugin', {
actions: {
handleClick: withSyncEvent( function* ( event ) {
event.preventDefault();
yield splitTask();
doTheWork();
} ),
},
} );
```
您可能会注意到此示例中使用了 [`withSyncEvent()`](#withsyncevent) 工具函数。这是必要的，因为正在进行的努力是将存储操作默认异步处理，除非它们需要同步事件访问（此示例由于调用了 `event.preventDefault()` 而需要）。否则将触发弃用警告，并在未来的版本中相应更改行为。