# @bsuite/ui 中文文档

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

版本：1\.3\.4
npm 元数据更新时间：2026-10-20T18:05:26.145Z
中文译文更新时间：2026-11-08T19:09:03.827Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40bsuite/ui
原文对照：https://npmcn.com/package/%40bsuite/ui/?lang=original
项目主页：https://github.com/Arcane-Fly/bsuite#readme
源码仓库：https://github.com/Arcane-Fly/bsuite

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

- 包体积（解压后）：196 kB，72 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：8 个
- peer 依赖：react ^18\.3\.0 \|\| ^19\.0\.0，react-dom ^18\.3\.0 \|\| ^19\.0\.0，@bsuite/theme \>=0\.7\.0 \<2，@supabase/postgrest-js ^2
- 首次发布：2026-04-21T01:41:53.655Z
- 最新版本发布：2026-10-20T18:05:25.836Z
- 近 30 天下载量：4230（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

BSuite应用软件(D2C Neon Electric + Corporation品牌)的共享UI原始产品.

## 安装

```sh
npm install @bsuite/ui
```

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

## README

# @bsuite/ ui (英语)

BSuite应用软件(D2C Neon Electric + Corporation品牌)的共享UI原始产品.

船舶作为 npm 包,因为Vercel 部署 每一个 BSuite 应用程序从自己的 GitHub repo — 父单曲 `packages/` 目录不存在于 vercel构建上下文。 消费者从npm安装有被固定的铸模.

## 构成部分

### 核心原始(v. 4.0+) s

该软件包现在拥有共享的 第一级 UI 原始应用程序应该聚合于:

```tsx
import {
  Button,
  Dialog,
  DialogContent,
  DialogHeader,
  DialogTitle,
  EmptyState,
  ErrorBoundary,
  LoadingSpinner,
  StatusBadge,
} from '@bsuite/ui'
```

这些原始人只使用 BSuite/shadcn 语义符号类(`bg-primary`, (中文(简体) ), `text-muted-foreground`, (中文(简体) ), `border-border`, (中文(简体) ), `text-status-success`d2C应用程序可以 把它剥光 `@bsuite/theme` 布莱登可以将同样的角色映射到 公司调色板.

### 故事书

从此软件包运行共享原始相册 :

```bash
pnpm -C packages/ui storybook
pnpm -C packages/ui build-storybook
```

### `DotPattern`

全景口点-平面背景. 特别工作组 `<pattern>` 平板-~1 DOM 节点 (vs~1800运动. 一个典型的取景口上的圆形节点).

```tsx
import { DotPattern } from '@bsuite/ui'

<div className="relative">
  <DotPattern
    width={28}
    height={28}
    cr={1.5}
    className="opacity-[0.35] text-muted-foreground"
  />
  {/* page content */}
</div>
```

通过语义 Tailwind 控制颜色 `text-*` 水电费(水电费) `fill="currentColor"`) (中文(简体) ).

### `Logo`

Slot-aware,主题-aware,品牌-aware标志组件 所有 BSuite app.

```tsx
import { Logo } from '@bsuite/ui'

<Logo slot="header" colorScheme="auto" />
```

### `D2CDefaultLogo`

内置 D2C 霓虹电器 SVG 标识(无资产依赖性).

```tsx
import { D2CDefaultLogo } from '@bsuite/ui'

<D2CDefaultLogo className="h-8 w-auto" />
```

## 品牌组件(v0.3.0+)

### `OklchColorPicker`

OKLCH色彩格式(BSite标准)的色彩输入组件.

```tsx
import { OklchColorPicker } from '@bsuite/ui'

<OklchColorPicker
  value="oklch(0.546 0.215 262.9)"
  onChange={(value) => console.log(value)}
  label="Primary Color"
  description="Your brand's primary color in OKLCH format"
/>
```

**特征 :**

-   现场颜色预览
-   L( 亮度)、 C( 色相)、 H( 色相) 输入字段
-   方便调整的滑动控制
-   验证 OKLCH 格式
-   可访问标签和错误消息

### `ColorEditorSheet`

用于编辑品牌颜色的平面/对话框,并配有基于槽的颜色编辑器.

```tsx
import { ColorEditorSheet, OklchColorPicker } from '@bsuite/ui'

<ColorEditorSheet
  open={isOpen}
  onOpenChange={setIsOpen}
  title="Edit Primary Color"
  description="Adjust the OKLCH color values"
  value="oklch(0.546 0.215 262.9)"
  onSave={(value) => updateBranding('primary', value)}
  renderEditor={(props) => <OklchColorPicker {...props} />}
/>
```

**特征 :**

-   幻灯片出工作表接口
-   基于槽的颜色编辑器( 输入您自己的拾取器)
-   保存/取消动作
-   反应设计
-   可访问的对话执行

### `BrandingCard`

用于显示和编辑租户品牌配置的卡片组件.

