XSLT如何生成注释和处理指令？

<blockquote>使用和可在XSLT输出中添加注释和处理指令，前者生成格式的注释以提升可读性、调试性，后者生成形式的指令以传递应用程序特定信息；二者均支持静态与动态内容结合，常用于嵌入元数据、样式表链接或系统状态，但需避免注释中出现–、确保PI目标名合法，并注意内容编码与信息冗余问题，最佳实践包括精简内容、封装模板、验证输出及防范敏感信息泄露。</blockquote><p><img src=”https://img.php.cn/upload/article/001/221/864/175584936953036.jpg” alt=”xslt如何生成注释和处理指令？”></p><p>XSLT在生成输出时，要添加注释（Comment）或处理指令（Processing Instruction），主要通过两个特定的XSLT元素来实现：<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>&lt;xsl:comment&gt;</pre>

</div> 用于生成XML注释，而 <div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>&lt;xsl:processing-instruction&gt;</pre>

</div> 则用于生成处理指令。这两种机制都允许你将静态文本与动态内容结合，以满足各种输出需求。</p><h3>解决方案</h3><p>要生成注释，你可以使用<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>&lt;xsl:comment&gt;</pre>

</div>元素。它的内容就是你希望出现在输出XML或HTML中的注释文本。例如：</p><div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=’brush:xml;toolbar:false;’>&lt;xsl:comment&gt; 这是一个简单的注释，可能包含一些关于文件生成的信息。</xsl:comment></pre>

</div><p>这段XSLT会生成如下的输出：</p><div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=’brush:xml;toolbar:false;’>&lt;!– 这是一个简单的注释，可能包含一些关于文件生成的信息。 –&gt;</pre>

</div><p>如果你需要注释内容是动态的，比如包含当前日期或从源XML中提取的数据，你可以这样写：</p><div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=’brush:xml;toolbar:false;’>&lt;xsl:comment&gt; 由系统于 <xsl:value-of select=”current-date()”/> 生成，源数据版本：<xsl:value-of select=”/root/version”/></xsl:comment></pre>

</div><p>这会生成类似这样的注释：</p><div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=’brush:xml;toolbar:false;’>&lt;!– 由系统于 2023-10-27 生成，源数据版本：1.2.3 –&gt;</pre>

</div><p>而对于处理指令，你需要使用<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>&lt;xsl:processing-instruction&gt;</pre>

</div>元素。它需要一个<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>name</pre>

</div>属性来指定处理指令的目标（Target），而其内容则是处理指令的数据部分。例如，生成一个XML样式表声明：</p><div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=’brush:xml;toolbar:false;’>&lt;xsl:processing-instruction name=&quot;xml-stylesheet&quot;&gt; type=&quot;text/xsl&quot; href=&quot;my-style.xsl&quot;&lt;/xsl:processing-instruction&gt;</pre>

</div><p>这段XSLT将输出：</p><div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=’brush:xml;toolbar:false;’>&lt;?xml-stylesheet type=&quot;text/xsl&quot; href=&quot;my-style.xsl&quot;?&gt;</pre>

</div><p>同样，处理指令的<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>name</pre>

</div>和内容都可以是动态的。<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>name</pre>

</div>属性可以使用属性值模板（Attribute Value Templates，即大括号<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>{}</pre>

</div>），内容部分则可以像注释一样使用<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>&lt;xsl:value-of&gt;</pre>

</div>或其他XSLT指令：</p><div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=’brush:xml;toolbar:false;’>&lt;xsl:variable name=&quot;pi-target&quot; select=&quot;’my-app-instruction’&quot;/&gt;&lt;xsl:processing-instruction name=&quot;{$pi-target}&quot;&gt; data-id=&quot;&lt;xsl:value-of select=&quot;/root/data/@id&quot;/&gt;&quot; status=&quot;processed&quot;&lt;/xsl:processing-instruction&gt;</pre>

</div><p>这可能生成：</p><div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=’brush:xml;toolbar:false;’>&lt;?my-app-instruction data-id=&quot;A123&quot; status=&quot;processed&quot;?&gt;</pre>

