# @alma-oss/spirit-web 中文文档

规范地址：https://npmcn.com/package/%40alma-oss/spirit-web/

版本：5\.3\.0
npm 元数据更新时间：2026-10-19T10:35:05.310Z
中文译文更新时间：2026-11-06T11:53:59.449Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：6 MB，659 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：4 个
- peer 依赖：sass-embedded \>=1\.57\.0 \< 2
- 首次发布：2025-12-15T11:36:15.528Z
- 最新版本发布：2026-10-19T10:35:04.912Z
- 近 30 天下载量：3351（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 19 个）

## 中文简介

CSS和香草JS 精神设计系统的实施

## 安装

```sh
npm install @alma-oss/spirit-web
```

也可以使用：`pnpm add @alma-oss/spirit-web`、`yarn add @alma-oss/spirit-web`、`bun add @alma-oss/spirit-web`

## README

# @alma-oss/spirit-web

> CSS实施精神设计系统.

## 安装

```shell
yarn add @alma-oss/spirit-web
```

或者说

```shell
npm install --save @alma-oss/spirit-web
```

## 使用量

### 快速启动 CSS

预建的Spirit CSS是小型一次性项目,原型和文档的绝佳选择.

在您的 HTML 模板中将完整、供应商前置和最小化的 CSS 与默认 Spirit 品牌链接 :

```html
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap" />
<link rel="stylesheet" href="node_modules/@alma-oss/spirit-web/css/themes.min.css" />
<link rel="stylesheet" href="node_modules/@alma-oss/spirit-web/css/foundation.min.css" />
<link rel="stylesheet" href="node_modules/@alma-oss/spirit-web/css/components.min.css" />
<link rel="stylesheet" href="node_modules/@alma-oss/spirit-web/css/helpers.min.css" />
<link rel="stylesheet" href="node_modules/@alma-oss/spirit-web/css/utilities.min.css" />
```

