# @brainfish-ai/components 中文文档

规范地址：https://npmcn.com/package/%40brainfish-ai/components/

版本：0\.37\.1
npm 元数据更新时间：2026-11-04T22:09:12.703Z
中文译文更新时间：2026-11-08T14:13:56.425Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40brainfish-ai/components
原文对照：https://npmcn.com/package/%40brainfish-ai/components/?lang=original

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

- 包体积（解压后）：1.1 MB，625 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：22\.x \|\| 24\.x
- 运行依赖：70 个
- peer 依赖：clsx ^2\.x，react 18\.x \|\| 19\.x，react-dom 18\.x \|\| 19\.x，usehooks-ts ^3\.x，tailwind-merge ^2\.x，tailwindcss-animate ^1\.x，@phosphor-icons/react ^2\.x，class-variance-authority ^0\.7\.x，@tailwindcss/container-queries 0\.1\.x
- 首次发布：2024-12-23T11:09:41.007Z
- 最新版本发布：2026-11-04T22:09:12.500Z
- 近 30 天下载量：2653（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：377（近 12 个月 149 个）

## 中文简介

脑鱼成分

## 安装

```sh
npm install @brainfish-ai/components
```

也可以使用：`pnpm add @brainfish-ai/components`、`yarn add @brainfish-ai/components`、`bun add @brainfish-ai/components`

## README

# 脑鱼成分

Brainfish组件是一个Resact组件库,支持批量进口和单个组件进口(类似于shadcn/ui),以优化树摇和捆绑尺寸.

## 安装

```bash
npm install @brainfish-ai/components
# or
yarn add @brainfish-ai/components
```

## 使用量

### 单个组件导入(建议)

仅导入最佳捆绑大小所需的组件 :

```tsx
// Import individual UI components
import { Button } from '@brainfish-ai/components/ui/button';
import { Dialog } from '@brainfish-ai/components/ui/dialog';
import { Input } from '@brainfish-ai/components/ui/input';

// Import other components
import { ChatSearch } from '@brainfish-ai/components/chat-search';
import { DatePicker } from '@brainfish-ai/components/date-picker';
import { Filter } from '@brainfish-ai/components/filter';

function MyApp() {
  return (
    <div>
      <Button>Click me</Button>
      <Input placeholder="Enter text..." />
      <DatePicker />
    </div>
  );
}
```

### 批量导入( Legacy)

立即导入所有组件( 更大的捆绑大小) :

```tsx
import { Button, Dialog, Input, ChatSearch } from '@brainfish-ai/components';
```

### 可用个人进口

#### UI 组件

-   `@brainfish-ai/components/ui/button`
-   `@brainfish-ai/components/ui/card`
-   `@brainfish-ai/components/ui/collapsible`
-   `@brainfish-ai/components/ui/command`
-   `@brainfish-ai/components/ui/dialog`
-   `@brainfish-ai/components/ui/dropdown-menu`
-   `@brainfish-ai/components/ui/input`
-   `@brainfish-ai/components/ui/label`
-   `@brainfish-ai/components/ui/popover`
-   `@brainfish-ai/components/ui/scroll-area`
-   `@brainfish-ai/components/ui/switch`
-   `@brainfish-ai/components/ui/textarea`
-   `@brainfish-ai/components/ui/tooltip`

#### 复杂组件

-   `@brainfish-ai/components/chat-search`
-   `@brainfish-ai/components/combobox`
-   `@brainfish-ai/components/date-picker`
-   `@brainfish-ai/components/feedback`
-   `@brainfish-ai/components/filter`
-   `@brainfish-ai/components/generating-star`
-   `@brainfish-ai/components/markdown`
-   `@brainfish-ai/components/select`

### 样式

别忘了输入CSS:

```tsx
import '@brainfish-ai/components/styles.css';
```

## 发展

### 开始

```bash
yarn install
```

### 发展中国家

要开始运行 :

```bash
yarn start
```

