XML
查询工具
使用辅助函数遍历和检查已解析的 XML Element 树
使用 xml2js() 解析 XML 后，用这些工具函数遍历和提取 Element 树中的数据。
查找子元素
findChild
按标签名查找第一个直接子元素：
import { xml2js, findChild } from "@office-open/xml";
const root = xml2js("<w:p><w:r><w:t>Hello</w:t></w:r></w:p>");
const run = findChild(root, "w:r");
children
获取所有匹配标签名的直接子元素：
import { xml2js, children } from "@office-open/xml";
const root = xml2js("<w:p><w:r/><w:r/><w:r/></w:p>");
const runs = children(root, "w:r"); // 3 个元素
allChildren
获取所有直接子元素（不限制标签名）：
import { allChildren } from "@office-open/xml";
const all = allChildren(root);
读取文本
childText
获取第一个匹配子元素的文本内容：
import { xml2js, findChild, childText } from "@office-open/xml";
const root = xml2js("<w:p><w:r><w:t>Hello</w:t></w:r></w:p>");
const text = childText(root, "w:t"); // "Hello"
textOf
获取元素本身的文本内容：
import { textOf } from "@office-open/xml";
const textEl = findChild(run, "w:t");
const text = textOf(textEl); // "Hello"
collectText
收集元素及其后代中所有文本节点的内容：
import { collectText } from "@office-open/xml";
const allText = collectText(paragraph); // 连接的文本内容
读取属性
attr
获取字符串类型的属性值：
import { xml2js, findChild, attr } from "@office-open/xml";
const element = xml2js('<w:spacing w:before="240" w:after="120"/>');
attr(element, "w:before"); // "240"
attr(element, "w:after"); // "120"
attrNum
获取数字类型的属性值：
attrNum(element, "w:before"); // 240
attrBool
获取布尔类型的属性值：
attrBool(element, "w:val"); // 根据 "true"/"1"/"false"/"0" 返回
attrMeasure
获取度量属性为数字（纯数字 token），或原样保留 UniversalMeasure/百分比字符串（用于 ST_TwipsMeasure、ST_MeasurementOrPercent、CT_TblWidth/@w）。表格宽度百分比的 fiftieths（5000 = 100%）在 docx 层转换为面向用户的百分比（widthFiftiethsToPct），而非在此处：
import { attrMeasure } from "@office-open/xml";
attrMeasure(spacing, "w:before"); // 240（数字）— 纯数字 token
attrMeasure(width, "w:w"); // 5000（数字）— docx 将 fiftieths 转为 100%
colorAttr
获取规范化后的十六进制颜色属性：
import { colorAttr } from "@office-open/xml";
colorAttr(element, "w:color"); // "FF0000"
检查结构
hasChild
检查元素是否包含特定子元素：
import { hasChild } from "@office-open/xml";
hasChild(paragraph, "w:pPr"); // true 或 false
findDeep
查找所有匹配标签名的后代元素：
import { findDeep } from "@office-open/xml";
const allTextNodes = findDeep(document, "w:t");
findFirst
查找第一个匹配标签名的后代元素，在首个匹配处短路（深度优先前序）。优于 findDeep(parent, name)[0]——避免遍历整个子树并分配完整结果数组：
import { findFirst } from "@office-open/xml";
const firstT = findFirst(document, "w:t");
childCount
获取直接子元素数量：
import { childCount } from "@office-open/xml";
childCount(paragraph); // 3
完整参考
| 函数 | 返回值 | 说明 |
|---|---|---|
findChild(parent, name) | Element | undefined | 按名称查找第一个直接子元素 |
children(parent, name) | Element[] | 按名称查找所有直接子元素 |
allChildren(parent) | Element[] | 所有直接子元素 |
childText(parent, name) | string | 第一个匹配子元素的文本 |
textOf(element) | string | 元素的文本内容 |
collectText(element) | string | 所有后代的文本内容 |
attr(element, name) | string | undefined | 字符串类型属性值 |
attrNum(element, name) | number | undefined | 数字类型属性值 |
attrMeasure(element, name) | number | string | undefined | 度量属性（保留单位） |
attrBool(element, name) | boolean | undefined | 布尔类型属性值 |
colorAttr(element, name) | string | undefined | 十六进制颜色属性 |
hasChild(parent, name) | boolean | 子元素是否存在 |
findDeep(parent, name) | Element[] | 按名称查找所有后代元素 |
findFirst(parent, name) | Element | undefined | 首个后代（短路） |
childCount(parent) | number | 直接子元素数量 |