# @debuffjp/ui 中文文档

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

版本：0\.33\.0
npm 元数据更新时间：2026-11-11T02:35:51.033Z
中文译文更新时间：2026-11-11T18:58:53.743Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40debuffjp/ui
原文对照：https://npmcn.com/package/%40debuffjp/ui/?lang=original
项目主页：https://debuff.jp/
源码仓库：https://github.com/debuffjp/debuff

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

- 包体积（解压后）：64.8 kB，26 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-10-17T05:56:34.415Z
- 最新版本发布：2026-11-11T02:35:50.645Z
- 近 30 天下载量：8788（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：55（近 12 个月 55 个）

## 中文简介

屏幕转换、 菜单和拆卸面板

## 安装

```sh
npm install @debuffjp/ui
```

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

## README

# @ debuffjp/ ui (英语)

游戏周围的屏幕:在区域之间逐渐淡出,标题和暂停菜单,被框面板. 没有依赖关系,每个出口都可以自行使用. 一切都在继续 `update(dt)`因此,重播和情景 保持决定性.

```ts
import { Menu, Transition } from "@debuffjp/ui";

const fade = new Transition({ duration: 0.35, color: "#1a1020" });
let volume = 10;
const pause = new Menu(
  [
    { label: "resume", onSelect: () => (paused = false) },
    { label: "volume", value: () => `${volume}`, change: (d) => (volume = Math.max(0, Math.min(10, volume + d))) },
    { label: "restart", onSelect: () => fade.run(reset) },
  ],
  { actions: { up: "up", down: "down", confirm: "jump", back: "pause", left: "left", right: "right" } },
);

// every step
fade.update(dt);
if (fade.blocking) return;
if (paused) pause.update(input);

// render, after the world
if (paused) pause.drawPanel(draw, game.width / 2, game.height / 2, { title: "paused" });
fade.draw(draw, 0, 0, game.width, game.height);
```

## 版式

文本用 `draw.measure`,所以任何事物都无法通过猜测来定位:

-   光标有自己的一栏 。 标签在焦点移动时不会转移.
-   数值(`value: () => string`)在自己的一栏中对齐.
-   `drawPanel` 将框架放在点上,镜像光标一栏,这样标签和标题就共享一个中心,并在四面均匀地铺平.
-   每个位置都会向整像素显示,所以像素字体保持简洁.

## API 密码

-   `Transition`数字 : `run(swap?)` 盖上屏幕,打电话 `swap` 被完全覆盖,然后发现. `update(dt)`, (中文(简体) ), `draw(draw, x, y, w, h)`, (中文(简体) ), `stop()`, (中文(简体) ), `active`, (中文(简体) ), `blocking`, (中文(简体) ), `cover`, (中文(简体) ), `inspect()`
-   `Menu`数字 : `new Menu(items, { actions, onBack, wrap })`, (中文(简体) ), `update(input)` (与 `input.pointer`,一个水龙头选择其下行;在一行数值上,左半下行和右半起行, `tap(x, y)`, (中文(简体) ), `move(delta)`, (中文(简体) ), `select()`, (中文(简体) ), `measure(draw, style)`, (中文(简体) ), `draw(draw, x, y, style)`, (中文(简体) ), `drawPanel(draw, cx, cy, style)`, (中文(简体) ), `focused`, (中文(简体) ), `inspect()`
    -   项目: `{ label, onSelect?, disabled?, value?, change? }`
    -   样式 : `font`, (中文(简体) ), `color`, (中文(简体) ), `focusColor`, (中文(简体) ), `disabledColor`, (中文(简体) ), `gap` (3), `align` (单位:千美元)`left`编号 :`center`, (中文(简体) ), `cursor` (单位:千美元)`>`, (中文(简体) ), `cursorGap` (4), (中文(简体) ), `valueGap` (12个), `highlight` (有重点的一行后面的一粒果冻丸;用德布夫的外观, `false` 关闭); 面板添加 `title`, (中文(简体) ), `titleFont`, (中文(简体) ), `titleColor`, (中文(简体) ), `titleGap` (6), (中文(简体) ), `borders`, (中文(简体) ), `fill`, (中文(简体) ), `padding`, (中文(简体) ), `radius`
-   `panel(draw, x, y, w, h, borders, fill?, chamfer?, radius?)`: 1px环,最外接先接后填; `radius` 每个角落, `chamfer` 用这么多像素把它剪掉
-   `panelAround(draw, cx, cy, w, h, { borders, fill, padding, radius, chamfer, shadow, shadowOffset })`: 安装在内容周围、 以像素为中心并按像素粘接的面板; 返回内容的左上角
-   `bar(draw, x, y, w, h, value, { segments, gap, fill, empty })`:分量计; `value` (0-1) 仅亮出整个单元格, 全部相同宽度; 返回所用的宽度

框外、面板、菜单和条 `neutral`:平地灰色,一个白色的焦点,4px角和一薄的边框,所以他们坐在你的游戏艺术下而不会带来自己的风格. 自己决定 `borders` 或者说 `fill`,或者你自己的 `color`,你得到 准确的设置.

外观是您所传播的样式对象 :

| 听着 | 这是什么 | 栏 |
| --- | --- | --- |
| `neutral` | 默认: 深灰色, 白色焦点 | `neutralBar` |
| `neutralLight` | 轻取游戏相同: 白色面板, 暗文本 | `neutralLightBar` |
| `squish` | debuff的外观:一个圆形的暗寡形面板,没有外观轮廓,有石灰聚焦,以及焦点移动时被压扁的亮点 | `squishBar` |

```ts
import { squish, squishBar } from "@debuffjp/ui";
pause.drawPanel(draw, game.width / 2, game.height / 2, { ...squish, title: "paused" });
bar(draw, 8, 8, 60, 4, hp / maxHp, squishBar);
```

### 在0.19年之前

高达0.18分,面板和菜单使用德布夫自己外观("squish")出盒:一个柔软而圆角的暗面面板,没有外观轮廓,有光标,有石灰焦并有果冻突出,在焦点移动时会粉碎. 栏杆默认为暗橄榄上的石灰细胞. 摆出自己的风格 `borders` 或者说 `fill` 保持原样. `debuffFrame` 那看起来是一种风格的物体, 扩散到任何事物:

```ts
import { debuffFrame } from "@debuffjp/ui";
pause.drawPanel(draw, game.width / 2, game.height / 2, { ...debuffFrame, title: "paused" });
```

从0.19起,扩散 `squish` (和通过) `squishBar` 改为 `bar`在那里,你依赖的默认. `debuffFrame` 仍然工作,被腐烂, 成为squish的框单 没有它的菜单颜色.

## 常见问题

### @debuffjp/ui 是什么？

屏幕转换、 菜单和拆卸面板

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

在项目目录运行 npm install @debuffjp/ui，或使用 pnpm add / yarn add / bun add。

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

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

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

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

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

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

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

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

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

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