sgds-layouts

SGDS 布局

可用于生产环境的页面布局模式，用于定义 Application Shell 内部内容区域的排列方式。每种布局都结合了 SGDS 组件和实用类，提供结构化的起点——放入内容块即可构成完整页面。

什么是布局？

布局定义页面上各内容区域的空间排列方式：

• 内容列的数量（单列、分栏、侧栏 + 主内容区）
• 导航的位置（仅顶部或侧边栏）
• 页面滚动方式（文档流或限制在视口内）

布局位于 Application Shell（必需的页面框架）和 Blocks/Templates（实际内容）之间。Shell 包裹布局；内容块填充布局中的内容区域。

先决条件

实现任何布局之前，请确保已具备：

1. sgds-getting-started：应用初始设置（Inter 字体、基础 CSS 导入、组件注册）
2. sgds-utilities：了解 SGDS 实用类（网格、间距、弹性布局等）
3. sgds-components：了解 SGDS Web 组件（masthead、mainnav、footer、sidebar）

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-getting-started 和 sgds-components。

---

快速选择指南

要构建的内容	布局类别	使用的布局
面向公众的简单页面，包含单个内容区域	Full Width	Default
带左侧侧栏/辅助面板的页面（4/8 分栏）	Full Width	Aside Left
带右侧侧栏/辅助面板的页面（8/4 分栏）	Full Width	Aside Right
同时带左、右辅助面板的页面（3/6/3 分栏）	Full Width	Aside Both
两个并排的等宽内容面板	Full Width	Split
带面包屑导航栏的页面	Full Width	Breadcrumb
仪表板/内部工具，包含单个内容区域	With Sidebar	Default
带左侧辅助面板的仪表板	With Sidebar	Aside Left
带右侧辅助面板的仪表板	With Sidebar	Aside Right
带面包屑的可折叠覆盖式侧边栏	With Sidebar	Overlay
带两个等宽内容面板的仪表板	With Sidebar	Split

---

两类布局

Full Width — 面向公众的页面

适用于通用应用、面向公众的数字服务，以及没有固定侧边导航的页面。

主要特点：

• 使用 .sgds-container 居中显示响应式内容
• 使用标准的 <sgds-masthead>、<sgds-mainnav>、<sgds-footer>
• 内容随文档流滚动（不限制在视口内）
• 基于网格的辅助面板使用 .sgds-grid 和 sgds-col-* 类

→ 阅读 reference/full-width.md，了解全部 6 种 Full Width 布局变体。

---

With Sidebar — 仪表板和内部工具

适用于需要在主内容旁固定显示侧边导航的内部工具、仪表板、管理门户和事务型应用。

主要特点：

• 使用 .sgds-container-sidebar 显示较窄的内容区域（为侧边栏宽度留出空间）
• 在 <sgds-masthead> 和 <sgds-mainnav> 上使用 fluid 属性
• 使用 <sgds-sidebar> 组件提供固定导航
• 使用 <sgds-footer tone="neutral" layout="sidebar"> 实现适配侧边栏的页脚
• 限制在视口高度内：sgds:h-screen sgds:flex sgds:flex-col sgds:overflow-hidden
• 主内容区域独立滚动：sgds:overflow-y-auto

→ 阅读 reference/with-sidebar.md，了解全部 5 种 With Sidebar 布局变体。

---

如何从 GitHub 原始链接中提取 HTML

stories/layouts/ 目录中的所有布局都有可用的故事实现。使用方法如下：

步骤 1：获取原始文件

curl https://raw.githubusercontent.com/GovTechSG/sgds-web-component/master/stories/layouts/{Category}/{File}.stories.js

步骤 2：从模板字面量中提取 HTML

故事文件会导出一个返回 html 模板字面量的 Template 函数：

const Template = () => html`
  
  <sgds-masthead></sgds-masthead>
  ...
  <sgds-footer></sgds-footer>
  
`;

步骤 3：清理 HTML

1. 移除 `html`` 包装和末尾的反引号
2. 移除 Lit 专用语法（${variable} 插值）——替换为内联 HTML
3. 移除 <style> 块（这些仅用于 Storybook 占位内容）
4. 完全保留所有 SGDS 组件和工具类
5. 使用一致的缩进格式（2 个空格）

---

面向 AI Agent

工作流

1. 加载 sgds-utilities 技能（用于参考工具类）
2. 加载 sgds-components 技能（用于了解组件 API）
3. 加载此技能
4. 根据用户需求阅读相应的参考文件
5. 如果需要完整实现，获取原始 GitHub 故事文件
6. 根据用户的内容调整布局

指南

• 每种布局都包含必需的应用外壳（<sgds-masthead>、<sgds-mainnav>、<sgds-footer>）
• 不要混用 Full Width 和 With Sidebar 模式——根据使用场景选择一种
• 对于侧边栏布局，始终在根包装器上添加视口约束类
• 使用 sgds-blocks 中的区块或 sgds-templates 中的模板填充侧边栏和内容区域