sgds-components

SGDS 组件设置技能

使用 <sgds-*> Web 组件的前提条件和框架集成说明。

安装

npm install @govtechsg/sgds-web-component
# or
pnpm add @govtechsg/sgds-web-component

在应用入口处导入一次该库：

import "@govtechsg/sgds-web-component";

框架集成

React

使用哪种导入方式取决于 React 版本。

React 19+（客户端，例如 Vite）

React 19 原生支持自定义元素——在应用入口处导入一次，然后即可在任意位置使用 Web 组件标签：

import "@govtechsg/sgds-web-component";

function App() {
  return (
    <sgds-button variant="primary" onsgds-blur={(e) => console.log(e)}>
      Click Me
    </sgds-button>
  );
}

React 19 中的自定义事件语法：在事件名称前加上小写的 on（sgds-blur → onsgds-blur）。

使用 Next.js？ Next.js 基于 SSR，需要不同的设置方式——请参阅下方的 Next.js 部分。

可声明式传递复杂属性（数组、对象）：

import "@govtechsg/sgds-web-component";

const steps = [
  { component: <Step1 />, stepHeader: "Personal details" },
  { component: <Step2 />, stepHeader: "Contact details" },
];

function App() {
  return <sgds-stepper steps={steps}></sgds-stepper>;
}

React 18 及更早版本

React ≤18 原生不支持自定义元素事件或复杂属性。请使用 React 包装组件：

import { SgdsButton } from "@govtechsg/sgds-web-component/react";

function App() {
  return (
    <SgdsButton variant="primary" onSgdsBlur={(e) => console.log(e)}>
      Click Me
    </SgdsButton>
  );
}

React 包装组件的事件命名：sgds-blur → onSgdsBlur，sgds-change → onSgdsChange（前缀为 on，每个以连字符分隔的单词均采用 camelCase 命名）。

在 React ≤18 中访问组件方法（通过 useRef）：

import { useRef } from "react";
import type { SgdsStepper as SStep } from "@govtechsg/sgds-web-component/components";
import SgdsStepper from "@govtechsg/sgds-web-component/react/stepper/index.js";

function StepperComponent() {
  const stepperRef = useRef<SStep>(null);
  return <SgdsStepper steps={steps} ref={stepperRef} />;
}

注意：对于 Next.js 和 SSR 框架，建议使用 React 包装组件，因为它们可以解决初始加载时的水合时序问题。

官方文档：https://webcomponent.designsystem.tech.gov.sg/?path=/docs/frameworks-react--docs

---

Next.js

Next.js 是一个 SSR 框架——Web 组件依赖浏览器 API，在服务器端渲染期间于模块级别导入时可能会导致水合问题。

推荐方式：使用 React 包装组件。 React 包装组件可以解决水合时序问题，避免初始页面加载时事件监听器失效——只需导入并使用：

'use client';
import { SgdsInput, SgdsButton } from "@govtechsg/sgds-web-component/react";

export default function MyForm() {
  return (
    <>
      <SgdsInput label="Name" onSgdsChange={(e) => console.log(e)} />
      <SgdsButton variant="primary">Submit</SgdsButton>
    </>
  );
}

事件命名遵循 camelCase 约定：sgds-change → onSgdsChange，sgds-after-show → onSgdsAfterShow。

TypeScript 支持——在项目根目录添加 types.d.ts，并引用 SGDS React 类型定义。这样，所有 sgds-* 元素的属性都能获得完整的 IntelliSense 支持，CustomEvent 详情负载也会有类型定义：

在 tsconfig 包含的任意 .d.ts 文件中使用 ES 导入：

import "@govtechsg/sgds-web-component/types/react";

如需了解更多信息，请参阅官方 Next.js 集成文档。

---

Vue

Vue 3 原生支持 Web 组件——没有 SGDS 专用包装组件。有关配置，请参阅 Vue + Web 组件文档。用于抑制未知元素警告的 SGDS 专用筛选条件为 tag.startsWith("sgds-")。

---

Angular

Angular 通过 CUSTOM_ELEMENTS_SCHEMA 原生支持 Web 组件——没有 SGDS 专用包装组件。有关配置，请参阅 Angular 元素文档。

---

排查组件行为问题

如果组件行为异常——触发了错误的事件、属性未生效、插槽未渲染——请直接阅读编译后的源码。其中包含完整的方法体、事件逻辑、内部默认值和边界情况处理，这些内容在文档中都没有记录。

从 node_modules/@govtechsg/sgds-web-component 中读取——安装软件包后，该目录就会存在：

node_modules/@govtechsg/sgds-web-component/components/Accordion/sgds-accordion.js
node_modules/@govtechsg/sgds-web-component/components/Accordion/sgds-accordion-item.js
node_modules/@govtechsg/sgds-web-component/components/Accordion/sgds-accordion.d.ts

将 Accordion/sgds-accordion 替换为相应的组件文件夹和文件名。.js 文件包含完整实现；.d.ts 文件列出了所有属性、类型、事件、插槽和 JSDoc 说明。

