@wordpress/rich-text

该模块包含一些辅助函数，用于将 HTML 或 DOM 树转换为富文本值并反向转换，以及使用类似于 String 方法的函数来修改该值，此外还包含一些用于格式化的附加函数。

安装

安装该模块

npm install @wordpress/rich-text

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

用法

Rich Text 包旨在辅助操作纯文本字符串，使其能够表示复杂格式。

通过使用 RichTextValue 值对象（下文简称 value），可以将文本与格式分离，从而便于搜索和操作富文本格式。

富文本格式的示例包括：

• 粗体、斜体、上标（等）
• 链接
• 无序/有序列表

RichTextValue 对象

该值对象由以下部分组成：

• text – 要应用富文本格式的文本字符串。
• formats – 一个与 text 长度相同的稀疏数组，在文本被格式化的位置填充 格式（例如 core/link、core/bold 等）。
• start – text 中的一个索引，表示当前活动选区的起始位置。
• end – text 中的一个索引，表示当前活动选区的结束位置。

你不应该尝试自行创建 value 对象，而应依靠 @wordpress/rich-text 包的内置方法来为你构建这些对象。

理解值如何表示富文本格式非常重要。下面通过一个示例进行说明。

如果 text 的位置 2-5 被格式化为粗体（core/bold），位置 2-8 被设置为链接（core/link），那么你会发现：

• 在稀疏数组的位置 2-5 处，包含 core/bold 格式的数组
• 在稀疏数组的位置 2-8 处，包含 core/link 格式的数组

示例如下：

{
  text: 'Hello world', // 长度 11
  formats: [
    [], // 0
    [],
    [ // 2
      {
        type: 'core/bold',
      },
      {
        type: 'core/link',
      }
    ],
    [
      {
        type: 'core/bold',
      },
      {
        type: 'core/link',
      }
    ],
    [
      {
        type: 'core/bold',
      },
      {
        type: 'core/link',
      }
    ],
    [
      {
        type: 'core/bold',
      },
      {
        type: 'core/link',
      }
    ],
    [ // 6
      {
        type: 'core/link',
      }
    ]
    [
      {
        type: 'core/link',
      }
    ],
    [
      {
        type: 'core/link',
      }
    ],
    [], // 9
    [], // 10
    [], // 11
  ]
}

选区

让我们继续考虑上面文本为 Hello world 的示例。

如果作为用户，我选择了单词 Hello，则会生成一个 start 和 end 分别为 0 和 5 的值对象。

通常，这有助于了解文本的哪一部分被选中。然而，我们需要考虑选区也可能是“折叠”的。

折叠选区

折叠选区是指 start 和 end 值相同的选区（例如 start: 4, end: 4）。这种情况发生在没有选择任何字符但存在插入符时。最常见的情形是用户将光标/插入符放置在文本字符串中但未进行选择。

由于选区没有“范围”（即 start 和 end 索引之间没有差异），因此从折叠值中查找当前选中的文本部分可能具有挑战性。

API

applyFormat

从给定的 startIndex 到给定的 endIndex，将格式对象应用到富文本值。如果未提供索引，则从选区中获取索引。

参数

• value RichTextValue：要修改的值。
• format RichTextFormat：要应用的格式。
• startIndex [number]：起始索引。
• endIndex [number]：结束索引。

返回值

• RichTextValue：应用该格式后的新值。

concat

将所有富文本值合并为一个。这类似于 String.prototype.concat。

参数

• values ...RichTextValue：要合并的对象。

返回值

• RichTextValue：合并所有给定记录后的新值。

create

从 Element 树（DOM）、HTML 字符串或纯文本字符串创建 RichText 值，并可选地通过 Range 对象设置选区。如果未提供任何输入就调用，将创建一个空值。可选函数可用于过滤内容。

值将具有以下结构，强烈建议不要在不使用辅助函数的情况下修改它：

{
  text: string,
  formats: Array,
  replacements: Array,
  ?start: number,
  ?end: number,
}

如你所见，文本和格式是分离的。text 保存文本，包括对象和行的任何替换字符。formats、objects 和 lines 都是与 text 长度相同的稀疏数组。其中保存了相关文本索引处的格式信息。最后，start 和 end 表示选择了哪些文本索引。只有在提供了 Range 时才会提供它们。

参数

