sgds-pattern-block-templates

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SGDS Block Templates

SGDS块模板

Reusable UI blocks that slot into any page layout. Each block is a self-contained section — drop it into a page template from sgds-pattern-page-templates to assemble complete pages without writing layout code from scratch.

可嵌入任意页面布局的可复用UI块。每个块都是独立的区块，你可以将其插入**sgds-pattern-page-templates**的页面模板中，无需从零编写布局代码即可组装出完整页面。

What is a block?

什么是块？

A block is a chunk of UI that:

Has a single, focused responsibility (filter content, display a stat, show a form section)
Works standalone inside any container
Can appear multiple times on a page or alongside other blocks

The Application Shell is a special mandatory block — it is the page chrome (

<sgds-masthead>

<sgds-mainnav>

<sgds-footer>

) that every SGDS page must include. All other blocks are content blocks that slot inside the shell.

Blocks are the ingredients. Page templates are the recipes.

块是满足以下条件的UI片段：

具备单一、明确的职责（筛选内容、展示统计数据、显示表单区块）
可在任意容器内独立运行
可在同一页面多次出现，也可与其他块并排使用

**Application Shell（应用外壳）**是特殊的必填块，它是每个SGDS页面都必须包含的页面外框（

<sgds-masthead>

、

<sgds-mainnav>

、

<sgds-footer>

）。其余所有块都是可嵌入外壳内的内容块。

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

Prerequisites

前置依赖

javascript

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

See sgds-components for full installation details.

javascript

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**获取完整安装说明。

Quick Decision Guide

快速选择指南

What you need	Block to use
Mandatory page chrome (masthead, mainnav, footer, container) for any SGDS page	Application Shell
Page-level header with breadcrumb, icon + title, description, and primary CTA	Page Header
Read-only entity summary card with key-value fields and an edit action	Basic Details Card
Sidebar panel that filters content by category using checkboxes	Filter Sidebar — Checkbox
Full detail view of a single event session: time, title, speaker, badges, description, profile	Session Detail
Search input + filter button + results count + data table for list and admin pages	Table Filter

所需功能	对应使用的块
任意SGDS页面必填的页面外框（页头、主导航、页脚、容器）	应用外壳
包含面包屑、图标+标题、描述和主CTA的页面级头部	页面头部
带键值字段和编辑操作的只读实体摘要卡片	基础详情卡片
使用复选框按类别筛选内容的侧边栏面板	复选框筛选侧边栏
单场活动环节的完整详情视图：时间、标题、讲者、标签、描述、简介	环节详情
用于列表和管理页面的搜索框+筛选按钮+结果计数+数据表格	表格筛选器

→ Read reference/application-shell.md

→ 查看 reference/application-shell.md

Required for every page. The application shell wraps all page content with the mandatory Singapore Government chrome:

<sgds-masthead>

<sgds-mainnav>

, and

<sgds-footer>

. Provides two layout variants — Simple App (

.sgds-container

, public-facing) and Sidebar App (

.sgds-container-sidebar

, dashboards and internal tools) — with full breakpoint tables and sticky-header patterns.

所有页面必填。 应用外壳用新加坡政府要求的必填外框包裹所有页面内容：

<sgds-masthead>

、

<sgds-mainnav>

和

<sgds-footer>

。提供两种布局变体——简单应用（

.sgds-container

，面向公众）和侧边栏应用（

.sgds-container-sidebar

，仪表盘和内部工具）——包含完整的断点表和粘性头部模式。

→ Read reference/page-header.md

→ 查看 reference/page-header.md

Breadcrumb trail + icon-tinted container + h1 heading + description + primary CTA button. Use at the top of any content page to orient the user and surface the primary action.

包含面包屑路径、带图标背景的容器、h1标题、描述和主CTA按钮。可用于任意内容页面的顶部，帮助用户定位并展示核心操作。

→ Read reference/basic-details.md

→ 查看 reference/basic-details.md

Bordered card with a subtitle heading, stacked key-value field pairs, and an optional edit button. Use to display read-only entity metadata (IDs, names, descriptions, contact info) on detail or profile pages.

带副标题、堆叠键值字段对和可选编辑按钮的带边框卡片。用于在详情页或个人资料页展示只读的实体元数据（ID、名称、描述、联系方式）。

→ Read reference/filter-sidebar-checkbox.md

→ 查看 reference/filter-sidebar-checkbox.md

Vertical filter panel with grouped

sgds-checkbox-group

sections and a "Clear all" link. Use when content (cards, table rows, event listings) needs to be narrowed by one or more categorical dimensions.

垂直筛选面板，包含分组的

sgds-checkbox-group

区块和「全部清除」链接。当需要按一个或多个分类维度缩小内容（卡片、表格行、活动列表）范围时使用。

→ Read reference/session-detail.md

→ 查看 reference/session-detail.md

