# @thetaskforge/design-system 中文文档

规范地址：https://npmcn.com/package/%40thetaskforge/design-system/

版本：0\.6\.1
npm 元数据更新时间：2026-11-02T15:12:47.393Z
中文译文更新时间：2026-11-02T16:48:32.064Z
软件包许可：UNLICENSED

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

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

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

- 包体积（解压后）：1.8 MB，306 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- peer 依赖：react ^18\.2\.0，motion ^12\.43\.0，recharts ^3\.10\.1，input-otp ^1\.5\.0，react-dom ^18\.2\.0，react-aria ^3\.52\.1，tailwindcss ^4\.3\.3，react-stately ^3\.50\.0，@iconify/react ^5\.0\.2，tailwind-merge ^3\.6\.0，qr-code-styling ^1\.9\.2，react-router-dom ^6\.30\.0，@react-aria/utils ^3\.34\.1，@untitledui/icons ^0\.0\.22，@react-types/shared ^3\.36\.1，tailwindcss-animate ^1\.0\.7，@react-stately/utils ^3\.12\.1，embla-carousel-react ^8\.6\.0，@react-types/overlays ^3\.10\.0，react-aria-components ^1\.21\.1，@untitledui/file-icons ^0\.0\.9，@internationalized/date ^3\.12\.4，@tailwindcss/typography ^0\.5\.20，@radix-ui/react-scroll-area ^1\.2\.18，tailwindcss-react-aria-components ^2\.2\.0
- 首次发布：2026-10-26T12:05:51.095Z
- 最新版本发布：2026-11-02T15:12:47.022Z
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

Taskforge设计系统（基于未命名的UI）：每个Taskforge前端共享的组件、钩子、utils和样式。

## 安装

```sh
npm install @thetaskforge/design-system
```

也可以使用：`pnpm add @thetaskforge/design-system`、`yarn add @thetaskforge/design-system`、`bun add @thetaskforge/design-system`

## README

# Taskforge设计系统（基于未命名的UI）

`@thetaskforge/design-system` 是每个Taskforge前端使用的单一副本。在这里更改一个组件，标记一个版本，然后把它放到应用程序中。 文件夹: `src/components/<group>/<name>/`.

## 在应用程序中使用它

1.  从npm安装：
    
    ```bash
    npm install @thetaskforge/design-system
    ```
    
2.  通过混叠保持导入的原样 `@/design-system` 来 `node_modules/@thetaskforge/design-system/src` 在 `tsconfig.json` （`paths`)和webpack `resolve.alias`.
3.  让webpack编译这个包的TypeScript: include `node_modules/@thetaskforge/design-system` 在TS/babel规则。
4.  在应用程序中 `index.scss`、进口 `@thetaskforge/design-system/styles/globals.css` 并添加 `@source "../node_modules/@thetaskforge/design-system/src";` 顺风看到了这些课程。
5.  添加对等依赖项 `package.json` 标记它们 `singleton` 在模块联盟中 `shared`.

> **注意**：因为这个包被发布到公共的npm注册表 `@thetaskforge` 范围，不需要特殊的Git令牌或存储库凭证 `npm install` 在Docker， CI/CD或Vercel中。

## 向npm发布新版本

### 方法一：终端单行命令（推荐）

执行以下命令：

```bash
npm run release:patch    # e.g. 0.3.24 -> 0.3.25
npm run release:minor    # e.g. 0.3.24 -> 0.4.0
npm run release:major    # e.g. 0.3.24 -> 1.0.0
```

这就会自动碰撞 `package.json`，提交，创建git标签，并推送到GitHub。GitHub Actions工作流(`.github/workflows/publish.yml`)直接运行类型检查、测试和发布到npm。

### 方法2：来自GitHub Actions Web UI

1.  去 **行动** 选项卡。
2.  选择 **发布到npm** 从左侧栏。
3.  点击 **运行工作流**,选择 `patch`， `minor`，或者 `major`，并按 **运行工作流**.

### 方法3：直接发布npm

```bash
npm publish
```

## 共享库（模块联合）

每个应用程序列表 `react-aria-components`， `react-aria`， `react-stately` 和 `@internationalized/date` 作为 `singleton` 共享库，紧挨着React和React Router。这样可以让一个库的副本保存设计系统的上下文，这样主机的路由器和覆盖上下文就可以到达来自另一个应用程序的组件。在应用程序之间保持它们的版本相同。

## 应用程序（全屏片）