```tsx
import { BrandingCard, OklchColorPicker } from '@bsuite/ui'

<BrandingCard
  branding={{
    primary: "oklch(0.546 0.215 262.9)",
    accent: "oklch(0.769 0.132 191.7)",
    logo_url: "https://example.com/logo.svg",
    company_name: "Acme Corp"
  }}
  onUpdate={async (key, value) => {
    await updateTenantBranding(key, value)
  }}
  renderColorEditor={(props) => <OklchColorPicker {...props} />}
/>
```

**特征 :**

-   显示当前品牌值( 颜色、 标志、 公司名称)
-   编辑每个品牌属性的按钮
-   与 ColorEditor Sheet 合并色彩编辑
-   标识的图像预览
-   无障碍和响应性设计
-   支持轻/暗模式标志变体

**标记属性 :**

-   `primary` - 主动作颜色(OKLCH)
-   `accent` - 丙烯/二级颜色(OKLCH)
-   `logo_url` - 主要标志 URL
-   `logo_light_url` - 轻模式标志变体(可选)
-   `logo_dark_url` - 暗模式标志变体(可选)
-   `favicon_url` - 法维康URL(16x16或32x32)
-   `company_name` - 备选文本的公司名称

## `EntitySelector` (v1.2.0+) (中文(简体) )

通用的、可忽略的可搜索组合框,用于从任意一行中选择一行 须菩提座. 从crm7(AD-5,2026-08-17)中摘录的crm7有65个文件: 收养和另外两个应用 开始亲手传送自己的副本 相同的路径。 这是目前唯一的执行.

数据访问是依赖注入的——软件包没有Supabase 客户端,因为每个应用程序的客户端形状不同(Vite-SPA singleton, 按请求数 `createClient()` 工厂,不同 `storageKey`, . : (中文(简体) )

```tsx
import { EntitySelector } from '@bsuite/ui'
import { supabase } from '@/lib/supabase' // your app's own client

<EntitySelector<Employer>
  supabaseClient={supabase}
  table="employers"
  value={form.employer_id}
  onSelect={(emp) => setValue('employer_id', emp?.id ?? null)}
  displayField={(r) => r.business_name}
  secondaryField={(r) => r.abn ?? r.industry}
  searchColumns={['business_name', 'trading_name', 'abn']}
/>
```

**建议的每项申请模式:** 将导入包入本地文件一次 绑起你的客户端, 所以其余的应用程序的~十几个呼叫网站 永远不要重复 `supabaseClient={supabase}`数字 :

```tsx
// src/components/entity/EntitySelector.tsx
import { EntitySelector as BaseEntitySelector, type EntitySelectorProps as BaseProps } from '@bsuite/ui'
import { supabase } from '@/lib/supabase'

export type EntitySelectorProps<T extends Record<string, unknown>> = Omit<BaseProps<T>, 'supabaseClient'>

export function EntitySelector<T extends Record<string, unknown>>(props: EntitySelectorProps<T>) {
  return <BaseEntitySelector<T> supabaseClient={supabase} {...props} />
}
```

**特征 :** 已卸出型号头( e)`ilike` 跨越已配置的列, 可选的横切图为(`schema` 道具),a `filterFn` 逃生舱门 任意 PostgREST 过滤链, “一发” 建议选项( 已列) 链接在较早的屏幕上,在任何打字前显示),一个自动安全 `onSelect` (当呼叫者通过一个 导入/ RPC 步骤),以及一个明显的错误状态(不是相同的“ 无结果” 复制 一个真正的空搜索显示).

也输出用于建造同一种视觉语言的自定义拾取器: `Command`, (中文(简体) ), `CommandInput`, (中文(简体) ), `CommandList`, (中文(简体) ), `CommandGroup`, (中文(简体) ), `CommandItem`, (中文(简体) ), `CommandEmpty`, (中文(简体) ), `Popover`, (中文(简体) ), `PopoverTrigger`, (中文(简体) ), `PopoverContent`。 。 。 .

## 用户

### `cn(...classes)`

阴影风格的类Name 合并 - `clsx` + 键 `tailwind-merge`备查 想要作曲的消费者 `@bsuite/ui` 有本地覆盖的组件 别再扯出阴影.

## 模块导出

该套件提供子路径导出, 用于更好的树摇:

```tsx
// Main exports
import { Logo, BrandingCard, Button, StatusBadge } from '@bsuite/ui'

// Dot pattern only
import { DotPattern } from '@bsuite/ui/dot-pattern'

// Utils only
import { cn } from '@bsuite/ui/utils'

// Branding components only
import { BrandingCard, ColorEditorSheet, OklchColorPicker } from '@bsuite/ui/branding'

// Primitive subpaths
import { Button } from '@bsuite/ui/button'
import { DialogContent } from '@bsuite/ui/dialog'
import { EmptyState } from '@bsuite/ui/empty-state'
import { EntitySelector } from '@bsuite/ui/entity-selector'
import { Command, CommandInput } from '@bsuite/ui/command'
import { Popover, PopoverContent } from '@bsuite/ui/popover'

// SVG asset
import logoSvg from '@bsuite/ui/assets/d2c-default-logo.svg'
```

## 释放