Full session detail block for event and conference websites. Shows time slot, session title with expand/collapse, speaker attribution, outlined classification badges, description, circular speaker photo with name and role, and a divider. Repeat for each session in a programme listing.

适用于活动和会议网站的完整环节详情块。展示时间段、支持展开/收起的环节标题、讲者署名、轮廓分类标签、描述、带姓名和职位的圆形讲者头像，以及分隔线。可在节目列表中为每个环节重复使用。

→ Read reference/table-filter.md

→ 查看 reference/table-filter.md

Page header + search input + outline filter button + results count + data table. Use on list and admin pages where users search or filter tabular records. Table cells support

sgds-link

sgds-badge

, and

sgds-button

for rich row content.

页面头部+搜索框+轮廓筛选按钮+结果计数+数据表格。用于用户需要搜索或筛选表格记录的列表页和管理页。表格单元格支持

sgds-link

、

sgds-badge

和

sgds-button

，可实现丰富的行内容。

Composing blocks with page templates

将块与页面模板组合

Blocks live inside the content area of a page template. The typical pattern:

html

<!-- Page template provides the chrome -->
<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">

    <!-- Two-column layout: block on the left, content on the right -->
    <div class="sgds:flex sgds:gap-layout-md sgds:items-start">

      <!-- Drop the block here -->
      <aside class="sgds:shrink-0 sgds:w-64">
        <!-- Filter Sidebar block -->
      </aside>

      <!-- Content area -->
      <div class="sgds:flex-1">
        <!-- Cards, table, results, etc. -->
      </div>

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

<sgds-footer></sgds-footer>

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

html

<!-- Page template provides the chrome -->
<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">

    <!-- Two-column layout: block on the left, content on the right -->
    <div class="sgds:flex sgds:gap-layout-md sgds:items-start">

      <!-- Drop the block here -->
      <aside class="sgds:shrink-0 sgds:w-64">
        <!-- Filter Sidebar block -->
      </aside>

      <!-- Content area -->
      <div class="sgds:flex-1">
        <!-- Cards, table, results, etc. -->
      </div>

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

<sgds-footer></sgds-footer>

Building Custom Blocks

构建自定义块

Users are free to design their own blocks with full creative latitude — layout, composition, and visual hierarchy are all open. The only constraint is that every block must stay within the SGDS system rails:

Requirement	How
UI components	Use `<sgds-*>` web components. Do not reach for plain HTML equivalents when an SGDS component exists (e.g. use `<sgds-badge>` , not a hand-rolled `<span>` chip).
Styling	Use `sgds:` Tailwind utilities exclusively for colours, spacing, typography, and layout. Do not write arbitrary CSS values that duplicate what the design token system already expresses.
Typography	Use semantic role tokens ( `sgds:text-heading-md` , `sgds:text-body-md` , `sgds:text-overline-md` , etc.) paired with matching weight, line-height, and tracking tokens. Do not use raw scale tokens ( `sgds:text-base` , `sgds:text-sm` ) which are not part of the public API.
Icons	Use `<sgds-icon name="...">` exclusively. Do not embed raw SVG or third-party icon libraries.
External inspiration	Fine to reference sites like shadcnblocks.com, Tailwind UI, or any other design gallery for layout ideas — but always re-implement using SGDS components and tokens, not the source site's CSS or component library.

→ Read reference/custom-block-rules.md for the full token reference, anti-patterns, and annotated examples.

用户可自由设计自己的块，布局、组合和视觉层级都完全开放。唯一限制是所有块必须符合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**获取完整的令牌参考、反模式和带注释的示例。

For AI agents

给AI Agent的说明

Every page must have the Application Shell —
```
<sgds-masthead>
```
,
```
<sgds-mainnav>
```
, and
```
<sgds-footer>
```
are mandatory on every SGDS page. Read reference/application-shell.md for layout patterns and container classes.
When a user asks for a filtered list page, combine the Filter Sidebar block with the List Page template from sgds-pattern-page-templates.
Adapt category labels, values, and counts to the user's actual data domain — do not copy the conference example verbatim.
When a user says "I want to build a custom block" or references an external design (shadcnblocks, Figma, screenshot), read reference/custom-block-rules.md before generating any output.

每个页面必须包含应用外壳——
```
<sgds-masthead>
```
、
```
<sgds-mainnav>
```
和
```
<sgds-footer>
```
是每个SGDS页面的必填项。查看**reference/application-shell.md**获取布局模式和容器类说明。
当用户需要带筛选的列表页时，将筛选侧边栏块与**sgds-pattern-page-templates**中的列表页模板组合使用。
请根据用户实际的数据领域调整分类标签、值和计数——不要直接照搬会议示例。
当用户表示「我想构建自定义块」或参考外部设计（shadcnblocks、Figma、截图）时，在生成任何输出前请先查看**reference/custom-block-rules.md**。