sgds-blocks

SGDS 区块模板

可重复使用的 UI 区块，可插入任何页面布局。每个区块都是独立的页面部分——将其放入 sgds-templates 中的页面模板，即可组装完整页面，无需从头编写布局代码。

什么是区块？

区块是一段 UI，具有以下特点：

• 职责单一且明确（筛选内容、显示统计数据、展示表单部分或创建主视觉横幅）
• 可独立用于任何容器中
• 可在页面上多次出现，也可与其他区块搭配使用

应用框架是一个特殊的必需区块——它是页面外壳（<sgds-masthead>、<sgds-mainnav>、<sgds-footer>），每个 SGDS 页面都必须包含这些元素。其他区块都是可插入框架的内容区块。

区块是素材，页面模板是配方。

前置条件

import "@govtechsg/sgds-web-component/themes/day.css";
import "@govtechsg/sgds-web-component/css/sgds.css";
import "@govtechsg/sgds-web-component/css/utility.css";

有关完整安装详情，请参阅 sgds-components。

---

快速选择指南

需求	使用的区块
适用于任何 SGDS 页面的必需页面外壳（masthead、mainnav、footer、container）	应用框架
带有标题、描述、CTA 按钮和可选图片的全宽主视觉部分	主视觉
带有图片／组件定位和网格比例的功能展示部分	功能展示
行动号召部分（主要、凸起、替代、居中或全宽）	CTA
统计数据展示（3、4、5 或 6 列）	统计数据
卡片网格布局（3 列或 4 列）	卡片
页面级页眉，包含面包屑、图标 + 标题、描述和主要 CTA	页面页眉
只读实体摘要卡片，包含键值字段和编辑操作	基本详情卡片
筛选界面和搜索结果布局	筛选器
多字段表单，具有恰当的组件尺寸、分组和布局规则	表单

---

→ 阅读 reference/application-shell.md

每个页面都必须使用。 应用框架使用必需的新加坡政府页面外壳包裹所有页面内容：<sgds-masthead>、<sgds-mainnav> 和 <sgds-footer>。提供两种布局变体——简易应用（.sgds-container，面向公众）和侧边栏应用（.sgds-container-sidebar，适用于仪表板和内部工具），并附有完整的断点表和固定页眉模式。

---

→ 阅读 reference/hero.md

提供多种布局和背景选项的主视觉部分。适用于着陆页、活动页面或章节介绍中首屏可见的内容。

---

→ 阅读 reference/feature.md

带有图片／组件定位和网格比例的功能展示部分。用于突出产品的主要优势、能力或功能。

---

→ 阅读 reference/cta.md

提供多种样式和对齐选项（主要、凸起、替代、居中、容器内或全宽）的行动号召部分。用于在整个页面中引导用户采取行动。

---

→ 阅读 reference/stats.md

统计数据展示，提供多种列数（3、4、5 或 6 列，并可选右对齐变体）。用于展示关键指标、成就或影响数据。

---

→ 阅读 reference/cards.md

卡片组件的网格布局（3 列或 4 列）。用于以结构化的卡片网格展示一组内容。

---

→ 阅读 reference/page-header.md

面包屑导航 + 图标着色容器 + h1 标题 + 描述 + 主要 CTA 按钮。用于任何内容页面的顶部，帮助用户了解当前位置并突出主要操作。

→ 阅读 reference/basic-details.md

带边框的卡片，包含副标题、纵向排列的键值字段对，以及可选的编辑按钮。用于在详情页或个人资料页中展示只读的实体元数据（ID、名称、描述、联系信息）。

---

→ 阅读 reference/filter.md

筛选界面和搜索结果布局。用于高级筛选和搜索结果展示。

---

→ 阅读 reference/form.md

表单布局规则：网格计算、组件配对、验证反馈和标准模式。 所有表单都使用包含 12 列的 .sgds-grid。表单容器宽 8 列（靠左或居中对齐）。配对字段各占 6 列（每行最多 2 个）。全宽字段（textarea、checkbox-group、radio-group、file-upload）始终跨越 12 列。包含 5 种可复用模式：仅全宽字段、配对字段、混合布局、多分区和侧边栏导航。

---

使用页面模板组合区块

区块位于页面模板的内容区域中。典型模式：

<sgds-masthead></sgds-masthead>
<sgds-mainnav>...</sgds-mainnav>

<div class="sgds:bg-surface-default sgds:min-h-screen">
  <div class="sgds:w-container sgds:mx-auto sgds:py-layout-md">

    
    <div class="sgds:flex sgds:gap-layout-md sgds:items-start">

      
      <aside class="sgds:shrink-0 sgds:w-64">
        
      </aside>

      
      <div class="sgds:flex-1">
        
      </div>

    </div>
  </div>