</div><h3><a style=”color:#f60; text-decoration:underline;” title=”为什么” href=”https://www.php.cn/zt/92702.html” target=”_blank”>为什么</a>我们需要在XSLT输出中添加注释或处理指令？</h3><p>这其实是个很实际的问题，我在日常工作中经常遇到。我们生成XML或HTML，通常是为了给机器消费，但别忘了，还有人类开发者需要阅读，还有其他应用程序需要特定的指示。</p><p><strong>对于注释（Comments）而言：</strong></p><ul><li><strong>可读性和维护性：</strong> 这是最直接的原因。想象一下，你生成了一个复杂的HTML页面，其中某个部分是动态加载的广告位。如果你不留个注释说明“<!– 广告位：由AdService动态注入 –>”，那将来另一个开发者接手时，他可能得花上好一会儿才能搞清楚这块空白区域是干嘛的，或者为什么它的内容总是变。对我来说，它就像是代码里的注释，是写给未来自己和同事的“备忘录”。</li><li><strong>调试和追踪：</strong> 在复杂的转换链中，我有时会加入一些特殊的注释，比如“<!– DEBUG: 此节点由Template ‘process-item’在XSLT v1.5中生成 –>”。这在排查问题时简直是救命稻草，能快速定位到问题出在哪里。</li><li><strong>元数据或非功能性信息：</strong> 有些信息不适合作为数据元素，但又需要传递。比如，一个XML文件可能需要在顶部注明“<!– 本文件遵循XXX协议，生成日期：[日期] –>”，这有助于接收方理解文件的上下文。</li></ul><p><strong>对于处理指令（Processing Instructions，PIs）而言：</strong></p> <div class=”aritcle_card”> <a class=”aritcle_card_img” href=”/ai/754″> <img src=”https://img.php.cn/upload/ai_manual/000/000/000/175679972542147.png” alt=”秒哒”> </a> <div class=”aritcle_card_info”> <a href=”/ai/754″>秒哒</a> <p>秒哒-不用代码就能实现任意想法</p> <div class=””> <img src=”/static/images/card_xiazai.png” alt=”秒哒”> <span>535</span> </div> </div> <a href=”/ai/754″ class=”aritcle_card_btn”> <span>查看详情</span> <img src=”/static/images/cardxiayige-3.png” alt=”秒哒”> </a> </div> <ul><li><strong>应用程序特定指令：</strong> 这是PIs的核心用途。最常见的例子就是<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>&lt;?xml-stylesheet …?&gt;</pre>

</div>，它告诉XML解析器或<a style=”color:#f60; text-decoration:underline;” title=”浏览器” href=”https://www.php.cn/zt/16180.html” target=”_blank”>浏览器</a>这个XML文档应该用哪个XSLT样式表来渲染。你也可以看到像<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>&lt;?php … ?&gt;</pre>

</div>或<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>&lt;?asp … ?&gt;</pre>

</div>这样的，它们指示Web服务器将内嵌的内容作为特定语言的代码来执行。PIs提供了一种“逃逸机制”，让你可以在XML文档中嵌入非XML规范的、针对特定应用程序的指令，而又不破坏XML本身的结构和有效性。</li><li><strong><a style=”color:#f60; text-decoration:underline;” title=”工具” href=”https://www.php.cn/zt/16887.html” target=”_blank”>工具</a>集成：</strong> 某些工具可能会扫描XML文档中的特定PIs来触发行为或提取配置。比如，一个文档管理系统可能会查找<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>&lt;?document-status approved?&gt;</pre>

</div>来更新文档状态。</li><li><strong>非侵入性扩展：</strong> 与添加新的XML元素不同，PIs不会改变XML文档的逻辑结构或数据模型。它们只是提供额外的、旁带的信息，这在需要保持XML Schema或DTD不变的情况下非常有用。</li></ul><p>简而言之，它们都是为了让机器生成的输出更“智能”、更“友好”，不仅对程序，也对人。</p><h3>处理指令与XML元素有何本质<a style=”color:#f60; text-decoration:underline;” title=”区别” href=”https://www.php.cn/zt/27988.html” target=”_blank”>区别</a>？</h3><p>这个问题问得好，它触及了XML设计哲学的一个核心点。在我看来，处理指令和XML元素，虽然都出现在XML文档中，但它们的“职责”和“身份”是截然不同的。</p><p><strong>XML元素</strong>，是XML文档的<strong>核心内容和结构</strong>。它们定义了数据是什么，以及数据之间的层级关系。一个<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>&lt;book&gt;</pre>

