变量 开发者文档

变量是可重用的、由模板驱动的片段，在 FaceFlow 管理的上下文中渲染。

对于技术使用者来说，变量是 FaceFlow 中最轻量的重用原语之一。当输出需要在布局、组件、列表或其他渲染表面之间共享，但又不想引入完整的组件（Component）模式时，变量是合适的选择。

核心职责

变量负责：

• 可重用的模板输出
• 可选的 CSS 和客户端行为
• 通过属性进行的简单参数化
• 上下文感知的渲染
• 针对重复输出的缓存感知交付

当重用单元比组件小但比复制的标记更持久时使用变量。

变量模型

一个典型的变量包括：

• 稳定的标识
• 一个 Facet 模板
• 可选的 CSS
• 可选的 JavaScript
• 可选的属性
• 分类和描述元数据
• 缓存模式

概念上：

{
  "name": "copyright-notice",
  "title": "Copyright Notice",
  "category": "footer",
  "cacheMode": "auto",
  "attributes": [
    { "name": "company", "default": "PageFace" }
  ],
  "html": "<p>&copy; {{ now.year }} {{ attr.company }}</p>",
  "css": ".copyright { color: #64748b; }",
  "js": ""
}

具体的存储实现是内部细节。上面的契约对技术作者来说才是重要的部分。

嵌入语法

变量通过双中括号语法嵌入：

[[copyright-notice]]

带属性的示例：

[[copyright-notice company="Acme Inc"]]

变量也可以嵌入到其他模板中：

<footer class="site-footer">
  [[copyright-notice company="Acme Inc"]]
</footer>

在嵌入语法中，属性值应作为带引号的字面量传入。

如果变量需要页面感知或运行时感知的行为，请在变量模板内部从渲染上下文读取，而不是试图在属性列表中注入未加引号的表达式。

属性模型

属性是在渲染时传递给变量的命名输入。

它们适用于：

• 文案变体
• 标签
• 简单的视觉选项
• 小型业务特定的值

示例：

[[cta-badge label="New" tone="accent"]]

模板用法：

<span class="badge badge-{{ attr.tone | default('neutral') }}">
  {{ attr.label }}
</span>

属性应保持轻量。如果重用单元需要大型可编辑的 schema，通常应该使用组件（Component）。

混合字面属性与运行时上下文的安全示例：

<span class="badge badge-{{ attr.tone | default('neutral') }}">
  {{ attr.label | default(page.title) }}
</span>

渲染上下文

变量可以针对更广泛的运行时上下文进行渲染。常见的上下文对象包括：

• page
• user
• pages
• site
• languages / lang
• now
• attr

示例：

<p class="eyebrow">
  {{ page.title }} updated {{ now.year }}
</p>

或者基于查询的示例：

<ul class="recent-posts">
  {{#pages selector="template=blog-post, sort=-published, limit=3" as="item"}}
    <li><a href="{{ item.url }}">{{ item.title }}</a></li>
  {{/pages}}
</ul>

这使得变量对于小型动态片段非常有用，而无需完整的列表或组件。

支持的放置位置

变量通常用于：

• 布局模板
• 组件模板
• 列表模板
• 其他变量
• 通过 FaceFlow 渲染的受支持内容表面

典型示例：

[[site-announcement]]
[[page-breadcrumbs]]
[[recent-posts title="From the blog"]]

嵌套

变量可以引用其他变量：

<div class="footer-meta">
  [[social-links]]
  [[copyright-notice company="PageFace"]]
</div>

当嵌套能提升清晰度时是有用的。避免产生让调试或变更影响难以判断的深层链式嵌套。

缓存模式

变量支持多种缓存策略。

自动

适用于大多数情况。运行时会根据渲染需求决定是使用静态还是动态行为。

静态

当输出不依赖于变化的用户、时间或请求敏感上下文时使用。

动态

当输出依赖于频繁变化的上下文且不应表现为完全缓存友好的片段时使用。

示例决策规则：

current year footer -> auto
simple shared legal text -> static
logged-in user greeting -> dynamic

性能指导

变量通常被广泛重用，因此性能纪律很重要。

• 除非确有必要，否则优先使用 auto 或 static
• 避免在跨多个页面使用的片段中执行昂贵的查询
• 将广泛共享的变量视为性能敏感的资产
• 在编辑被大量重用的变量之前审查变更影响

预览与测试

测试变量时，请检查：

• 使用真实属性的渲染
• 在实际页面或组件上下文中的行为
• 在预期缓存模式下的输出
• 如果涉及组合，检查嵌套变量的行为

示例测试模式：

[[cta-badge label="Launch Ready" tone="success"]]
[[cta-badge label="New" tone="accent"]]

何时使用变量

当满足以下条件时使用变量：

• 片段在多个地方重用
• 结构小且稳定
• 输入有限
• 输出需要上下文感知

不应在以下情况下使用变量：

• 内容仅对某一页面唯一
• 需要完整的可编辑 schema
• 结构足够大，应作为可重用的节（section）
• 输出更像是动态存档而不是片段

反模式

避免：

• 将变量变成迷你页面
• 在单个变量内隐藏大型业务流程
• 添加过多属性来模拟组件 schema
• 拥有不明确归属的深层嵌套变量链
• 在没有真实需要的情况下默认使用 dynamic 缓存模式

示例构建模式

小型实用片段：

[[copyright-notice company="PageFace"]]

页面感知的可重用片段：

<aside class="page-summary">
  <h3>{{ page.title }}</h3>
  <p>{{ page.summary }}</p>
</aside>

基于查询的小部件：

<div class="resource-count">
  {{ pages.count selector="template=resource-item" }} resources
</div>

相关

• Facet
• 组件
• 列表
• 变量产品概览