• $1 [Object]：可选命名参数。
• $1.element [Element]：用于创建值的元素。
• $1.text [string]：用于创建值的文本。
• $1.html [string]：用于创建值的 HTML。
• $1.range [Range]：用于创建值的范围。
• $1.__unstableIsEditableTree [boolean]：

返回值

• RichTextValue：富文本值。

EventListenersProps

回调集合（callback-Set）引用私有事件监听器辅助函数分发所来自的 refs。

getActiveFormat

根据类型获取选区起始位置处的格式对象。这可以用于获取例如当前选区处链接格式的 URL，也可以用于检查某个格式是否在选区处处于激活状态。如果选区处没有格式，则返回 undefined。

参数

• value RichTextValue：要检查的值。
• formatType string：要查找的格式类型。

返回值

• RichTextFormat|undefined：指定类型的激活格式对象，或 undefined。

getActiveFormats

获取选区起始位置处的所有格式对象。

参数

• value RichTextValue：要检查的值。
• EMPTY_ACTIVE_FORMATS Array：如果没有激活格式，则返回该数组。

返回值

• RichTextFormatList：激活的格式对象。

getActiveObject

获取激活的对象（如果有）。

参数

• value RichTextValue：要检查的值。

返回值

• RichTextFormat|void：激活的对象，或 undefined。

getTextContent

获取富文本值的文本内容。这类似于 Element.textContent。

参数

• value RichTextValue：要使用的值。

返回值

• string：文本内容。

insert

在给定 startIndex 处，将富文本值、HTML 字符串或纯文本字符串插入富文本值中。startIndex 和 endIndex 之间的任何内容都会被移除。如果未提供索引，则从选区中获取索引。

参数

• value RichTextValue：要修改的值。
• valueToInsert RichTextValue|string：要插入的值。
• startIndex [number]：起始索引。
• endIndex [number]：结束索引。

返回值

• RichTextValue：插入该值后的新值。

insertObject

在给定 startIndex 处，将格式作为对象插入富文本值中。startIndex 和 endIndex 之间的任何内容都会被移除。如果未提供索引，则从选区中获取索引。

参数

• value RichTextValue：要修改的值。
• formatToInsert RichTextFormat：要作为对象插入的格式。
• startIndex [number]：起始索引。
• endIndex [number]：结束索引。

返回

• RichTextValue：包含已插入对象的新值。

isCollapsed

检查富文本值的选区是否已折叠。已折叠表示没有选择任何字符，但存在光标。如果没有选区，将返回 undefined。这与 window.getSelection().isCollapsed() 类似。

参数

• props RichTextValue：要检查的富文本值。
• props.start RichTextValue[ 'start' ]：
• props.end RichTextValue[ 'end' ]：

返回

• boolean | undefined：如果选区已折叠则为 true，否则为 false；如果没有选区则为 undefined。

isEmpty

检查富文本值是否为空，即不包含任何文本或任何对象（例如图片）。

参数

• value RichTextValue：要使用的值。

返回

• boolean：如果值为空则为 true，否则为 false。

join

将一组富文本值合并为一个值，可选择使用 separator 分隔，该分隔符可以是富文本值、HTML 字符串或纯文本字符串。这与 Array.prototype.join 类似。

参数

• values Array<RichTextValue>：要合并的值数组。
• separator [string|RichTextValue]：分隔符字符串或值。

返回

• RichTextValue：新的合并值。

privateApis

私有的 @wordpress/rich-text API。

registerFormatType

注册一个新格式，需提供唯一名称以及定义其行为的对象。

参数

• name string：格式名称。
• settings Omit<WPFormat, 'name'>：格式设置。name 会从第一个参数注入。

返回

• WPFormat|undefined：如果已成功注册，则为该格式；否则为 undefined。

remove

从富文本值中移除给定 startIndex 和 endIndex 之间的内容。如果未提供索引，则从选区获取索引。

参数

• value RichTextValue：要修改的值。
• startIndex [number]：起始索引。
• endIndex [number]：结束索引。

返回

• RichTextValue：移除内容后的新值。

removeFormat

按类型从富文本值中移除从给定 startIndex 到给定 endIndex 的任何格式对象。如果未提供索引，则从选区获取索引。

参数

• value RichTextValue：要修改的值。
• formatType string：要移除的格式类型。
• startIndex [number]：起始索引。
• endIndex [number]：结束索引。

返回

• RichTextValue：移除格式后的新值。

replace

