Diazo主题开发必学：XSLT 1.0实战指南与性能优化

1. 项目概述：当 Diazo 遇上 XSLT——不是魔法，是可控的 DOM 重编排

在 Plone 主题开发圈里，Diazo 常被称作“CSS 开发者的救星”：用熟悉的 CSS 选择器写规则，就能把 Plone 的 HTML 输出和你的前端模板缝合起来。但凡你试过用theme.html+rules.xml把一个带下拉菜单、动态面包屑、多级导航栏的现代主题跑通，就会发现——有些事，纯 CSS 选择器真干不了。比如：给每个导航项之间自动插一个<li class="divider">；把用户工具栏里散落的<a>标签统一包进<ul><li>结构；或者根据当前页面路径，动态给某个<nav>添加><replace css:theme-children="#main-content" css:content="#content-core" />

会被编译成类似这样的 XSLT 片段：

<xsl:template match="*[@id='main-content']/*"> <xsl:copy-of select="document('')//xhtml:div[@id='content-core']/*" /> </xsl:template>

看到没？css:theme-children最终落地为match="*[@id='main-content']/*"，这是标准 XPath。而css:content被转成select="document('')//xhtml:div[@id='content-core']/*"。这意味着，Diazo 的“CSS 模式”只是表层语法，底层永远是 XSLT/XPath 的世界。当你需要突破 CSS 选择器的能力边界时——比如不能只选“第一个 li”，还要“选第 1、3、5 个 li”；不能只“替换整个块”，还要“遍历每个子节点，对文本内容做二次处理”——你就必须直面 XSLT。这不是 Diazo 的缺陷，而是它的设计取舍：用语法糖降低入门门槛，用原生能力保障上限。我在为某省级政务平台做响应式改造时，就遇到一个典型场景：旧版 Plone 导航是<ul id="portal-globalnav"><li><a>首页</a></li><li><a>政务公开</a></li></ul>，而新设计要求在移动端折叠为<select><option value="/">首页</option><option value="/about">政务公开</option></select>。用纯 CSS 规则，你只能replace整个<ul>，但无法生成<option>标签——因为replace只能替换节点，不能创建新节点结构。这时，XSLT 的xsl:for-each就成了唯一解：遍历每个<li>，提取<a>的href和文本，组装成<option>。这就是“双轨制”的核心逻辑：CSS 规则负责“定位与搬运”，XSLT 负责“生成与计算”。

2.2 何时必须切换到 XSLT：三个不可替代的实战信号

在上百次 Plone 主题迭代中，我总结出触发 XSLT 使用的三个明确信号，它们直接对应性能、结构、逻辑三类问题：

信号一：需要 DOM 节点重组（Performance 影响最直接）
当主题结构与 Plone 输出结构存在“粒度不匹配”时，纯replace会导致大量冗余 DOM 操作。例如，Plone 的面包屑是<div id="portal-breadcrumbs"><span>首页</span> &gt; <span>关于我们</span> &gt; <span>团队介绍</span></div>，而设计稿要求<nav aria-label="Breadcrumb"><ol><li><a href="/">首页</a></li><li><a href="/about">关于我们</a></li><li>团队介绍</li></ol></nav>。如果用replace css:theme="#portal-breadcrumbs"，你得把整个<div>替换掉，但其中的>符号和<span>标签都得手动重建。而用 XSLT：

<replace css:theme="#portal-breadcrumbs"> <nav aria-label="Breadcrumb"> <ol> <xsl:for-each select="span"> <li> <xsl:choose> <xsl:when test="position() = last()"> <xsl:value-of select="text()" /> </xsl:when> <xsl:otherwise> <a href="{concat('/', substring-after(text(), ' '))}"> <xsl:value-of select="text()" /> </a> </xsl:otherwise> </xsl:choose> </li> </xsl:for-each> </ol> </nav> </replace>

这段代码不仅生成了正确结构，还通过position() = last()判断最后一个节点不加链接，避免了 JavaScript 后续补丁。更重要的是，它只执行一次 XSLT 转换，比多次replace减少 DOM 重排次数，实测在 Chrome DevTools 的 Rendering 面板中，布局计算耗时下降 40%。

信号二：需要条件逻辑分支（结构健壮性关键）
Plone 的输出不是静态的。同一位置，登录态显示“我的账户”，未登录态显示“登录/注册”；内容页显示“编辑按钮”，列表页不显示。CSS 选择器无法做if-else，但 XSLT 的xsl:choose可以。我在为某高校科研管理系统做主题时，导航栏右侧需根据用户权限显示不同内容：管理员看到“后台管理”，普通用户看到“个人中心”，游客看到“登录”。用xsl:choose：

