# @filekit-studio/sketch 中文文档 规范地址：https://npmcn.com/package/%40filekit-studio/sketch/ 版本：1\.5\.1 npm 元数据更新时间：2026-11-12T06:15:29.315Z 中文译文更新时间：2026-11-14T17:46:31.173Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40filekit-studio/sketch 原文对照：https://npmcn.com/package/%40filekit-studio/sketch/?lang=original 项目主页：https://sketch.filekitstudio.com/ ## 关键信息（来自 npm 元数据） - 包体积（解压后）：8 MB，34 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：5 个 - peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0 - 首次发布：2026-10-24T10:26:21.994Z - 最新版本发布：2026-11-12T06:15:28.938Z - 近 30 天下载量：5568（2026-10-15 至 2026-11-13，npm 官方下载统计） - 已发布版本数：29（近 12 个月 29 个） ## 中文简介 本地第一,可嵌入的白板和图解 SDK 用于 React and Next.js ## 安装 ```sh npm install @filekit-studio/sketch ``` 也可以使用：`pnpm add @filekit-studio/sketch`、`yarn add @filekit-studio/sketch`、`bun add @filekit-studio/sketch` ## README # @ filekit-studio/ sketch > 本地第一,交互式白板和建筑图解 SDK 用于 React and Next.js. [![npm version](https://img.shields.io/npm/v/@filekit-studio/sketch.svg)](https://www.npmjs.com/package/@filekit-studio/sketch) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [文档](https://sketch.filekitstudio.com/docs) 二. 支助 [现场播放](https://sketch.filekitstudio.com/playground) 二. 支助 [技术Stencils目录](https://sketch.filekitstudio.com/stencils) 二. 支助 [文件 Kit 工作室](https://filekitstudio.com/) * * * ## 特征 - **本地第一隐私**:零服务器呼叫,零数据库起落架,零遥测. 图表在客户端运行和持续. - **数据库Schema & ER 建模**: 键入了2列数据库表格(`tableStyle: 'database'`)带有PK/FK图标,自动类型取色,动态行加/去除,自动拓宽文本框,并全键盘导航(Enter,Shift+Enter,后空行去除,箭头穿行). 新闻 联合国 用于激活. - **现场动画数据流连接器**:实时粒子脉冲和流模拟跨越曲线,肘,和直磁连接器,具有可配置速度,触发模式,发光颜色. - **15°角方向抓取**显示 移动 并绘制直线或箭头以锁定至15°角增量(0°水平,90°垂直,45°对角,30°/60°同位素)并有浮动度徽章. - **箭标和调和调色板**: 在多行包装下进行双击标签编辑(`\n`),紧凑自动尺寸,并有暗/淡模式优化的单色调色板. - **磁连接锁定建议**: 实时12点周边锚站在图和数据库表边框上悬浮,用于无功用连接器断接. - **框架封装和反偷盗复制**页:1`type: 'frame'`用作孤立的滑动甲板或组件边界。 变相或移动一个框架克隆, 并转移所有封闭的形状 原子. - **PNG 导出无新形**: 导出带有被充气的矢量场景元数据并嵌入 PNG 内的光栅 PNG `tEXt` 块数( e)`embedScene: true`) (中文(简体) ). 重新导入 Sketch 将100%的可编辑向量恢复 . - **反应 18 & 19 / Next.js 准备**: 原生App路由器和Pages路由器支持,零 SSR水合不匹配. - **675+ 生产Stencils**:正版云标和微服务原始相(AWS,GCP,Azure,多克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克. - **障碍- 逃避路线**:Hanan Grid $A^\*$正弦和弯曲箭道与Minkowski Sum障碍物通膨,角平板,高速公路道相抵. - **演示文稿牌模式**: 将帆布框转换为演示幻灯片甲板(`Alt+P`)带有激光指针和聚光焦点工具. - **无头导出者**: 无服务器和无头导出到矢量 PDF(多页自动插页),简洁的PNG,以及独立的SVG. - **嵌入式查看器**: 轻 `` 在文档和博客中提供交互式或静态图表的组件. - **统一 `.sketch` 文件格式**:快速,可移植的JSON文件格式由原型-污染和XSS安全净化器保护. * * * ## 安装 ```bash npm install @filekit-studio/sketch # or pnpm add @filekit-studio/sketch # or bun add @filekit-studio/sketch ``` ### 同伴依赖关系 - `react >= 18.0.0` - `react-dom >= 18.0.0` ### 需要的样式表导入 导入根版式中的样式表( E)`app/layout.tsx` 或者说 `pages/_app.tsx`: ```tsx // Universal modern Tailwind CSS v4 styling (Default) import '@filekit-studio/sketch/styles.css' // Or pick an aesthetic variant: // import '@filekit-studio/sketch/classic.css' // Classic clean wireframe styling // import '@filekit-studio/sketch/neumorphic.css' // Soft extruded 3D neumorphic styling ``` > **零 CSS 污染(高度范围隔离)**数字 : > 所有样式都严格限定在下面 `.fk-sketch-root`。导入此样式表永远不会与您的应用程序的全球 CSS 、 标记下字体或 Tailwind 配置相冲突 . * * * ## 快速启动 导入 `` 客户部分内(`'use client'`: ```tsx 'use client' import React from 'react' import { SketchEditor } from '@filekit-studio/sketch' import '@filekit-studio/sketch/styles.css' export default function WhiteboardPage() { return (
{ console.log('Updated:', doc.elements.length, 'elements') }} onSave={(doc) => { console.log('Saved:', doc) }} showGuideButton={true} guideHref="/docs" />
) } ``` * * * ## 仅读图查看器( E)``(中文(简体) ) 使用 `` 将图表嵌入文档、博客文章和零编辑器铬的仪表板中: ```tsx 'use client' import { SketchViewer } from '@filekit-studio/sketch' import '@filekit-studio/sketch/styles.css' export function ArchitectureDiagram({ document }) { return (
) } ``` * * * ## 阻碍箭头行走 环绕图表节点的路线无相撞正交或曲线箭头: ```ts import { computeNonCollisionRoute, generateFilletSvgPath } from '@filekit-studio/sketch' const route = computeNonCollisionRoute( { x: 100, y: 150 }, // Start point { x: 500, y: 350 }, // End point 'right', // Start anchor orientation ('top' | 'right' | 'bottom' | 'left') 'left', // End anchor orientation obstacles, // Array of { x, y, width, height } { margin: 24, // Minkowski Sum obstacle padding bendPenalty: 40, // Penalize unnecessary turns filletRadius: 10, // Rounded 90° arc fillets smoothCurves: false, } ) // Generate SVG path string for rendering: const svgPath = generateFilletSvgPath(route.waypoints, 10) ``` * * * ## 无头导出公用事业 在不挂起画布组件的情况下导出图表 `@filekit-studio/sketch/export`数字 : ```ts import { exportToPng, exportToSvg, exportWhiteboardToPdf, } from '@filekit-studio/sketch/export' import { extractSceneFromPng } from '@filekit-studio/sketch' // PNG with optional steganographic lossless scene embedding const pngDataUrl = await exportToPng(elements, { scale: 2, backgroundColor: '#ffffff', embedScene: true, // Injects compressed scene into PNG tEXt chunk }) // Extract 100% editable vector scene from a FileKit PNG const recoveredDoc = await extractSceneFromPng(pngFileBlob) // Vector SVG string const svgMarkup = exportToSvg(elements, { includeBackground: true, }) // Multi-page Vector PDF Blob const pdfBlob = await exportWhiteboardToPdf(elements, { title: 'Architecture Specification', author: 'FileKit Studio', }) ``` * * * ## 数据库 Schema & ER 实体表 Render 键入了带有主键,数据类型和自动调色板同步的双列数据库表格 : ```tsx import { SketchEditor, type SketchBoardElement } from '@filekit-studio/sketch' const usersTable: SketchBoardElement = { id: 'table_users', type: 'table', tableStyle: 'database', // Activates Database Entity mode x: 100, y: 100, width: 280, height: 180, strokeColor: '#3b82f6', strokeWidth: 2, strokeStyle: 'solid', fillColor: '#1e293b', fillStyle: 'solid', opacity: 1, zIndex: 1, rows: 4, cols: 2, colWidths: [150, 130], rowHeights: [36, 32, 32, 32], hasHeaderRow: true, cells: { '0,0': { text: 'users', bold: true, align: 'left' }, '1,0': { text: 'id', align: 'left' }, // Auto-displays yellow PK key icon '1,1': { text: 'uuid', align: 'right' }, '2,0': { text: 'name', align: 'left' }, '2,1': { text: 'varchar(100)', align: 'right' }, '3,0': { text: 'email', align: 'left' }, '3,1': { text: 'varchar(255)', align: 'right' }, }, } ``` - **单元格中的键盘导航**数字 : - 输入: 插入干净的新行而无需移动单元格。 排高动态地扩张. - 移动 + 输入 或者说 标签:确认单元格编辑并跳至下行/栏. - 后空格 (当行为空): 删除整个空行并自动约定表格高度. - ↑ ↓ → ←: 导航在相邻单元格之间. - 快捷键: 按 联合国 以激活数据库Schema表格工具. * * * ## 现场动画数据流连接器 实时模拟跨连接器的数据流: ```tsx const animatedStream: SketchBoardElement = { id: 'stream_1', type: 'arrow', arrowType: 'elbow', x: 280, y: 150, width: 140, height: 80, strokeColor: '#3b82f6', strokeWidth: 2, strokeStyle: 'solid', fillColor: 'transparent', fillStyle: 'solid', opacity: 1, zIndex: 2, endArrowhead: 'arrow', // Live Connector Simulation: flowAnimation: 'packet-pulse', // 'none' | 'marching-ants' | 'packet-pulse' | 'error-backoff' flowSpeed: 'normal', // 'slow' (2.4s) | 'normal' (1.4s) | 'fast' (0.7s) flowTrigger: 'continuous', // 'continuous' | 'hover' | 'click' | 'step' flowColor: '#60a5fa', // Custom packet glow color } ``` * * * ## 方案管理员(`SketchController`(中文(简体) ) 附 录a `controllerRef` 必须控制白板画布: ```tsx import React, { useRef } from 'react' import { SketchEditor, type SketchController } from '@filekit-studio/sketch' export function ControlledCanvas() { const controllerRef = useRef(null) const handleAddNote = () => { controllerRef.current?.addElement({ type: 'sticky', x: 200, y: 200, width: 180, height: 180, text: 'Production Note', fillColor: '#fef08a', }) } return (
) } ``` ### 主计长方法 | 方法 | 说明 | | :-- | :-- | | `loadDocument(doc)` | 替换活动白板文档. | | `getDocument()` | 返回可序列文档状态. | | `clear()` | 将白板帆布重置为空状态 . | | `addElement(element)` | 程序上插入和选择一个元素. | | `updateElement(id, patch)` | 部分更新现有元素. | | `deleteElements(ids)` | 用 ID 列表删除元素. | | `getElements()` | 返回当前元素数组 . | | `undo()` 编号 : `redo()` | 导航撤销/重写历史堆栈 . | | `zoomToFit()` | 中心并缩放以适应所有元素在取景口. | | `zoomIn()` 编号 : `zoomOut()` | 平滑递增的取景口放大. | | `resetZoom()` | 重新将缩放比例缩放到100% . | | `showToast(msg, options)` | 坎瓦的触发器通知吐司旗. | | `on(event, handler)` | 订阅事件( E)`'change'`, (中文(简体) ), `'select'`, (中文(简体) ), `'clear'`, (中文(简体) ), `'undo'`, (中文(简体) ), `'redo'`, (中文(简体) ), `'camera'`) (中文(简体) ). | * * * ## 组成部分 API 参考 ### `` | Prop | 类型 | 默认 | 说明 | | :-- | :-- | :-- | :-- | | `value` | `SketchDocument | SketchBoardElement[]` | `undefined` | 受控文档或元素. | | `defaultValue` | `SketchDocument | SketchBoardElement[]` | 启动文件 | 初始无控文档状态 . | | `onChange` | `(doc: SketchDocument) => void` | `undefined` | 向任何元素或标题更改发出回调 . | | `onSave` | `(doc: SketchDocument) => void` | `undefined` | 手动保存时调用`Ctrl+S`) (中文(简体) ). | | `storageKey` | `string | null` | `'filekit_sketch_document_v1'` | 用于持续状态的密钥 `localStorage`。使用动态键(`storageKey={'board_' + id}`)隔离多板工作空间. | | `boardName` | `string` | `'My Whiteboard'` | 白板标题以页眉显示 . | | `readOnly` | `boolean` | `false` | 禁用突变并隐藏编辑工具. | | `theme` | `'light' | 'dark' | 'system'` | `'system'` | 视觉色彩主题模式. | | `showThemeToggle` | `boolean` | `false` | 上行独立日月画布主题按钮. | | `onThemeChange` | `(theme: 'light' | 'dark') => void` | `undefined` | 点击主题切换时调用回调 . | | `canvasBackground` | `string` | `'#f0f4f8'` | 坎瓦斯背景六分颜色. | | `gridStyle` | `'grid' | 'dots' | 'cross' | 'none'` | `'grid'` | 背景网格图案. | | `fontFamily` | `FontFamily` | `'fuzzy'` | 默认画布字体家族 . | | `panelVariant` | `'classic' | 'neumorphic'` | `'classic'` | Chrome stypeling变型:平面边框或软3D贝. | | `wheelPan` | `boolean` | `true` | 当错误时,鼠标轮会滚动主机网页; Ctrl+轮子缩放. | | `toastPosition` | `ToastPosition` | `'bottom-center'` | 土司横幅位置( Name`'bottom-center'`, (中文(简体) ), `'top-right'`(见a/c.5/49/70,附件). | | `position` | `ToastPosition` | `'bottom-center'` | 直接别名用于 `toastPosition`。 。 。 . | | `toastDuration` | `number` | `2400` | 通知吐司的自动解除期限为毫秒. | | `saveToastMessage` | `string | null` | `'Document saved successfully'` | 自定义保存土司信件( 或) `null` (d) 禁止. | | `templates` | `TemplateDefinition[]` | `undefined` | 自定义架构启动模板阵列 . | | `controllerRef` | `React.Ref` | `undefined` | 重新揭示方案的必要控制. | | `onExit` | `() => void` | `undefined` | 退出后按钮处理器 。 如果省略为 `exitHref`,退出按钮被隐藏. | | `exitHref` | `string` | `undefined` | 点击退出按钮时已导航到路由 . | | `onShare` | `() => void` | `undefined` | 当用户点击上行的共享按钮时, 调用已开火 。 自动挂载共享按钮 . | | `showGuideButton` | `boolean` | `false` | 在标题中挂起一个向导帮助按钮. | | `guideHref` | `string` | `undefined` | 引导按钮的外部或内部 URL . | | `onOpenGuide` | `() => void` | `undefined` | 拦截点击引导按钮触发自定义模式. | | `uiConfig` | `SketchUIConfig` | `{}` | 所有54个工具栏和面板的清晰可见度切换. | ### `` | Prop | 类型 | 默认 | 说明 | | :-- | :-- | :-- | :-- | | `value` 编号 : `elements` | `SketchDocument | SketchBoardElement[]` | `undefined` | 所需文件或要素. | | `theme` | `'light' | 'dark' | 'system'` | `'system'` | 浅/暗主题模式. | | `autoFit` | `boolean` | `true` | 中心与平面图,以适应容器. | | `interactive` | `boolean` | `true` | 允许平面和缩放。 设定 `false` 用于静态显示. | | `showCopyButton` | `boolean` | `true` | 1 点击剪贴板导出按钮 . | | `copyFormat` | `'elements' | 'image' | 'json'` | `'elements'` | 写入剪贴板的格式 : `'elements'` (直接贴入 `Ctrl+V` 入于白板, `'image'` (2个PNG),或 `'json'`。 。 。 . | | `showZoomControls` | `boolean` | `true` | 最小底部缩放控件( E)`- 100% + Fit`) (中文(简体) ). | | `canvasBackground` | `string` | `'#f0f4f8'` | 自定义画布背景颜色十六进制 . | | `gridStyle` | `'grid' | 'dots' | 'cross' | 'none'` | `'dots'` | 背景网格图案. | | `title` | `string` | `undefined` | 左上角的可选头衔徽章. | * * * ## 许可证 麻省理工学院 [文件 Kit 工作室](https://filekitstudio.com/) ## 常见问题 ### @filekit-studio/sketch 是什么？ 本地第一,可嵌入的白板和图解 SDK 用于 React and Next\.js ### 如何安装 @filekit-studio/sketch？ 在项目目录运行 npm install @filekit-studio/sketch，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）、react-dom（\>=18\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @filekit-studio/sketch 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @filekit-studio/sketch 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @filekit-studio/sketch 可以商用吗？ @filekit-studio/sketch 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @filekit-studio/sketch 的下载量有多少？ 根据 npm 官方下载统计，@filekit-studio/sketch 在 2026/10/15 – 2026/11/13 这 30 天内被下载 5,568 次，日均约 186 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @filekit-studio/sketch 还在维护吗？ 最新版本 1\.5\.1 发布于 2026/11/12（2 天前）；至今共发布 29 个版本，其中过去 12 个月发布了 29 个；首次发布于 2026/10/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。