# @daikin-oss/design-system-web-components 中文文档

规范地址：https://npmcn.com/package/%40daikin-oss/design-system-web-components/

版本：2\.1\.0
npm 元数据更新时间：2026-09-24T07:31:43.416Z
中文译文更新时间：2026-11-11T09:01:08.031Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40daikin-oss/design-system-web-components
原文对照：https://npmcn.com/package/%40daikin-oss/design-system-web-components/?lang=original
项目主页：https://github.com/dsv-rp/DDS
源码仓库：https://github.com/dsv-rp/DDS

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：5.2 MB，1415 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：7 个
- peer 依赖：@daikin-oss/dds-tokens ^2\.0\.0
- 首次发布：2024-05-24T22:08:44.476Z
- 最新版本发布：2026-09-24T07:31:43.243Z
- 近 30 天下载量：2820（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：37（近 12 个月 20 个）

## 中文简介

使用网络组件的设计系统

## 安装

```sh
npm install @daikin-oss/design-system-web-components
```

也可以使用：`pnpm add @daikin-oss/design-system-web-components`、`yarn add @daikin-oss/design-system-web-components`、`bun add @daikin-oss/design-system-web-components`

## README

# 戴金设计系统-Web组件

该项目是使用Web组件的Daikin设计套件的实施.

* * *

## 使用量

安装软件包开始 :

```sh
npm install @daikin-oss/design-system-web-components @daikin-oss/dds-tokens
```

