`hutool.core.util.xml`¶

Module Contents¶

Classes¶

XmlUtil

XML工具类

API¶

class hutool.core.util.xml.XmlUtil¶

XML工具类

static read_xml(xml_str_or_path: str) → xml.etree.ElementTree.Element¶

读取XML（字符串或文件路径）

支持传入XML字符串或文件路径，自动判断并解析。

参数:: xml_str_or_path – XML字符串或文件路径
返回:: 解析后的XML根元素

static parse_to_map(xml_str: str) → dict¶

XML转字典

将XML字符串递归转换为嵌套字典结构。如果同名子元素出现多次，值为列表。

参数:: xml_str – XML字符串
返回:: 转换后的字典

static to_xml_str(root_name: str, data: dict) → str¶

字典转XML字符串

参数:

root_name – 根元素名称
data – 待转换的字典数据

返回:

XML字符串

static map_to_xml(data: dict, root_name: str = 'root') → str¶

字典转XML

将字典递归转换为XML字符串。

参数:

data – 待转换的字典数据
root_name – 根元素名称，默认为”root”

返回:

XML字符串

static _build_xml(parent: xml.etree.ElementTree.Element, data: Any) → None¶

递归构建XML元素

参数:

parent – 父元素
data – 当前数据（字典或值）

static format_xml(xml_str: str) → str¶

格式化XML

将XML字符串格式化为带缩进的可读格式。

参数:: xml_str – 待格式化的XML字符串
返回:: 格式化后的XML字符串

static get_element_text(element: xml.etree.ElementTree.Element, xpath: str) → Optional[str]¶

获取元素文本

通过xpath查找子元素并返回其文本内容。

参数:

element – XML元素
xpath – 子元素的标签路径，如 “child/subchild”

返回:

元素文本内容，未找到则返回None

static clean_invalid(xml_str: str) → str¶

清理XML中的非法字符

移除XML规范中不允许的控制字符（除了制表符、换行符、回车符）。

参数:: xml_str – 原始XML字符串
返回:: 清理后的XML字符串

static create_xml(root_name: str) → xml.etree.ElementTree.Element¶

创建空 XML 根元素。

参数:: root_name – 根元素名称
返回:: XML 根元素

static get_root_element(xml_str: str) → xml.etree.ElementTree.Element¶

获取 XML 的根元素。

参数:: xml_str – XML 字符串
返回:: 根元素

static get_elements(element: xml.etree.ElementTree.Element, tag: str) → list¶

获取所有匹配 tag 的子元素列表。

参数:

element – XML 元素
tag – 子元素标签名

返回:

匹配的元素列表

static get_element(element: xml.etree.ElementTree.Element, tag: str) → Optional[xml.etree.ElementTree.Element]¶

获取第一个匹配 tag 的子元素。

参数:

element – XML 元素
tag – 子元素标签名

返回:

匹配的元素，未找到返回 None

static element_text(element: xml.etree.ElementTree.Element, tag: str) → Optional[str]¶

获取子元素的文本内容。

参数:

element – 父元素
tag – 子元素标签名

返回:

子元素文本，未找到返回 None

static clean_comment(xml_str: str) → str¶

清除 XML 注释。

参数:: xml_str – XML 字符串
返回:: 清除注释后的 XML 字符串

static append_child(parent: xml.etree.ElementTree.Element, tag: str, text: Optional[str] = None) → xml.etree.ElementTree.Element¶

为父元素添加子元素。

参数:

parent – 父元素
tag – 子元素标签名
text – 子元素文本内容，可选

返回:

新创建的子元素

static append_text(element: xml.etree.ElementTree.Element, text: str) → None¶

为元素添加/追加文本内容。

参数:

element – XML 元素
text – 文本内容

static is_element(obj: Any) → bool¶

判断对象是否为 XML Element。

参数:: obj – 对象
返回:: 是否为 Element

static to_str(element: xml.etree.ElementTree.Element, pretty: bool = False, charset: str = 'utf-8') → str¶

将 XML 元素序列化为字符串。

参数:

element – XML 元素
pretty – 是否格式化输出
charset – 字符集

返回:

XML 字符串

static to_file(element: xml.etree.ElementTree.Element, file_path: str, charset: str = 'utf-8') → None¶

将 XML 元素写入文件。

参数:

element – XML 元素
file_path – 文件路径
charset – 字符集

static write(element: xml.etree.ElementTree.Element, stream, charset: str = 'utf-8') → None¶

将 XML 元素写入流。

参数:

element – XML 元素
stream – 可写流
charset – 字符集

static create_document() → xml.etree.ElementTree.Element¶

创建一个空的 XML 文档根元素。

返回:: 根为 <root/> 的 Element

static bean_to_xml(obj: Any, root_tag: str = 'root') → str¶

将字典或数据类对象转换为XML字符串。

支持字典和带 __dict__ 属性的数据类对象，递归处理嵌套结构。

参数:

obj – 字典或数据类对象
root_tag – 根元素标签名，默认为 "root"

返回:

XML字符串

static xml_to_bean(xml_str: str, target_class: Any = None) → Any¶

