查询工具 - Office Open

使用 parse() 解析 XML 后，用这些工具函数遍历和提取 Element 树中的数据。

#查找子元素

#findChild

按标签名查找第一个直接子元素：

import { parse, findChild } from "@office-open/xml";

const root = parse("<w:p><w:r><w:t>Hello</w:t></w:r></w:p>");
const run = findChild(root, "w:r");

#children

获取所有匹配标签名的直接子元素：

import { parse, children } from "@office-open/xml";

const root = parse("<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 { parse, findChild, childText } from "@office-open/xml";

const root = parse("<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 { parse, findChild, attr } from "@office-open/xml";

const element = parse('<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`	直接子元素数量