# @carbon/element-styles 中文文档

规范地址：https://npmcn.com/package/%40carbon/element-styles/

版本：0\.4\.4
npm 元数据更新时间：2026-11-05T14:58:17.919Z
中文译文更新时间：2026-11-09T18:49:51.114Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40carbon/element-styles
原文对照：https://npmcn.com/package/%40carbon/element-styles/?lang=original
项目主页：https://github.com/carbon-design-system/carbon-element-styles#readme
源码仓库：https://github.com/carbon-design-system/carbon-element-styles

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

- 包体积（解压后）：873 kB，97 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：1 个
- peer 依赖：@carbon/styles ^1\.115\.0
- 首次发布：2026-03-25T07:24:00.319Z
- 最新版本发布：2026-11-05T14:58:17.591Z
- 近 30 天下载量：1848（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：60（近 12 个月 60 个）

## 中文简介

实验性为原生HTML元素的造型系统,依靠语义,属性焦点选择器而不是类名.

## 安装

```sh
npm install @carbon/element-styles
```

也可以使用：`pnpm add @carbon/element-styles`、`yarn add @carbon/element-styles`、`bun add @carbon/element-styles`

## README

![](https://npmcn.com/package/%40carbon/element-styles/docs/public/banner-light.svg)

# @ 碳/元素样式

`@carbon/element-styles` 是一种实验性的用于本土HTML元素的造型系统,依赖于语义,属性焦点选择器而不是类名. 碳元素样式与碳设计系统核心反应和Web组件实施之间没有1:1的等同. 其用法案例更多针对简单的网页和编辑内容,如刻出打分文件.

## 开始

### 安装

```console
npm i @carbon/element-styles
```

#### 光盘N

您也可以使用其中的任何一个 [预建样式表](https://npmcn.com/package/%40carbon/element-styles/#readme-using-prebuilts) 通过我们的CDN:

```html
<!-- specific version (recommended) -->
<link
  rel="stylesheet"
  href="https://1.www.s81c.com/common/carbon/element-styles/version/v[x.y.z]/prebuilt/expressive.css"
/>

<!-- "latest" tag -->
<link
  rel="stylesheet"
  href="https://1.www.s81c.com/common/carbon/element-styles/tag/v0/latest/prebuilt/expressive.css"
/>

<!-- "next" tag -->
<link
  rel="stylesheet"
  href="https://1.www.s81c.com/common/carbon/element-styles/tag/v0/next/prebuilt/expressive.css"
/>
```

### 导入单个元素

为了利用单个元素,通过 `@use` 并包括 `styles` 混入您的 Sass 样式表 :

```scss
@use "@carbon/element-styles/scss/elements/button";

@include button.styles;
```

#### 创建自定义选择器

每个元素都有一个默认选择器,其样式被放出. 您可以配置此选择器, 但需要确保 HTML 标签和语义保存 .

这个 `button` 例如,元素预计会在 `<button>` 标签。 默认是选取器 `button`。如果您只想在明确显示类型按钮的按钮上发出这些样式,您可以通过 `with` sass的语法或每次包括混音.

```scss
@use "@carbon/element-styles/scss/elements/button" with (
  $config: (
    selector: 'button[type="button"]',
  )
);

@include button.styles;
```

```scss
@use "@carbon/element-styles/scss/elements/button";

@include button.styles(
  (
    selector: 'button[type="button"]',
  )
);
```

#### 配置元素

一些元素有额外的配置选项来调整其视觉外观. 您可以以配置选择器的同样方式配置这些选项: `with` sass 的语法或每次包含混音的语法 :

```scss
@use "@carbon/element-styles/scss/elements/button" with (
  $config: (
    kind: "ghost",
  )
);

@include button.styles;
```

```scss
@use "@carbon/element-styles/scss/elements/button";

@include button.styles(
  (
    kind: "ghost",
  )
);
```

将这些选项与自定义选择器合并,意味着您可以根据同一元素的多个变体的上下文发出:

```scss
@use "@carbon/element-styles/scss/elements/button";

@include button.styles;
@include button.styles(
  (
    selector: 'button[type="submit"]',
    kind: "primary",
  )
);
```

#### 具体性

所有被排放的元素样式被CSS级联层所包裹(`@layer carbon-element-styles`),以确保更低的特异性,并允许没有高特异性选择器的易被覆盖.

必要时,您可以通过配置模块配置层名 :

```scss
@use "@carbon/element-styles/scss/config" with (
  $cascade-layer-name: "custom-layer-name"
);
@use "@carbon/element-styles/scss/elements/button";

@include button.styles;

/**
 * ↪ @layer custom-layer-name {
 *     button { … }
 *   }
 */
```

### 使用预建

此库提供几个预建( opinion) 样式表, 您可以使用外框 :

#### 生产

包括所有可用的元素及其默认选择器。 采用有中等尺寸元素的生产风格. 用于交互重的页面.

<table><tbody><tr><th>常设委员会</th><td><code>/scss/prebuilt/productive/index.scss</code></td></tr><tr><th>支助科</th><td><code>/css/prebuilt/productive.css</code></td></tr><tr><th>光盘N</th><td>https://1.www.s81c.com/com/common/carbon/element-styles/tag/v0/latest/prebuilt/生产.css</td></tr></tbody></table>

#### 表达式

包括所有可用的元素及其默认选择器。 使用有大尺寸元素的表达式. 用于营销或文档等内容繁重的页面.

<table><tbody><tr><th>常设委员会</th><td><code>/scss/prebuilt/expressive/index.scss</code></td></tr><tr><th>支助科</th><td><code>/css/prebuilt/expressive.css</code></td></tr><tr><th>光盘N</th><td>https://1.www.s81c.com/com/common/carbon/element-styles/tag/v0/latest/prebuilt/expressive.css (中文(简体) )</td></tr></tbody></table>

#### 编辑

只包含与其默认选择器的非交互元素. 使用有大元素的表达式. 用于博客等仅包含内容的网页.

<table><tbody><tr><th>常设委员会</th><td><code>/scss/prebuilt/editorial/index.scss</code></td></tr><tr><th>支助科</th><td><code>/css/prebuilt/editorial.css</code></td></tr><tr><th>光盘N</th><td>https://1.www.s81c.com/common/carbon/element-styles/tag/v0/latest/预建/编辑.css</td></tr></tbody></table>

## 释放碳符号

`@carbon/element-styles` 依赖定义的符号 `@carbon/styles`因此,它不是要单独使用,而是在一个排放碳主题的容器中使用.

**重要**: 为了使按钮样式有效,您必须发出用于按钮的Carbon组件符号。 如果你在用的话 `@carbon/styles` 可能已经是这样了 为方便起见,该图书馆还提供 `emit-carbon-tokens` 组合其中包含必要的组件符号.

```scss
@use "@carbon/element-styles";

:root {
  @include element-styles.emit-carbon-tokens("white");
}
```

要生成所有可用颜色的 CSS 自定义属性,请使用 `emit-carbon-colors` 组合 :

```scss
@use "@carbon/element-styles";

:root {
  @include element-styles.emit-carbon-colors;
}

/**
 * ↪ :root {
 *     --cds-black-100: #000000;
 *     --cds-blue-10: #edf5ff;
 *     --cds-blue-20: #d0e2ff;
 *     …
 *   }
 */
```

## 配置布局选项

所有元素都建立在定义大小和密度等属性的上下文布局符号上. 您可以为页面的各个部分指定这些布局符号.

密度

### 密度

控制元素的密度,主要通过内线垫.

#### 支持的数值

-   `condensed`
-   `normal` (默认)

#### 发件人

-   `$density--padding`

#### 示例

```scss
@use "@carbon/element-styles/scss/layout";

:root {
  @include layout.density("condensed");
}

.callout {
  padding: layout.$density--padding;
}
```
模式

### 模式

通过字体大小和间距控制整个视觉印象.

#### 支持的数值

-   `productive` (默认)
-   `expressive`

#### 发件人

-   `$mode--max-inline-size`
-   `$mode--margin-block`
-   `$mode--transition-duration`
-   `$mode--transition-timing-function`

#### 可用混音器

-   `mode--body`
-   `mode--body-compact`
-   `mode--heading`
-   `mode--heading-compact`
-   `mode--label`
-   `mode--helper-text`
-   `mode--code`
-   `mode--quotation`
-   `mode--heading-level-1`
-   `mode--heading-level-2`
-   `mode--heading-level-3`
-   `mode--heading-level-4`
-   `mode--heading-level-5`
-   `mode--heading-level-6`

#### 示例

```scss
@use "@carbon/element-styles/scss/layout";

:root {
  @include layout.mode("expressive");
}

.callout {
  margin-block: layout.$mode--margin-block;
}

.callout header {
  @include layout.mode--heading-compact;
}
```
大小

### 大小

控制元素的高度.

#### 支持的数值

-   `xs`
-   `sm`
-   `md` (默认)
-   `lg`
-   `xl`

#### 发件人

-   `$size--block-size`
-   `$size--padding-block-start`
-   `$size--padding-block-end`

#### 示例

```scss
@use "@carbon/element-styles/scss/layout";

:root {
  @include layout.size("lg");
}

.callout header {
  block-size: layout.$size--block-size;
}
```

## 指导原则

### 1\. 平台邻近

该库的目标是为本土的HTML元素和ARIA模式提供有观点的风格. 由于缺乏匹配的本地对口单位,该项目有意缺少核心碳库的若干组成部分。 其用意是不依赖类名或特殊属性.

但有一个例外:瓦片元素。 平板是"碳"中最基本和被广泛使用的组件之一. 瓦片样式的默认选择器是 `[data-tile]`。 。 。 .

### 2\. 逻辑布局

应当在多个要素之间保持一致的布局决定不是这些要素的责任。 相反,他们的母版式(页或区)应控制诸如大小、密度和整体偏好等方面.

### 3\. 地貌展望

这个库中并非所有元素都与所有主要浏览器完全兼容. 该项目有意使用一些浏览器可以使用的最新功能,以验证它们是否适合支持碳设计系统目前和即将出现的概念.

## 许可证

凭 [Apache 2.0 (英语)](https://npmcn.com/package/%40carbon/element-styles/LICENSE) 执照.

## ![IBM Telemetry](https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-light.svg) IBM 遥测

本套件使用 IBM 遥测来收集去识别和匿名的度量衡 数据。 通过安装此包作为依赖, 您同意远程测量 藏书。 选择退出,看 [选择退出IBM遥测数据收集](https://github.com/ibm-telemetry/telemetry-js/tree/main#opting-out-of-ibm-telemetry-data-collection)。 。 。 . 有关所收集数据的更多信息,请参见: [IBM 遥测文档](https://github.com/ibm-telemetry/telemetry-js/tree/main#ibm-telemetry-collection-basics)。 。 。 .

## 常见问题

### @carbon/element-styles 是什么？

实验性为原生HTML元素的造型系统,依靠语义,属性焦点选择器而不是类名\.

### 如何安装 @carbon/element-styles？

在项目目录运行 npm install @carbon/element-styles，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@carbon/styles（^1\.115\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @carbon/element-styles 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/carbon\_\_element-styles 是否存在。

### @carbon/element-styles 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @carbon/element-styles 可以商用吗？

@carbon/element-styles 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @carbon/element-styles 的下载量有多少？

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

### @carbon/element-styles 还在维护吗？

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