# @canonical/react-ds-global 中文文档
规范地址：https://npmcn.com/package/%40canonical/react-ds-global/
版本：0\.45\.0
npm 元数据更新时间：2026-10-23T01:44:45.405Z
中文译文更新时间：2026-11-09T01:32:32.750Z
软件包许可：LGPL-3\.0
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40canonical/react-ds-global
原文对照：https://npmcn.com/package/%40canonical/react-ds-global/?lang=original
项目主页：https://github.com/canonical/pragma-web#readme
源码仓库：https://github.com/canonical/pragma-web
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：638 kB，894 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：7 个
- 首次发布：2026-01-18T11:35:48.499Z
- 最新版本发布：2026-10-23T01:44:44.966Z
- 近 30 天下载量：8547（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：39（近 12 个月 39 个）
## 中文简介
Pragma设计系统的通用反应组件. 这个软件包提供了适用于所有Canonical网络应用程序的基础UI元素:按钮,徽章,卡片,工具提示等.
## 安装
```sh
npm install @canonical/react-ds-global
```
也可以使用：`pnpm add @canonical/react-ds-global`、`yarn add @canonical/react-ds-global`、`bun add @canonical/react-ds-global`
## README
# @ canonical/ react-ds- global(全球)
Pragma设计系统的通用反应组件. 这个软件包提供了适用于所有Canonical网络应用程序的基础UI元素:按钮,徽章,卡片,工具提示等.
## 先决条件
- 反应19或以上
## 安装
```bash
bun add @canonical/react-ds-global @canonical/styles
```
导入设计系统的样式 **第一个** 在应用程序条目中,在进口部件之前:
```ts
import "@canonical/styles";
```
每个组件在导入时都会带出自己的样式表.
## 使用量
以名称导入组件 :
```tsx
import { Button, Badge, Card, Tooltip } from "@canonical/react-ds-global";
function Example() {
return (
New
);
}
```
组件接受其基本元素的标准HTML属性. A 类 `Button` 全部接受( e) `ButtonHTMLAttributes`页:1 `Link` 全部接受( e) `AnchorHTMLAttributes`,等等。 (笑声).
## 修饰家庭
几个组件接受与修饰家庭相对应的外观道具 `@canonical/ds-types`数字 :
```tsx
```
与 CSS 定义的自定义属性相融合的修改类 `@canonical/styles`。 。 。 .
## 样式
`@canonical/styles` 提供全局设计符号(颜色、间距、打字)。 本套件中的每个组件将自己的组件级符号放在一个 `styles.css` 文件位于组件源旁边。 这些组件符号参考了来自 `@canonical/design-tokens` ,并在组件被导入时自动包含.
### CSS 组件如何到达页面
每个组件模块都导入自己的样式表(`import "./styles.css"`),所以导入一个组件就是将它的CSS放入页面. 捆绑者收集这些导入到应用程序的CSS中;这里没有在运行时注入,也没有样式表可以手动链接. 结果是,一个你从未进口过没有CSS的船体的部件, 并且一个捆绑者碰巧放出床单的命令, 并不是你能够依赖的, 这就是下面的级联层的目的.
这就是下面的总和。 它本身没有一层,进口是赤裸裸的:它进口的每张纸都已经打开了自己的块,所以进口一张 `layer(…)` 将它嵌入一个更深的平面 而不是放在它.
### 要链接的文件
包船的每个部件样式表也以一个集合列出:
```css
@import url("@canonical/styles");
@import url("@canonical/react-ds-global/index.css");
```
这就是整个文件,一个 `@import` 每个组件样式表,没有其它东西——它购买的是存在,而不是位置.
每个组件都从模块中导入自己的样式表,因此没有集合组件的规则只有在让其达到的JavaScript时才能到达页面. 因此,在部件的CSS到达之前,懒散的路线会作画. 连接汇总将每个组件规则放入条目样式表,从第一个颜料中呈现出来,因此任何路由都无法被渲染出不样式.
它没有固定规则在所建的床单中的位置。 两种副本都到达了建筑——集合和组件模块的建筑——和一个去除重复的修饰器保持了 **最后一个**,这是模块的。 按参考应用程序衡量:每个组件规则的活下来副本在应用程序自己的CSS之后,确切位置是没有集合的;其前方的所有集合叶子是11个 `@media` 编号 : `@starting-style` 编号 : `:has()` 碎片不能崩溃(1,033字节)。 组件与应用程序之间的顺序在此不确定,不应依赖。 用组件样式表包裹 `ds.components.global` ——下面一节——按层次和源头位置进行的级联仲裁根本不重要.
列表是来源,而不是输出:它是手写的,如寄存器的章程所要求(通过一个构建步骤明确导入,通过命名惯例来发现文件),以及 `src/lib/index.css.test.ts` 如果停止匹配磁盘上的样式表,则无法构建 . **添加组件表示添加其行**按字母顺序排列,在 `src/lib/index.css`。 。 。 .
字节已经装入捆绑中: 软件包声明不 `sideEffects`因此,一个到达桶的捆绑机 将所有46个床单拉入不管。 在参考建构上,总和在简洁的样式表上增加了1,033个字节——重复去除的叶子的残留物,在一个不去除重复的建筑上大约增加了96个KB.
公布的路径是 `@canonical/react-ds-global/index.css` (子路径 `exports` 地图名称)和 `dist/esm/lib/index.css` (档案本身). 货单上还有 `style`,一些工具读取了该软件包的样式表而无需导入 `@canonical/react-ds-global-form` 用于自己的用途.
### 软件包所出版的内容以及如何导入
名单现在载有 `exports` 映射,这是此软件包对下列路径的列表:
| 指定者 | 它给你什么 |
| --- | --- |
| `@canonical/react-ds-global` | 组件 |
| `@canonical/react-ds-global/index.css` | 上面的集合样式表 |
| `@canonical/react-ds-global/dist/…` | 任何已公布的文件, 按其确切路径 |
| `@canonical/react-ds-global/package.json` | 显示 |
**对于通过地图未回答的路径导入的任何人来说,这是一个突破性的变化.** 之前,一个没有的包 `exports` 映射让解析器到达目录中的任何文件, 在大多数捆绑者中, 猜测其它文件—— 您离开的扩展名, 或是 `index.js` 在您命名的文件夹中 。 有两件事不起作用了:
- **一个文件夹而不是一个文件 .** `@canonical/react-ds-global/dist/esm` 财务报告和审定财务报表 `@canonical/react-ds-global/dist/esm/lib/component/Button` 用来找到 `index.js` 在他们体内。 文件名称 : `…/dist/esm/index.js`, (中文(简体) ), `…/dist/esm/lib/component/Button/index.js`。 。 。 .
- **外面的任何东西 `dist`。 。 。 .** `@canonical/react-ds-global/README.md`,或任何 `src/…` 在工作空间校验中解决的路径, 现在失败 `ERR_PACKAGE_PATH_NOT_EXPORTED`。这些文件无论如何都不公布; `files` 仅列出过 `dist`。 。 。 .
将扩展名离开真实文件( E)`…/Button/Button`)仍然在我们测试的解决者中工作,但它取决于解决者而不是这个包——写扩展.
按名称导入软件包,或按其子路径导入样式表,不会受到影响,几乎每个消费者都会这样做.
### 每个组件样式表都在 `ds.components.global`
每个组件 `styles.css` 在此包件中用一个级联层包裹:
```css
@layer ds.components.global {
.ds.my-component {
/* … */
}
}
```
`@canonical/styles` 在一个语句中宣布每层的顺序 `ds.components.global` 坐于其上相近相. 二事随顺.
上面是其他组件级,它们沿着设计系统自己的分层树,平: `ds.components.sites`, (中文(简体) ), `ds.components.documentation`, (中文(简体) ), `ds.components.stores` 财务报告和审定财务报表 `ds.components.apps`,在其中每一个上方,有一个产品本身组件的分层 `ds.components.apps-lxd`,该软件包宣布了它本身,在其CSS条目中的第一个规则,因为样式包的订单语句不能知道产品的名称. 平地而不是筑巢:筑巢 `ds.components.apps.lxd` 将排序 _内部_ `ds.components.apps` 所以就输掉所有直接写下来的规则 与产品级的需求相反.
这些软件包还没有被包裹——在撰写时,下面没有样式表 `packages/react/ds-app*` 或者说 `packages/svelte/ds-app*` 背负着一层一层——并且正在用一个包包与这个包包一起进行包装。 因此,今天一个产品级仍然比这个软件包好,原因恰恰相反:它是无层的,无层的节拍是分层的。 层层保证,一旦这些套件落地, 产品级规则 对于一个组件,这个套件的样式也会通过级联层胜出, 而不是通过最后释放的装入器的捆绑胜出.
申请本身 **无层** CSS现在击败了这个软件包中的每一个规则,无论哪一边的选取者,因为没有层次的作者规则排在每层的分数后. 这是CSS设计的,这是故意逃出舱门:一个需要覆盖一个组件的应用程序会写出一个简单的规则,它会获胜。 实际的应用程序 _没有_ 无意中取胜,让CSS进入 `@layer app`。 。 。 .
**捐助者规则:** 每个组件 `styles.css` 在这个包中,用包装打开. `@keyframes` 和该部件本身 `:root` 默认值会进入其中; `@property` 财务报告和审定财务报表 `@font-face` 登记在外,在街区上方。 这是惯例,不是级联的力量:层层的确在排序注册——高层层 `@property` 或者说 `@keyframes` 以任一源顺序击败下层,而未下层的则击败了两者(在Chromium 151中测量出). 将注册内容保留在区块之上, 让他们读作自己. `@keyframes` 进到块内是相反的选择, 和深思熟虑: 它让一个应用层 替换一个动画层。 此包件船是导入的 **赤线**从不与 `layer(ds.components.global)`:它已经打开了自己的块,关键词会把它嵌入更深一层,在 `ds.components.global.ds.components.global` ——一个在任何特异性(Chrimium 151中测量)中输给本层自身规则的子层. `layer(…)` 在导入时,是用于不带一层自带的工作表。 永远无法到达 `!important` 以赢得争斗——一项重要宣言颠倒了地层秩序,完全不能被地层仲裁. 包裹的船是一号, `component/Tooltip/styles.css:16`,它将边距从任何工具提示上剥去;这是一个已知的缺陷,组件-hygiene的改变可以去除它。 这个 `@canonical/styles` README"卡斯卡德地层"部分是全序和被故意留下的未分层的参考.
### 拥有他们制作的原生人的盒子
A. 使本地要素具有下列特性的组成部分: `