用途
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 文件的结构与操作方法,资料未说明其支持的具体应用、插件或命令;预设颜色的实际色值由应用决定,技能本身未给出。