OpenNodes V1 — Shape、Text、Sticky note、Frame、Group 和 Connector

本文件是 DWS OpenNodes V1 协议的拆分章节。按需读取入口见协议索引。

7.4 Shape

shape 必须提供 geometry，格式为 dml:<name>：

{
  "id": "shape-1",
  "type": "shape",
  "x": 100,
  "y": 80,
  "width": 160,
  "height": 100,
  "geometry": "dml:roundRect",
  "style": {
    "fill": {
      "type": "solid",
      "color": "#DCEEFF"
    },
    "stroke": {
      "paint": {
        "type": "solid",
        "color": "#225588"
      },
      "width": 2
    }
  }
}

query 可能返回 adjustments，但 V1 update 不支持写入；带 adjustments 的 shape 会标为只读。dml-v1 的完整 geometry 目录见附录 A。

7.5 Text node 与 Sticky note

text node 使用公共几何、必填 text 和可选 style。

stickyNote 使用公共几何、可选 text 和可选 style。省略 text 时创建空便签。query 还可能返回：

creator：创建者展示信息。
tags：标签 ID、文本和背景 paint。

这两个字段是 query-only；存在 creator 或 tags 的 stickyNote 会被标为只读。

7.6 Frame

frame 的 update 结构见第 6 节 OpenFrameNodeWrite。

约束：

frame 必须是页面直属节点，不能带 parentId。
angle 只允许 0。
presentationOrder 是非负整数，并且不能和已有或本次创建的 frame 冲突。
frame 的子节点通过子节点 parentId 引用 frame 临时 ID。
frame 不能包含 frame 或 connector。
frame 默认 layer 为 background。

7.7 Group

group 的写入字段只有公共字段中的 id、parentId?、x、y、layer?、 zIndex? 和 hidden?。其 width、height、angle 和 children 都由服务端根据子节点推导。

group 必须：

提供临时 id。
至少包含两个直接子节点。
至少有一个直接子节点可见。

group 的任一子节点为只读时，query 会把 group 一并标为只读。

7.8 Connector

connector 的几何由端点和路由推导，因此 update 不能提供 x、y、 width、height 或 angle。

query 的连接线结构如下：

type OpenConnectorRouting =
  | "straight"
  | "polyline"
  | "curve"
  | "orthogonal";

interface OpenConnectorMarker {
  catalogId: string;
}

type OpenConnectorAnchor =
  | {
      mode: "fixed";
      side: "top" | "right" | "bottom" | "left";
      position: OpenPoint;
    }
  | {
      mode: "fixed";
      side: "custom";
      position: OpenPoint;
    };

type OpenConnectorEndpoint =
  | {
      type: "point";
      point: OpenPoint;
      marker: OpenConnectorMarker;
    }
  | {
      type: "node";
      nodeRef: { scope: "document"; id: string };
      anchor: OpenConnectorAnchor;
      resolvedPoint: OpenPoint;
      marker: OpenConnectorMarker;
    };

interface OpenBezierSegment {
  start: OpenPoint;
  control1: OpenPoint;
  control2: OpenPoint;
  end: OpenPoint;
}

type OpenResolvedConnectorPath =
  | { type: "polyline"; points: OpenPoint[] }
  | { type: "bezier"; segments: OpenBezierSegment[] };

update 端点有两种形式：

type OpenConnectorEndpointWrite =
  | {
      type: "point";
      point: { x: number; y: number };
      marker?: { catalogId: "none" | "arrow.open" | "arrow.filled" };
    }
  | {
      type: "node";
      nodeRef: { scope: "request"; id: string };
      anchor?:
        | { mode: "auto" }
        | {
            mode: "fixed";
            side: "top" | "right" | "bottom" | "left";
          };
      marker?: { catalogId: "none" | "arrow.open" | "arrow.filled" };
    };

query 的 marker catalogId 使用 string，以便返回无法映射的既有 marker； update 只接受上面列出的 "none"、"arrow.open"、"arrow.filled"。

路由规则：

`routing`	`waypoints`
`straight`	禁止提供，包括空数组。
`polyline`	必须至少提供一个。
`curve`	可选。
`orthogonal`	可选；显式点路径的相邻线段必须水平或垂直。

其他约束：

所有 point 和 waypoint 都使用页面绝对坐标。
node 端点只能引用同一请求中的 shape、text、stickyNote、frame、group 或 path。
node 端点不能引用隐藏节点、connector 或 query 中既有节点。
update 引用范围固定为 scope: "request"；query 返回的节点引用范围为 scope: "document"，不能直接回写。
同一连接线的两端不能引用同一个节点。
零长度或无效路径会被拒绝。
marker 省略时默认为 none。
anchor 省略时按 auto 处理。

query 额外返回服务端解析后的：

node 端点 resolvedPoint。
fixed anchor 的归一化 position。
resolvedPath，类型为 polyline points 或 cubic bezier segments。
由真实路径推导的 absoluteBounds。

这些解析字段都是 query-only。

4.8 KiB Raw Blame History Unescape Escape