# OpenNodes V1 — 支持矩阵、富文本和样式

> 本文件是 DWS OpenNodes V1 协议的拆分章节。按需读取入口见
> [协议索引](../open-nodes-v1.md)。

## 7. 节点类型

### 7.1 支持矩阵

| `type` | query | update | 主要字段 |
| --- | --- | --- | --- |
| `shape` | 支持 | 支持 | `geometry`、`text?`、`style?` |
| `text` | 支持 | 支持 | `text`、`style?` |
| `connector` | 支持 | 支持 | `start`、`end`、`routing`、`waypoints?`、`style?` |
| `stickyNote` | 支持 | 支持 | `text?`、`style?` |
| `frame` | 支持 | 支持 | `title?`、`style?`、`presentationOrder?`、`resizeMode?` |
| `group` | 支持 | 支持 | 子关系通过 `parentId` 表达 |
| `image` | 支持 | 只读 | 仅公共字段 |
| `vector` | 支持 | 支持 | `resource` |
| `icon` | 支持 | 支持 | `catalogId` |
| `path` | 支持 | 支持 | `path`、`style?` |
| `pdf` | 支持 | 只读 | 仅公共字段 |
| `media` | 支持 | 只读 | 仅公共字段 |
| `webLink` | 支持 | 只读 | 仅公共字段 |
| `table` | 支持 | 只读 | 仅公共字段 |
| `chart` | 支持 | 只读 | 仅公共字段 |
| `uml` | 支持 | 只读 | 仅公共字段 |
| `swimlane` | 支持 | 只读 | 仅公共字段 |
| `mind` | 支持 | 只读 | 仅公共字段 |
| `timer` | 支持 | 只读 | 仅公共字段 |
| `placeholder` | 支持 | 只读 | 仅公共字段 |
| `unknown` | 支持 | 只读 | 未识别或尚未定义独立语义的节点统一映射到此类型 |

表中标记为只读的类型仍会完整返回公共几何、层级和顺序信息，但 update 提交会以
`nodeTypeUnsupported` 失败。

`timer`、`table`、`webLink` 不支持 V1 update。query 仅返回这些节点的公共几何、
层级、顺序和诊断字段，不承诺完整业务字段。文字 run 中的 `link` 是富文本能力，
不属于 `webLink` 节点，V1 支持读写。

`webLink` 只保留只读查询；OpenNodes V1 不支持创建或重建该节点。

### 7.2 Text

query 和 update 均支持普通段落、无序列表、有序列表、多 block、多 run 和文字
链接：

```ts
interface OpenTextRun {
  text: string;
  marks?: {
    fontFamily?: string;
    fontSize?: number;
    bold?: boolean;
    italic?: boolean;
    underline?: boolean;
    strike?: boolean;
    color?: string;
    highlight?: string;
  };
  link?: { url: string };
}

interface OpenTextBlock {
  type: "paragraph" | "bulletList" | "orderedList";
  horizontalAlign?: "left" | "center" | "right";
  runs: OpenTextRun[];
}

interface OpenTextWrite {
  blocks: OpenTextBlock[];
  verticalAlign?: "top" | "center" | "bottom";
  padding?: number | [number, number];
}

interface OpenText extends OpenTextWrite {
  plainText: string;
  writeSupport: "readWrite" | "readOnly";
  unsupportedFeatures?: string[];
}
```

约束：

- `blocks.length >= 1`，每个 block 的 `type` 必须是 `paragraph`、
  `bulletList` 或 `orderedList`。
- 每个 block 都必须满足 `runs.length >= 1`。
- run 的 `text` 不能包含 `\r`、`\n`、U+2028 或 U+2029。换行和列表项使用
  独立 block 表达；每一段或每个列表项应写成一个 block，而不是把原始换行符
  放进单个 run。
- 每个 `bulletList` / `orderedList` block 表示一个列表项；服务端会把连续且同类的
  block 解释为同一个列表中的多个列表项。
- `link.url` 长度必须为 `1..2048`，不能包含控制字符、`<`、`>`。支持无 scheme
  的相对/裸链接，以及 `http`、`https`、`mailto`、`tel`、`dingtalk` scheme；
  `javascript:`、`data:` 等可执行或未知 scheme 会被拒绝。
