@wordpress/dom

WordPress 的 DOM 工具模块。

安装

安装该模块

npm install @wordpress/dom --save

API

computeCaretRect

获取容器内选区的矩形区域。

参数

• win Window: 选区所在的窗口。

返回

• DOMRect | null: 矩形区域。

documentHasSelection

检查当前文档是否存在选区。这包括输入字段、文本域以及一般富文本选区中的焦点。

参数

• doc Document: 要检查的文档。

返回

• boolean: 如果存在选区则返回 true，否则返回 false。

documentHasTextSelection

检查当前文档是否包含已选中的文本。这适用于文档中的文本范围，不适用于 <input> 和 <textarea> 元素内部的选区。

参见：https://developer.mozilla.org/en-US/docs/Web/API/Window/getSelection#Related_objects。

参数

• doc Document: 要检查的文档。

返回

• boolean: 如果存在选区则返回 true，否则返回 false。

documentHasUncollapsedSelection

检查当前文档是否存在任何形式的（非折叠）选区。这包括跨元素的文本范围以及文本类 <input> 和 <textarea> 元素内的任何选区。

参数

• doc Document: 要检查的文档。

返回

• boolean: 文档中是否存在任何可识别的文本选区。

focus

将 focusable 和 tabbable 工具函数按同名键分组到对象中。

getFilesFromDataTransfer

从 DataTransfer 对象中获取所有文件。

参数

• dataTransfer DataTransfer: 要检查的 DataTransfer 对象。

返回

• File[]: 包含所有文件的数组。

getOffsetParent

返回最近的定位元素，或者在 offsetParent 规范的任一条件下返回 null。与 offsetParent 不同，此函数不限于 HTMLElement，并接受任何 Node（例如 Node.TEXT_NODE）。

相关

• https://drafts.csswg.org/cssom-view/#dom-htmlelement-offsetparent

参数

• node Node: 用于查找偏移父节点的节点。

返回

• Node | null: 偏移父节点。

getPhrasingContentSchema

获取短语内容可能路径的模式。

相关

• https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content

参数

• context [string]: 设置为 “paste” 以排除不可见元素和敏感数据。

返回

• Partial<ContentSchema>: 模式。

getRectangleFromRange

获取给定 Range 的矩形区域。如果找不到合适的矩形，则返回 null。请替代使用 Range.getBoundingClientRect()，后者通常存在问题，尤其是对于折叠范围的矩形计算。

参数

• range Range: 范围。

返回

• DOMRect?: 矩形区域。

getScrollContainer

给定一个 DOM 节点，找到最近的滚动容器节点或该节点本身（如果它是可滚动的）。

参数

• node Element | null: 开始搜索的节点。
• direction ?string: 要搜索的可滚动容器的方向（‘vertical’、‘horizontal’、‘all’）。默认为 ‘vertical’。

返回

• Element | undefined: 找到的可滚动容器节点。

insertAfter

给定两个 DOM 节点，将前者作为后者的下一个兄弟节点插入到 DOM 中。

参数

• newNode Node: 要插入的节点。
• referenceNode Node: 在其之后执行插入操作的节点。

返回

• void:

isEmpty

递归检查元素是否为空。如果元素包含文本或包含带有属性（如图片）的子元素，则不为空。

参数

• element Element: 要检查的元素。

返回

• boolean: 元素是否为空。

isEntirelySelected

检查元素的内容是否已被完全选中。如果不存在选区的可能性，则返回 true。

参数

• element HTMLElement: 要检查的元素。

返回

• boolean: 如果完全选中则返回 true，否则返回 false。

isFormElement

检测元素是否为表单元素。

参数

• element Element: 要检查的元素。

返回

• boolean: 如果是表单元素则返回 true，否则返回 false。

isHorizontalEdge

检查选区是否在容器的水平边缘处。

参数

• container HTMLElement: 可聚焦元素。
• isReverse boolean: 设置为 true 检查左侧，false 检查右侧。

返回

• boolean: 如果在水平边缘则返回 true，否则返回 false。

isNumberInput

检查给定元素是否为 number 类型的输入字段。

参数

• node Node: HTML 节点。

返回

• node is HTMLInputElement: 如果节点是数字输入则返回 true。

isPhrasingContent

确定给定节点是否为短语内容。

相关

• https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content

参数

• node Node: 要测试的节点。

返回

• boolean: 如果是短语内容则返回 true，否则返回 false。

isRTL

判断元素的文本方向是否为从右到左。

参数

• element Element: 要检查的元素。

返回

• boolean: 如果是 RTL 则返回 true，LTR 则返回 false。

isSelectionForward

如果给定的选区对象是正向方向，则返回 true，否则返回 false。

相关

• https://developer.mozilla.org/en-US/docs/Web/API/Node/compareDocumentPosition

参数

• selection Selection: 要检查的选区对象。

返回

• boolean: 选区是否为正向。

isTextContent

参数

• node Node:

返回

• boolean: 节点是否为文本内容

isTextField

检查给定元素是否为文本字段，其中文本字段的定义是能够在输入中选择文本，或者它是 contenteditable。

参见：https://html.spec.whatwg.org/#textFieldSelection

参数

• node Node: HTML 元素。

返回

• node is HTMLElement: 如果元素是文本字段则返回 true，否则返回 false。

isVerticalEdge

检查选区是否在容器的垂直边缘处。

参数

• container HTMLElement: 可聚焦元素。
• isReverse boolean: 设置为 true 检查顶部，false 检查底部。

返回

• boolean: 如果在垂直边缘则返回 true，否则返回 false。

placeCaretAtHorizontalEdge

将光标放置在给定元素的开头或结尾。

参数

• container HTMLElement: 可聚焦元素。
• isReverse boolean: 为 end 时设为 true，为 start 时设为 false。

placeCaretAtVerticalEdge

将光标放置在给定元素的顶部或底部。

参数

• container HTMLElement: 可聚焦元素。
• isReverse boolean: 为 bottom 时设为 true，为 top 时设为 false。
• rect [DOMRect]: 用于定位光标的矩形区域。

remove

给定一个 DOM 节点，将其从 DOM 中移除。

参数

• node Node: 要移除的节点。

返回

• void:

removeInvalidHTML

给定一个模式，清理 HTML 中的节点、属性和类。

参数

• HTML string: 需要清理的 HTML。
• schema import('./clean-node-list').Schema: HTML 的模式。
• inline boolean: 是否针对内联模式进行清理。

返回

• string: 清理后的 HTML。

replace

给定两个 DOM 节点，在 DOM 中将前者替换为后者。

参数

• processedNode Element: 要被移除的节点。
• newNode Element: 要插入以替代前者的节点。

返回

• void:

replaceTag

将给定的节点替换为具有给定标签名的新节点。

参数

• node Element: 要替换的节点
• tagName string: 新的标签名。

返回

• Element: 新节点。

safeHTML

从 HTML 中剥离脚本和 on* 属性。

参数

• html string: 需要清理的 HTML。

返回

• string: 清理后的 HTML。

unwrap

展开给定的节点。这意味着任何子节点都会被移动到父节点处。

参数

• node Node: 要展开的节点。

返回

• void:

wrap

使用具有给定标签名的新节点包裹给定的节点。

参数

• newNode Element: 要插入的节点。
• referenceNode Element: 要被包裹的节点。

为此包做出贡献

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

要了解有关为此包或整个 Gutenberg 做出贡献的更多信息，请阅读项目的主要 贡献者指南。