1.  在下方编辑源 `src/`。 。 。 .
2.  `pnpm -C packages/ui test` 所有案件都必须通过.
3.  `pnpm -C packages/ui build` - 发射 `dist/`。 。 。 .
4.  弹出版本 `package.json` (em.
5.  将软件包释放的 PR 合并到 `main`· ; `.github/workflows/publish-ui.yml` 通过 npm 信任出版商出版(GitHub Actions OIDC, no) `NPM_TOKEN`) (中文(简体) ).
6.  更新消费者 `package.json` 重新生成锁文件 **外部** bsuite 树( 见根) `CLAUDE.md` 第7条) lockfile + 一个消费者侧凸起式 PR.

**从来没有** 使用情况 `workspace:*` 或者说 `file:../packages/ui` 用于此软件包的 a 消费者 Vercel Building无法解决这些问题.

## 发布 1.3.4

最后敲定 `1.3.4-next.2` 源代码没有进一步的运行时间变化。 那个预览 已经拒绝每个样式表上下文中的资源加载图像函数 并包括下面可访问选择器的清晰控制。 消费者采用 在公布和检查现有所储存的品牌CSS之后,将推出稳定版本.

### 自定义品牌 CSS 边界

资源加载图像函数被拒绝 完整样式表,在逃出解码后, 案件折叠和供应商前缀删除,每处上下文(规则, `@media`, (中文(简体) ), `@supports` 前奏 键盘, `@property` 和定制财产价值, `var()` 倒计时 : `url`, (中文(简体) ), `src`, (中文(简体) ), `image`, (中文(简体) ), `image-set`, (中文(简体) ), `cross-fade`, (中文(简体) ), `element` 财务报告和审定财务报表 `paint`. 纯油漆 例如 `linear-gradient`, (中文(简体) ), `radial-gradient`, (中文(简体) ), `conic-gradient` 联合国 重复表格仍然被接受,但须遵守以下语义-颜色规则。 存储 使用这些功能的租户CSS现在无法验证; 测量存储的 数据是一个消费者-采纳步骤,而不是这个软件包变化的一部分.

`validateCustomCss` 双向导出 `@bsuite/ui` 财务报告和审定财务报表 `@bsuite/ui/branding`。 。 。 . 在保存样式表前调用它 。 接受的结果包含不变的结果 样式表; 无效或不支持的结果包含可操作的理由,并且, 可用时,源行. 保留作者的草稿拒绝. `sanitizeCustomCss` 每个运行时间槽保留其现有的字符串 API,并 返回已拒绝样式表的空字符串。 通过插入接受的CSS `HTMLStyleElement.textContent`从HTML插入.

拥有的剖析器为CSS-tree 3.2.1. 其AST和财产/描述语法允许 排版、打字、媒体/支持/容器/层规则、键框和界限 本地自定义属性。 彩色消费者必须使用语义主题变量; 透明且当前颜色仍为中性值。 原始调色板颜色, 端点颜色,包括α形式、不安全的资源、受保护的角色和 阴影定义, 和不支持的语法拒绝整个样式表 。 逃亡, 可变回落、别名级联和打入自定义财产初始值 穿过同一个边界。 解析的 @ supports 容量探测器不画或 重新界定角色;其真正的规则块仍然受到注意,资源/可执行 整个样式表仍然适用排除。 自定义动画和网格名称保留其大小写和 不被误认为颜色绑定。 解析器和别名的扩展 明确源、符、深度和节点限制.

主题调色板命名空间及其颜色别名也受到保护,因为 主题角色在已提交的样式表之外消耗它们。 尾风颜色和 整个油漆/效果槽(包括梯度、阴影、环和口罩)不能 重新定义。 它的数位变换,位置和口罩几何槽仍然保留 可编写,并检查有颜色的别名和回放。 测试得到这个 主题来源和实际排放的 Tailwind 公用事业的边界; 此 不声称在不相关的外部样式表中识别任意变量.

编辑器必须表面拒绝,而不是默默地保存空CSS. 运行时间 还需要验证,因为现有的持续CSS早于这一规则. BSU, CRM7 和 Braden 是当前六应用程序中的三个定制CSS消费者 来源普查;仍采用出版物包装和部署用户验收 分开的大门.

`EntitySelector` 显示选中的可选本地兄弟清晰按钮 实体。 它的可访问名称包括所选标签. 单击、输入和 空间呼叫 `onSelect(null)` 一次返回焦点到组合框中而不打开 选择者或提交周围表格。 残疾人 `clearable=false` 合同适用于此按钮。 承诺回归的父储蓄仍然具有权威性: a 有待澄清的防止重新提交和相互冲突的选择/设定, 拒绝保留所保存的选择 显示重试消息,然后按照控值成功清除。 仅注重定居返回 (a) 仍在启动控制中或因使其失效而丢失; 焦点被保留到另一个字段. 选定的ID水合和过滤是分开的 合同,但因这一修补而保持不变.

## 常见问题

### @bsuite/ui 是什么？

BSuite应用软件\(D2C Neon Electric \+ Corporation品牌\)的共享UI原始产品\.

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

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

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

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

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

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

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

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

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

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

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

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