# @filekit-studio/diagram 中文文档 规范地址：https://npmcn.com/package/%40filekit-studio/diagram/ 版本：1\.0\.10 npm 元数据更新时间：2026-11-07T19:35:02.027Z 中文译文更新时间：2026-11-14T18:10:11.478Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40filekit-studio/diagram 原文对照：https://npmcn.com/package/%40filekit-studio/diagram/?lang=original 项目主页：https://sketch.filekitstudio.com/ ## 关键信息（来自 npm 元数据） - 包体积（解压后）：451 kB，8 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：1 个 - peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0，@filekit-studio/sketch \>=1\.1\.0 - 首次发布：2026-10-24T21:13:13.933Z - 最新版本发布：2026-11-07T19:35:01.848Z - 近 30 天下载量：2242（2026-10-15 至 2026-11-13，npm 官方下载统计） - 已发布版本数：12（近 12 个月 12 个） ## 中文简介 用于 @ filekit- studio/sketch 的解析图-as-Code & JSON 图表编译器 ## 安装 ```sh npm install @filekit-studio/diagram ``` 也可以使用：`pnpm add @filekit-studio/diagram`、`yarn add @filekit-studio/diagram`、`bun add @filekit-studio/diagram` ## README # @ filekit- studio/ diagram (英语) > 声明式图表- as- Code & JSON 图形编译器 `@filekit-studio/sketch`。 。 。 . [![npm version](https://img.shields.io/npm/v/@filekit-studio/diagram.svg)](https://www.npmjs.com/package/@filekit-studio/diagram) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [文档](https://sketch.filekitstudio.com/docs/diagram) 二. 支助 [快速启动指南](https://sketch.filekitstudio.com/docs/diagram/quickstart) 二. 支助 [现场播放](https://sketch.filekitstudio.com/playground) `@filekit-studio/diagram` 让您直接从React 和 Next.js 中的 JSON 或 Diagram-as-Code 中生成和渲染出美丽的手绘白板、建筑图和流程图. - **需要零坐标**:提供节点,边缘,和集群——决定式DAG布局引擎位置并自动对齐一切. - **纹理美学**: 电源 `@filekit-studio/sketch`,使有机的手拉式形状,粗糙的填充,以及磁接头箭头. - **寻找出行障碍和走廊**:正弦肘行会自动在外形上绕行而无需通过中间服务. - **潜入隧道**:被曲折的行会自动变成形状下有细微破碎的X射线路径. - **方向流动**: 支持从左到右 ()`LR`),从上到下(`TB`页:1`RL`),和从下到下`BT`) (中文(简体) ). - **解析原生**: 从 `.excalidraw` schema文件和元素阵列. - **100% 客户端**:零服务器呼叫,零跟踪,工作全部下线. * * * ## 安装 ```bash bun add @filekit-studio/diagram @filekit-studio/sketch # or npm install @filekit-studio/diagram @filekit-studio/sketch # or pnpm add @filekit-studio/diagram @filekit-studio/sketch ``` ### 需要的样式表导入 导入根版式中的自定义样式表( E)`app/layout.tsx` 或者说 `pages/_app.tsx`: ```tsx import '@filekit-studio/diagram/styles.css' // or: import '@filekit-studio/sketch/styles.css' ``` > **零 CSS 漏报**: 所有样式都严格限定在下面 `.fk-sketch-root`。导入此样式表永远不会与您的应用程序的全球 CSS 、 字体或 Tailwind 配置相冲突 . * * * ## 快速启动 ### 1\. 声明 `` 构成部分 ```tsx 'use client' import React from 'react' import { Diagram, type DiagramData } from '@filekit-studio/diagram' import '@filekit-studio/diagram/styles.css' const architecture: DiagramData = { title: 'Cloud Payment Pipeline', direction: 'LR', nodes: [ { id: 'client', label: 'Client Browser\n(React / Next.js)', shape: 'rectangle', color: 'indigo', badge: 'FRONTEND', }, { id: 'gateway', label: 'API Gateway', description: 'Kong / Cloudflare', shape: 'rounded', color: 'blue', }, { id: 'auth', label: 'Auth Service', description: 'JWT / OAuth2', shape: 'diamond', color: 'amber', }, { id: 'db', label: 'Primary Database\n(PostgreSQL)', shape: 'cylinder', color: 'emerald', badge: 'STORAGE', }, ], edges: [ { from: 'client', to: 'gateway', label: 'HTTPS POST' }, { from: 'gateway', to: 'auth', label: 'Verify Token' }, { from: 'auth', to: 'db', label: 'SQL Query' }, ], groups: [ { id: 'backend', label: 'Internal VPC Cluster', nodeIds: ['gateway', 'auth', 'db'], color: 'indigo', }, ], } export default function ArchitectureDoc() { return (
{/* Automatically inherits dark/light mode and sets contrast */}
) } ``` * * * ### 2\. 方案汇编`diagramToSketch`(中文(简体) ) 如果您想要将图表 JSON 编译为 `SketchDocument` 以保存、变异或导出 : ```tsx import { diagramToSketch } from '@filekit-studio/diagram' const sketchDoc = diagramToSketch(architecture, { direction: 'LR', nodeSpacing: 80, rankSpacing: 220, }) console.log(sketchDoc.elements) // Array of SketchBoardElement objects ``` * * * ### 3\. 渲染 Excalidraw JSON 文件 ```tsx import { Diagram } from '@filekit-studio/diagram' import excalidrawFile from './diagram.excalidraw.json' export function ExcalidrawViewer() { return (
) } ``` * * * ## `` 推荐参考 | Prop | 类型 | 默认 | 说明 | | :-- | :-- | :-- | :-- | | `data` | `DiagramData | string` | _所需经费_ | 图表规格对象或JSON字符串. | | `mode` | `'viewer' | 'editor'` | `'viewer'` | 显示模式:清洁医生取景器或全白板工作室. | | `direction` | `'TB' | 'BT' | 'LR' | 'RL'` | `'LR'` | DAG自动放出引擎的流程方向. | | `theme` | `'light' | 'dark' | 'system'` | `'system'` | 颜色主题模式 。 自动检测活动网站暗模式 . | | `canvasBackground` | `string` | `'#f0f4f8'` | 十六进制背景颜色覆盖( H)`#121214` )),阴暗模式下. | | `gridStyle` | `'grid' | 'dots' | 'cross' | 'none'` | `'dots'` | Canvas网格图案. | | `autoFit` | `boolean` | `true` | 装入容器的缩放和中心元素 . | | `interactive` | `boolean` | `true` | 允许点击并拖入相轮缩放. | | `showCopyButton` | `boolean` | `true` | 显示 1 单击剪贴板导出按钮 . | | `copyFormat` | `'elements' | 'image' | 'json'` | `'elements'` | `'elements'` ctrl+V 粘贴为 Sketch 白板, `'image'` 用于巴布亚新几内亚,或 `'json'`。 。 。 . | | `showZoomControls` | `boolean` | `true` | 显示最小浮动缩放百分比和 `+`编号 :`-`编号 :`Fit` 控制系统. | | `layoutOptions` | `DiagramLayoutOptions` | `{}` | 间距微调`nodeSpacing`, (中文(简体) ), `rankSpacing`、边际和垫地. | | `uiConfig` | `SketchUIConfig` | `{}` | 用于所有54个UI控制和菜单(编辑模式)的 Granular toggle旗. | | `controllerRef` | `Ref` | `undefined` | 参考必要的控制器方法`zoomToFit`, (中文(简体) ), `zoomIn`, (中文(简体) ), `zoomOut`(见a/c.5/49/70,附件). | * * * ## 许可证 麻省理工学院 [文件 Kit 工作室](https://filekitstudio.com/) ## 常见问题 ### @filekit-studio/diagram 是什么？ 用于 @ filekit- studio/sketch 的解析图-as-Code & JSON 图表编译器 ### 如何安装 @filekit-studio/diagram？ 在项目目录运行 npm install @filekit-studio/diagram，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）、react-dom（\>=18\.0\.0）、@filekit-studio/sketch（\>=1\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @filekit-studio/diagram 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @filekit-studio/diagram 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @filekit-studio/diagram 可以商用吗？ @filekit-studio/diagram 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @filekit-studio/diagram 的下载量有多少？ 根据 npm 官方下载统计，@filekit-studio/diagram 在 2026/10/15 – 2026/11/13 这 30 天内被下载 2,242 次，日均约 75 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @filekit-studio/diagram 还在维护吗？ 最新版本 1\.0\.10 发布于 2026/11/08（6 天前）；至今共发布 12 个版本，其中过去 12 个月发布了 12 个；首次发布于 2026/10/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。