- 相邻且 URL 相同的 linked run 会呈现为同一个链接，同时保留各 run 自己的 marks。
- `fontSize > 0`，padding 各项必须大于等于 `0`。
- `plainText`、文本级 `writeSupport` 和 `unsupportedFeatures` 是 query-only。
- text 节点必须提供 `text`；shape 和 stickyNote 的 `text` 可省略。
- 受支持的 paragraph、列表、链接、多 run 都保持
  `writeSupport = "readWrite"`；未知 list style、非法链接、未支持的 block 或
  run marks 会令文本和所属节点变为 `readOnly`。

下面的文本会显示为两个段落，第一段由两个不同样式的 run 组成：

```json
{
  "blocks": [
    {
      "type": "paragraph",
      "horizontalAlign": "left",
      "runs": [
        {
          "text": "OpenNodes ",
          "marks": { "fontSize": 18, "bold": true, "color": "#2563EB" }
        },
        {
          "text": "rich text",
          "marks": { "fontSize": 18, "italic": true, "color": "#0F172A" }
        }
      ]
    },
    {
      "type": "paragraph",
      "horizontalAlign": "right",
      "runs": [
        {
          "text": "第二段",
          "marks": { "fontSize": 16, "underline": true, "color": "#047857" }
        }
      ]
    }
  ],
  "verticalAlign": "center",
  "padding": [4, 8]
}
```

同一 `OpenTextWrite` 结构适用于独立 text 节点、shape 文本、stickyNote 文本和
frame title。

下面三个 block 会生成两个无序列表项，其中第二项包含文字链接：

```json
{
  "blocks": [
    {
      "type": "bulletList",
      "runs": [{ "text": "准备输入数据" }]
    },
    {
      "type": "bulletList",
      "runs": [
        {
          "text": "查看钉钉文档",
          "marks": { "underline": true },
          "link": { "url": "https://alidocs.dingtalk.com" }
        }
      ]
    },
    {
      "type": "orderedList",
      "runs": [{ "text": "执行生成" }]
    }
  ]
}
```

颜色接受以下 CSS 形式：3/4/6/8 位十六进制、颜色名，以及
`rgb()`、`rgba()`、`hsl()`、`hsla()`、`oklch()`、`lab()`、`lch()`、
`color()`。字符串最长 128 字符，不能包含控制字符、`<`、`>` 或 `;`。
这里只接受可独立解析的字面量；依赖外部样式上下文的 `var()`、`calc()`、
`color-mix()` 等动态表达式不属于 V1。颜色名必须是标准 CSS named color，
任意字母串不会被当成颜色。

### 7.3 Style

query 可表达：

- `none`、`solid`、`theme`、线性渐变、径向渐变和图片 paint。
- shadow、blur 和 unknown effect。

V1 update 支持 `none`、`solid`、`theme`、线性渐变、九方向径向渐变，以及
单个自定义 shadow。主题明暗参数和渐变色标位置使用 `0～100` 的百分比，
不会归一化成 `0～1`：

```ts
type OpenRadialGradientPosition =
  | "topLeft"
  | "topCenter"
  | "topRight"
  | "centerLeft"
  | "center"
  | "centerRight"
  | "bottomLeft"
  | "bottomCenter"
  | "bottomRight";

interface OpenColorStop {
  offset: number;
  color: string;
  opacity?: number;
}

interface OpenImagePaint {
  type: "image";
  resource: {
    kind: "managed" | "external" | "embedded" | "unresolved";
    resourceId?: string;
  };
  intrinsicWidth: number;
  intrinsicHeight: number;
}

type OpenPaint =
  | { type: "none" }
  | { type: "solid"; color: string; opacity?: number }
  | {
      type: "theme";
      token: string;
      lumMod?: number;
      lumOff?: number;
      resolvedColor?: string;
    }
  | {
      type: "linearGradient";
      angle: number;
      stops: OpenColorStop[];
    }
  | {
      type: "radialGradient";
      position: OpenRadialGradientPosition | "custom";
      stops: OpenColorStop[];
    }
  | OpenImagePaint;

type OpenEffect =
  | {
      type: "shadow";
      offsetX: number;
      offsetY: number;
      blur: number;
      color: string;
      opacity: number;
    }
  | { type: "blur"; blur: number }
  | { type: "unknown" };

interface OpenNodeStyle {
  opacity?: number;
  fill?: OpenPaint;
  stroke?: {
    paint: OpenPaint;
    width?: number;
    dash?: number[];
    lineCap?: "butt" | "round" | "square";
    lineJoin?: "miter" | "round" | "bevel";
  };
  effects?: OpenEffect[];
  writeSupport: "readWrite" | "readOnly";
  unsupportedFeatures?: string[];
}

interface OpenColorStopWrite {
  offset: number; // [0, 100]，百分比
  color: string;
  opacity?: number; // [0, 1]
}

type OpenPaintWrite =
  | { type: "none" }
  | { type: "solid"; color: string; opacity?: number }
  | {
      type: "theme";
      token: string;
      lumMod?: number; // [0, 100]，默认 100
      lumOff?: number; // [0, 100]，默认 0
    }
  | {
      type: "linearGradient";
      angle: number;
      stops: OpenColorStopWrite[];
    }
  | {
      type: "radialGradient";
      position: OpenRadialGradientPosition;
      stops: OpenColorStopWrite[];
    };

interface OpenShadowEffectWrite {
  type: "shadow";
  offsetX: number;
  offsetY: number;
  blur: number;
  color: string;
  opacity: number;
}

interface OpenNodeStyleWrite {
  opacity?: number;
  fill?: OpenPaintWrite;
  stroke?: {
    paint: OpenPaintWrite;
    width?: number;
    dash?: number[];
    lineCap?: "butt" | "round" | "square";
    lineJoin?: "miter" | "round" | "bevel";
  };
  effects?: OpenShadowEffectWrite[];
}
```