这将构建一个版本的您的库,运行监视器,并运行故事书. 要手动打开"故事本"打开浏览器并导航到 [http://localhost:6006 (英语)](http://localhost:6006/)。 。 。 . 开始在 `src/components` 文件夹并更新 `src/index.js` 相应的文件. 总是提供 `YourComponent.story.tsx` 文件,所以您的组件将出现在故事本中.

### 大楼

以单个组件导出构建库 :

```bash
yarn build:components
```

* * *

## 发展指南

本节解释此组件库用于帮助新开发者快速启动的架构和模式.

### 颜色系统

我们的颜色系统建立在定义于 `src/global.css`所有变量都使用 `--bfc-` 前缀(Brainfish 组件).

#### 颜色调试缩放

颜色跟随100-1000比例尺,较低数字更轻而较高数字更暗:

```css
--bfc-v2-color-blue-100: #e9f2fe;  /* lightest */
--bfc-v2-color-blue-500: #4688ec;  /* mid-tone */
--bfc-v2-color-blue-1000: #1c2b42; /* darkest */
```

#### 可用的颜色调色板

| 调色板 | CSS 变量模式 |
| --- | --- |
| 单曲 | `--bfc-v2-color-mono-{100-1000}` |
| 红色 | `--bfc-v2-color-red-{100-1000}` |
| 橙红色 | `--bfc-v2-color-orange-{100-1000}` |
| 黄色 | `--bfc-v2-color-yellow-{100-1000}` |
| 莱姆 | `--bfc-v2-color-lime-{100-1000}` |
| 绿色 | `--bfc-v2-color-green-{100-1000}` |
| 蓝色 | `--bfc-v2-color-blue-{100-1000}` |
| 提尔 | `--bfc-v2-color-teal-{100-1000}` |
| 紫色 | `--bfc-v2-color-purple-{100-1000}` |
| 紫红色 | `--bfc-v2-color-magenta-{100-1000}` |

#### 语义色彩托肯斯

与其使用生色值,不如使用适应主题的语义符号:

| 脚本 | 目的 |
| --- | --- |
| `--bfc-primary` | 主要品牌颜色 |
| `--bfc-background` | 页面背景 |
| `--bfc-foreground` | 主文本颜色 |
| `--bfc-muted` | 下层背景 |
| `--bfc-muted-foreground` | 已修改文本 |
| `--bfc-border` | 边框颜色 |
| `--bfc-destructive-bg` | 错误/危险背景 |
| `--bfc-success-bg` | 成功状态背景 |

#### 黑暗模式

黑暗模式通过添加 `.dark` 分类到元素。 颜色尺度会自动倒置(100会变成最黑暗的,1000会变成最轻的),确保两个主题的一致对比.

```html
<!-- Light mode (default) -->
<html>...</html>

<!-- Dark mode -->
<html class="dark">...</html>
```

### 尾风 CSS 整合

我们使用Tailwind CSS, 带有一个自定义的预设, 将我们的颜色系统映射到Tailwind公用事业.

#### 使用尾风预设

这个库的消费者可以导入我们的 Tailwind 预设, 用同样的设计符号:

```js
// tailwind.config.js
module.exports = {
  presets: [require('@brainfish-ai/components/tailwind')],
  // ... your config
};
```

#### 语义色彩类

使用语义性 Tailwind 类而不是生色 :

```tsx
// Good - uses semantic colors that adapt to themes
<div className="bg-primary text-foreground border-border" />
<div className="bg-destructive text-destructive" />
<div className="bg-muted text-muted-foreground" />

// Bad - hardcoded colors won't adapt to dark mode
<div className="bg-[#a3e635] text-[#171717]" />
```

#### 字型设备

自定义的打字类用于一致的文本样式:

| 类 | 字体大小 | 使用大小写 |
| --- | --- | --- |
| `.heading-xxl` | 2点 | 页面标题 |
| `.heading-xl` | 1.75雷姆 | 科头 |
| `.heading-lg` | 1.5雷姆(1.5雷姆) | 纸牌头 |
| `.heading-m` | 1.25雷门 | 分节 |
| `.heading-sm` | 1雷姆( 1雷姆) | 小标题 |
| `.paragraph-lg` | 1雷姆( 1雷姆) | 文本正文 |
| `.paragraph-md` | 0.875亿雷姆 | 默认文本 |
| `.paragraph-sm` | 0.75亿雷姆 | 说明、标签 |

#### 这个 `cn()` 工具

使用 `cn()` 从 `@/lib/utils` 安全合并 Tailwind 类:

```tsx
import { cn } from '@/lib/utils';

// Merges classes and handles conflicts properly
<div className={cn('bg-primary p-4', isActive && 'bg-accent', className)} />
```

### 组件模式(阴影/井)

我们的UI组件如下 [阴影/ ui](https://ui.shadcn.com/) 模式和公约.

#### 构成部分

-   基础UI组件 : `src/components/ui/`
-   复杂/复合组件: `src/components/`

#### 构成部分结构

组件使用 `class-variance-authority` (CVA)用于变种管理:

```tsx
import * as React from 'react';
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/utils';

// Define variants with CVA
const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-md text-sm font-medium',
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground',
        destructive: 'bg-destructive text-destructive-foreground',
        outline: 'border border-input bg-background',
      },
      size: {
        default: 'h-9 px-4 py-2',
        sm: 'h-8 px-3 text-sm',
        lg: 'h-10 px-8',
      },
    },
    defaultVariants: {
      variant: 'default',
      size: 'default',
    },
  }
);

// Component with forwarded ref
export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {}

const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant, size, ...props }, ref) => (
    <button
      className={cn(buttonVariants({ variant, size, className }))}
      ref={ref}
      {...props}
    />
  )
);
Button.displayName = 'Button';

export { Button, buttonVariants };
```

#### 主要公约

1.  **总是使用语义颜色** - 在组件中不要使用原始六分法值
2.  **预览** - 所有组成部分均应提交灵活性参考文件
3.  **使用 `cn()` 用于类Name** - 总是与来类合并Name
4.  **导出变体** - 出口CVA变体再利用
5.  **设定显示Name** - 总是设置 `displayName` 用于更好的调试

### 故事书要求

**每个组件MUST都有相伴随的"故事本"故事文件.**

#### 为什么故事重要

-   启用独立的组件测试和开发
-   作为组成部分API的活文件
-   允许视觉回归测试
-   帮助设计者和开发者合作

#### 故事文件公约

对于一个构成部分 `Button.tsx`创建 `Button.stories.tsx` 在同一目录中:

```
src/components/ui/
├── button.tsx
├── button.stories.tsx  <-- Required!
└── button.test.tsx     <-- Optional unit tests
```

#### 故事结构

```tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './button';

const meta: Meta<typeof Button> = {
  title: 'UI/Button',
  component: Button,
  tags: ['autodocs'],
};

export default meta;
type Story = StoryObj<typeof Button>;

// Show all variants
export const Default: Story = {
  args: { children: 'Click me' },
};

export const Destructive: Story = {
  args: { variant: 'destructive', children: 'Delete' },
};

export const AllSizes: Story = {
  render: () => (
    <div className="flex gap-4">
      <Button size="sm">Small</Button>
      <Button size="default">Default</Button>
      <Button size="lg">Large</Button>
    </div>
  ),
};
```

#### 运行故事本

```bash
yarn storybook
```

然后打开 [http://localhost:6006 (英语)](http://localhost:6006/) 在您的浏览器中.

* * *

## Typescript 的 Linting 和代码格式化

通过 Linting 和代码格式化 [ESLint 语录](https://eslint.org/) 财务报告和审定财务报表 [高级](https://prettier.io/) 使用 [eslint- 插件反应](https://www.npmjs.com/package/eslint-plugin-react) 财务报告和审定财务报表 [埃斯林特- 配置- prettier](https://github.com/prettier/eslint-config-prettier)。 。 。 . 你可以修改林地规则,在 `.eslintrc.cjs` 文档.

```
yarn lint
```

或(如果可以自动固定)

```
yarn lint:fix
```

## 测试

测试用完了 [维特](https://vitest.dev/) 财务报告和审定财务报表 [@ testing-library/反应](https://testing-library.com/docs/react-testing-library/intro/) 你可以参考 `Button.test.js` 作为例子.

```
yarn test
```

## 将您的图书馆发布给国家预防机制

向国家防范机制或私人登记处开放图书馆,确保您在 [国家预防机制](https://www.npmjs.com/)、 `.npmrc` 文件被正确设置, 注册 URL 发布 Config 在 `package.json` 文件设置为您的仓库 url, 然后 :

```
yarn release
```

## 故事书

关于自定义布局,造型和更多关于"故事书"的信息,请参见: [故事书](https://storybook.js.org/basics/writing-stories/) 文档.

#### 向 GitHub 页部署故事本

确定主页 URL 在 `package.json` 文件设置为您的 githup 页面 url, 然后 :

```
yarn deploy
```

## 脚本

-   `yarn start` :只服务于故事书.
-   `yarn build` :构建您的库(可在 `dist` 文件夹).
-   `yarn storybook:build` :构建静态故事书,以备你想部署.
-   `yarn test` :进行测试.
-   `yarn test:coverage`:运行测试并显示覆盖.
-   `yarn lint` :运行linter, Typescript 类型检查和样式lint.
-   `yarn lint:fix` :运行linter, Typescript 类型检查和样式lint并修正自动可修复的问题.
-   `yarn eslint`: 只运行 JavaScript linter.
-   `yarn eslint:fix`: 只运行 JavaScript 插件并修正自动可修复的问题.
-   `yarn stylelint`: 只运行样式 linter .
-   `yarn stylelint:fix`:只运行样式的linter并修正自动可修复的问题.
-   `yarn check-types`: 运行打字机类型检查器.
-   `yarn ci`:运行Linting,测试和打字机一起运行.
-   `yarn release` : 在国家预防机制或私人登记处公布图书馆(取决于您在国家预防机制或私人登记处的配置) `.npmrc` 存档).
-   `yarn storybook`: 和纱线的开头一样,为故事书服务.
-   `yarn storybook:build`: 生成故事书的构建 `storybook-static` 文件夹,可以在您需要的地方部署.
-   `yarn storybook:deploy`:构建并部署"故事本"到"GitHub Pages".

## 资源

### 邦德勒语Name

-   [滚出.js](https://rollupjs.org/guide/en)

### 代码格式

-   [高级](https://prettier.io/)

### 故事书

-   [故事书](https://storybook.js.org/)

### 测试

-   [维特](https://vitest.dev/)
-   [@ testing-library/反应](https://testing-library.com/docs/react-testing-library/intro/)
-   [@ testing-library/jest-dom (英语)](https://github.com/testing-library/jest-dom)

### 线性

-   [ESLint 语录](https://eslint.org/)
-   [eslint- 插件反应](https://www.npmjs.com/package/eslint-plugin-react)
-   [埃斯林特- 配置- prettier](https://github.com/prettier/eslint-config-prettier)
-   [样式lint - prettier](https://github.com/prettier/stylelint-prettier)
-   [样式林特- scs](https://github.com/kristerkari/stylelint-scss)

### 编译器

-   [字体](https://www.typescriptlang.org/)

## 常见问题

### @brainfish-ai/components 是什么？

脑鱼成分

### 如何安装 @brainfish-ai/components？

在项目目录运行 npm install @brainfish-ai/components，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：clsx（^2\.x）、react（18\.x \|\| 19\.x）、react-dom（18\.x \|\| 19\.x）、usehooks-ts（^3\.x）、tailwind-merge（^2\.x）、tailwindcss-animate（^1\.x）、@phosphor-icons/react（^2\.x）、class-variance-authority（^0\.7\.x）、@tailwindcss/container-queries（0\.1\.x）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @brainfish-ai/components 支持 TypeScript 吗？

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

### @brainfish-ai/components 支持 ESM 还是 CommonJS？

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

### @brainfish-ai/components 需要什么版本的 Node\.js？

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

### @brainfish-ai/components 可以商用吗？

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

### @brainfish-ai/components 的下载量有多少？

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

### @brainfish-ai/components 还在维护吗？

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