<replace css:theme-children="#portal-personaltools"> <xsl:choose> <xsl:when test="contains(//body/@class, 'userrole-manager')"> <li><a href="/@@manage-sites">后台管理</a></li> </xsl:when> <xsl:when test="contains(//body/@class, 'userrole-member')"> <li><a href="/personalize">个人中心</a></li> </xsl:when> <xsl:otherwise> <li><a href="/login">登录</a></li> <li><a href="/register">注册</a></li> </xsl:otherwise> </xsl:choose> </replace>

这里的关键是//body/@class—— Diazo 在编译时会注入 Plone 的 body class（如userrole-manager userrole-authenticated），我们直接读取即可。这种写法比在前端用 JS 判断更可靠，因为它是服务端渲染阶段完成的，不存在 FOUC（Flash of Unstyled Content）。

信号三：需要循环处理同级节点（避免硬编码）
这是 Diazo 新手最容易陷入的陷阱。比如 Plone 的侧边栏小工具（portlets）默认是<div class="portlet portletNavigationTree">...</div><div class="portlet portletCalendar">...</div>，而设计稿要求所有 portlet 包在一个<aside class="sidebar">里，且每个 portlet 加><replace css:theme-children=".sidebar"> <div class="portlet portletNavigationTree"><replace css:theme-children=".sidebar"> <xsl:for-each select="//div[contains(@class, 'portlet')]"> <xsl:variable name="portlet-class" select="substring-before(substring-after(@class, 'portlet '), ' ')"/> <div class="{@class}"><xsl:key name="nav-by-id" match="li" use="@id" /> <!-- 后续用 key('nav-by-id', 'home') 快速定位，比 //li[@id='home'] 快 3 倍 -->

这种优化在 XSLT 2.0/3.0 的动态类型系统里反而难实现。所以，接受 XSLT 1.0 的“限制”，就是拥抱 Diazo 的性能基线。

3. 核心细节解析与实操要点：XSLT 在 Diazo 中的生存指南

3.1 Diazo 的 XSLT 上下文：你操作的不是原始 HTML，而是编译后的中间树

这是绝大多数人踩坑的根源。新手常以为xsl:for-each select="#portal-globalnav > li"是在操作 Plone 输出的原始 HTML，其实不然。Diazo 在执行 XSLT 前，会先将theme.html和rules.xml编译成一棵“中间 DOM 树”，这棵树的结构已按 Diazo 规则预处理过。例如，<replace css:theme="#header" css:content="#portal-header" />执行后，中间树里#header节点的内容已经是#portal-header的副本，而非原始#header。因此，你在 XSLT 中写的select表达式，永远是针对这棵中间树，而不是原始 Plone HTML 或原始 theme HTML。我在为某金融客户做合规审计主题时，就因忽略这点栽过跟头：需求是“在所有<a>标签上添加rel="noopener noreferrer"”，我写了：

<xsl:template match="a"> <a> <xsl:copy-of select="@*" /> <xsl:attribute name="rel">noopener noreferrer</xsl:attribute> <xsl:apply-templates /> </a> </xslt>

结果发现部分链接没生效。排查发现，Plone 的某些 portlet 生成的<a>已被 Diazo 的wrap规则包裹过，中间树里它们是<div class="portletContent"><a>...</a></div>，而我的模板只匹配顶层<a>。正确做法是用//a（全路径匹配）或更稳妥的*//a。这个教训让我养成了一个习惯：在开发复杂 XSLT 前，先用 Diazo 的 debug 模式输出中间树。方法是在rules.xml顶部加：

<rules xmlns:diazo="http://namespaces.plone.org/diazo" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml"> <xsl:output method="xml" indent="yes" /> <!-- 在任意规则前插入 --> <xsl:template match="/"> <xsl:copy-of select="." /> </xsl:template> </rules>

然后访问http://yoursite.com/@@diazo-debug，就能看到 Diazo 编译后的完整 XML 树。这相当于前端开发者的 React DevTools，是理解 XSLT 执行上下文的唯一可靠途径。

3.2 CSS 选择器前缀css:的真相：它只是 XPath 的翻译器，不是万能胶

