@wordpress/element 详解

@wordpress/element 是 WordPress 官方提供的轻量级 React 抽象层，专门为 WordPress 区块编辑器（Gutenberg）和其他 WordPress JavaScript 应用设计。它提供 React 的核心功能，同时深度集成 WordPress 生态系统。

核心功能

1. React Hooks 支持

useState - 状态管理

import { useState } from '@wordpress/element';

const [state, setState] = useState(initialValue);

在 ActivityPub 项目中的使用示例：

// 反应区块的状态管理
const [isOpen, setIsOpen] = useState(false);
const [buttonRef, setButtonRef] = useState(null);

// 关注者区块的状态管理
const [followers, setFollowers] = useState([]);
const [loading, setLoading] = useState(true);

useEffect - 副作用处理

import { useEffect } from '@wordpress/element';

useEffect(() => {
  // 副作用逻辑
  return () => {
    // 清理逻辑
  };
}, [dependencies]);

在 ActivityPub 项目中的使用示例：

// 数据获取副作用
useEffect(() => {
  if (providedReactions) {
    setReactions(providedReactions);
    setLoading(false);
    return;
  }

  if (!postId || typeof postId !== 'number') {
    onError();
    return;
  }

  setLoading(true);
  apiFetch({
    path: `/\({namespace}/posts/\){postId}/reactions`,
  })
    .then((response) => {
      // 处理响应数据
      setReactions(response);
      setLoading(false);
    })
    .catch(onError);
}, [postId, providedReactions, fallbackReactions, namespace]);

useRef - DOM 引用

import { useRef } from '@wordpress/element';

const ref = useRef(initialValue);

在 ActivityPub 项目中的使用示例：

// 容器引用用于弹出层定位
const containerRef = useRef(null);

useMemo - 记忆化计算

import { useMemo } from '@wordpress/element';

const memoizedValue = useMemo(() => computeExpensiveValue(a, b), [a, b]);

2. JSX 渲染支持

@wordpress/element 提供完整的 JSX 语法支持，与 WordPress 组件系统无缝集成：

import { useState } from '@wordpress/element';
import { Button, Popover } from '@wordpress/components';

const ReactionGroup = ({ items, label }) => {
  const [isOpen, setIsOpen] = useState(false);
  
  return (
    <div className="reaction-group">
      <Button
        className="reaction-label is-link"
        onClick={() => setIsOpen(!isOpen)}
        aria-expanded={isOpen}
      >
        {label}
      </Button>
      {isOpen && (
        <Popover onClose={() => setIsOpen(false)}>
          {/* 弹出内容 */}
        </Popover>
      )}
    </div>
  );
};

3. 工具函数

createInterpolateElement - 创建带插值的 React 元素

这个函数专门用于处理包含 HTML 标签的翻译字符串：

import { createInterpolateElement } from '@wordpress/element';
import { __ } from '@wordpress/i18n';

const text = __(
  'This <strong>Follow Me</strong> block will adapt to the page it is on.',
  'activitypub'
);

const element = createInterpolateElement(text, { 
  strong: <strong /> 
});

在 ActivityPub 项目中的实际应用：

// src/shared/inherit-block-fallback.js
const text = sprintf(
  __(
    'This <strong>%1\(s block will adapt to the page it is on...',
    'activitypub'
  ),
  name
);

return (
  
    {createInterpolateElement(text, { strong:  })}
  
);
```

## 设计目的和优势

### 1. 依赖管理

- **版本控制**: 避免直接依赖 React，便于 WordPress 核心统一管理 React 版本
- **稳定性**: 提供稳定的 API 接口，即使底层 React 版本升级也不会破坏现有代码
- **兼容性**: 确保与 WordPress 核心和其他插件的兼容性

### 2. WordPress 深度集成

- **组件系统**: 与 `@wordpress/components` 无缝集成
- **国际化**: 内置支持 `@wordpress/i18n` 系统
- **数据管理**: 与 `@wordpress/data` 状态管理集成
- **API 交互**: 与 `@wordpress/api-fetch` 配合使用

### 3. 性能优化

- **轻量级**: 只包含必要的 React 功能，减少包大小
- **针对性优化**: 针对 WordPress 使用场景进行性能优化
- **树摇优化**: 支持现代打包工具的树摇优化

## 在 ActivityPub 项目中的具体应用

### 1. 状态管理

**关注者区块 (`src/followers/edit.js`):**
```javascript
import { useState, useEffect } from '@wordpress/element';

const Edit = ({ attributes, setAttributes }) => {
  const [followers, setFollowers] = useState([]);
  const [loading, setLoading] = useState(true);
  
  // 状态管理逻辑...
};
```

### 2. 副作用处理

**反应区块 (`src/reactions/reactions.js`):**
```javascript
useEffect(() => {
  if (providedReactions) {
    setReactions(providedReactions);
    setLoading(false);
    return;
  }
  
  // 异步数据获取逻辑
  apiFetch({
    path: `/\){namespace}/posts/\({postId}/reactions`,
  })
    .then(setReactions)
    .catch(onError);
}, [postId, providedReactions]);
```

### 3. 用户交互

**关注我区块 (`src/follow-me/edit.js`):**
```javascript
import { useEffect, useState } from '@wordpress/element';

const Edit = ({ attributes, setAttributes }) => {
  const [isModalOpen, setIsModalOpen] = useState(false);
  
  const openModal = () => setIsModalOpen(true);
  const closeModal = () => setIsModalOpen(false);
  
  // 模态框交互逻辑...
};
```

### 4. 国际化插值

**继承模式回退组件 (`src/shared/inherit-block-fallback.js`):**
```javascript
import { createInterpolateElement } from '@wordpress/element';
import { sprintf, __ } from '@wordpress/i18n';

const text = sprintf(
  __(
    'This %1\)s</strong> block will adapt to the page it is on...',
    'activitypub'
  ),
  name
);

return createInterpolateElement(text, { strong: <strong /> });

// 推荐：按需导入
import { useState, useEffect, useRef } from '@wordpress/element';

// 不推荐：全部导入
import * as Element from '@wordpress/element';

// 推荐：清晰的依赖数组
useEffect(() => {
  // 副作用逻辑
}, [userId, postId]);

// 不推荐：缺少依赖或依赖不完整
useEffect(() => {
  // 副作用逻辑
}, []);

// 推荐：相关状态分组
const [userData, setUserData] = useState({
  followers: [],
  following: [],
  loading: true
});

// 不推荐：分散的状态
const [followers, setFollowers] = useState([]);
const [following, setFollowing] = useState([]);
const [loading, setLoading] = useState(true);