# @stordata/design-system 中文文档 规范地址：https://npmcn.com/package/%40stordata/design-system/ 版本：1\.0\.20261102135257 npm 元数据更新时间：2026-11-02T13:55:14.445Z 中文译文更新时间：2026-11-02T14:11:31.407Z 软件包许可：UNLICENSED 本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40stordata/design-system 原文对照：https://npmcn.com/package/%40stordata/design-system/?lang=original ## 关键信息（来自 npm 元数据） - 包体积（解压后）：645 kB，230 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - Node.js 要求：\>= 24 - 运行依赖：3 个 - peer 依赖：@mui/material ^9，@emotion/react ^11，@emotion/styled ^11，@mui/x-data-grid-premium ^9 - 首次发布：2026-06-29T08:05:32.934Z - 最新版本发布：2026-11-02T13:55:14.192Z - 已发布版本数：184（近 12 个月 184 个） ## 中文简介 ![build](https://gitlab.stordata.fr/stordata/design-system/badges/main/pipeline.svg) [![coverage](https://gitlab.stordata.fr/stordata/design-system/badges/main/coverage.svg)](https://coverage.stordata.dev/stordata/design-system/) ## 安装 ```sh npm install @stordata/design-system ``` 也可以使用：`pnpm add @stordata/design-system`、`yarn add @stordata/design-system`、`bun add @stordata/design-system` ## README # 设计系统 ![build](https://gitlab.stordata.fr/stordata/design-system/badges/main/pipeline.svg) [![coverage](https://gitlab.stordata.fr/stordata/design-system/badges/main/coverage.svg)](https://coverage.stordata.dev/stordata/design-system/) 真相来源： [https://zeroheight.com/239aea73f](https://zeroheight.com/239aea73f) ## 安装 为了让你的应用的设计系统功能齐全，你需要 - 安装它 `npm i --save -E @stordata/design-system` - 添加样式在你的 `` -> `import '@stordata/design-system/style.css';` - 添加一个 `` 对你 `` -> `` - 可选地添加主题到您的 `` 重载默认属性 - 现在您已经准备好享受我们强大的DS组件的美丽和力量了！ ### 可选 如果你想用 `DSDataGrid`，一个有样式的MaterialUI [数据表格](https://mui.com/x/react-data-grid/) 组件时，还请安装以下依赖项 ```bash npm i --save -E @mui/material @mui/x-data-grid-premium @emotion/react @emotion/styled ``` ### 使用设计系统 #### DSProvider 在使用任何设计系统组件之前，需要在类中呈现应用程序 `` 组件。 该组件为所有设计系统组件提供主题，以及一些其他实用功能，如定位、响应等。 ```tsx import DSProvider from '@stordata/design-system/DSProvider'; export default function App() { return ( ); } ``` 提供者接受 `locale` 由一些呈现本地化文本的组件使用的Prop。它也接受 `theme` 道具 您可以使用它来定制设计系统组件的外观和行为。更多细节见下文。 #### 主题 这个 `DSProvider` 组件可以给定 `Theme` 对象进行定制 - 所有组件的默认属性 - 颜色模式，调色板，语义符号，排版等。 - 动画持续时间和缓动功能 - 响应断点、间距和其他一些与布局相关的设置 #### 默认样式 要更改特定组件的默认样式，请在应用程序中包含一个针对该组件的样式表： ```css .ds.ds-stack { flex-direction: row; } ``` 类名的约定是 - 所有的设计系统都有 `ds` 类 - 全设计系统 _组件_ 有 `ds-component` 类 - 每个特定的组件都有一个 `ds-` 类, `` 组件的名称是小写的，蛇形的吗 灯泡：建议始终使用 `.ds` 上课，以防万一。 #### 动态样式 所有组件都支持 `sx` 道具，这是一个增强 `style` 道具添加一些功能： - 对所有属性的响应性支持。请参见下面的示例。 - 这个 `mode` 属性，可用于覆盖单个组件的颜色模式（例如：在深色表面上呈现中性按钮）。 通过对象表示法支持响应性，其中键是断点，值是要使用的属性值 当相应的断点处于活动状态时。以移动优先的方式，从最小到最大地应用断点。 下面的例子将根据屏幕大小改变文本颜色： ```tsx Responsive text color ``` ```tsx This button renders in dark mode ``` ## 约定 ### 实现 组件应该 - 呈现原生HTML元素，或者 - 呈现由BaseUI提供的组件 所有组件都支持 `render` 来自BaseUI的道具在渲染组件时，该道具被转发到根组件 组件，或通过 `useRender` 钩子，允许进一步定制。 所有组件都支持一组公共属性： - id - 类名称 - 风格 - ref（一个React ref） 在实现新组件时，您应该 - 为组件props编写一个TypeScript接口，扩展常用属性和 `HTMLAttributes` （或子接口）来继承默认的HTML道具。 - 使用 `useMergeProps` 将来自主题的默认属性与传递给组件的属性合并。 - 中添加一个部分 `Theme` 为新组件的默认道具设置接口，并选择默认值。 #### 道具 除了特定于组件的道具(比如 `variant`， `size`等)，所有组件都应该支持根元素上的扩展道具。 自动处理 `useRender` 在呈现原生HTML元素时，但需要为BaseUI组件手动完成。 这允许所有的原生HTML道具(如 `style`， `onClick`等)被转发。 #### 参考文献 所有组件都接受 `ref` 应该经常使用。要么 - 转发到BaseUI组件（它们都接受refs），或者 - 给 `useRender` 钩子在渲染原生HTML元素时。看到 [https://base-ui.com/react/utils/use-render#merging-refs](https://base-ui.com/react/utils/use-render#merging-refs) ### 样式 样式化是使用每个组件的CSS模块来完成的。 通常，所有CSS模块都应该以根类开始 `.` 它被应用于组件的根元素。 键入常用样式属性时，例如 `color` 或者 `size`请始终为属性定义一个TypeScript类型， 并在组件道具界面中使用它。如果支持与通用值相同的值集，则可以使用类型别名。 例如 ```typescript export type DSMyComponentSize = ComponentSize; ``` #### 分级 在适用的情况下，组件应该支持 `size` 属性，可以设置为小、中或大。默认大小为中。 在组件的CSS模块中， `.small`， `.medium` 和 `.large` 应该定义类，以便为每种大小应用适当的样式。 在呈现组件时，使用 `classNames` 工具来应用适当的大小类 `size` 财产。 灯泡：只支持可用尺寸的一个子集是可以的。 #### 变体 在适用的情况下，组件应该支持 `variant` 属性，该属性可设置为主要、次要或第三。默认的变量是primary。 在组件的CSS模块中， `.primary`， `.secondary` 和 `.tertiary` 应该定义类，以便为每个变体应用适当的样式。 在呈现组件时，使用 `classNames` 的基础上应用适当的变体类 `variant` 财产。 ：bulb：只支持可用变体的一个子集是可以的。 #### 行高 一般来说，不要重写 `line-height` CSS属性。它使垂直对齐变得困难，尤其是在文本旁边的图标。 在需要的时候，使用重写 `DSTypography` 在变体上设置自定义行高。 ## 测试 要做测试，确保你有 [码头工人](https://www.docker.com/) 第一次安装。 运行 `docker compose up -d` 启动所需的容器，然后 `npm test` 来做Vitest测试 ### 报道 运行 `npm run coverage` 用代码覆盖率运行一次测试（V8）。它打印摘要并在其中写入HTML报告 `coverage/`. 在CI中，覆盖率不能低于 `main` ，其报道报告可在网上浏览 [https://coverage.stordata.dev/stordata/design-system/](https://coverage.stordata.dev/stordata/design-system/) ### 更新Chromium容器以匹配最新的剧作家版本 拉出无浏览器的图像 ```bash docker pull ghcr.io/browserless/chrome:v2.xx.x ``` 把它标记在我们的注册表上 ```bash docker tag ghcr.io/browserless/chrome:v2.xx.x docker.stordata.fr/docker.io/chrome:v2.xx.x ``` 从我们的注册表中取出它来本地测试，如果现在一切都修复了 ```bash docker push docker.stordata.fr/docker.io/chrome:v2.xx.x ``` ## 常见问题 ### 如何安装 @stordata/design-system？ 在项目目录运行 npm install @stordata/design-system，或使用 pnpm add / yarn add / bun add。 ### @stordata/design-system 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @stordata/design-system 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @stordata/design-system 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>= 24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @stordata/design-system 可以商用吗？ @stordata/design-system 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。 ### @stordata/design-system 还在维护吗？ 最新版本 1\.0\.20261102135257 发布于 2026/11/02（今天）；至今共发布 184 个版本，其中过去 12 个月发布了 184 个；首次发布于 2026/06/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。