用途:指导在项目中安装并使用 <sgds-*> Web Components,按框架与渲染模式给出对应的引入和事件绑定方式。
安装与引入:npm install @govtechsg/sgds-web-component(或 pnpm add),在应用入口 import "@govtechsg/sgds-web-component";。
框架集成:React 19+(客户端,如 Vite)支持原生自定义元素,标签内直接使用,事件以小写 on 前缀书写(sgds-blur → onsgds-blur),数组/对象等复杂属性可声明式传入。React ≤18 不支持自定义元素事件与复杂属性,需使用 React 包装组件(import { SgdsButton } from "@govtechsg/sgds-web-component/react"),事件为 onSgdsBlur、onSgdsChange 等驼峰写法,方法通过 useRef 访问;官方说明包装组件将在未来主版本中逐步淘汰。Next.js 为 SSR,禁止模块顶层引入,需建立 'use client' 的加载组件在 useEffect 中动态 import,加入根布局 head,使用 suppressHydrationWarning,事件通过 useEffect + addEventListener 绑定,并在 types.d.ts 中声明各 sgds-* 标签的 JSX 类型。Vue 3 与 Angular 原生支持 Web Components,无 SGDS 专用包装;Vue 可用 tag.startsWith("sgds-") 过滤未知元素告警,Angular 使用 CUSTOM_ELEMENTS_SCHEMA。
排障:组件事件、属性或插槽行为异常时,优先阅读 node_modules/@govtechsg/sgds-web-component/components/{ComponentName}/ 下的 .js 实现与 .d.ts 类型(含属性、事件、插槽与 JSDoc)。仅当无 node_modules(CDN 使用)时,按所用版本在 npm 包页面查看源码。
限制:资料未提供具体组件清单、版本兼容矩阵、浏览器支持及收费信息;实现细节以所用版本源码为准。