要部署必要的 CSS 变量,请从 `@daikin-oss/dds-tokens` 软件包 : 详情请查看 [dds- tokens 仓库](https://github.com/dsv-rp/dds-tokens?tab=readme-ov-file#readme)。 。 。 .

```js
import "@daikin-oss/dds-tokens/css/daikin/Light/variables.css";
```

您可以在捆绑中导入必要的组件( . js 扩展是可选的):

```js
import "@daikin-oss/design-system-web-components/components/button/index.js";
```

### 字体

我们使用机器人作为UI组件的字体. 此字体不包含在我们软件包中,因此开发者需要将它包含在他们的应用中.

所需重量和变式如下:

-   常规( 400), 普通
-   粗体( 700), 正常

#### 带有 Google 字体

如果可以使用外部的CDN,可以使用Google字体来加载.

```html
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;700&display=swap"
  rel="stylesheet"
/>
```

#### 有字体来源

如果您想要在应用程序中不依赖外部 CDN 来发送字体, 您可以使用类似软件包 [字体来源](https://fontsource.org/fonts/roboto) 这样做.

以 :

```sh
npm install @fontsource/roboto
```

然后在您的应用程序中导入 :

```js
import "@fontsource/roboto/400.css";
import "@fontsource/roboto/700.css";
```

### 黑暗模式和品牌/主题

_由于由Web组件规格来封装样式,主题的应用方式在未来可能会有变化._

对于暗模式支持和非戴金品牌,你需要添加 `tokens` 在您的 html 中包含 CSS 引用 :

```sh
npm install @daikin-oss/dds-tokens
```

#### 黑暗模式

在 HTML 中引用 CSS :

```html
<link
  rel="stylesheet"
  href="node_modules/@daikin-oss/dds-tokens/build/css/DKN/Dark/variables.css"
  media="(prefers-color-scheme: dark)"
/>
```

使用 CSS 软件 `@import` 与 `prefers-color-scheme`数字 :

```css
@import "@daikin-oss/dds-tokens/css/daikin/Dark/variables.css"
  (prefers-color-scheme: dark);
```

#### 其他品牌/主题

在 HTML 中引用 CSS :

```html
<link
  rel="stylesheet"
  href="node_modules/@daikin-oss/dds-tokens/build/css/AAF/Dark/variables.css"
  media="(prefers-color-scheme: light)"
/>
<link
  rel="stylesheet"
  href="node_modules/@daikin-oss/dds-tokens/build/css/AAF/Dark/variables.css"
  media="(prefers-color-scheme: dark)"
/>
```

使用 CSS 软件 `@import` 与 `prefers-color-scheme`数字 :

```css
@import "@daikin-oss/dds-tokens/css/aaf/Light/variables.css"
  (prefers-color-scheme: light);
@import "@daikin-oss/dds-tokens/css/aaf/Dark/variables.css"
  (prefers-color-scheme: dark);
```

* * *

## 捐款

以下是给软件包贡献者的指示.

### 设置

克隆和安装依赖性 :

```bash
git clone https://github.com/dsv-rp/DDS.git
cd DDS

# install dependencies
npm i

# install Playwright browsers
npx playwright install
```

### 构建

要构建用于制作的文件 :

```bash
npm run build
```

Vite用于将TypeScript代码转换为在现代浏览器中运行的JavaScript.

已建文件写入 `/dist`。 。 。 .

### 文档

故事书用于记录设计系统组件/工具/实例.

要以开发模式运行 :

```bash
# Web Components version
npm run storybook

# or React version
npm run storybook:react
```

生成可分配文件 `/storybook-static/web-components` 财务报告和审定财务报表 `/storybook-static/react` 文件夹 :

```bash
npm run build-storybook
```

### 测试

目前有两套测试套件:VRT(视觉回转测试)和交互测试.

视觉回归测试,放置在 `*.visual.test.ts`,由 Playwright 在容器中运行完成. 为了消除环境之间的渲染差异,取取截图的浏览器必须在容器上运行.

目前,Web组成部分在大多数主要框架中都得到充分支持 [除了反应](https://custom-elements-everywhere.com/)。 。 。 . 因此,我们单独测试两个Web组件,并在React导入时进行测试:

```bash
# start a container for running the browsers
docker compose up -d

# run VRT for Web Components and React versions
npm run test:visual

# stop the container
docker compose down
```

对 Podman 用户, 使用 `podman-compose -f compose.podman.yaml` 或者说 `podman compose -f compose.podman.yaml` 改为 `docker compose`。 。 。 .

要更新快照, 请使用 `npm run test:visual-update`

* * *

互动测试,放置在 `*.stories.ts`,由故事书执行,故事书内部也使用Playwright. 相互作用测试不使用容器,因为使环境之间的差异不重要.

```bash
npm run test:interaction
```

### 林入和类型检查

Linting由ESLint进行,用于JavaScript和TypeScript的普通林克,并 [升分析器](https://www.npmjs.com/package/lit-analyzer) 键入 lit-html 模板中的检查约束. [c spell 键](https://cspell.org/) 用于拼写检查. [伊丝-林特](https://ls-lint.org/) 还用于确保使用一致的文件名.

要插入项目, 运行 :

```bash
npm run lint
npx tsc -b
```

如果你遇到一个 `Unknown word` 错误,将单词添加到 `cspell-dictionary.txt`。 。 。 .

### 设计托肯斯

我们管理和使用设计标志,以确保设计系统的一致性.

1.  **真相来源**数字 : 我们使用的标志 是我们设计风格的基础 被从 [https://github.com/dsv-rp/dds-tokens (中文(简体) )](https://github.com/dsv-rp/dds-tokens)。 。 。 . 这些设计符被作为CSS变量来部署.
    
2.  **组件使用量**数字 : 这些组件通过引用CSS变量来使用设计符号. 由于它们与Tailwind CSS集成在一起,它们大多被用作公用类,但在某些情况下直接使用 `var()`。 。 。 .
    

```ts
@ddsElement("daikin-link")
export class DaikinLink extends DDSElement {
  static override readonly styles = css`
    ${unsafeCSS(tailwindStyles)}

    :host([show-visited]:not([disabled])) a:visited {
      /* HERE */
      color: var(--dds-color-link-text-visited-default);
    }
  `;

  override render() {
    /* AND HERE (`text-ddt-*` classes) */
    return html`
      <a
        class="text-ddt-color-link-text-default hover:text-ddt-color-link-text-hover"
        href="https://www.example.com/"
      >
        ...
      </a>
    `;
  }
}
```

### 尾风CSS

有个习俗 `daikinPlugin` 管理 [这里](https://github.com/dsv-rp/tailwind)。 。 。 .

### 与 VSCode 一起开发

该项目为VSCode提供了推荐的扩展和工作空间设置.

参考资料 [戴金设计套件](https://www.figma.com/file/VyaaU8Ta9yzyf0PsURWSSf/DDS%3A-Design-Kit?node-id=2421%3A7943)

## 常见问题

### @daikin-oss/design-system-web-components 是什么？

使用网络组件的设计系统

### 如何安装 @daikin-oss/design-system-web-components？

在项目目录运行 npm install @daikin-oss/design-system-web-components，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@daikin-oss/dds-tokens（^2\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @daikin-oss/design-system-web-components 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @daikin-oss/design-system-web-components 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @daikin-oss/design-system-web-components 可以商用吗？

@daikin-oss/design-system-web-components 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @daikin-oss/design-system-web-components 的下载量有多少？

根据 npm 官方下载统计，@daikin-oss/design-system-web-components 在 2026/10/11 – 2026/11/09 这 30 天内被下载 2,820 次，日均约 94 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @daikin-oss/design-system-web-components 还在维护吗？

最新版本 2\.1\.0 发布于 2026/09/24（1 个月前）；至今共发布 37 个版本，其中过去 12 个月发布了 20 个；首次发布于 2024/05/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。