组件开发者文档

组件是通过 FaceFlow 渲染的、由模式驱动的网站区域。

对于技术用户，组件是系统中核心的可重用分区契约。它们结合了字段定义、Facet 模板输出、可选样式、可选客户端行为以及具有作用域感知的重用能力。

核心职责

组件负责：

定义一个可重用的分区契约
暴露受控的编辑模式(schema)
通过 Facet 渲染输出
可选地附加作用域样式和行为
支持在页面、布局或站点级别的重用

组件应当解决可重复出现的分区问题。它们不应成为任意页面特定标记的松散容器。

组件定义模型

典型的组件定义包括：

{
  "name": "contact-section",
  "title": "Contact Section",
  "version": "1.0.0",
  "type": "component",
  "category": "contact",
  "defaultScope": "page",
  "description": "Contact section with CTA and embedded form support",
  "fields": [
    { "name": "title", "label": "Title", "type": "text" },
    { "name": "summary", "label": "Summary", "type": "textarea" },
    { "name": "contactForm", "label": "Form", "type": "formSelect" }
  ],
  "html": "<section><h2>{{ title }}</h2><p>{{ summary }}</p><div data-form-embed=\"{contactForm}\"></div></section>",
  "style": ".contact-section { padding: 4rem 0; }",
  "script": "/* optional behavior */"
}

该模型使组件能够像受管控的分区契约而不是一段松散复制的代码片段那样工作。

核心元数据

重要的元数据字段包括：

name
title
version
type
category
defaultScope
description

指导建议：

在发布后保持 name 的稳定
使用 title 提升编辑器中的清晰度
在模式或渲染行为发生变化时有意地更新 version
根据预期的重用情况选择 defaultScope，而不是为了方便而选择

字段架构

字段架构定义了作者在不改变分区结构的前提下可以更改的内容。

顶层支持的字段类型包括：

text
textarea
number
url
date
image
images
file
select
checkbox
richtext
htmlcode
map
repeater
formSelect
reviewSelect

在 repeater 内可以使用的额外子字段类型包括：

color
email
tel
range

示例：

{
  "name": "faqItems",
  "label": "FAQ Items",
  "type": "repeater",
  "fields": [
    { "name": "question", "type": "text" },
    { "name": "answer", "type": "textarea" }
  ]
}

按内容意图选择字段类型，而不是出于方便考虑。url 应保持为 URL。重复的卡片集合应使用 repeater，而不是若干不相关的文本字段。

参见完整字段参考：

模板模型

组件的 html 部分通过 Facet 渲染。

这意味着模板可以使用：

字段输出
条件语句
循环
过滤器
页面感知的上下文
可重用变量

示例：

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

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

    {{#if ctaUrl}}
      <a href="{{ ctaUrl }}" class="btn-primary">{{ ctaLabel }}</a>
    {{/if}}
  </div>
</section>

或使用重复器：

<div class="faq-list">
  {{#each faqItems as="item"}}
    <article class="faq-item">
      <h3>{{ item.question }}</h3>
      <p>{{ item.answer }}</p>
    </article>
  {{/each}}
</div>

语法详情参见：

作用域模型

组件可以存在于三种重用级别：

site
layout
page

概念上：

site scope   -> reusable across the broader site
layout scope -> shared inside one page family
page scope   -> local to one page

作用域决定了可见性和更改影响范围。如果组件在 site 作用域发生更改，那是一项广泛的架构性更改，而不是本地编辑。

关于更广泛模型：

作用域系统

渲染行为

在渲染时，FaceFlow 通过组合以下内容来解析组件实例：

组件定义
已保存的字段值
当前渲染上下文
相关的运行时服务（如媒体、变量、表单和评论）

概念上：

component definition
  + saved field values
  + runtime context
  -> Facet render
  -> final section output

这是字段数据变为运行时标记的时刻。

样式与行为

组件可以附加可选样式和可选行为。

示例：

.pricing-card {
  border-radius: 1rem;
  padding: 2rem;
}

document.querySelectorAll('.faq-item button').forEach((button) => {
  button.addEventListener('click', () => {
    button.closest('.faq-item').classList.toggle('is-open');
  });
});

谨慎使用。大多数分区行为应保持简单、可预测且易于维护。

组件中的表单与评论

对于交互性分区，有两种字段类型特别重要：

formSelect
reviewSelect

它们允许组件嵌入业务工作流，而无需硬编码某一特定模型。

典型标记：

<div data-form-embed="{contactForm}"></div>
<div data-review-embed="{serviceReview}"></div>

这使分区在可重用的同时，允许在编辑时更改所选的表单或评论模型。

示例组件模式

基本内容分区：

fields:
  title
  summary
template:
  heading + paragraph

FAQ 分区：

fields:
  faqItems repeater
template:
  each item -> question + answer

潜在客户收集分区：

fields:
  title
  summary
  contactForm (formSelect)
template:
  copy + data-form-embed marker

技术评审清单

该组件是否解决了一个可重复的分区问题？
字段架构是否清晰且有意图？
模板是否可读且稳定？
为预期重用选择的作用域是否正确？
将来编辑者是否仅凭字段契约就能理解如何使用它？

反模式

避免：

在一个组件上承担不相关的用例
添加本应在分区契约之外的页面特定业务逻辑
在可用结构化字段模型更安全时使用 htmlcode
仅因为以后可能重用就扩大作用域
在已有内容存储后重命名字段

何时拆分组件

当出现以下情况时拆分组件：

字段架构变得过于宽泛
多个布局或页面上下文需要冲突的版本
模板充斥例外情况和一次性分支
编辑者不再理解该分区应做什么

如果契约不再清晰，重用通常也会失去价值。

FaceFlow Components