如果缺少 node_modules——说明尚未安装软件包。请先让用户运行常规安装步骤（npm install / pnpm install），再检查源文件。

---

对于 AI Agent：主要决策依据是 React 版本和渲染模式：

• Next.js（SSR）：使用 React 封装组件（来自 @govtechsg/sgds-web-component/react 的 SgdsInput、SgdsButton 等）——它们可解决初次加载时的水合时序问题。事件属性使用驼峰命名法（onSgdsChange）。
• React 19+ CSR（Vite 等）：可以使用原生 <sgds-*> 标签和 onsgds-change 语法，也可以使用带有 onSgdsChange 的 React 封装组件——两者效果相同。
• React ≤18：使用 SGDS React 封装组件，事件属性采用驼峰命名法（onSgdsChange）
• Vue / Angular：采用标准 Web Component 集成方式；Vue 的 SGDS 特定配置为 tag.startsWith("sgds-")，用于抑制未知元素警告

当用户反馈组件行为异常（事件错误、属性未生效、插槽未渲染）时，请先引导他们阅读编译后的源码，再尝试其他方法——参见上文的 排查组件行为问题 部分。

全局规则——绝不要为 SGDS 组件设置显式宽度。 不要直接在任何 <sgds-*> 元素上添加 width、style="width: ..." 或固定宽度的实用类（例如 sgds:w-40）。宽度由父级布局控制——使用 flex、grid 或包装 div 来限制宽度。唯一例外是用户明确要求固定宽度的情况。

---

Available Components

Category	Component	Reference
Actions	Button	→ reference/button.md
Actions	Icon Button	→ reference/icon-button.md
Actions	Close Button	→ reference/close-button.md
Actions	Link	→ reference/link.md
Actions	Dropdown	→ reference/dropdown.md
Actions	Overflow Menu	→ reference/overflow-menu.md
Navigation	Masthead	→ reference/masthead.md
Navigation	Main Nav	→ reference/mainnav.md
Navigation	Footer	→ reference/footer.md
Navigation	Breadcrumb	→ reference/breadcrumb.md
Navigation	Pagination	→ reference/pagination.md
Navigation	Sidenav	→ reference/sidenav.md
Navigation	Sidebar	→ reference/sidebar.md
Navigation	Subnav	→ reference/subnav.md
Navigation	Tab	→ reference/tab.md
Navigation	Table of Contents	→ reference/table-of-contents.md
Layout	Accordion	→ reference/accordion.md
Layout	Divider	→ reference/divider.md
Layout	Drawer	→ reference/drawer.md
Layout	Modal	→ reference/modal.md
Content	Badge	→ reference/badge.md
Content	Card	→ reference/card.md
Content	Icon Card	→ reference/icon-card.md
Content	Image Card	→ reference/image-card.md
Content	Thumbnail Card	→ reference/thumbnail-card.md
Content	Description List	→ reference/description-list.md
Content	Data Table	→ reference/data-table.md
Content	Icon	→ reference/icon.md
Content	Icon List	→ reference/icon-list.md
Content	Table	→ reference/table.md
Content	Tooltip	→ reference/tooltip.md
Forms	Input	→ reference/input.md
Forms	Textarea	→ reference/textarea.md
Forms	Select	→ reference/select.md
Forms	Checkbox	→ reference/checkbox.md
Forms	Radio	→ reference/radio.md
Forms	Combo Box	→ reference/combo-box.md
Forms	Datepicker	→ reference/datepicker.md
Forms	File Upload	→ reference/file-upload.md
Forms	Quantity Toggle	→ reference/quantity-toggle.md
Feedback	Switch	→ reference/switch.md
Workflow	Stepper	→ reference/stepper.md

---

表单输入组件

构建表单时，使用以下 9 个表单输入组件来收集用户数据：

1. <sgds-input> — 文本字段
2. <sgds-textarea> — 多行文本
3. <sgds-select> — 下拉选择
4. <sgds-checkbox> / <sgds-checkbox-group> — 多选
5. <sgds-radio> / <sgds-radio-group> — 单选
6. <sgds-combo-box> — 可搜索的选择框
7. <sgds-datepicker> — 日期输入
8. <sgds-file-upload> — 文件选择器
9. <sgds-quantity-toggle> — 数值计数器

请勿在表单中使用（这些是反馈/状态组件，不是输入组件）：

• <sgds-switch> — 这是一个反馈组件（用于显示切换状态），不是表单输入组件。请改用 <sgds-checkbox> 或 <sgds-radio-group> 来收集用户选择。
• 其他非输入组件（Alert、Badge、Button、Card 等）— 这些是布局/反馈组件，不是表单控件。

有关表单布局模式（字段配对、间距、宽度限制、使用 <sgds-stepper> 的多步骤表单、标题层级），请参阅 sgds-blocks 表单布局技能。 | 反馈 | Alert | → reference/alert.md | | 反馈 | Spinner | → reference/spinner.md | | 反馈 | Skeleton | → reference/skeleton.md | | 反馈 | Progress Bar | → reference/progress-bar.md | | 反馈 | Toast | → reference/toast.md | | 反馈 | System Banner | → reference/system-banner.md |