Facet 开发者文档

Facet 是 FaceFlow 用于动态渲染的模板层。

它为技术用户提供了一种受控的方式来输出值、组合可复用的模板片段、使用循环与条件，并在 PageFace 内构建动态显示逻辑。

Facet 的用途

• 组件模板
• 变量模板
• 动态列表输出
• 共享内容渲染
• 上下文感知的页面输出

Facet 不是整个 FaceFlow 系统。它是其中的渲染语言。FaceFlow 定义对象与契约。Facet 定义这些对象如何安全地渲染动态输出。

核心能力

技术用户通常依赖 Facet 来实现：

• 转义和原始输出
• 条件语句与循环块
• 页面感知与查询感知的渲染
• 过滤链与格式化
• 变量嵌入
• 在可重用对象内安全地组合模板

Facet 与 FaceFlow 的区别

请明确区分：

• FaceFlow 定义诸如页面、组件、变量、列表、表单和评论等对象
• Facet 定义这些对象如何渲染动态输出

如果技术用户在决定要创建哪种对象，那就是 FaceFlow 的设计范畴。

如果他们在决定现有对象应如何渲染字段、条件和循环，那就是 Facet 的范畴。

出现位置

Facet 常出现在：

• 组件的 HTML 模板
• 变量模板
• 列表项模板
• 需要运行时上下文的小型动态片段

一个简单示例：

<section class="hero">
  <h1>{{ title }}</h1>

  {{#if summary}}
    <p>{{ summary }}</p>
  {{/if}}

  [[sales-contact-badge]]
</section>

该示例展示了最常见的思维模型：

• FaceFlow 对象提供契约
• Facet 提供渲染逻辑

Facet 不应做的事

Facet 很强大，但不应取代良好的对象建模。

不要使用 Facet 来：

• 用模板技巧来掩盖薄弱的内容结构
• 把一个模板变成业务工作流引擎
• 当问题本质上是基于查询的内容时，用手写的归档逻辑替代列表
• 用模板模拟本应为组件的大型可编辑模式

如何学习 Facet

建议的学习路径：

1. 从 模板语法 开始
2. 继续阅读 参考
3. 然后回到拥有你正在编辑模板的 FaceFlow 对象上

之所以按此顺序，是因为语法优先，其次是更深的模式，最后是面向对象的具体应用。

常见用例

当技术用户需要以下场景时，通常会使用 Facet：

• 清晰显示可选字段
• 遍历重复内容
• 格式化与页面相关的值
• 嵌入可复用的变量
• 在不使用原始平台代码的情况下构建归档和列表模板

常见错误

技术用户最常在以下情况下遇到问题：

• 把过多逻辑塞入一个模板
• 将重复片段视为复制的标记而不是一个变量
• 用条件语句来弥补不明确的字段模型
• 在本应为列表的情况下在组件中构建动态归档
• 忘记可读性是模板质量的一部分

设计指导

• 保持模板可读
• 保持业务逻辑浅显
• 优先使用良好的对象建模，而非巧妙的模板技巧
• 对重复片段使用变量，而不是复制标记
• 当问题是动态内容选择而不仅仅是展示时，使用列表

决策捷径

当问题类似于以下情况时，请使用 Facet：

• “这个字段应该如何渲染？”
• “该部分是否应仅在存在数据时显示？”
• “我如何遍历这些项？”
• “我如何重用这个小片段？”

当问题实际上是以下情形时，不要仅停留在 Facet：

• “这应该是组件还是变量？”
• “这些内容应该是一个列表吗？”
• “这应该属于布局还是页面？”

相关

• FaceFlow 组件
• FaceFlow 变量
• FaceFlow 列表
• 模板语法
• 参考