@wordpress/element-WordPress区块编辑器手册-果果开发

Element 是一个基于 React 构建的包，提供了一套用于处理 React 组件和 React 元素的实用工具。

安装

安装该模块

npm install @wordpress/element --save

此包假设您的代码将在 ES2015+ 环境中运行。如果您使用的环境对这类语言特性和 API 支持有限或完全不支持，您应该在代码中包含 @wordpress/babel-preset-default 随附的 polyfill。

为什么选择 React？

冒着引发关于任何单一“最佳”前端框架的争论的风险，使用任何工具的选择都应具体地服务于系统的需求。在建模区块（block）的概念时，我们观察到以下技术要求：

从其底层值（在随机图像示例中，即一个类别）的角度理解区块
一种根据这些值描述区块 UI 的方法

在最基本的层面上，React 提供了一个简单的输入/输出机制。给定一组输入（“props”），开发者描述要在页面上显示的输出。这在它的函数组件中可以最优雅地观察到。React 的作用是协调期望的输出与页面当前状态之间的关系。

随着这些需求的增加，任何框架的功能必然变得更加复杂；许多前端框架规定了关于页面路由、检索和更新数据以及管理布局的理念。React 也不例外，但引入的复杂性很少是由 React 本身引起的，而是由管理一系列支持工具的安排引起的。通过将这些问题转移到系统内部（WordPress 核心代码）的视线之外，我们可以将插件作者的责任最小化为一组小而清晰的接触点。

API

Children

提供用于处理 React 子元素（children）的实用工具的对象的集合。

cloneElement

创建一个带有扩展 props 的元素副本。

参数

element Element: 元素
props ?Object: 应用于克隆元素的 Props

Element: 克隆后的元素。

Component

用于创建 WordPress 组件（Refs、state 和生命周期钩子）的基础类。

concatChildren

连接两个或多个 React 子元素对象。

参数

childrenArguments ReactNode[][]: – 要连接的子元素参数数组（数组/字符串/对象的数组）。

ReactNode[]: 连接后的值。

createContext

创建一个包含两个组件的上下文对象：一个 provider 和一个 consumer。

参数

defaultValue Object: 存储在上下文中的默认数据。

Object: 上下文对象。

createElement

返回给定类型的新元素。类型可以是字符串标签名称，也可以是另一个返回元素的函数。

参数

type ?(string|Function): 标签名或元素创建器
props Object: 元素属性，要么是应用于 DOM 节点的属性集，要么是要传递给元素创建器的值
children ...Element: 后代元素

Element: 元素。

createInterpolateElement

此函数根据传入的字符串创建插值元素，其中特定标签与字符串如何通过转换映射值转换为元素相匹配。

用法

例如，对于给定的字符串：

“This is a string with a link and a self-closing
tag”

作为 conversionMap 的值，您可能会得到类似这样的内容：

{
    span: <span />,
    a: <a href={ 'https://github.com' } />,
    CustomComponentB: <CustomComponent />,
}

参数

interpolatedString Input: 要解析的插值字符串。
conversionMap ConversionMap< InterpolationString< Input > >: 用于将字符串转换为 React 元素的映射。

ReactElement: 一个 wp 元素。

createPortal

创建一个门户，组件可以在其中渲染。

相关

https://react.dev/reference/react-dom/createPortal

createRef

返回一个对象，通过其 current 属性跟踪对已渲染元素的引用，该属性可以是 DOMElement 或 Element，具体取决于使用 ref 属性渲染的元素类型。

Object: Ref 对象。

createRoot

为目标 DOM 节点创建一个新的 React 根。

相关

https://react.dev/reference/react-dom/client/createRoot

更改日志

6.2.0 在 WordPress 核心中引入。

findDOMNode

查找 React 组件的 dom 节点。

参数

component React.ComponentType: 组件实例。

flushSync

强制 React 同步刷新提供的回调内的任何更新。

相关

https://react.dev/reference/react-dom/flushSync

forwardRef

用于启用将 ref 传递到其包装组件的组件增强器。传递一个函数参数，该参数接收 props 和 ref 作为其参数，返回使用转发的 ref 的元素。返回值是一个转发其 ref 的新组件。

参数

forwarder Function: 传递 props 和 ref 的函数，预期返回一个元素。

Component: 增强后的组件。

Fragment

一个渲染其子元素而不带任何包装元素的组件。

hydrate

已弃用 自 WordPress 6.2.0 起。请改用 hydrateRoot。

将给定元素水合（hydrate）到目标 DOM 节点中。

相关

https://react.dev/reference/react-dom/hydrate

hydrateRoot

为目标 DOM 节点创建一个新的 React 根，并使用预生成的标记对其进行水合。

相关

https://react.dev/reference/react-dom/client/hydrateRoot

更改日志

6.2.0 在 WordPress 核心中引入。

isEmptyElement

检查提供的 WP 元素是否为空。

参数

element unknown: 要检查的 WP 元素。

boolean: 当元素被视为空时为 True。

isValidElement

检查对象是否是有效的 React 元素。

参数

objectToCheck Object: 要检查的对象。

boolean: 如果 objectToTest 是有效的 React 元素则返回 true，否则返回 false。

lazy

相关

https://react.dev/reference/react/lazy

memo

相关

https://react.dev/reference/react/memo

Platform

用于检测当前正在使用的平台的组件。使用 Platform.OS === 'web' 来检测是否在 Web 环境中运行。

以下是如何使用 select 方法的示例：

用法

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

const placeholderLabel = Platform.select( {
    web: __(
        'Drag images, upload new ones or select files from your library.'
    ),
    default: __( 'Add media' ),
} );

PureComponent

相关

https://react.dev/reference/react/PureComponent

RawHTML

用于渲染未转义 HTML 的组件。

注意：renderElement 序列化程序将移除 div 包装器，除非存在非 children props；通常是在准备保存区块时。

用法

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

const Component = () => (
    <RawHTML>
        <h3>Hello world</h3>
    </RawHTML>
);
// Edit: <div><h3>Hello world</h3></div>
// save: <h3>Hello world</h3>

参数