</div>元素包含<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>&lt;title&gt;</pre>

</div>和<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>&lt;author&gt;</pre>

</div>，这清晰地表达了“书有标题和作者”这个事实。元素是XML的“名词”和“动词”，它们构建了文档的语义骨架。当一个XML解析器处理元素时，它会解析标签名、属性、内容，并构建一个DOM树或触发SAX事件，这些都是为了表示数据本身。元素必须遵循严格的嵌套规则，并可以被XML Schema或DTD进行验证。</p><p><strong>处理指令（PIs）</strong>，则完全是另一回事。它们不是文档数据的一部分，而是<strong>给处理应用程序的指令</strong>。PIs的格式是<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>&lt;?target data?&gt;</pre>

</div>。这里的<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>target</pre>

</div>是一个“名字”，它告诉哪个应用程序应该处理这条指令；<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>data</pre>

</div>部分则是具体的指令内容，这个内容对XML解析器来说通常是不透明的，它只是一个字符串，由<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>target</pre>

</div>指定的应用程序去解释。</p><p>举个例子，<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>&lt;?xml-stylesheet type=&quot;text/xsl&quot; href=&quot;style.xsl&quot;?&gt;</pre>

</div>这个PI，它告诉浏览器或XML<a style=”color:#f60; text-decoration:underline;” title=”处理器” href=”https://www.php.cn/zt/16030.html” target=”_blank”>处理器</a>：“嘿，有个叫<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>xml-stylesheet</pre>

</div>的应用程序，它需要知道这个文档应该用<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>style.xsl</pre>

</div>这个XSLT文件来渲染。”浏览器会去读取<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>type</pre>

</div>和<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>href</pre>

</div>，然后加载并应用样式表。但这个PI本身并不是XML文档数据的一部分，你不能说“文档的<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>xml-stylesheet</pre>

</div>是<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>style.xsl</pre>

</div>”。它只是一个“命令”。</p><p><strong>核心区别总结：</strong></p><ol><li><strong>角色与目的：</strong> 元素描述<strong>数据本身</strong>和<strong>其结构</strong>；PIs提供<strong>应用程序特定的指令</strong>。</li><li><strong>语义：</strong> 元素具有语义（例如，<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>&lt;price&gt;</pre>

</div>表示价格），可以被通用地理解和处理；PIs的语义完全依赖于其<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>target</pre>

</div>应用程序，对其他应用程序来说可能毫无意义。</li><li><strong>解析与验证：</strong> 元素的内容会被XML解析器进一步解析、验证（如果存在Schema/DTD），并构建成信息集；PIs的<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>data</pre>

</div>部分通常被解析器当作一个纯文本字符串传递给应用程序，不会进行XML级别的解析或验证。</li><li><strong>结构性：</strong> 元素是层级结构的一部分，它们有父子关系；PIs是独立的，它们只是文档流中的一个点，不参与XML的层级数据结构。</li><li><strong>语法：</strong> 元素使用<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>&lt;tag&gt;</pre>

</div>和<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>&lt;/tag&gt;</pre>

</div>（或自闭合<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>&lt;tag/&gt;</pre>

</div>）以及属性；PIs使用<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>&lt;?target data?&gt;</pre>

</div>的特殊语法。</li></ol><p>所以，如果你的信息是关于文档内容的，用元素；如果你的信息是关于如何处理文档的，用PIs。这是一个非常清晰的界限。</p><h3>在动态生成注释或处理指令时，有哪些常见的陷阱或最佳实践？</h3><p>动态生成这类内容，尤其是在XSLT这种声明式语言里，确实有些微妙的地方。我个人在实践中踩过一些坑，也总结了一些经验。</p><p><strong>常见的陷阱：</strong></p><ol><li><strong>注释中的“–”序列：</strong> 这是最经典也最容易被忽视的陷阱。XML规范规定，注释内容中不能包含双连字符<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>–</pre>

</div>。如果你动态生成注释时，内容里不小心出现了<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>–</pre>

