SuperAPI AI 工具集

json-canvas

通用与其它

查看项目

更新于 10-30 16:18

技能介绍

用途

json-canvas 用于创建和编辑 JSON Canvas 文件(扩展名 .canvas),这类文件遵循 JSON Canvas Spec 1.0。适合在需要制作可视化画布时使用,例如思维导图、项目看板、研究画布和流程图。

文件结构

一个 .canvas 文件包含两个顶层数组:

{
  "nodes": [],
  "edges": []
}

其中 nodes(节点)和 edges(连线)均为可选数组。节点数组的顺序决定图层先后:排在前面的位于底层,排在后面的位于顶层。

常见工作流

1. 新建画布

以 {"nodes": [], "edges": []} 为基础结构创建 .canvas 文件;为每个节点生成唯一的 16 位十六进制 ID(如 "6f0ad84f44ce9c17");添加节点时须包含 id、type、x、y、width、height 这些必填字段;添加连线时通过 fromNode 和 toNode 引用有效节点 ID;最后解析 JSON 确认格式有效,并核对所有 fromNode/toNode 都指向 nodes 数组中存在的节点。

2. 向现有画布添加节点

读取并解析已有的 .canvas 文件;生成不与现有节点或连线 ID 冲突的唯一 ID;选择不与现有节点重叠的坐标(建议留出 50–100px 间距);将新节点对象追加到 nodes 数组;可选地添加连线,把新节点连接到已有节点;最后校验 ID 是否唯一、连线引用是否都能解析到现有节点。

3. 连接两个节点

确定源节点与目标节点的 ID;生成唯一连线 ID;将 fromNode 与 toNode 设为对应节点 ID;可选设置 fromSide/toSide(top、right、bottom、left)指定锚点;可选设置 label 为连线添加说明文字;将连线追加到 edges 数组;校验 fromNode 与 toNode 均指向现有节点 ID。

4. 编辑现有画布

以 JSON 读取并解析 .canvas 文件;按 id 找到目标节点或连线;修改所需属性(文本、位置、颜色等);把更新后的 JSON 写回文件;编辑完成后再次检查 ID 唯一性与连线引用完整性。

节点

节点是放置在画布上的对象。通用属性包括:id(必填,唯一的 16 位十六进制标识)、type(必填,取值为 text、file、link 或 group)、x/y(必填整数,像素坐标)、width/height(必填整数,像素尺寸)、color(可选,预设 "1"–"6" 或十六进制色值)。

文本节点

text 为必填的字符串,支持 Markdown 语法。示例:

{
  "id": "6f0ad84f44ce9c17",
  "type": "text",
  "x": 0,
  "y": 0,
  "width": 400,
  "height": 200,
  "text": "# Hello World\n\nThis is **Markdown** content."
}

注意:JSON 字符串中的换行应使用 \n;不要使用字面量 \n,否则会渲染出字符 \ 和 n。

文件节点

file 为必填,表示系统内的文件路径;subpath 为可选,用于指向标题或块(以 # 开头)。示例:

{
  "id": "a1b2c3d4e5f67890",
  "type": "file",
  "x": 500,
  "y": 0,
  "width": 400,
  "height": 300,
  "file": "Attachments/diagram.png"
}

链接节点

url 为必填,表示外部链接。示例:

{
  "id": "c3d4e5f678901234",
  "type": "link",
  "x": 1000,
  "y": 0,
  "width": 400,
  "height": 200,
  "url": "https://obsidian.md"
}

分组节点

分组用于在视觉上收纳其他节点,子节点应放置在分组的边界内。可选属性包括 label(分组标签)、background(背景图路径)、backgroundStyle(cover、ratio 或 repeat)。示例:

{
  "id": "d4e5f6789012345a",
  "type": "group",
  "x": -50,
  "y": -50,
  "width": 1000,
  "height": 600,
  "label": "Project Overview",
  "color": "4"
}

连线

连线通过 fromNode 与 toNode 的节点 ID 连接两个节点。属性包括:id(必填,唯一标识)、fromNode(必填,源节点 ID)、fromSide(可选,top/right/bottom/left)、fromEnd(可选,默认 none,取值 none 或 arrow)、toNode(必填,目标节点 ID)、toSide(可选,top/right/bottom/left)、toEnd(可选,默认 arrow,取值 none 或 arrow)、color(可选,线条颜色)、label(可选,文字标签)。示例:

{
  "id": "0123456789abcdef",
  "fromNode": "6f0ad84f44ce9c17",
  "fromSide": "right",
  "toNode": "a1b2c3d4e5f67890",
  "toSide": "left",
  "toEnd": "arrow",
  "label": "leads to"
}

颜色

canvasColor 类型接受十六进制字符串或预设编号:"1" 红、"2" 橙、"3" 黄、"4" 绿、"5" 青、"6" 紫。预设色的具体色值有意未定义,由各应用使用自身品牌色。

ID 生成

生成 16 位小写十六进制字符串(64 位随机值),例如 "6f0ad84f44ce9c17"、"a3b2c1d0e9f8a7b6"。

布局建议

坐标可以为负值(画布可无限延展);x 向右增大,y 向下增大,坐标指左上角位置;节点之间留 50–100px 间距,分组内留 20–50px 内边距;对齐到网格(10 或 20 的倍数)可使布局更整齐。推荐尺寸:小文本 200–300×80–150,中文本 300–450×150–300,大文本 400–600×300–500,文件预览 300–500×200–400,链接预览 250–400×100–200。

校验清单

创建或编辑画布文件后,需核对:所有 id 在 nodes 与 edges 中唯一;每个 fromNode/toNode 都指向存在的节点 ID;各节点类型具备必填字段(文本节点有 text,文件节点有 file,链接节点有 url);type 为 text、file、link、group 之一;fromSide/toSide 为 top、right、bottom、left 之一;fromEnd/toEnd 为 none 或 arrow;颜色预设为 "1"–"6" 或合法十六进制(如 "#FF0000");JSON 可解析。若校验失败,检查重复 ID、悬空连线引用或格式错误的 JSON 字符串(尤其是文本内容中未转义的换行)。

完整示例与参考

资料提到可参见 references/EXAMPLES.md 获取完整画布示例(含思维导图、项目看板、研究画布、流程图),并列出参考资料 JSON Canvas Spec 1.0 与 JSON Canvas GitHub;但该示例文件的具体内容与链接地址在本次资料中暂未提供。

限制

该技能仅覆盖 .canvas 文件的结构与操作方法,资料未说明其支持的具体应用、插件或命令;预设颜色的实际色值由应用决定,技能本身未给出。