搜索富文本值，并将匹配项替换为 replacement。这与 String.prototype.replace 类似。

参数

• value RichTextValue：要修改的值。
• pattern RegExp|string：RegExp 对象或字面量。也可以是字符串。它会被视为原义字符串，不会被解释为正则表达式。只有第一个匹配项会被替换。
• replacement Function|string|RichTextValue：匹配项将被指定值、指定函数返回的值或给定的富文本值替换。

返回

• RichTextValue：应用替换后的新值。

RichTextData

RichTextData 类用于实例化富文本值的包装器，其方法可用于转换或操作数据。

• 创建一个空实例：new RichTextData()。
• 从 HTML 字符串创建：RichTextData.fromHTMLString(
'<em>hello</em>' )。
• 从包装器 HTMLElement 创建：RichTextData.fromHTMLElement(
document.querySelector( 'p' ) )。
• 从纯文本创建：RichTextData.fromPlainText( '1\n2' )。
• 从富文本值创建：new RichTextData( { text: '...',
formats: [ ... ] } )。

RichTextFormat

应用于 RichTextValue 内某个字符范围的单个格式，例如 core/bold。更多信息请参见 @wordpress/rich-text 主文档。

RichTextValue

表示格式化字符串的对象。更多信息请参见 @wordpress/rich-text 主文档。

slice

从 startIndex 到 endIndex 截取富文本值。如果未提供索引，则从选区获取索引。这与 String.prototype.slice 类似。

参数

• value RichTextValue：要修改的值。
• startIndex [number]：起始索引。
• endIndex [number]：结束索引。

返回

• RichTextValue：提取出的新值。

split

在给定 startIndex 和 endIndex 处将富文本值拆分为两个值，或在给定分隔符处拆分。这与 String.prototype.split 类似。如果未提供索引，则从选区获取索引。

参数

• value RichTextValue：
• string [number|string]：起始索引，或要拆分处的字符串。

返回

• Array<RichTextValue>|undefined：新值数组。

store

rich-text 命名空间的 Store 定义。

相关

• https://github.com/WordPress/gutenberg/blob/HEAD/packages/data/README.md#createReduxStore

类型

• Object

toggleFormat

在当前选区处切换应用到富文本值的格式对象。

参数

• value RichTextValue：要修改的值。
• format RichTextFormat：要应用或移除的格式。

返回

• RichTextValue：应用或移除格式后的新值。

toHTMLString

从富文本值创建 HTML 字符串。

参数

• $1 Object：命名参数。
• $1.value RichTextValue：富文本值。
• $1.preserveWhiteSpace [boolean]：如果为 true，则保留换行符。

返回

• string：HTML 字符串。

unregisterFormatType

注销一个格式。

参数

• name string：格式名称。

返回

• WPFormat|undefined：如果已成功注销，则为之前的格式值；否则为 undefined。

useAnchor

此 hook 应在格式类型的 Edit 组件中使用，它返回被格式化的活动元素；如果没有活动格式，则返回表示选区范围的虚拟元素。返回的值可用于为 UI 定位，例如通过 anchor prop 将其传递给 Popover 组件。

参数

• obj { editableContentElement: HTMLElement | null; settings?: WPFormat; }：命名参数。
• obj.editableContentElement HTMLElement | null：包含可编辑内容的元素。
• obj.settings WPFormat：格式类型的设置。

返回

• Element | VirtualAnchorElement | undefined | null：活动元素或选区范围。

useAnchorRef

此 hook 应在格式类型的 Edit 组件中使用，它返回被格式化的活动元素；如果没有活动格式，则返回选区范围。返回的值可用于为 UI 定位，例如将其传递给 Popover 组件。

参数

• $1 Object：命名参数。
• $1.ref RefObject<HTMLElement>：包含可编辑内容的元素的 React ref。
• $1.value RichTextValue：要检查选区的值。
• $1.settings WPFormat：格式类型的设置。

返回

• Element|Range：活动元素或选区范围。

参与该包的贡献

这是一个独立的软件包，它是 Gutenberg 项目的一部分。该项目被组织为一个 monorepo。它由多个自包含的软件包组成，每个软件包都有特定用途。此 monorepo 中的软件包会发布到 npm，并被 WordPress 以及其他软件项目使用。

如需了解更多关于为此软件包或整个 Gutenberg 项目做贡献的信息，请阅读项目的主贡献者指南。