</div>

<sgds-footer></sgds-footer>

---

编写表单代码前

表单较为复杂，因为 SGDS 组件有特定的限制。请先阅读 reference/form.md — 其中包含所有网格计算、组件配对规则、5 种标准模式和定位变体。

验证组件 API

阅读你使用的每个 <sgds-*> 元素的组件参考文档：

• 子元素命名：每个组件都有特定的子元素名称。<sgds-select> 使用 <sgds-select-option>（而非 <sgds-option>）。<sgds-combo-box> 使用 <sgds-combobox-option>。请务必查看 sgds-components skill 参考文档。
• 插槽要求：<sgds-file-upload> 插槽要求提供文本标签（不能只有图标）。请确认组件是否需要子元素、插槽内容或 JS 属性。
• 可选属性：<sgds-stepper> 使用 JS 属性（steps 数组），而非 <sgds-stepper-item> 这类 HTML 子元素。请确认哪些组件接受属性，哪些接受 JS 属性。

表单专用限制

根据 reference/form.md：

• .sgds-container 中的表单恰好占 8 列
• 可配对字段（Input、Select、Datepicker、Combo-box 单选）：在 lg+ 断点各占 6 列（在 sm 断点占 4 列）
• 全宽字段（Textarea、Checkbox-group、Radio-group、Combo-box 多选、File-upload）：始终占 12 列
• 网格计算：sidebar_cols + form_cols + toc_cols ≤ 12
• 多选 combo-box：⚠️ 重要 — 必须全宽，绝不能与任何其他组件配对

编码前务必对照 reference/form.md 进行核验。

构建自定义区块

用户可以充分发挥创意，自由设计自己的区块——布局、构图和视觉层级均不受限制。唯一的约束是，每个区块都必须遵循 SGDS 系统规范：

要求	方式
UI 组件	使用 <sgds-*> Web 组件。如果存在 SGDS 组件，请勿使用普通 HTML 替代（例如，使用 <sgds-badge>，而不是手动制作 <span> 标签作为徽章）。
样式	颜色、间距、排版和布局一律使用 sgds: Tailwind 工具类。请勿编写与设计令牌系统已有表达重复的任意 CSS 值。
排版	使用语义角色令牌（sgds:text-heading-md、sgds:text-body-md、sgds:text-overline-md 等），并搭配匹配的字重、行高和字间距令牌。请勿使用不属于公共 API 的原始比例令牌（sgds:text-base、sgds:text-sm）。
图标	仅使用 <sgds-icon name="...">。请勿嵌入原始 SVG 或第三方图标库。
外部灵感	可以参考 shadcnblocks.com、Tailwind UI 或其他设计图库中的布局创意，但务必使用 SGDS 组件和令牌重新实现，不要使用源网站的 CSS 或组件库。

→ 阅读 reference/custom-block-rules.md，了解完整的令牌参考、反模式和注释示例。

---

面向 AI Agent

⚠️ 关键规则——务必先加载以下技能

编写任何区块代码之前：

1. 加载 sgds-utilities 技能——你需要完整的工具类参考
2. 加载 sgds-components 技能——你需要组件 API 和子元素名称
3. 然后阅读此技能中的 reference/custom-block-rules.md

样式规则（适用于所有区块）：

• 间距、颜色、排版和布局一律使用 sgds: Tailwind 工具类
• UI 元素一律使用 <sgds-*> 组件
• 切勿使用内联 <style> 块来复刻设计令牌（例如，margin: 24px、var(--sgds-*)）
• 切勿编写与设计令牌已有表达重复的任意 CSS

如果你没有先加载工具类和组件，就会默认使用内联样式，从而破坏设计系统。这是 Agent 编写区块时最常见的错误。

---

Agent 工作流（按顺序）

1. 加载 sgds-utilities 技能
2. 加载 sgds-components 技能
3. 加载此技能
4. 阅读 reference/custom-block-rules.md
5. 然后使用工具类和组件编写区块代码

指南

1. 每个页面都必须包含应用外壳——每个 SGDS 页面都必须包含 <sgds-masthead>、<sgds-mainnav> 和 <sgds-footer>。阅读 reference/application-shell.md，了解布局模式和容器类。
2. 用户要求创建筛选列表页时，将筛选侧边栏区块与 sgds-templates 中的列表页模板组合使用。
3. 根据用户的实际数据领域调整类别标签、数值和数量——不要原样照搬会议示例。
4. 用户提出“我想构建一个自定义区块”或引用外部设计（shadcnblocks、Figma、截图）时，生成任何内容之前都要阅读 reference/custom-block-rules.md。