将XML字符串转换为数据类对象或字典。

若指定 target_class，则将解析后的字典作为关键字参数传入构造函数；否则直接返回嵌套字典。

参数:

xml_str – XML字符串
target_class – 目标数据类，为 None 时返回字典

返回:

数据类实例或字典

static xml_to_map(xml_str: str) → dict¶

XML转字典（parse_to_map 的别名）。

参数:: xml_str – XML字符串
返回:: 转换后的字典

static map_to_xml_str(map_data: dict, root_tag: str = 'root') → str¶

字典转XML字符串（map_to_xml 的别名）。

参数:

map_data – 待转换的字典数据
root_tag – 根元素标签名，默认为 "root"

返回:

XML字符串

static get_by_xpath(element: xml.etree.ElementTree.Element, xpath: str) → Optional[str]¶

通过XPath查询获取元素文本。

使用 element.find 查找第一个匹配元素并返回其文本内容。

参数:

element – XML元素
xpath – XPath表达式

返回:

元素文本内容，未找到则返回 None

static get_node_by_xpath(element: xml.etree.ElementTree.Element, xpath: str) → Optional[xml.etree.ElementTree.Element]¶

通过XPath查询获取单个节点。

参数:

element – XML元素
xpath – XPath表达式

返回:

匹配的元素节点，未找到则返回 None

static get_node_list_by_xpath(element: xml.etree.ElementTree.Element, xpath: str) → list¶

通过XPath查询获取节点列表。

参数:

element – XML元素
xpath – XPath表达式

返回:

匹配的元素节点列表

static parse_xml(xml_str: str) → xml.etree.ElementTree.Element¶

解析XML字符串并返回根元素。

参数:: xml_str – XML字符串
返回:: 解析后的XML根元素

static read_xml_file(file_path: str) → xml.etree.ElementTree.Element¶

读取XML文件并返回根元素。

参数:: file_path – XML文件路径
返回:: 解析后的XML根元素

static transform_xml(xml_str: str, xslt_str: str) → str¶

使用XSLT对XML进行基本转换。

基于 ElementTree 实现的简易转换，仅支持 <xsl:value-of select="..."/> 标签的文本替换。复杂XSLT场景建议使用 lxml 等专业库。

参数:

xml_str – XML字符串
xslt_str – XSLT样式表字符串

返回:

转换后的XML字符串

static escape_xml(text: str) → str¶

转义XML特殊字符。

将 &、<、>、"、' 转义为对应的XML实体。

参数:: text – 原始文本
返回:: 转义后的文本

static unescape_xml(text: str) → str¶

反转义XML特殊字符。

将XML实体还原为原始字符。

参数:: text – 包含XML实体的文本
返回:: 还原后的文本

static format_xml_pretty(xml_str: str, indent: int = 2) → str¶

使用自定义缩进格式化XML。

参数:

xml_str – 待格式化的XML字符串
indent – 缩进空格数，默认为 2

返回:

格式化后的XML字符串

static write_object_as_xml(obj: Any, file_path: str, root_tag: str = 'root') → None¶

将字典或数据类对象以XML格式写入文件。

参数:

obj – 字典或数据类对象
file_path – 目标文件路径
root_tag – 根元素标签名，默认为 "root"

static dict_to_element(data: dict, tag: str = 'item') → xml.etree.ElementTree.Element¶

将 dict 转换为 XML Element。

参数:

data – 字典数据
tag – 根元素标签名，默认 "item"

返回:

XML Element 对象

elem = XmlUtil.dict_to_element({"name": "test", "age": 20})
assert elem.tag == "item"
assert elem.find("name").text == "test"

static list_to_element(data: list, tag: str = 'root', item_tag: str = 'item') → xml.etree.ElementTree.Element¶

将 list 转换为 XML Element。

参数:

data – 列表数据
tag – 根元素标签名，默认 "root"
item_tag – 子项标签名，默认 "item"

返回:

XML Element 对象

elem = XmlUtil.list_to_element([{"id": 1}, {"id": 2}])
assert elem.tag == "root"
assert len(list(elem)) == 2

static dict_to_xml(data: dict, tag: str = 'item', encoding: str = 'utf-8') → str¶

将 dict 转换为 XML 字符串。

参数:

data – 字典数据
tag – 根元素标签名
encoding – 编码格式，默认 "utf-8"

返回:

XML 字符串

static list_to_xml(data: list, tag: str = 'root', item_tag: str = 'item', encoding: str = 'utf-8') → str¶

将 list 转换为 XML 字符串。

参数:

data – 列表数据
tag – 根元素标签名
item_tag – 子项标签名
encoding – 编码格式

返回:

XML 字符串

static indent_element(element: xml.etree.ElementTree.Element, level: int = 0, indent: str = ' ') → None¶

对 XML Element 递归添加缩进（美化输出）。

参数:

element – XML Element 对象
level – 当前缩进层级
indent – 每层缩进字符，默认两个空格

hutool.core.util.xml¶

Module Contents¶

Classes¶

API¶

`hutool.core.util.xml`¶