# @bloom-housing/ui-seeds 中文文档

规范地址：https://npmcn.com/package/%40bloom-housing/ui-seeds/

版本：3\.4\.3
npm 元数据更新时间：2026-07-13T17:01:06.153Z
中文译文更新时间：2026-11-08T07:51:30.950Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40bloom-housing/ui-seeds
原文对照：https://npmcn.com/package/%40bloom-housing/ui-seeds/?lang=original
项目主页：https://github.com/bloom-housing/ui-seeds

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

- 包体积（解压后）：821 kB，265 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：13 个
- 首次发布：2022-11-17T19:51:07.890Z
- 最新版本发布：2026-04-22T22:55:56.648Z
- 近 30 天下载量：2755（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：64（近 12 个月 13 个）

## 中文简介

这个包裹是 [布鲁姆](https://bloomhousing.com/)其核心UI组件,意在从各种应用内部导入. 种子取代了Bloom之前的"ui-组件"包.

## 安装

```sh
npm install @bloom-housing/ui-seeds
```

也可以使用：`pnpm add @bloom-housing/ui-seeds`、`yarn add @bloom-housing/ui-seeds`、`bun add @bloom-housing/ui-seeds`

## README

# 种子 — Bloom 组件库

这个包裹是 [布鲁姆](https://bloomhousing.com/)其核心UI组件,意在从各种应用内部导入. 种子取代了Bloom之前的"ui-组件"包.

种子使用TypeScript,React,和Sass来构建. 它使用"故事本"作为混凝土组件示例,并使用"杰斯"作为测试.

我们建议在装入种子时使用节点版本22.

## 设计系统文档

[此逗号页面](https://exygy.notion.site/Seeds-11a684ea9b7544f4bbc99d2284aa4613?source=copy_link) 是补充种子文档的中心.

同样在"概念"中,我们使用 [零高到文档符号、组件和图案](https://zeroheight.com/5e69dd4e1/p/938cb5-seeds-design-system) 种子设计系统.

对于代码级别随着时间的推移的变化, [参见 GitHub 更改日志的发布](https://github.com/bloom-housing/ui-seeds/releases)。 。 。 .

## 使用量

### 下一个.js

为了建立种子,首先增加 `@bloom-housing/ui-seeds` 包通过 npm 或纱线。 下一个, 更新 `next.config.js` 将软件包名称纳入其 `transpilePackages` 配置选项 :

```js
  transpilePackages: [
    "@bloom-housing/ui-seeds"
  ]
```

您需要安装 Sass & PostCSS , 同时安装 `@csstools/postcss-global-data` 打开 `postcss-custom-media` 软件包。 确保通过《公约》提供 `postcss.config.js` 文件 :

```js
  plugins: {
    "@csstools/postcss-global-data": {
      // in the Bloom monorepo, this starts with `../../`:
      files: ["node_modules/@bloom-housing/ui-seeds/src/global/tokens/screens.scss"],
    },
    "postcss-custom-media": {},
    ...
  }
```

最后,在您输入种子的主要 CSS 切入点 `_app.tsx` 文件 :

```js
import "@bloom-housing/ui-seeds/src/global/app-css.scss"
```

现在您可以在您需要使用种子的页面上导入单个种子反应组件 .

## 捐款

种子主要包括: **设计符号** 财务报告和审定财务报表 **组件**. 有一些全球风格规则和实用类,但被故意保持在最低限度。 尽可能采用组件范围样式规则.

对于设计标志、组件类别和公用事业类别,一般建议从 `seeds` 前缀.

### 设计托肯斯

设计标志分为两层: **基础符号** 财务报告和审定财务报表 **语义符号**语义符号 _消费_ 基础标志。 只要有可能,组件就应当依赖语义符号而不是基号. 这将使下游主题易于定制(鼓励消费者推翻语义符号, _没有_ 基础符号).

譬如说, `--seeds-color-blue-500` 设置为 `#0077da`此外, `--seeds-color-primary` 设置为 `var(--seeds-color-blue-500)`您的组件应当使用 `--seeds-color-primary` 而不是说 `--seeds-color-blue-500`除非你知道这一点 _永远_ 需要使用这种特定的颜色,无论下游主题的变化如何.

鼓励组件设置自己的组件特有符号,这些符号既能发挥语义符号的作用,又能发挥基础符号的作用(当合适的语义符号没有可用时). 例如:

```css
.seeds-card {
  --card-spacing-md: var(--seeds-s6); /* a base token */
  --card-background-color: var(--seeds-bg-color-surface); /* a semantic token */
}
```

在一个组件中的各种部件/子组件中,许多组件消耗了在这个顶层定义的组件符号.

我们不鼓励在顶层以下定义符号, 因为消费者需要知道一个组件的内部DOM结构, 这不利于未来兼容性.

```css
/* Bad */
.seeds-component {
  --component-token-1: var(--seeds-s3);

  padding: var(--component-token-1);

  > .seeds-component-section {
    --component-token-2: var(--seeds-s5);

    padding: var(--component-token-2);
  }
}

/* Good */
.seeds-component {
  --component-token-1: var(--seeds-s3);
  --component-section-token-1: var(--seeds-s5);

  > .seeds-component-section {
    padding: var(--component-section-token-1);
  }
}
```

### 构成部分定义

组件被构建为功能回放组件,有文件名来匹配组件名称. 这么说吧 `FieldValue.tsx` 导出一个命名的组件 `FieldValue`。组件文件位于“侧车”旁边 `.scss` 包含组件样式的文件.

组件类是前缀组件的kebab cased名 `seeds`。这样 `FieldValue` 构成部分将与 `seeds-field-value` 类名.

部件可能提供多种变体,如颜色/类型变体,大小等. 鼓励使用 `data-*` 要指定这些变量的 HTML 属性 :

```jsx
<span
  id={props.id}
  className={classNames.join(" ")}
  data-variant={props.variant || "primary"}
  data-size={props.size}
  aria-label={props.ariaLabel}
>
  {props.children}
</span>
```

在您的样式表中, 您可以根据这些属性添加样式规则 :

```css
.seeds-tag {
  &[data-variant="primary"] {
    background-color: var(--seeds-color-primary-light);
    color: var(--seeds-color-primary-dark);
  }

  &[data-size="lg"] {
    font-size: var(--tag-font-size-lg);
    font-weight: var(--tag-font-weight-lg);
  }
}
```

一些布尔式的变体或"状态"作为条件类更直接. 在这种情况下,我们通常使用 `is-` 或者说 `has-` 前缀,例如:. `.is-fullwidth` 或者说 `.has-lead-icon`。 。 。 .

一些州也通过使用ARIA的角色和属性得到更好的表达. 如果ARIA无论如何都需要通过HTML标记来管理,那么最好将样式从那些上挂起,而不是通过额外的属性/类引入重复.

### 文档

故事记录在 `__stories__` 文件夹在 `.stories.tsx` 文档。 然后这些故事可以在零高度范围内被显示在文档中.

此外 `.docs.mdx` 文件将显示道具和造型信息.

组件道具与JSDoc评论一起使用TypeScript接口来记录. 这些评论将在《故事书》中使用 `ArgsTable` mDX文件中的组件.

组件符也使用故事MDX文件中的Markdown表来记录.

在"零高"中,由于设置的集成,故事很容易被一一地嵌入. 然而,要嵌入道具/样式的docs页面,您需要打开"故事本",点击"Docs"选项卡一个组件,并将URL复制到"iframe"嵌入于零高度以内.

## 测试

单位测试设在 `__tests__` 文件夹,用 React 的测试库编写,并通过 Jest 执行 。 单元测试的目的是核查一个组件的基本功能以及显示逻辑中的任何主要分支.

## 常见问题

### @bloom-housing/ui-seeds 是什么？

这个包裹是 布鲁姆其核心UI组件,意在从各种应用内部导入\. 种子取代了Bloom之前的"ui-组件"包\.

### 如何安装 @bloom-housing/ui-seeds？

在项目目录运行 npm install @bloom-housing/ui-seeds，或使用 pnpm add / yarn add / bun add。

### @bloom-housing/ui-seeds 支持 TypeScript 吗？

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

### @bloom-housing/ui-seeds 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @bloom-housing/ui-seeds 可以商用吗？

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

### @bloom-housing/ui-seeds 的下载量有多少？

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

### @bloom-housing/ui-seeds 还在维护吗？

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