约束：

- opacity 范围为 `[0, 1]`。
- solid paint 的 `color` 与 `opacity` 在 query 后仍保持独立字段，不会合并为
  动态 CSS 表达式。
- theme 的 `token` 必须能在当前白板主题中解析；
  `lumMod`、`lumOff` 范围均为 `[0, 100]`。token 不存在时在
  Request graph 阶段返回 `themeTokenNotFound`，不会写出部分节点。
  token 长度为 `1～64`，首尾不能有空白，也不能包含空白、控制字符、
  `<`、`>` 或 `;`。
- query 的 theme paint 还会返回按当前白板主题计算出的 query-only
  `resolvedColor`。调用方写入时只传 `token/lumMod/lumOff`，不传
  `resolvedColor`。
- 渐变必须至少有一个 stop；`offset` 范围为 `[0, 100]`，单位是百分比。
- 线性渐变 `angle` 范围为 `[0, 360]`。
- 径向渐变只接受上述九宫格位置。query 遇到九宫格以外的位置时返回
  `position: "custom"` 并将该节点标为只读。
- `effects` 最多包含一个 `shadow`；`offsetX/offsetY` 必须是有限数，
  `blur >= 0`，shadow opacity 范围为 `[0, 1]`。
- stroke width 和 dash 各项必须大于等于 `0`。
- 一旦提供 stroke，`stroke.paint` 必填。
- 样式级 `writeSupport` 和 `unsupportedFeatures` 是 query-only。
- 能在当前白板主题中解析且明暗参数合法的 theme paint 可写。无法解析的主题
  token、越界的主题明暗参数、image paint、blur、unknown effect、叠加 effect
  或自定义径向位置会令节点只读；受支持的 theme、渐变和单个 shadow 本身不会
  令节点只读。

主题色示例：

```json
{
  "fill": {
    "type": "theme",
    "token": "ac3",
    "lumMod": 20,
    "lumOff": 80
  },
  "stroke": {
    "paint": {
      "type": "theme",
      "token": "sk1",
      "lumMod": 80,
      "lumOff": 20
    },
    "width": 2
  }
}
```

示例中的 `ac3`、`sk1` 只是主题 token 示例，不是所有白板都可用的全局枚举。
调用方只能使用已确认可由当前白板主题解析的 token；无法确认时应改用
`solid` 颜色。

DWS 不提供新增、修改或切换主题的命令。当前白板没有有效主题时，应改用
`solid`。

示例：

```json
{
  "fill": {
    "type": "linearGradient",
    "angle": 35,
    "stops": [
      { "offset": 0, "color": "#1677ff", "opacity": 0.4 },
      { "offset": 100, "color": "#69b1ff" }
    ]
  },
  "effects": [
    {
      "type": "shadow",
      "offsetX": 8,
      "offsetY": 8,
      "blur": 19,
      "color": "rgba(93,190,172,1)",
      "opacity": 0.5
    }
  ]
}
```

未传 `style` 时使用节点类型的默认样式。调用方如需稳定的视觉结果，应显式传入
`fill` 和 `stroke`。