# @brightspot/ui 中文文档

规范地址：https://npmcn.com/package/%40brightspot/ui/

版本：6\.8\.3
npm 元数据更新时间：2026-11-09T18:51:33.444Z
中文译文更新时间：2026-11-09T18:53:04.725Z
软件包许可：UNLICENSED

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

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

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

- 包体积（解压后）：32.7 MB，1166 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：8 个
- peer 依赖：lit ^3\.0\.0
- 首次发布：2025-05-07T18:39:59.675Z
- 最新版本发布：2026-11-09T18:51:33.271Z
- 近 30 天下载量：2448（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：138（近 12 个月 125 个）

## 中文简介

一个用于构建Brightspot CMS组件的UI库.

## 安装

```sh
npm install @brightspot/ui
```

也可以使用：`pnpm add @brightspot/ui`、`yarn add @brightspot/ui`、`bun add @brightspot/ui`

## README

# 亮点UI

`@brightspot/ui` 是一个现成的界面部件——按钮、部件、图标——的库,外加布莱特斯波克CMS内屏幕的全套颜色和样式(浅色、暗色和高相通度).

CMS自己的接口是从这个UI库所建,我们逐渐将其余部分移走. 亦会发表.

## 你想怎样?

-   [修正或更改 CMS 用户界面](https://npmcn.com/package/%40brightspot/ui/#readme-fix-or-change-the-cms-ui)
-   [在工程中使用 UI 库](https://npmcn.com/package/%40brightspot/ui/#readme-use-the-ui-library-in-a-project)
-   [改进UI 库本身](https://npmcn.com/package/%40brightspot/ui/#readme-improve-the-ui-library-itself)

* * *

## 修正或更改 CMS 用户界面

CMS 接口位于 `src/legacy/tool-ui/`。编辑那里的文件,并以两种方式之一运行的 CMS 预览它们.

**你会需要:** 节点 22 (`nvm use 22`),Yarn 1,当地人 `brightspot` 离职,以及 `yarn install` 接下来 `yarn build` 跑一次这里。 CMS 捆绑从构建输出中导入一些库组件, 所以重新运行 `yarn build` 在改变它们之后.

> **编辑器提示 :** 在VSCode中,建议的扩展自动完成 `btu-*` 按键的课。 见 [VSCode 设置注释](https://npmcn.com/package/%40brightspot/ui/src/legacy/tool-ui/README.md#visual-studio-code)。 。 。 .

### 快活方式——直播预览(供每日编辑)

1.  启动 CMS 后端( 在您的 `brightspot/` 文件夹 :
    
    ```sh
    docker compose up -d
    ```
    
2.  启动现场预览( 这里) :
    
    ```sh
    cd src/legacy/tool-ui
    yarn server:local
    ```
    
3.  打开 Dev 服务器 - 注意到 **`:8080`**,不简单 `localhost`数字 :
    
    ```
    https://localhost:8080/cms/
    ```
    
    通过证书警告( 本地证书- 普通) 单击 .
    

现在编辑任何内容 `src/legacy/tool-ui/src/` 和浏览器自行更新——不重建.

_看见 `502` 错误? CMS后端无法被接通——检查插座台阶._

_看见 `The 'btu-…' class does not exist` 在拉后吗? 运行 `yarn install` 在这里。 新的公用事业可以带来新的依赖性版本——图标名称来自 `lucide-static` ——和一拉更新代码而不更新安装的. 运行在 repo 根安装 `src/legacy/tool-ui/` 工作空间也一样,所以一个命令覆盖两个._

### 全程——构建正版包(仅供最终检查)

慢些,但实际生成 CMS 飞船。 需要两个临时编辑 `brightspot` —— 说 **别让他们犯法**。 。 。 .

1.  构建软件包( 这里):
    
    ```sh
    ./gradlew publishToMavenLocal
    ```
    
2.  点 `brightspot` 在你的建筑:
    
    -   `site/build.gradle` 添加 `mavenLocal()` 下级 `repositories`
        
    -   `platform/brightspot-dependencies/build.gradle` ——将cms-tool-ui线改为:
        
        ```groovy
        api 'com.brightspot.ui:cms-tool-ui:9999-SNAPSHOT'
        ```
        
3.  重建并运行( 在 `brightspot/`:
    
    ```sh
    ./gradlew docker
    ```
    
4.  请在 https://localhost/ cms/ 上检查, 完成后撤销这两个编辑 .
    

* * *

## 在工程中使用 UI 库

> 开始一个新的前端软件包吗 ? [`@brightspot/ui-builder`](https://www.npmjs.com/package/@brightspot/ui-builder) 脚手架 建筑(Vite)和电线 这个预设给你。 下面的步骤是将库添加到您已有的建筑中.

**你会需要:** a 前端使用 TailwindCSS v3.

```sh
yarn add -D @brightspot/ui
```

如果您还没有, 请在您前端的根部创建 Tailwind 配置文件 `tailwind.config.mjs`数字 :

```js
// tailwind.config.mjs
export default {
  content: ['./src/**/*.{js,ts,html,java}'], // wherever your markup lives, including Java that builds class lists
}
```

然后添加 `@brightspot/ui` 作为 [预设](https://v3.tailwindcss.com/docs/presets)一行牵出一切——所有颜色、风格和组件:

```js
// tailwind.config.mjs
import preset from '@brightspot/ui'

export default {
  presets: [preset],
  content: ['./src/**/*.{js,ts,html,java}'],
}
```

离开 `plugins` 空出——预设已经注册了每个组件的插件,所以再次列出它们的双注册.

要使用一个组件,请导入它(它自登记为 `btu-*` 元素),然后使用标记。 从 `components/` 子路径与 `.js` ——不是深层 `dist/` 路径 :

```ts
import '@brightspot/ui/components/badge/Badge.js'
```

```html
<btu-badge>Draft</btu-badge>
```

在CMS的一页上,CMS只定义了其中的几个元素本身. 导入您插件使用的其他元素, 包括您 Java 通过生成的元素 `com.brightspot.ui.dari` 课程. [在插件中使用这些](https://npmcn.com/package/%40brightspot/ui/docs/components/README.md#using-these-in-a-plugin) 列出CMS定义的.

在 [(原始内容存档于2017-10-29). ui.brightspot.com](https://ui.brightspot.com/)。网站只显示最新版本。 为浏览您安装的版本( 6. 8. 1 或 稍后的版本), 提供包件中船舶的复制件并打开 http://localhost: 6006:

```sh
npx http-server node_modules/@brightspot/ui/dist/storybook -p 6006
```

开幕 `index.html` 直接从磁盘上跳出来不起作用, 因为浏览器会屏蔽它的脚本 `file://`。 。 。 .

### 指定您的 AI 编码代理

包船为编码代理撰写的文件,与已安装的版本相匹配: `llms.txt` 在软件包根,每个组件一页 `docs/components/`,和"自定义元素表". 探员不会自己找到的 所以把这个加进你的项目 `AGENTS.md` 或者说 `CLAUDE.md`数字 :

```md
## @brightspot/ui

This project uses `@brightspot/ui` web components (`btu-*` tags). Before writing or changing code that uses them,
read `node_modules/@brightspot/ui/llms.txt` and the component pages it links to. They match the installed version,
so prefer them over what you remember about this library.
```

没有本地安装, 给代理 `https://ui.brightspot.com/llms.txt`,它描述了最新的发布.

* * *

## 改进UI 库本身

添加或固定一个组件、样式或颜色.

**你会需要:** 节点 22 (`nvm use 22`(原始内容存档于2018-03-13) (中文(简体) ). Yarn 1.

**物所居之处:**

-   `src/` ——UI库(组件,样式,颜色);这就是要出版的内容.
-   `src/legacy/tool-ui/` ——CMS接口(见第一节).
-   `tool-ui/` - 只有包装.

在目录中构建和预览组件——不需要 CMS :

```sh
yarn storybook
```

承诺前:

```sh
yarn build              # compile everything
yarn check:conventions  # check the rules
yarn format             # tidy formatting
yarn test:storybook     # run tests
```

**房屋规则** 当你摸到其中一个区域时,请在 `.ai/` 第一条:

| 区域 | 指南 |
| --- | --- |
| 命名(大小、图标、事件、CSS vars) | `.ai/LESSONS-NAMING.md` |
| JSDoc和类型 | `.ai/LESSONS-JSDOC.md` |
| 重用原始按钮 | `.ai/LESSONS-BUTTON-REUSE.md` |
| 保留插件样式 | `.ai/LESSONS-PLUGIN-ISOLATION.md` |
| 在运行时编写安全列表类 | `.ai/LESSONS-SAFELIST.md` |
| 预设 vs 故事本配置; 添加新插件 | `.ai/LESSONS-TAILWIND-CONFIGS.md` |
| CSS 自定义属性 + Tailwindow gotchas | `.ai/LESSONS-CSS-PROPS.md` |
| 写故事书故事 | `.ai/LESSONS-STORYBOOK.md` |
| 锚地定位/弹出式 | `.ai/LESSONS-ANCHOR-POSITIONING.md` |
| 减少动议 | `.ai/LESSONS-REDUCED-MOTION.md` |
| 移动标签索引 | `.ai/LESSONS-ROVING-TABINDEX.md` |
| 编组组件 | `.ai/LESSONS-COMPONENT-COMPOSITION.md` |

见 [`CONTRIBUTING.md`](https://npmcn.com/package/%40brightspot/ui/CONTRIBUTING.md) 文件标准.

**释放** 自动: 合并到 `main`,并为您标记并发布一个版本.

## 常见问题

### @brightspot/ui 是什么？

一个用于构建Brightspot CMS组件的UI库\.

### 如何安装 @brightspot/ui？

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

### @brightspot/ui 支持 TypeScript 吗？

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

### @brightspot/ui 支持 ESM 还是 CommonJS？

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

### @brightspot/ui 可以商用吗？

@brightspot/ui 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @brightspot/ui 的下载量有多少？

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

### @brightspot/ui 还在维护吗？

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