Diazo 文档里说css:前缀让 XSLT 支持 CSS 语法，这容易让人误解为“CSS 选择器可以直接嵌入 XSLT”。实际上，css:是 Diazo 编译器的预处理器指令，它只在css:select、css:theme等特定属性上生效，不会作用于 XSLT 内部的select属性。看这个常见错误：

<!-- 错误！css:select 只在 Diazo 规则属性上有效，这里无效 --> <xsl:for-each select="css:#portal-globalnav > li"> ... </xsl:for-each>

xsl:for-each的select属性必须是标准 XPath，css:前缀在这里会被lxml当作非法字符报错。正确写法是：

<!-- 正确：用 XPath 等价写法 --> <xsl:for-each select="*[@id='portal-globalnav']/li"> ... </xsl:for-each>

或者更健壮的：

<xsl:for-each select="//div[@id='portal-globalnav']/ul/li | //nav[@id='portal-globalnav']/li"> ... </xsl:for-each>

因为 Plone 不同版本的导航结构可能变化（4.x 用<div>，5.x 用<nav>），硬写*[@id='portal-globalnav']/li可能漏匹配。Diazo 的css:前缀本质是语法糖翻译器，它把css:#portal-globalnav翻译成*[@id='portal-globalnav']，把css:.mainNav翻译成*[contains(concat(' ', @class, ' '), ' mainNav ')]。理解这一点，就能避免 80% 的 XPath 报错。我在教团队新人时，会让他们先禁用css:前缀，全部用原生 XPath 写一遍，等熟悉了再切回css:——这就像学开车先练离合，再碰油门。

3.3 XSLT 变量与作用域：为什么xsl:variable不能“重新赋值”

XSLT 1.0 的变量是不可变的，这是函数式编程的核心特性，也是性能保障的基础。<xsl:variable name="count" select="1" />定义后，$count的值永远是 1，你无法写$count = $count + 1。这看似反直觉，但恰恰避免了状态混乱。在 Diazo 主题中，这影响最大的是计数场景。比如，需求是“给导航项编号：1. 首页，2. 关于我们，3. 联系我们”。新手常想：

<!-- 错误：XSLT 不支持变量重赋值 --> <xsl:variable name="i" select="0" /> <xsl:for-each select="//li"> <xsl:variable name="i" select="$i + 1" /> <!-- 语法错误！ --> <li><span><xsl:value-of select="$i" />.</span><xsl:apply-templates /></li> </xsl:for-each>

正确解法是用position()函数：

<xsl:for-each select="//li"> <li> <span><xsl:value-of select="position()" />.</span> <xsl:apply-templates /> </li> </xsl:for-each>

position()返回当前节点在for-each集合中的序号，天然满足计数需求。更复杂的场景，如“只给前 5 个导航项编号”，用position() <= 5即可。另一个常见需求是“提取 URL 路径名作为 class”。Plone 的<a href="/news/2023/article1">，想生成<a href="/news/2023/article1" class="article1">。这时要用substring-after：

<xsl:template match="a"> <a> <xsl:copy-of select="@*" /> <xsl:attribute name="class"> <xsl:value-of select="substring-after(@href, '/')" /> <!-- /news/2023/article1 -> news/2023/article1，还需进一步处理 --> <xsl:text>-</xsl:text> <xsl:value-of select="substring-after(substring-after(@href, '/'), '/')" /> <!-- news/2023/article1 -> 2023/article1，仍不理想 --> </xsl:attribute> <xsl:apply-templates /> </a> </xsl:template>

更好的是用tokenize（XSLT 2.0）？不行，Diazo 不支持。终极解法是substring-after嵌套 +substring-before：

<xsl:attribute name="class"> <xsl:variable name="path" select="substring-after(@href, '/')" /> <xsl:choose> <xsl:when test="contains($path, '/')"> <xsl:value-of select="substring-after($path, '/')" /> </xsl:when> <xsl:otherwise> <xsl:value-of select="$path" /> </xsl:otherwise> </xsl:choose> </xsl:attribute>

这段代码先取/后的子串，再判断是否还含/，决定取最后一段。虽然啰嗦，但 100% 兼容 XSLT 1.0，且性能稳定。

3.4 Diazo 特有的命名空间处理：xhtml:前缀不是装饰，是必需品

Diazo 的theme.html默认是 XHTML 文档，其根元素是<html xmlns="http://www.w3.org/1999/xhtml">。这意味着所有元素都在http://www.w3.org/1999/xhtml命名空间下。而 XSLT 处理带命名空间的 XML 时，必须声明并使用前缀。如果你写：

<xsl:template match="div[@id='header']"> ... </xslt>

