XML DOM – Comment 对象

XML DOM – Comment 对象（注释节点）

Comment 是 XML DOM 中代表 <!-- 注释内容 --> 的节点类型。
它在结构上与 Text 节点几乎完全相同，只是语义不同，且在序列化时以 <!-- --> 形式输出。

1. 基本信息一览表

项目	值 / 说明
nodeType	8（Node.COMMENT_NODE）
nodeName	始终为 "#comment"
nodeValue / data	注释的纯文本内容（不包含 <!-- 和 -->）
textContent	与 nodeValue 完全相同
length	注释文本的字符长度（UTF-16）
继承自	CharacterData → Node（和 Text、CDATASection 同源）
创建方法	document.createComment("内容")
输出形式	<!--内容-->（自动加上注释标记）

2. 与 Text / CDATASection 完整对比

特性	Comment	Text	CDATASection
nodeType	8	3	4
nodeName	“#comment”	“#text”	“#cdata-section”
是否被渲染	完全不渲染	渲染为文字	渲染为文字（不转义）
是否转义	是（内容中 < & 会被转义）	是	否
可否包含 -->	不能（会提前结束注释）	可以	不能包含 ]]>
典型用途	开发提示、条件注释、占位	普通文本内容	存放脚本、HTML 片段

3. 创建与使用示例

const doc = new DOMParser().parseFromString('<root/>', 'text/xml');
const root = doc.documentElement;

// 创建注释
const comment1 = doc.createComment("这是普通注释");
const comment2 = doc.createComment("TODO: 待完成国际化");
const comment3 = doc.createComment("以下为调试信息，仅开发环境可见");

// 插入不同位置
root.appendChild(comment1);                    // 作为最后一个子节点
root.insertBefore(comment2, root.firstChild);  // 作为第一个子节点
doc.insertBefore(comment3, doc.documentElement); // 放在 <root> 之前（文档级别）

console.log(new XMLSerializer().serializeToString(doc));

输出：

<?xml version="1.0"?>
<!--以下为调试信息，仅开发环境可见-->
<!--TODO: 待完成国际化-->
<root>
  <!--这是普通注释-->
</root>

4. 高级操作（继承自 CharacterData，所有 Text 方法都可用）

const comment = doc.documentElement.firstChild; // 假设是注释

// 修改内容
comment.data = "已完成 v2.1.0 版本上线";
comment.appendData(" by 张三");

// 替换部分内容
comment.replaceData(0, 5, "紧急修复");

// 拆分注释（极少用，但可以）
const part1 = comment.splitText(10);  // 前10个字符留在原节点
console.log(part1.data);              // 剩余部分

// 获取完整注释文本
console.log(comment.wholeText);       // 如果有连续多个注释，会合并

5. 实战应用场景（非常常见）

场景	推荐写法
给 XML 添加版本信息	<!-- Generated by MyApp v3.5.1 on 2025-11-26 -->
条件注释（XSLT、Ant 等工具识别）	<!-- @if(debug) -->...<![CDATA[...]]>...<!-- @endif -->
临时屏蔽一段 XML	整段包在 <!-- 和 --> 里（最快）
在 XSLT 中写调试信息	<xsl:comment>当前节点：<xsl:value-of select="name()"/></xsl:comment>
给代码生成器留标记	<!-- ### INSERT MENU HERE ### -->
兼容旧版 IE 的条件注释（XHTML 时）	<!--[if IE 8]>...<![endif]-->

6. 关键限制与坑（务必记住！）

限制内容	说明 & 解决办法
注释内不能出现 --	<!-- 这里有错误 -- --> 是非法的！ 解决：改成 - 或拆成两个注释
不能以 > 结尾连续两个 --	<!-- comment --> --> 非法
不能放在 <?xml ...?> 之前	文档第一个节点必须是 XML 声明或注释都不行（注释可以紧跟其后）
HTML 中会被浏览器渲染为可见文本？	不会，HTML 也正确识别 <!-- --> 为注释

7. 最佳实践总结

操作	推荐方式
添加单行注释	document.createComment("xxx")
添加多行长注释	仍然用 createComment（换行符 \n 会被保留）
临时注释掉一段 XML	用编辑器选中 → Ctrl+/（大多数支持）
需要条件判断的注释	用 <!-- @marker --> 配合后处理器识别
想隐藏但保留在源码中的代码	优先用 <!-- -->，其次才是 CDATA（CDATA 更重）

8. 一句话终极总结

Comment 节点 = “永不显示、永不执行、可读写、可拆分、继承 Text 所有能力”的完美隐藏层
在 XML 世界里，它是写备注、打标记、占位置、条件编译、调试追踪的万能工具，几乎每个正式发布的 XML 文件都会带上至少一个 <!-- Generated by ... --> 注释。

记住这三件事，你就彻底掌握了 Comment 节点：

1. createComment() → 加注释
2. node.data → 读写内容
3. <!-- 不能出现连续两个 -- --> → 唯一语法禁区