QQ 或者,您可以使用 [光盘N](https://npmcn.com/package/%40alma-oss/spirit-web/#readme-cdn) 当您不想安装任何 npm 包时链接.

### 他们

为使组件独立, **范围外观变化**,"精神设计"系统使用主题. 你可以使用任何一个 提供的主题或 [创建自己的](https://npmcn.com/package/%40alma-oss/spirit-web/#readme-custom-themes)。只需在基础 CSS 文件之前包含主题 CSS 文件. 鉴于命名公约 `theme-<NAME OF THE THEME>`,您可以在 HTML 的任意时间切换主题 :

```html
<body class="text-primary bg-primary">
  <p>This paragraph uses the default light theme.</p>
  <section class="theme-light-on-brand bg-primary">
    <p class="text-primary">This paragraph uses the light theme on brand background.</p>
  </section>
</body>
```

### 颜色方案

灵灵 **颜色方案** 为: **语义表面** 由设计符号建造。 他们和CSS不一样 [`color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme) 属性 或 OS 轻/暗模式(`prefers-color-scheme`它们是Spirit自己在树下搭配前景、背景和边框的图案. 在实践中,这意味着您选择一个表层类,而Spirit为UI的这一部分保持文本,背景和边框颜色同步.

见 [颜色方案](https://github.com/alma-oss/spirit-design-system/blob/main/docs/content/color-schemes.md) 全图的指南——对齐逻辑,所有可用的方案,它们设置的CSS自定义属性,以及它们与主题和动态颜色的关系.

#### 如何运作

1.  **表面类** 装入 `color-scheme-on-<suffix>` 容器(例如 `color-scheme-on-neutral-basic`, (中文(简体) ), `color-scheme-on-emotion-success-basic`, (中文(简体) ), `color-scheme-on-accent-01-subtle`,或 `color-scheme-on-disabled`) (中文(简体) ). 每组 **当地** CSS 内容、边框和背景的自定义属性(带有 Spirit CSS 变量前缀, 例如 `--spirit-local-color` 财务报告和审定财务报表 `--spirit-local-background-color`。 。 。 .
    
    iQQ 每一个表层类也同时暴露出背景和内容颜色的强度,无论你选择哪一个变体 (单位:千美元)`--spirit-local-background-color-basic`, (中文(简体) ), `--spirit-local-background-color-subtle`, (中文(简体) ), `--spirit-local-color-basic`,以及 `--spirit-local-color-subtle`因此,一个 单表面类可以给结合它们的组件配色,例如带有基本颜色指示器的微妙表面. 对于 `color-scheme-on-disabled`,基本背景是被禁用的前景——坐落在被禁用地表上被填充元素的颜色——及其单色 内容颜色既是内容强度,又是内容强度.
    
2.  **水电或部件** ——在同一元素上(或已经具有地表等级的祖先),使用读取这些本地人的公用事业: `bg-color-scheme`, (中文(简体) ), `text-color-scheme`,以及 `border-color-scheme` 所以背景、文字和边框 都放在纸盘上 而不列出每个符号 见 [动态色彩帮助演示](https://github.com/alma-oss/spirit-design-system/blob/main/packages/web/src/scss/helpers/dynamic-color/index.html) 用于实例. 或者直接在组件 CSS 类中读取颜色方案( 例如) `Pill`) (中文(简体) ).
    
3.  **键** ——感官和情感计划遵循口音和情感键 [`spirit-design-tokens`](https://github.com/alma-oss/spirit-design-system/tree/main/packages/design-tokens)新的口音或情感 转换为附加符号 `color-scheme-on-*` 当主题构建时。 固定键等 `neutral-*`, (中文(简体) ), `selected-*`,以及 `disabled` 在同一个生成器中与它们并列定义.
    

### 高级产品执行

❗ **重要内容:** 确保你有 `sass` 在您的工程中安装的依赖( e)`sass` 标记为可选对等依赖,因为您可以使用预建的分布式 CSS. 还有 [配置 Sass 装载路径](https://github.com/alma-oss/spirit-design-system/tree/main/packages/design-tokens#in-sass) 页:1 `@tokens`, (中文(简体) ), `@themes`,以及 `node_modules` 所以所有的依赖性都是由萨斯解决的.

已配置 Sass 载入路径, 您可以导入您的 Sass 样式表所需的组件 :

```scss
// my-product-styles.scss

// Spirit themes and foundation are mandatory
@use 'node_modules/@alma-oss/spirit-web/scss/themes';
@use 'node_modules/@alma-oss/spirit-web/scss/foundation';

// Spirit components can be hand-picked
@use 'node_modules/@alma-oss/spirit-web/scss/components/Button';

// Spirit helpers and utilities are optional
@use 'node_modules/@alma-oss/spirit-web/scss/helpers';
@use 'node_modules/@alma-oss/spirit-web/scss/utilities';
```

### 混合函数的使用

本套件提供的混接器和功能仅供内部使用. 它们的稳定性在语义化版本中得不到保证. 如果你选择使用,考虑把它们复制到自己的代码库来避免可能出现的问题.

### 自定义主题

#### 自动: 使用图像和超新星

建议的创建自定义主题的方法是使用Figma和Supernova来定义和导出您的设计符号,包括它们的主题变体. 一旦你得到了你的设计符号,你可以 [在您的 Sass 项目中使用](https://github.com/alma-oss/spirit-design-system/tree/main/packages/design-tokens#basic-usage)。 。 。 .

为了根据所提供的设计符号生成实际主题,仅包括我们 `themes` 在您的 Sass 项目中的文件 :

```scss
@use 'node_modules/@alma-oss/spirit-web/scss/themes';
```

#### 手动创建主题

如果您不使用"Figma"和"超新星",或者您需要仅以您UI中的一个小作品为主题,您可以手动创建自己的主题. 定义您的主题变量, 以便与您在 [`scss/themes/_color-tokens.scss`](https://github.com/alma-oss/spirit-design-system/blob/main/packages/design-tokens/src/scss/themes/_color-tokens.scss) 文件在设计符号包中.

例如:

```scss
@use '@tokens' as tokens;

:root,
.my-theme-light {
  --#{tokens.$token-prefix}color-text-primary: #007bff;
}

.my-theme-dark {
  --#{tokens.$token-prefix}color-text-primary: #beddff;
}
```

### 前置 CSS 类名称

您可以在 CSS 类名称中添加前缀, 以更好地将Spi精神与其他 CSS 区分开来 在你的项目。 建议的方法是使用PostCSS和 [`postcss-prefix-selector`](https://www.npmjs.com/package/postcss-prefix-selector) 插件 :

```js
// postcss.config.js

const postcssPrefixSelector = require('postcss-prefix-selector');

module.exports = {
  plugins: [
    postcssPrefixSelector({
      prefix: 'spirit-',
      transform(prefix, selector) {
        // Ignore interaction state classes controlled by JS: .is-* | .has-*
        const regex = /\.(?!is-|has-)/gi;
        return selector.replaceAll(regex, `.${prefix}`);
      },
    }),
  ],
};
```

### Java 脚本

一些组件需要JavaScript插件才能完全实现功能. 可以使用单个模块或编译的捆绑.

#### 个人或汇编

插件可单独作为ECMAScript模块(使用 `import { <plugin> } from '@alma-oss/spirit-web'`,参见 [使用 Spirit Web 作为模块](https://npmcn.com/package/%40alma-oss/spirit-web/#readme-using-spirit-web-as-a-module-in-browser)),或同时使用 `js/{cjs|esm|bundle}/spirit-web.js` 或修改 `js/{cjs|esm|bundle}/spirit-web.min.js` (不包括两者),所有文件都准备好了UMD.

```html
<script src="node_modules/@alma-oss/spirit-web/js/cjs/spirit-web.min.js" async></script>
```

如果使用捆绑器(Webpack, Rollup,.),可以使用 `/js/*.js` 文档是 ECMAScript 模块.

#### 在浏览器中使用 Spirit Web 作为模块

我们提供精神网络的版本 `ESM` (单位:千美元)`spirit-web.esm.js` 财务报告和审定财务报表 `spirit-web.esm.min.js`),它允许您在浏览器中使用Spirit Web作为模块.

```html
<script type="module">
  import { Header } from 'spirit-web.esm.min.js';

  Array.from(document.querySelectorAll('.header')).forEach((headerNode) => new Header(headerNode));
</script>
```

#### 数据属性

几乎所有Spirit-Web插件都可以通过HTML单独启用并配置数据属性(我们使用JavaScript功能的首选方式). 请确定仅在单个元素上使用一组数据属性( 例如, 您不能从同一按钮触发工具提示和模式) .

iQQ 关闭此功能时不会设置 `data-spirit-toggle` 属性并使用程序化 API.

> #### 选择器
> 
> 目前,为了查询DOM元素,我们使用本地方法 `querySelector` 财务报告和审定财务报表 `querySelectorAll` 基于性能原因,您必须使用有效的选择器. 如果使用特殊选择器,例如: `collapse:Example` 一定要逃脱他们.

#### 活动

Spirit-Web为大多数插件的独特动作提供自定义事件. 一般说来,这些是无限的和过去形式的 -- -- 无限的(前). `show`)在事件开始时被触发,以及其过去的participle形式(ex. `shown`)在动作完成后被触发.

所有无限活动都提供 [`preventDefault()`](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault) 函数. 这提供了在行动开始前停止执行的能力. 从事件处理器返回错误也会自动调用 `preventDefault()`。 。 。 .

```javascript
var myModal = document.getElementById('my-modal');

myModal.addEventListener('show.modal', function (event) {
  if (!data) {
    return event.preventDefault(); // stops modal from being shown
  }
});
```

#### 程序化 API

```javascript
var myModalEl = document.getElementById('my-modal');

var modal = new Modal(myModalEl); // initialized with defaults
```

如果您想要获得特定插件实例, 每个插件都会曝光一个 `getInstance` 方法.

#### CSS 构造器中的选择器

您也可以使用 CSS 选择器作为第一个参数,而不是 DOM 元素来初始化插件 . 目前,插件的元素由 `querySelector` 方法,因为我们的插件只支持单一元素.

```javascript
var modal = new Modal('#myModal');
var dropdown = new Dropdown('[data-spirit-toggle="dropdown"]');
```

### 光盘N

精神设计系统也可在CDN上访问:

| 说明 | 網址 |
| --- | --- |
| CSS:基金会 | https://cdn.jsdelivr.net/npm/@alma-oss/spirit-web@latest/cs/foundation.min.css |
| CSS:组件 | https://cdn.jsdelivr.net/npm/@alma-oss/spirit-web@latest/cs/组件.min.css |
| CSS: 帮助者 | https://cdn.jsdelivr.net/npm/@alma-oss/spirit-web@latest/cs/ helpers.min.css |
| CSS:主题 | https://cdn.jsdelivr.net/npm/@alma-oss/spirit-web@latest/cs/theoms.min.css 互联网档案馆的存檔,存档日期2014-12-21 |
| CSS:公用事业 | https://cdn.jsdelivr.net/npm/@alma-oss/spirit-web@latest/cs/utilities.min.css |
| Java 脚本 | https://cdn.jsdelivr.net/npm/@alma-oss/spirit-web@latest/js/bundle/spirit-web.bundle.min.js |

考虑使用特定版本而不是 `latest` 在生产中.

## 单位 - `rem`

精神主要用来 `rem` 相距、打字、光度和阴影 以 `rem` 相对于a **16 个 px** 根字体大小。 故意行为 `px` 存在例外 对于不能以根字体大小缩放的值,例如边框宽度和 隐形公用技术.

见 [单位指南](https://github.com/alma-oss/spirit-design-system/tree/main/docs/contribution/units.md) 详细情况,包括常设委员会 `px-to-rem()` 函数,以及基准字体大小与设计符号的关系.

## 重命名

设计符使Spirit Sass的组件和风格能够快速而轻松地被重新命名. 一旦你创建了自己的设计符号, 就把它们提供给你的 Sass 编译器, 你准备走了! 学习更多在 [`spirit-design-tokens` 文档](https://github.com/alma-oss/spirit-design-system/tree/main/packages/design-tokens#rebranding-spirit)。 。 。 .

## 发展

启动本地开发服务器 `yarn start` 要开始。 您将在浏览器中获取所有组件和插件的活性预览 。 只要弄脏东西,改变一些东西, 你会看到改变是活的.

Dev-stack是基于 [维特](https://vitejs.dev/)。 。 。 .

## 折旧

此套件对在下个主放出时会被去掉或被替换的道具,功能和组件使用去化警告. 检查您的浏览器控制台, 以查看您是否正在使用任何已贬值的功能 .

![Deprecations in the Browser's console](https://github.com/alma-oss/spirit-design-system/blob/main/static/deprecations-browser-console.png?raw=true)

👉 [参见 DePRECATES 文件](https://github.com/alma-oss/spirit-design-system/tree/main/packages/web/DEPRECATIONS.md) 列出所有贬值情况.

## 特性旗

见 [特性标记文档](https://github.com/alma-oss/spirit-design-system/blob/main/docs/contribution/feature-flags.md) 如何使用它们.

## 实例

见 [实例](https://spirit-design-system.netlify.app/packages/web/) 现场演示.

## 许可证

见 [自由主义](https://github.com/alma-oss/spirit-design-system/blob/main/packages/web/LICENSE.md) 文档供参考.

## 常见问题

### @alma-oss/spirit-web 是什么？

CSS和香草JS 精神设计系统的实施

### 如何安装 @alma-oss/spirit-web？

在项目目录运行 npm install @alma-oss/spirit-web，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：sass-embedded（\>=1\.57\.0 \< 2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @alma-oss/spirit-web 支持 TypeScript 吗？

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

### @alma-oss/spirit-web 支持 ESM 还是 CommonJS？

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

### @alma-oss/spirit-web 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @alma-oss/spirit-web 可以商用吗？

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

### @alma-oss/spirit-web 的下载量有多少？

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

### @alma-oss/spirit-web 还在维护吗？

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