# @aivenio/aquarium 中文文档

规范地址：https://npmcn.com/package/%40aivenio/aquarium/

版本：7\.1\.0
npm 元数据更新时间：2026-11-02T13:30:53.447Z
中文译文更新时间：2026-11-05T20:04:12.609Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：3.3 MB，968 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.12\.0
- 运行依赖：11 个
- peer 依赖：react 16\.x \|\| 17\.x \|\| 18\.x \|\| 19\.x，lodash-es 4\.x，react-dom 16\.x \|\| 17\.x \|\| 18\.x \|\| 19\.x
- 首次发布：2022-11-30T12:12:42.839Z
- 最新版本发布：2026-11-02T07:25:19.194Z
- 近 30 天下载量：32263（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：208（近 12 个月 37 个）

## 中文简介

Aiven水族馆设计系统

## 安装

```sh
npm install @aivenio/aquarium
```

也可以使用：`pnpm add @aivenio/aquarium`、`yarn add @aivenio/aquarium`、`bun add @aivenio/aquarium`

## README

# Aiven水族馆设计系统

实施Aiven Aquarium设计系统,作为npm包发布. 快速巡演:

-   我们用法格玛来设计系统. 设计符号在 Figma 页面中控制 _(见 [实例页](https://www.figma.com/file/GR4yS2Es6wuA33JfT9NdAH/Design-System-Tokens?node-id=8916%3A120229)(中文(简体) )_,并同步 [自动](https://npmcn.com/package/%40aivenio/aquarium/tools/figma/) 改为 [符号. json](https://npmcn.com/package/%40aivenio/aquarium/tokens.json)
-   构成部分执行用途 [设计符号](https://uxdesign.cc/design-tokens-for-dummies-8acebf010d71) 以定义他们的视觉。 这将使未来通过改变道具来更方便地更新视觉.
-   水族馆设计系统通过npm作为反应组件被曝光
-   [尾风](https://tailwindcss.com/) 用于样式

## 安装

要安装水族馆到您的应用程序 :

-   `npm install --save @aivenio/aquarium`
    
-   确保您在应用程序中添加正确的字体 . [间](https://fonts.google.com/specimen/Inter) aiven主题.
    
-   将 CSS 导入您的应用程序
    
    -   Aiven 主题为 `import '@aivenio/aquarium/dist/styles.css'`
    -   如果你用过 `THEME=X npm run build` 用于建造、使用 `import '@aivenio/aquarium/dist/styles_X.css'`
-   将 React 上下文组件添加到您的 React app 的根
    
    ```diff
      import MyApp from './MyApp';
    + import { Context } from '@aivenio/aquarium';
    
      const Root = () => (
        return (
    +    <Context>
            <MyApp />
    +    </Context>
        )
      )
    ```
    
-   如果您遇到解决 EcmaScript 模块的问题, 请使用此 Webpack 配置功能禁用“ 完全指定” 模式 :
    
    ```module.exports
      webpack: {
          configure: {
              module: {
                  rules: [
                      {
                        test: /\.m?js/,
                        resolve: {
                          fullySpecified: false,
                        },
                      },
                  ]
              },
          }
      },
    };
    ```
    

## 发展

**使用npm 7! 使用npm 7!** 使用更旧的 npm 版本,手动安装端点依赖性 。 如果您遇到“ 找不到模块... ” 错误, 请尝试 `rm -rf node_modules && npm i`。这似乎是 npm@7 引入的错误 .

### 先决条件

此工程需要在命令前设定某些环境变量, 如 : `npm run build` 将工作。 大多数都可以在队友的帮助下复制/粘贴,但你需要自己制作一个国家预防机制标志.

-   创建 npm 账户 [这里](https://www.npmjs.com/signup) 如果你还没有一个.
    
-   为您的账户创建一个符号 。 你可以读到如何做到这一点 [这里](https://docs.npmjs.com/creating-and-viewing-access-tokens)。为了建设该项目,只读访问即可.
    
-   复制样本环境文件 : `cp .env.sample .env`
    
-   在新创建中添加必要的数据 `.env` 文档.
    
-   来源 `.env` 要设置的环境变量文件 : `source .env`
    
    注意, 每当创建新 shell 实例时( 例如, 当您重新启动您的计算机时), 您需要运行 `source .env` ,否则变量将不会被设定。 考虑使用如下解决方案: `autoenv` 自动应用 `.env` 文档.
    

#### 可选 DX 改进

-   用于 VSCode
    -   安装 Tailwind CSS IntelliSense 扩展名. 见 [https://github.com/tailwindlabs/tailwindcs-intellisense#推荐-vs-代码设置](https://github.com/tailwindlabs/tailwindcss-intellisense#recommended-vs-code-settings)
    -   在保存时安装 ESLint 扩展并选择启用自动格式 。 见 _“步骤4——保存上的格式”_ 从 [https://www.digitalocean.com/community/tourics/linting-and-formating- with-eslint-in-vs-code (中文(中国大陆) )](https://www.digitalocean.com/community/tutorials/linting-and-formatting-with-eslint-in-vs-code)

### 常见命令

-   `npm ci` 以安装依赖关系
-   `npm run build` 建造图书馆生产大楼
-   `npm start` 开始故事书

### 在您的应用程序中开发

要在应用程序中开发水族馆组件,在您的应用程序中运行本地修改版的水族馆就比较容易了. 这样做有两种方法: [npm 链接](https://docs.npmjs.com/cli/v7/commands/npm-link),或者将模块复制到您的应用程序中。 这使得您可以修改组件,并立即看到应用程序上下文中的变化.

#### `npm link`

> QQ TODO:目前这个盒子没有用. 修改指令

1.  在设计系统目录中,运行 `npm link`
2.  在设计系统目录中,运行 `npm link <path to your app>/node_modules/react` 避免遇到两次反应的冲突。 否则会打破钩子规则并崩溃应用程序. 关于这一问题的更多信息 [这里](https://reactjs.org/warnings/invalid-hook-call-warning.html#duplicate-react)。如果命令在端点依赖性上出现出错,则重新运行命令,添加 `--force` 在结尾.
3.  在应用程序目录中运行 `npm link @aivenio/aquarium`
4.  现在 `<path to your app>/node_modules/@aivenio/aquarium` 是一个与您的本地水族馆目录的符号链接 .
5.  在设计系统目录中,运行 `npm run watch`
6.  没问题! 现在,您应该能够在当地开发DS, 更改会反映到依赖于 `@aivenio/aquarium`
7.  如果您想要停止使用 npm 链接, 请返回普通导入的版本, 在您的应用目录中运行 `npm unlink --no-save @aivenio/aquarium`,则 `npm i` 重新建立依赖.

#### 复制模块

> 如果你在DS一侧安装了新的依赖,这行不通. 见 [npm 包的指令](https://npmcn.com/package/%40aivenio/aquarium/#readme-copy-module) 换句话说.

npm链接可能很棘手才能工作. 一个更简单的方法是建造一个DS的制作楼,并把它复制到您的应用程序中 `node-modules` 目录。 记得一旦DS建成并复制完毕, 请重新启动您的应用程序的构建进程 。 这里有一个片段可以做这一切:

```sh
cd <path to ds> \
  && npm run build \
  && cd <path to your app> \
  && rm -rf ./node_modules/@aivenio/aquarium/dist \
  && cp -R <path to ds>/dist ./node_modules/@aivenio/aquarium # && <the dev/build command of your app>
```

#### `npm pack`

复制模块是一个黑客,当依赖性自您的应用端最后一次安装以来在DS端发生了变化时,它就失效了.

你用得着 `pack-and-install.sh` 创建本地发布软件包并安装到本地应用程序的实用脚本.

```sh
APP_PATH=<path to your app> ./pack-and-install.sh && <run dev/build command for your app>
```

每次更改后再次运行, 并重新启动您的应用程序的 Dev 服务器 。 剧本留下了应用软件 `package.json` 财务报告和审定财务报表 `package-lock.json` 没有动 就跑吧 `npm ci` 在应用程序中返回发布版本.

或者你想的话,你也可以跑 `npm pack` 命令,然后安装到您的应用程序.

```sh
cd <path to ds> \
  && npm run build \
  && jq --arg file_name $(npm pack 2>&1 | tail -1) '.dependencies["@aivenio/aquarium"] = "file:<path to ds>/\($file_name)"' <path to your app>/package.json > <path to your app>/package-json-new.tmp \
  && cd <path to your app> \
  && mv package-json-new.tmp package.json \
  && npm install # && <the dev/build command of your app>
```

确保您全部替换 `<path to ds>` 财务报告和审定财务报表 `<path to your app>` 用精确的绝对路径串起.

### 正在测试

记住 `source .env` 在国家防范机制下达命令之前,需要这样做.

-   `npm test` 运行所有测试一次
-   `npm test -- Button` 只运行匹配的测试 `Button`
-   `npm run test:watch` 以监视模式运行测试
-   `npm run test:coverage` 运行所有测试并查看覆盖范围

记着! 开发时在表模式下运行测试是好主意. 例如,如果快照测试由于一些代码更改而失败,那么就很容易更新那些带有快克命令行工具的. 如果你想只是更新可以完成的快照 `jest --updateSnapshot`更多信息 [这里](https://jestjs.io/docs/en/snapshot-testing#updating-snapshots)

### 其他有用的命令

-   `THEME=<brand> npm start` 以主题开始本地故事书
-   `THEME=<brand> npm run build` 以主题构建 DS 模块
-   `npm run figma -- sync -i .figma-file.json` 生成 `./tokens.json` 而不是从 API 获取巨大的 Figma 文件 .
-   `npm run figma -- sync --debug` 以启用更多动词输出
-   `npm run figma -- sync --foundation-page-name 'my foundations'` 以覆盖选项.
-   `jq '.document.children[] | select(.id == "8916:120229")' .cache/figma-file.json` 从整个 Figma 文件 JSON 中切入基础页面.

有一个 [更多文档](https://npmcn.com/package/%40aivenio/aquarium/tools/figma/readme.md) 用于图像同步工具.

## 构建和发布进程

### 故事书

#### 在当地建立故事书

运行 `npm run build:storybook`。 。 。 .

#### 故事书部署

故事书被部署到Cloudflare Pages中,每次新代码被合并到主.

Aiven Runtime应用程序服务也部署同样的任务 [部署-故事手册. yml](https://npmcn.com/package/%40aivenio/aquarium/.github/workflows/deploy-storybook.yml),这引发了该 服务以重建根 [粘贴文件](https://npmcn.com/package/%40aivenio/aquarium/Dockerfile) 并和UI一起为MCP服务器服务.

工作流程需要这些 Repo 设置 :

| 仁爱 | 名称 | 数值 |
| --- | --- | --- |
| 秘诀 | `AIVEN_TOKEN` | Aiven API 令牌, 并带有服务上的调用权限 |
| 变量 | `AIVEN_PROJECT` | 目标 Aiven 项目名称 |
| 变量 | `AIVEN_APP_NAME` | aiven 应用程序服务名称 |

#### 故事本 MCP 服务器

故事书揭露 [MCP 服务器](https://storybook.js.org/docs/next/ai/mcp/overview) 如此的探员 可以查询真实的组件文档和道具,而不是猜测。 它来自这个repo的MDX 文件页和类型Script道具类型——见 [一般事务人员(其他职等)](https://npmcn.com/package/%40aivenio/aquarium/AGENTS.md) 这里面的规则代理人 repo在使用时会跟随.

-   **本地 dev :** 运行 `npm start`,然后MCP服务器在 `http://localhost:6006/mcp`已经 有窃听器通过 [. mcp.json (英语)](https://npmcn.com/package/%40aivenio/aquarium/.mcp.json)。 。 。 .
    
-   **从另一个项目** (例如,一个指向这个设计系统的控制台):一旦故事本是 在此运行, 添加为远程 MCP 服务器 `claude mcp add --transport http aquarium-storybook http://localhost:6006/mcp`。 。 。 .
    
-   **主机 :** 每次合并到主机都会在Aiven Runtime上重新部署容器,所以没有必要 在本地运行故事本, 以查询 docs - 点 `<service-url>/mcp` 换句话说 找到服务 Aiven 控制台中的 URL 。 它住在VPC里,所以检查它能从你运行的地方到达 探员.
    
-   **集装箱:** 构建和运行 [粘贴文件](https://npmcn.com/package/%40aivenio/aquarium/Dockerfile) 获取静态故事书和 自托管的仅多克的 MCP 服务器 (`mcp-server/`在同一端口:
    
    ```sh
    docker build -t aquarium-storybook-mcp .
    docker run --rm -p 6006:6006 aquarium-storybook-mcp
    ```
    
    两人从 `http://localhost:6006`。只有文档工具集在这里工作,它没有 运行 dev 服务器,以预览或测试针对的故事 .
    
    只向代理人提供交叉文件页(概念、设计标志、如何向导)。 这个 每个组件的MDX页被删除,因为每个组件的指向都生活在元中a JSDoc 并通过其组件条目联系代理商。 内容故事、片段和 道具表不受影响。 见 [mcp 服务器/服务器](https://npmcn.com/package/%40aivenio/aquarium/mcp-server/server.ts) 为什么这不是 完成的故事书 `!manifest` 标签.
    

### 水族馆套装

#### 如何在当地建立水族馆软件包

-   运行 `npm run build`
-   见 `dist` 用于构建代码

#### 如何创建释放

1.  运行 `npm run release -- --bump <bump>` _(所有破折号都需要)_ 撞伤是其中之一 `major`, (中文(简体) ), `minor` 或者说 `patch`。 。 。 .
    
    此命令将自动检查一个发布分支, 输入版本突起, 并打开您的浏览器提交 PR .
    
2.  审查创建的公关,并合并到主机上. GH动作会处理其余的.
    

**任何API的突破更改都应该是主要的版本起伏并应该在发行注释中提及!**

#### 中断更改

中断更改示例 :

-   在按钮组件中重命名道具
-   将卡片组件重命名为 Box
-   删除道具
-   删除组件

这些不是打破更改 :

-   为按钮添加新道具
-   添加新组件
-   更改故事书
-   更改测试

## 背景情况

对现有的设计系统做了大量研究,如果我们能再利用 部分内容。 得出的结论是,我们主要从好的 并使用单个组件 通过复制粘贴代码到我们的系统.

### 对现有反应图书馆的评价

一些工程是巨大的,最常用的链接直接指向定义组件的代码基础部分. 对于测试,我检查了一些组件的测试 看上去不错,没有做覆盖或更深入的分析.

接下来要考虑的事项:

-   使用图书馆的一部分时 树能摇动吗? 地盘的大小也是一个重要因素,但树木摇晃后,各图书馆的脚印应该相当相近
-   成熟性和活性(承诺、最近的活动、贡献者分布、结束的与未解决的问题、公关合并活动)
-   他们是否迁移到另一个技术领域? TS, Sass - > 有型组件等
-   老板,是社区驱动还是公司驱动? 有13颗恒星的项目如果是公司内部开发的,N年投入20克就可以超成熟了
-   无障碍
-   自定义性, 您需要叉子还是可以在获取上游更新时自定义 ?

| 链接 | 提交\* | 联合来文/TS | 样式 | 许可证 | 测试 | 其它 |
| --- | --- | --- | --- | --- | --- | --- |
| [蚂蚁设计](https://github.com/ant-design/ant-design/tree/master/components) | 18.6k (韩语) | TS 翻译 | 减. [实例](https://github.com/ant-design/ant-design/blob/master/components/card/style/index.less) | 麻省理工学院 | ☑️ |  |
| [阿拉贡大学](https://github.com/aragon/aragon-ui/blob/master/src/components/) | 0.8k (中文(简体) ) | 联合来文 | 样式组件 | 麻省理工学院 | [没什么](https://github.com/aragon/aragon-ui/search?q=test&unscoped_q=test) |  |
| [Uber 的 Baseweb 网络](https://github.com/uber/baseweb/tree/master/src) | 2.3k (单位:千美元) | 联合来文(Flow) | [样式](https://github.com/styletron/styletron) | 麻省理工学院 | ☑️ |  |
| [依据](https://github.com/moroshko/basis/blob/master/src/components) | 0.3k (简体中文) | 联合来文 | 情绪 | 麻省理工学院 | ☑️ |  |
| [蓝图](https://github.com/palantir/blueprint/tree/develop/packages/core/src/components) | 1.8k (中文(简体) ) | TS 翻译 | 萨斯 | Apache 2.0 (英语) | ☑️ |  |
| [碳矿](https://github.com/carbon-design-system/carbon/tree/master/packages/react/src) | 6.8k (简体中文) | 联合来文 | CSS 类名链接到 [萨斯](https://github.com/carbon-design-system/carbon/blob/master/packages/components/src/components/button/_button.scss) | Apache 2.0 (英语) | ☑️ | · 故事本 |
| [微软的流利UI](https://github.com/microsoft/fluentui/tree/master/packages/office-ui-fabric-react/src) | 8.6k (单位:千美元) | TS 翻译 | 联署材料中的CSS似乎是一个 [自定义一](https://github.com/microsoft/fluentui/blob/master/packages/utilities/src/styled.tsx) | 麻省理工学院 | ☑️ |  |
| [格罗姆特](https://github.com/grommet/grommet/blob/master/src/js/components/) | 5.2k (韩语) | 联合来文 | 样式组件 | Apache 2.0 (英语) | ☑️ | · 故事本 |
| [材料界面](https://github.com/mui-org/material-ui/tree/master/packages/material-ui/src) | 11.9k (韩语) | 联合来文 | CLSX,JS中的CSS. [示例](https://github.com/mui-org/material-ui/blob/edb2d6382e271dbfc28384b10c417c0f5843e8f8/packages/material-ui/src/Button/Button.js#L9) | 麻省理工学院 | ☑️ |  |
| [MongoDB 设计](https://github.com/mongodb/design/tree/master/client/react-components) | 0.4k (简体中文) | 联合来文 | 支助科 | package.json说麻省理工学院没有LICENSE文件 | [没有](https://github.com/mongodb/design/search?q=test&unscoped_q=test) |  |
| [关键UI](https://github.com/pivotal-cf/pivotal-ui/tree/master/src/react) | 4.0k (中文(简体) ) | 联合来文 | 萨斯 | 麻省理工学院 | ☑️ |  |
| [由 Shopify 创建的极地](https://github.com/Shopify/polaris-react/tree/master/src/components) | 6.1k (韩语) | TS 翻译 | 萨斯 | 修改后的麻省理工学院, [看见更多](https://github.com/Shopify/polaris-react#licenses) | ☑️ |  |
| [GitHub 的首页](https://github.com/primer/components/tree/master/src) | 4.5克级 | 联合来文 | 样式组件 | 麻省理工学院 | ☑️ |  |
| [反射启动陷阱](https://github.com/react-bootstrap/react-bootstrap/tree/master/src) | 3.8k (单位:千克) | 联合来文 | 靴子CSS类 | 麻省理工学院(Bootstrap也是麻省理工学院) | ☑️ |  |
| [反应陷阱](https://github.com/reactstrap/reactstrap/tree/master/src) | 0.8k (中文(简体) ) | 联合来文 | 靴子CSS类 | 麻省理工学院 | ☑️ |  |
| [罗姆妇女理事会](https://github.com/jamesmfriedman/rmwc/tree/master/src) | 1.9k (单位:千美元) | 联合来文 | 使用 CSS 类名 [材料组件-网络](https://github.com/material-components/material-components-web/tree/master/packages/material-components-web) 由 Google (来源为 Sass) | 麻省理工学院(材料组件网络也是麻省理工学院) | ☑️ |  |
| [销售力设计系统](https://github.com/salesforce-ux/design-system/tree/master/ui/components) | 9.5克级 | 联合来文 | 萨斯 | 代码 BSD 3- Clause,参见: [https://github.com/salesforce-ux/design-system#licenses (英语)](https://github.com/salesforce-ux/design-system#licenses) | ☑️ |  |
| [缩略图](https://github.com/thumbtack/thumbprint/tree/master/packages/thumbprint-react/components) | 0.7k (简体中文) | TS 翻译 | 萨斯 | Apache 2.0 (英语) | ☑️ |  |
| [VTEX 样式指南](https://github.com/vtex/styleguide/tree/master/react) | 4.3克级 | 联合来文 | 自定义 [塔克扬](https://vtex.github.io/vtex-tachyons/) + CSS 类。 示例 [执行](https://github.com/vtex/styleguide/blob/master/react/components/Input/index.js) 财务报告和审定财务报表 [支助科](https://github.com/vtex/styleguide/blob/master/react/components/Input/Input.css) | [无执照](https://github.com/vtex/styleguide/issues/625) | [没什么](https://github.com/vtex/styleguide/issues/1083) |  |
| [禅桌花园](https://github.com/zendeskgarden/react-components/tree/master/packages) | 0.8k (中文(简体) ) | TS 翻译 | 样式组件 | Apache 2.0 (英语) | ☑️ | · 故事本 |

-   这些再现者大多是同Lerna一起管理的单发. 承诺数只是粗略估计代码被重复了多少 .

为了进一步调查,您可以在 GitHub 中找到许多组件: [https://github.com/search?l=&p=99&q=创建了%3A%3E2015-01-01+extension%3Ajs+extension%3Ajsx+extension%3Ats+extension%3Atsx+signal%3Abutton.js+filename%3Abutton.jsx+filename%3Abutton.jsxssearch&type=Code](https://github.com/search?l=&p=99&q=created%3A%3E2015-01-01+extension%3Ajs+extension%3Ajsx+extension%3Ats+extension%3Atsx+size%3A%3E100+filename%3AButton.js+filename%3AButton.ts+filename%3AButton.jsx+filename%3AButton.tsx+filename%3Abutton.js+filename%3Abutton.ts+filename%3Abutton.jsx+filename%3Abutton.tsx&ref=advsearch&type=Code)

**您可以在此找到更多设计系统 :** [https://github.com/alexpate/awesome-design-systems (中文(简体) )](https://github.com/alexpate/awesome-design-systems)。并不是所有人都有开源代码.

## 常见问题

### @aivenio/aquarium 是什么？

Aiven水族馆设计系统

### 如何安装 @aivenio/aquarium？

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

### @aivenio/aquarium 支持 TypeScript 吗？

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

### @aivenio/aquarium 支持 ESM 还是 CommonJS？

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

### @aivenio/aquarium 需要什么版本的 Node\.js？

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

### @aivenio/aquarium 可以商用吗？

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

### @aivenio/aquarium 的下载量有多少？

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

### @aivenio/aquarium 还在维护吗？

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