它永远不会匹配成功，因为div实际是{http://www.w3.org/1999/xhtml}div。正确写法是：

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xhtml="http://www.w3.org/1999/xhtml" exclude-result-prefixes="xhtml"> <xsl:template match="xhtml:div[@id='header']"> ... </xsl:template> </xsl:stylesheet>

exclude-result-prefixes="xhtml"是为了防止输出 HTML 时带上冗余的xmlns:xhtml属性。这个细节在小型主题里可能不显眼，但在大型项目中，漏掉命名空间声明会导致整套规则静默失效——没有报错，只是不生效，排查起来极其痛苦。我在为某跨国企业做多语言主题时，就因忘记xmlns:xhtml，导致法语版的<div id="header">一直用着英文版的 theme，花了 3 小时才定位到。从此，我的rules.xml模板第一行永远是：

<rules xmlns="http://www.w3.org/1999/xhtml" xmlns:diazo="http://namespaces.plone.org/diazo" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

并确保所有xsl:template的match属性都带xhtml:前缀。这是 Diazo XSLT 开发的“安全带”，系好再出发。

4. 实操过程与核心环节实现：从零搭建一个高性能 XSLT 主题模块

4.1 实战案例：构建响应式导航栏（兼顾 Performance 与可维护性）

我们以 Plone 5.2 的默认导航为例，目标是：

• 桌面端：水平导航条，每项间加<li class="divider">
• 移动端：折叠为<select>下拉菜单
• 性能要求：渲染耗时 ≤ 100ms（实测基准）

第一步：分析 Plone 输出结构
访问http://yoursite.com/@@diazo-debug，找到导航部分：

<nav id="portal-globalnav" class="navTree navTreeLevel0"> <ul class="navTreeLevel0"> <li class="navItem navItem-1"> <a href="/" title="Go to the front page">首页</a> </li> <li class="navItem navItem-2"> <a href="/about" title="About us">关于我们</a> </li> </ul> </nav>

注意：<nav>是容器，<ul>是列表，<li>是项。

第二步：编写桌面端 XSLT（rules.xml片段）

<replace css:theme-children="#portal-globalnav"> <xsl:variable name="nav-items" select="//nav[@id='portal-globalnav']/ul/li" /> <ul class="nav navbar-nav"> <xsl:for-each select="$nav-items"> <xsl:if test="position() > 1"> <li class="divider"></li> </xsl:if> <li> <xsl:copy-of select="node()" /> </li> </xsl:for-each> </ul> </replace>

关键点：

• 用<xsl:variable>提前定义$nav-items，避免在for-each中重复计算 XPath，提升性能（实测快 12%）
• xsl:if test="position() > 1"控制 divider 插入时机，比xsl:for-each嵌套更简洁
• xsl:copy-of select="node()"复制<li>的所有子节点（即<a>），保留原有属性和事件绑定

第三步：编写移动端 XSLT（媒体查询驱动）
Diazo 本身不支持 CSS 媒体查询，但我们可以利用 Plone 注入的bodyclass。Plone 5+ 在响应式主题中会添加mobile或tabletclass：

<replace css:theme-children="#portal-globalnav" css:if-content="body.mobile"> <select class="nav-select"> <xsl:for-each select="//nav[@id='portal-globalnav']/ul/li"> <xsl:variable name="href" select="a/@href" /> <xsl:variable name="text" select="a/text()" /> <option value="{$href}"> <xsl:value-of select="$text" /> </option> </xsl:for-each> </select> </replace>

css:if-content="body.mobile"是 Diazo 的条件规则，只有当body元素包含mobileclass 时才执行此规则。这比用 JavaScript 检测屏幕宽度更可靠，因为它是服务端决策，无延迟。

第四步：性能验证与优化
在 Plone 后台开启@@diazo-performance（需安装plone.app.diazo），查看渲染耗时：

• 避免//li全局搜索，改用//nav[@id='portal-globalnav']/ul/li精确定位
• 用xsl:variable缓存 XPath 结果，减少lxml解析次数
• 删除所有xsl:copy（深拷贝），改用xsl:copy-of（浅拷贝），节省内存

4.2 实战案例：动态面包屑生成（解决结构错位与 SEO 友好）

Plone 默认面包屑是纯文本<div id="portal-breadcrumbs">首页 &gt; 关于我们 &gt; 团队介绍</div>，不利于 SEO 和无障碍访问。目标：

• 生成语义化<nav aria-label="Breadcrumb"><ol><li><a>首页</a></li>...</ol></nav>
• 当前页不加链接（符合 WCAG 2.1）
• 支持多级深度（不限 3 级）

XSLT 实现：

<replace css:theme="#portal-breadcrumbs"> <nav aria-label="Breadcrumb"> <ol> <xsl:for-each select="span"> <li> <xsl:choose> <!-- 最后一项：当前页，不加链接 --> <xsl:when test="position() = last()"> <xsl:value-of select="normalize-space(text())" /> </xsl:when> <!-- 其他项：加链接，href 从文本推导 --> <xsl:otherwise> <xsl:variable name="text" select="normalize-space(text())" /> <xsl:variable name="slug" select="translate($text, ' ', '-')" /> <a href="{concat('/', translate($slug, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz'))}"> <xsl:value-of select="$text" /> </a> </xsl:otherwise> </xsl:choose> </li> </xsl:for-each> </ol> </nav> </replace>

normalize-space()去除首尾空格和多余换行，translate()实现大小写转换和空格转短横线，这是 XSLT 1.0 处理字符串的“土办法”。虽然不如 Python 的slugify优雅，但足够可靠。

SEO 与无障碍增强：

• aria-label="Breadcrumb"让屏幕阅读器正确播报
• <ol>语义化列表，比<div>更利于搜索引擎理解层级
• 当前页无链接，避免用户误点刷新页面

4.3 实战案例：用户工具栏重构（处理动态内容与权限逻辑）

Plone 的#portal-personaltools包含登录态/游客态混合内容，结构不稳定。目标：

• 登录用户：显示“我的账户”、“退出”
• 游客：显示“登录”、“注册”
• 所有链接统一为<li><a>...</a></li>结构

XSLT 实现（利用 Plone body class）：

<replace css:theme-children="#portal-personaltools"> <xsl:choose> <!-- 检测 body class 是否含 'userrole-authenticated' --> <xsl:when test="contains(//body/@class, 'userrole-authenticated')"> <li><a href="/personalize">我的账户</a></li> <li><a href="/logout">退出</a></li> </xsl:when> <!-- 检测是否含 'userrole-anonymous' --> <xsl:when test="contains(//body/@class, 'userrole-anonymous')"> <li><a href="/login">登录</a></li> <li><a href="/register">注册</a></li> </xsl:when> <!-- 默认兜底 --> <xsl:otherwise> <li><a href="/login">登录</a></li> </xsl:otherwise> </xsl:choose> </replace>

//body/@class是 Diazo 编译时注入的黄金字段，它实时反映用户权限状态，比任何 JavaScript 判断都准。

注意事项：

提示：Plone 的 body class 可能包含多个角色，如userrole-authenticated userrole-member，所以必须用contains()而非=精确匹配。
注意：/logout链接需确保 Plone 后台已启用plone.app.users，否则 404。建议在rules.xml中加注释说明依赖。

5. 常见问题与排查技巧实录：那些年我们一起踩过的 XSLT 坑

5.1 XSLT 报错信息晦涩？三步定位法拯救你

Diazo 的 XSLT 错误信息 notoriously 不友好，比如XPath evaluation returned no nodes或Invalid expression。别慌，按这三步走：

第一步：确认错误发生在哪条规则
在rules.xml中，给每条 XSLT 规则加唯一id：

<replace id="nav-divider-rule" css:theme-children="#portal-globalnav"> ... </replace>

错误日志里会显示nav-divider-rule，快速定位。

第二步：简化 XPath 到最小可复现单元
假设报错在<xsl:for-each select="//nav[@id='portal-globalnav']/ul/li">，先简化为：

<xsl:for-each select="//nav"> <xsl:message>Found nav: <xsl:value-of select="@id" /></xsl:message> </xsl:for-each>

xsl:message会输出到 Plone 日志（var/log/instance.log），确认//nav能否匹配。如果没输出，说明//nav根本不存在，可能是 Plone 版本差异（4.x 用<div id="portal-globalnav">）。

第三步：用xsl:copy-of输出上下文
在报错规则前插入：

<xsl:template match="/"> <xsl:copy-of select="//nav[@id='portal-globalnav']" /> </xsl:template>

访问@@diazo-debug，看是否输出<nav>。如果输出为空，证明 XPath 写错了；如果输出有内容，证明问题在for-each内部逻辑。

这是我处理过最棘手的案例：某客户升级 Plone 5.2 后，所有 XSLT 规则失效。用三步法定位，发现 `//nav[@id='portal-globalnav