sgds-pattern-block-templates

SGDS 区块模板

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

什么是区块？

区块是一段 UI，它：

• 只负责一项明确的任务（筛选内容、显示统计数据、展示表单部分）
• 可在任何容器中独立使用
• 可在页面上多次出现，也可与其他区块并列

Application Shell 是一个特殊的必需区块——它是每个 SGDS 页面都必须包含的页面框架（<sgds-masthead>、<sgds-mainnav>、<sgds-footer>）。其他所有区块都是嵌入框架内的内容区块。

区块是食材，页面模板是菜谱。

先决条件

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）	Application Shell
包含面包屑、图标 + 标题、描述和主要 CTA 的页面级页眉	Page Header
包含键值字段和编辑操作的只读实体摘要卡片	Basic Details Card
使用复选框按类别筛选内容的侧边栏面板	Filter Sidebar — Checkbox
单个活动场次的完整详情视图：时间、标题、演讲者、徽章、描述、个人资料	Session Detail
适用于列表和管理页面的搜索输入框 + 筛选按钮 + 结果数量 + 数据表格	Table Filter

---

→ 阅读 reference/application-shell.md

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

---

→ 阅读 reference/page-header.md

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

---

→ 阅读 reference/basic-details.md

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

---

→ 阅读 reference/filter-sidebar-checkbox.md

纵向筛选面板，包含分组的 sgds-checkbox-group 部分和“全部清除”链接。适用于需要按一个或多个类别维度筛选内容（卡片、表格行、活动列表）的情况。

---

→ 阅读 reference/session-detail.md

适用于活动和会议网站的完整场次详情区块。显示时间段、支持展开/折叠的场次标题、演讲者署名、描边分类徽章、描述、带姓名和职位的圆形演讲者照片，以及分隔线。在活动日程列表中为每个场次重复使用。

---

→ 阅读 reference/table-filter.md

页面页眉 + 搜索输入框 + 描边筛选按钮 + 结果数量 + 数据表格。适用于用户需要搜索或筛选表格记录的列表页和管理页面。表格单元格支持使用 sgds-link、sgds-badge 和 sgds-button 展示丰富的行内容。

---

使用页面模板组合区块

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

<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 系统规范：

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