# @hanzo/canvas 中文文档

规范地址：https://npmcn.com/package/%40hanzo/canvas/

版本：0\.2\.4
npm 元数据更新时间：2026-09-04T16:28:27.010Z
中文译文更新时间：2026-11-17T08:11:29.811Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：185 kB，87 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \>=19\.2\.8，react-dom \>=19\.2\.8，@hanzo/gui \>=8\.3\.1，@xyflow/react \>=12
- 首次发布：2026-07-10T10:00:18.528Z
- 最新版本发布：2026-09-04T16:28:26.802Z
- 近 30 天下载量：5307（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

Pannable/zoomable PaaS项目帆布——一个服务会节点,有活的状态,有公制火花线,部署时间表,一个环境切换器,以及一个服务细节抽屉. @hanzo/gui 主持人不可知论 反应表面,品牌/白色标签意识,由每个人共享

## 安装

```sh
npm install @hanzo/canvas
```

也可以使用：`pnpm add @hanzo/canvas`、`yarn add @hanzo/canvas`、`bun add @hanzo/canvas`

## README

# @hanzo/canvas (英语)

A 类 **可全能/可分解 PaaS项目帆布** 用于任何汉藏控制台的 服务节点,有实时状态、公制火花线、部署时间表、 环境切换器,还有服务细节抽屉.

建造在 [`@hanzo/gui`](https://github.com/hanzoai/ui) (就这样) **商标/ 白色标签意识** 通过设计符号——在设计符号中提供相同的组件 韩佐、鲁克思和动物园的操纵台,每个品牌都有可选的 [`@xyflow/react`](https://reactflow.dev/) 画布本身的同位素 .

每个组件都是 **列报和数据辅助驱动**: 主机获取其 `/v1` 将它们映射到平面视图模型中 `./types`。纯折叠 (状态正常化、布局、相对时间)由单位单独测试 组件永远不会到达数据层。 一种方法来做一切,分解.

## 安装

```sh
pnpm add @hanzo/canvas
# peers: @hanzo/gui, react, react-dom, and (for the canvas) @xyflow/react
```

## 碎片

| 导出 | 这是什么 |
| --- | --- |
| `ProjectCanvas` | 平板/分板(React Flow):点-网格,迷你地图,控制,自动放出,主题-意识. 动态导入, 并禁用 SSR . |
| `ServiceNode` | 分层服务卡——图标,名称,类型+ `/v1` 能力 状态徽章 源代码 复制品 最新的部署时间 度量活性. |
| `ServiceStatusBadge` | 状态药丸(点+标签),有活脉冲 `active`编号 :`deploying`。 。 。 . |
| `MetricSparkline` | 微小而诚实的火花(没有数据时的平面基线——从不假趋势). |
| `DeployTimeline` | 纵向部署/建设时间表. |
| `EnvSwitcher` | 分块环境切换器(生产/预览/.). |
| `ServiceDetailDrawer` | 右侧抽屉有服务头+主机提供标签(部署、变量、计量、日志、域名、SBOM). |
| `SourceRef`, (中文(简体) ), `ReplicaPill` | 小原始人——回波/图像源回想和可复制计数药. |
| `normalizeServiceStatus`, (中文(简体) ), `layoutGraph`, (中文(简体) ), `relativeTime`, (中文(简体) ), `toEpochMs`, (中文(简体) ), `statusColors`, (中文(简体) ), `withAlpha`, (中文(简体) ), `kindLabel` | 纯帮助主机将其数据映射通过. |

## 使用量

```tsx
import dynamic from 'next/dynamic'
import { type ServiceNodeData } from '@hanzo/canvas'

// The canvas touches browser globals at import — load it client-side only.
const ProjectCanvas = dynamic(
  () => import('@hanzo/canvas').then((m) => m.ProjectCanvas),
  { ssr: false },
)

const nodes: ServiceNodeData[] = apps.map((a) => ({
  id: a.id,
  name: a.name,
  kind: 'app',
  status: normalizeServiceStatus(a.phase ?? a.status),
  source: { kind: 'image', ref: `${a.image.repository}:${a.image.tag}` },
  replicas: a.replicas,
  deployedAt: toEpochMs(a.updatedAt),
  capability: { id: 'platform', label: 'App Platform' },
}))

<ProjectCanvas
  nodes={nodes}
  edges={edges}
  theme={resolvedTheme}
  reducedMotion={reducedMotion}
  onOpenDetail={(svc) => setSelected(svc)}
/>
```

状态颜色是 **语义而非品牌** (绿色=活跃,琥珀=部署, 红色 = 坠毁, 并可通过 `statusPalette` 道具; 全部 卡片铬使用中性设计符号,所以画布上每个品牌的 主题自动.

## 常见问题

### @hanzo/canvas 是什么？

Pannable/zoomable PaaS项目帆布——一个服务会节点,有活的状态,有公制火花线,部署时间表,一个环境切换器,以及一个服务细节抽屉\. @hanzo/gui 主持人不可知论 反应表面,品牌/白色标签意识,由每个人共享

### 如何安装 @hanzo/canvas？

在项目目录运行 npm install @hanzo/canvas，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=19\.2\.8）、react-dom（\>=19\.2\.8）、@hanzo/gui（\>=8\.3\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @hanzo/canvas 支持 TypeScript 吗？

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

### @hanzo/canvas 支持 ESM 还是 CommonJS？

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

### @hanzo/canvas 可以商用吗？

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

### @hanzo/canvas 的下载量有多少？

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

### @hanzo/canvas 还在维护吗？

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