</div>，比如“<!– 版本1–2发布 –>”，这会导致生成的XML文档不符合规范，解析器会报错。虽然一些XSLT处理器（特别是较新的版本）可能会智能地将其替换为<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>- -</pre>

</div>或<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>&amp;#45;&amp;#45;</pre>

</div>来避免错误，但最好还是在生成前就避免这种情况，或者确保你的XSLT处理器能正确处理。</li><li><strong>处理指令的目标名（Target Name）不合法：</strong> 处理指令的<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>name</pre>

</div>属性（也就是PI的target）必须是一个有效的XML名称。这意味着它不能包含空格、斜杠、冒号（除非是合法的QName前缀）、不能以数字或<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>xml</pre>

</div>开头等。如果你的<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>name</pre>

</div>是动态生成的，并且源数据中包含非法字符，就会导致输出的XML不规范。</li><li><strong>内容编码问题：</strong> 如果动态生成的内容包含特殊字符（如<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>&</pre>

</div>，<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”><</pre>

</div>，<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>></pre>

</div>），XSLT会负责将其正确编码为实体引用（<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>&</pre>

</div>，<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”><</pre>

</div>，<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>></pre>

</div>），这对于XML元素内容是没问题的。但对于处理指令的<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>data</pre>

</div>部分，如果接收应用程序不期望这些实体，或者它有自己的解析规则，可能会导致问题。通常PI的<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>data</pre>

</div>部分应避免这些字符，或者确保接收方能正确解码。</li><li><strong>过度使用或信息冗余：</strong> 就像代码注释一样，过多的、无用的注释只会让输出文件变得臃肿，难以阅读。处理指令也一样，如果一个PI没有实际的应用程序去消费它，那它就是多余的噪音。</li></ol><p><strong>最佳实践：</strong></p><ol><li><strong>明确目的，精简内容：</strong> 在决定添加注释或PI之前，先问自己：这个信息是给谁看的？它有什么用？如果答案不清晰，那就不要加。注释应该简洁明了，PI应该只包含接收应用程序所需的最少信息。</li><li><strong>利用XSLT的动态能力：</strong> 充分利用<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”><xsl:value-of select=”…” /></pre>

</div>、属性值模板（<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>{…}</pre>

</div>）以及XSLT函数（如<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>current-date()</pre>

</div>、<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>format-date()</pre>

</div>）来构建动态内容。这样可以确保注释和PI始终反映最新的状态或数据。</li><li><strong>验证和测试输出：</strong> 这一点至关重要。特别是在涉及动态内容时，你永远不知道源数据会是什么样。生成完XML后，用一个XML验证器（如<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”>xmllint</pre>

</div>或任何IDE内置的验证工具）检查其规范性。如果输出是HTML，在浏览器中测试其渲染效果。对于PI，确保目标应用程序能够正确识别和处理它们。</li><li><strong>封装和重用：</strong> 如果你需要在多个地方生成相似的注释或处理指令（比如每个文件的顶部都需要一个版权声明），可以考虑将其封装在一个具名模板（<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”><xsl:template name=”generate-header-comment”></pre>

</div>）中。这样不仅提高了代码复用性，也方便统一管理和修改。</li><li><strong>考虑输出类型：</strong> 如果你输出的是HTML，并且注释是给浏览器看的，那么HTML注释（<div class=”code” style=”position:relative; padding:0px; margin:0px;”><pre class=”brush:php;toolbar:false;”><!– … –></pre>

</div>）是合适的。如果输出是XML，则XML注释规则适用。处理指令则通常是给XML处理器或特定应用程序的。</li><li><strong>安全考量：</strong> 永远不要在注释或处理指令中放置敏感信息，尤其是当你的输出可能会被公开访问时。它们不是加密或安全存储<a style=”color:#f60; text-decoration:underline;” title=”敏感数据” href=”https://www.php.cn/zt/36496.html” target=”_blank”>敏感数据</a>的地方。</li></ol><p>总而言之，动态生成注释和处理指令是XSLT非常实用的功能，但用得好不好，往往取决于你对XML规范的理解、对目标应用程序行为的预期，以及在实践中积累的细致。</p>

以上就是XSLT如何生成注释和处理指令？的详细内容，更多请关注创想鸟其它相关文章！