# @cordis-tavern/ct-ui-tools 中文文档

规范地址：https://npmcn.com/package/%40cordis-tavern/ct-ui-tools/

版本：0\.1\.0
npm 元数据更新时间：2026-10-31T19:26:32.078Z
中文译文更新时间：2026-10-31T21:10:53.673Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：76.5 kB，9 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.18
- 运行依赖：0 个
- peer 依赖：@cordis-tavern/cordis ^4\.0\.0-rc\.11，@cordis-tavern/cosmokit ^1\.8\.1，@cordis-tavern/schemastery \*，@cordis-tavern/plugin-loader ^1\.0\.0-rc\.7，@cordis-tavern/plugin-include ^1\.1\.0
- 首次发布：2026-10-31T19:09:06.562Z
- 最新版本发布：2026-10-31T19:26:31.854Z
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

（toast / modal）

## 安装

```sh
npm install @cordis-tavern/ct-ui-tools
```

也可以使用：`pnpm add @cordis-tavern/ct-ui-tools`、`yarn add @cordis-tavern/ct-ui-tools`、`bun add @cordis-tavern/ct-ui-tools`

## README

# @cordis-tavern/ct-ui-tools

浏览器 Cordis 服务 **`uiTool`**：非模态 `toast`（五态）+ 模态 `modal`（normal / risk）。 原生 DOM，零运行期依赖；颜色只消费 `--ct-color-*`，缺主题时用兜底色。

## 服务面

```ts
const loading = uiTool.toast('info', '正在保存…')
loading.done(true, '保存成功')

const ok = await uiTool.modal('risk', {
  title: '删除数据表？',
  message: '此操作将永久删除 users_backup。',
  detail: '删除后无法恢复。',
  confirmText: '永久删除',
  cancelText: '取消',
})
```

其他客户端插件经 cordis `inject: ['uiTool']` 使用。

## toast

`uiTool.toast(type?, context)`

| type | 自动消失 | 点击 | 返回 | 视觉 |
| --- | --- | --- | --- | --- |
| `success` | 2000ms | 可 | `undefined` | `--ct-color-success` + `✓` |
| `error` | 不 | 可，带守卫 | `undefined` | `--ct-color-error` + `!` |
| `warning` | 5000ms | 可 | `undefined` | `--ct-color-warning` + `!` |
| `info` | 不 | 不可 | `ToastHandle` | `--ct-color-info` + 转圈 |
| 省略 | 2000ms | 可 | `undefined` | `--ct-color-info`，无图标 |

`info` 是 loading：

```ts
const handle = uiTool.toast('info', '正在保存…')
handle.done(true, '保存成功')   // 同一节点转 success，2s 后消失
handle.done(false, '保存失败')  // 同一节点转 error，常驻
```

-   `done` 只生效一次。
-   `context` 省略时保留 loading 原文案。
-   loading 期间点击无效。

### error 防误关

按住 `≥ 500ms`、指针位移 `> 10px`、或 toast 内有非折叠选区时，点击不会关闭； 普通短按才关闭。长文本会换行，error 文本可选中复制。

### 堆叠

顶部居中，同屏最多 4 条，超出先关最旧的一条。

## modal

`uiTool.modal(type, context?): Promise<boolean>`

| type | 说明 |
| --- | --- |
| `normal` | 普通确认，蓝色语义 |
| `risk` | 风险确认，红色语义 + `detail` 红框 |

`context`：

| 字段 | 默认 | 说明 |
| --- | --- | --- |
| `title` | `提示` | 标题 |
| `message` | `''` | 正文 |
| `detail` | `''` | 额外说明；空串不渲染，risk 下为红色提示框，normal 下为中性提示框 |
| `confirmText` | `确定` | 确认按钮 |
| `cancelText` | `取消` | 取消按钮 |
| `closeOnOverlay` | `true` | 点遮罩是否关闭 |

-   确认 `true`；取消 / Esc / 点遮罩 `false`。
-   初始焦点：normal 在确认，risk 在取消；Tab 焦点陷阱，关闭后焦点回到触发元素。
-   同一时刻只有一个 modal；开第二个时前一个以 `false` 收尾，旧 modal 不抢焦点、不解锁滚动。
-   打开时锁 body 滚动。

## 视觉

-   z-index：toast `30000`，modal `20000`（高于 layout overlay 的 `10000`）。
-   颜色只引用 token 且带兜底：success `#47A76E`、error `#EA6B58`、warning `#C97A1A`、info `#5B8DEF`、surface `#1F1F1F`、surface-2 `#262626`、border `#333333`、text `#D6D6D6`。
-   类名前缀 `ct-ui-toast` / `ct-ui-modal` / `ct-ui-tools`；样式一次性注入 `<style id="ct-ui-tools-style">`。
-   `prefers-reduced-motion` 下只保留透明度过渡。

## 包形态

| 项 | 值 |
| --- | --- |
| Node 入口 | 空 `apply`，只进发现链 |
| 浏览器入口 | `exports["./client"]` IIFE，`provide('uiTool')` |
| 声明 | `insert id: uiTool`；`ct.client.inject: ["@cordis-tavern/ct-client-cordis"]` |
| 依赖 | 运行期零依赖；peer 与兄弟包一致 |

安装：

```bash
ct plugin add -p <环境名> @cordis-tavern/ct-ui-tools
```

## 开发

```bash
pnpm install
pnpm build
pnpm test
pnpm typecheck
```

`pnpm test` 读取 `dist/`，先 `pnpm build`。

## License

MIT

## 常见问题

### @cordis-tavern/ct-ui-tools 是什么？

（toast / modal）

### 如何安装 @cordis-tavern/ct-ui-tools？

在项目目录运行 npm install @cordis-tavern/ct-ui-tools，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@cordis-tavern/cordis（^4\.0\.0-rc\.11）、@cordis-tavern/cosmokit（^1\.8\.1）、@cordis-tavern/schemastery（\*）、@cordis-tavern/plugin-loader（^1\.0\.0-rc\.7）、@cordis-tavern/plugin-include（^1\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cordis-tavern/ct-ui-tools 支持 TypeScript 吗？

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

### @cordis-tavern/ct-ui-tools 支持 ESM 还是 CommonJS？

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

### @cordis-tavern/ct-ui-tools 需要什么版本的 Node\.js？

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

### @cordis-tavern/ct-ui-tools 可以商用吗？

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

### @cordis-tavern/ct-ui-tools 还在维护吗？

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