| 组件 | 用它来 |
| --- | --- |
| `app-navigation` | 侧边栏、页眉和移动导航 |
| `breadcrumbs/Breadcrumbs` | 当前页面上方的页面轨迹 |
| `page-header/PageHeader` | 页面标题，描述，徽章，面包屑和操作按钮 |
| `steps/Steps` | 过程的各个阶段（水平或垂直） |
| `metrics/MetricCard` | 带有标签（和注释、图标）的数字 |
| `table/Table` | 数据表(`scrollClassName`， `scrollOrientation` 选项) |
| `tabs`， `pagination`， `date-picker`， `empty-state`， `loading-indicator`， `file-upload`， `carousel`， `charts` | 作为命名 |
| `modals/ModalShell`， `modals/ConfirmActionModal` | 对话和“Are you sure?”确认 |
| `slideout-menus/SlideoutMenu`， `slideout-menus/Drawer` | 侧板。 `Drawer` 保持安装，所以它可以滑动，标题，副标题和页脚 |
| `toast` | 诸如“链接已复制”之类的通知 |
| `slideout-menus/DockedPanel` | 页面旁边的非模态面板（没有背景），用于设置所选内容 |
| `floating-toolbar/FloatingToolbar`， `FloatingToolbarButton`， `FloatingToolbarDivider` | 浮动在画布上的图标动作的可折叠药丸 |
| `floating-action-button/FloatingActionButton`， `AnchoredPopup` | 一个大的圆形可拖拽按钮和在它旁边打开的弹出窗口，翻转以停留在屏幕上 |
| `command-menu/CommandMenu` | 具有固定搜索和滚动体的可搜索分段列表 |
| `workflow-canvas/PalettePanel`， `PaletteItem` | 带有工具提示的图标可拖动快捷方式 |
| `workflow-canvas/WorkflowNodeCard`， `NodeHandle`， `CanvasGroup`， `EdgeLabel`， `CanvasPanel`， `ZoomControls` | 流程画布：步骤卡，阶段组，连接器标签，缩放 |
| `workflow-canvas/CanvasGroup` (国家 `default` / `new` / `drop`， `isEditingName`， `menu`)， `GroupMenu`， `CollapsedGroupCard` | 阶段：盒子，命名，拉高亮，它的菜单（重命名，颜色，折叠，取消组）和折叠卡片 |
| `workflow-canvas/SelectionBox`， `SelectionBar`， `SelectionBarButton`， `SelectionBarDivider` | 选中的步骤上方的矩形和它们上方的黑色条（分组步骤，对齐，删除） |
| `sortable-list/SortableList` | 通过拖动手柄或键盘重新排序的行 |
| `condition-row/ConditionRow`， `ConditionJoin` | 作为句子的条件，带有And / Or |
| `problem-card/ProblemCard` | 从检查中找到一个，有一个跳转按钮 |
| `version-row/VersionRow` | 实时，草稿，过去和分组自动保存历史记录的行 |
| `timeline/Timeline` | 沿着一条时间线的彩色事件 |
| `rich-text-editor/RichTextEditor` | 小HTML消息编辑器：粗体，斜体，链接，列表 |

## 基础（小型积木）

| 组件 | 用它来 |
| --- | --- |
| `accordion/Accordion` | 打开显示内容的标题 |
| `badges/Badge`， `badges/StatusBadge` | 标签。 `StatusBadge` 将状态字映射到颜色（用覆盖） `tones`） |
| `buttons/Button`， `ButtonUtility`， `CloseButton` | 动作、图标按钮 |
| `input/Input`， `InputNumber`， `InputDate`， `PinInput`， `InputTags`， `CopyField` | 字段。 `CopyField` 是灰色的只读字段与复制图标 |
| `select/Select`， `ComboBox`， `MultiSelect`， `TagSelect`， `SelectNative` | 器。 `ComboBox` 是可搜索的吗 |
| `segmented/Segmented` | 二到四选项切换（画布/列表，和/或） |
| `reference-chip/ReferenceChip` | 作为芯片显示的值、目的地或缺失的引用 |
| `code-block/CodeBlock` | 带副本的只读代码 |
| `toggle/Toggle`， `toggle/ToggleRow` | 开/关开关，一个带有标题和说明的开关 |
| `avatar`， `card`， `checkbox`， `dropdown`， `radio-buttons`， `slider`， `textarea`， `tags`， `tooltip`， `banner`， `button-group`， `progress-indicators`， `skeleton`， `scroll-area`， `form` | 作为命名 |

## 钩子/ utils

`use-breakpoint`， `use-clipboard`， `use-persisted-state`， `cx`， `timezones`， `anchored-placement/computeBesidePlacement`， `group-bounds/getGroupBounds`， `isCentreInside`.

## 规则

-   在编写本地组件之前，请先了解这些内容。如果缺少了什么，在这里添加。
-   光模式仅适用于模拟；在构建器和公共页面中使用容器查询，而不是viewport变体。

## 常见问题

### @thetaskforge/design-system 是什么？

Taskforge设计系统（基于未命名的UI）：每个Taskforge前端共享的组件、钩子、utils和样式。

### 如何安装 @thetaskforge/design-system？

在项目目录运行 npm install @thetaskforge/design-system，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.2\.0）、motion（^12\.43\.0）、recharts（^3\.10\.1）、input-otp（^1\.5\.0）、react-dom（^18\.2\.0）、react-aria（^3\.52\.1）、tailwindcss（^4\.3\.3）、react-stately（^3\.50\.0）、@iconify/react（^5\.0\.2）、tailwind-merge（^3\.6\.0）、qr-code-styling（^1\.9\.2）、react-router-dom（^6\.30\.0）、@react-aria/utils（^3\.34\.1）、@untitledui/icons（^0\.0\.22）、@react-types/shared（^3\.36\.1）、tailwindcss-animate（^1\.0\.7）、@react-stately/utils（^3\.12\.1）、embla-carousel-react（^8\.6\.0）、@react-types/overlays（^3\.10\.0）、react-aria-components（^1\.21\.1）、@untitledui/file-icons（^0\.0\.9）、@internationalized/date（^3\.12\.4）、@tailwindcss/typography（^0\.5\.20）、@radix-ui/react-scroll-area（^1\.2\.18）、tailwindcss-react-aria-components（^2\.2\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @thetaskforge/design-system 支持 TypeScript 吗？

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

### @thetaskforge/design-system 支持 ESM 还是 CommonJS？

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

### @thetaskforge/design-system 可以商用吗？

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

### @thetaskforge/design-system 还在维护吗？

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