来源：https://ui.docs.xihanfun.com/runtime/designer-shell

# 设计器零件

`@xihan-ui/designer-shell` 是画布式设计器共用的界面零件：属性面板、标尺与参考线、变换覆盖层、物料面板与拖放、页面结构、历史记录、问题列表、小地图、外框、设置对话框、导入字段对话框与新手引导。打印、流程、表单、报表四款设计器用同一套零件，名字、手势与事件对齐。

```ts
import { defineDesignerShell } from "@xihan-ui/designer-shell";
import "@xihan-ui/designer-shell/style.css"; // 配无层皮肤时改引 style.unlayered.css

defineDesignerShell();
```

## 只出 Web Components

这个包是本库「组件三端齐备」惯例的例外：

- 只有 Web Components，没有 headless 契约，也没有 Vue 与 React 版本，不进三端一致性套件。四款设计器都以原生 Web Components 交付，这些零件只给设计器用，不是通用组件。
- 元素自己生成内部结构，不要求作者写 `data-xh-part` 的 Light DOM。部件用 `data-part` 标出，供样式与测试选取。作者内容用 `slot="<名>"` 标在零件的直接子节点上，零件把它搬进对应区域。
- 内部用到的库内元素（字段、开关、选择器、标签等）经 `defineXhElement` 按需注册，不全量注册 `@xihan-ui/web-components`。
- 样式随包发两份，都只消费语义令牌，不进 `@xihan-ui/styles` 的组件槽：`style.css` 在 `xihan.components` 层里，配有层的组件皮肤 `@xihan-ui/styles`；`style.unlayered.css` 内容相同、没有层壳，配无层的组件皮肤 `@xihan-ui/styles/index.unlayered.css`（本站与各设计器的文档站就是这样）。皮肤与零件样式要成对：无层规则不论特指度都压过有层规则，配无层皮肤却引 `style.css` 时，零件覆盖库内组件部件的那几条会静默失效，如 JSON 编辑框的定高与等宽字体、外框分隔条的直角。

## 注册

| 函数 | 说明 |
| --- | --- |
| `defineDesignerShell()` | 注册全部零件，重复调用不报错 |
| `defineDesignerShellElement(tag, ctor)` | 按需注册一个零件；同名标签注册了别的类时抛错 |
| `DESIGNER_SHELL_ELEMENTS` | 标签名到元素类的登记表 |

## 约定

- 零件不持有文档、不碰历史栈：只吃数据、吐事件。改文档与记撤销由设计器做。
- 坐标只认 `@xihan-ui/designer-kit` 的视口：屏幕 = 世界 × `zoom` + (`x`, `y`)。世界单位由设计器定，`zoom` 就是一个世界单位等于多少屏幕像素。控制柄大小、吸附阈值、标尺厚度等固定尺寸一律按屏幕像素。
- 事件一律 `CustomEvent`，冒泡并穿过 shadow 边界，名字用短横线、不带前缀。
- 零件自己生成的结构只用 `div`、`span`、`button` 这类没有正文排版的标签，列表靠 `role="list"` 与 `role="listitem"` 标出。宿主按标签名重置 `p`、`ul`、`li` 等的边距与列表样式（文档站的示例舞台、CSS 框架的基础重置），影响不到零件。
- 每个零件都有 `readonly`：只能浏览与选择，不出编辑手势、不派发修改类事件。零件的布尔 attribute 与库内元素同一个三态读法：`readonly="false"` 不只读，不写交给缺省。
- 文案键是零件的标签名，自带英文缺省。各语言的文案在 `@xihan-ui/designer-shell/locale`，与 UI 的内建语言包一一对应，导出名是 `designerShell` 加 UI 的语言包名，如 `jaJP` 对 `designerShellJaJP`。各产品把同一语言的这一份并进自己的语言包，宿主只合并一份产品包。

## 属性面板

`<xh-designer-properties>` 按 `@xihan-ui/designer-kit/properties` 的属性描述列出字段。设计器给出被编辑的对象，面板分组、挑编辑器、派发修改，自己不写文档。

面板生成的部件都带 `data-scope="designer-properties"`，样式只认它：`header`、`footer` 插槽与宿主编辑器里的作者内容，即使也用了 `data-part="title"` 之类的部件名，也不受面板样式影响。

```ts
const panel = document.createElement("xh-designer-properties");
panel.targets = [{ kind: "task", id: "t1", value: node, descriptors }];
panel.addEventListener("property-change", (event) => {
  const { path, value, targets, merge } = event.detail;
  history.execute(opsFor(targets, path, value), { merge, mergeWithin: Infinity });
});
panel.addEventListener("property-commit", () => history.seal());
```

| 属性 | 说明 |
| --- | --- |
| `targets` | 被编辑的对象 `{ kind, id, value, descriptors }`；空数组显示空状态，多个时只显示共同属性 |
| `editors` | 宿主编辑器表，按 `resolvePropertyEditor` 查找；查不到的内建种类用自带编辑器 |
| `groupOrder` / `groupLabel` | 分组的先后与标题，标题缺省显示分组 id |
| `labelOf` / `hintOf` | 字段的标签与说明；标签缺省取描述的 `label`，再缺省取 `formatJsonPath(path)` |
| `optionLabel` / `unitLabel` | select 选项与 number、sides 单位的文案；单位文案为空串时不显示后缀 |
| `dataFields` | `dataField` 选字段与 `filter` 列字段用的字段树（designer-kit 的 `DataField`）：描述里没写 `fields` 的绑定字段与条件树共用这一份；两处都没有时 `dataField` 是输入字段路径的文本框，`filter` 没有可选的字段 |
| `errors` | 字段错误 `{ target, path, message }`，文字由设计器换好，`path` 相对对象；落在属性里层的错误归到它所属的那一行，见下文 |
| `heading` | 标题下一行，如「表格 · t1」「已选中 3 个」 |
| `empty-text` | 空状态文案 |
| `toggle-limit` | select 单选且选项不超过它时改用切换按钮组；缺省不用。描述写了 `appearance: "dropdown"` 或 `"toggle"` 的 select 不看它，总是下拉或总是切换按钮组（多选也可以），绑定字段这类运行时生成的选项宜写 `dropdown` |
| `collapsible` | 分组可折叠，折叠状态按分组 id 保留，换选择不重置 |
| `readonly` | 字段只读，不派发修改 |
| `headless` | 放进外框的卡片时写：不画自己的标题与 `heading`，由面板头显示；页头插槽有内容时页头照旧显示 |

| 事件 | detail |
| --- | --- |
| `property-change` | `{ path, value, targets, merge }`：每次输入都派发，`value` 为 `undefined` 表示清除；`merge` 是合并键，交给历史栈的 `execute` |
| `property-commit` | `{ path }`：一次编辑结束（失焦、改选、切换、回车），设计器封口 |

- 共同属性是每个对象都有、`path` 相同、`control` 按 JSON 相等的那些；任一对象上不显示即不显示。取值不同时字段留空，显示占位「多个值」，宿主编辑器拿到的 `value` 为 `undefined`。
- 字段用 `<xh-field>` 包库内控件，标签、说明与错误接到控件的可聚焦部件上。换选择只换数据时，同一属性、同一编辑器的字段原样复用，焦点与光标不丢。
- 宿主编辑器的 `setValue` 与 `commit` 也走这两个事件。
- 宿主编辑器返回的 `element` 自己写了 `data-xh-part="control"` 时（库内表单控件，或原生 `input` / `select` / `textarea`），面板把它放进 `<xh-field>` 当字段的控件，标签、说明与校验状态由字段接上。没写时按一组控件处理：整行 `role="group"`，标签与说明经 `aria-labelledby` / `aria-describedby` 接上，组里的控件各自给可访问名称。
- 没有编辑器的编辑方式显示只读的一行：左边是标签文字，右边是占位说明，不进字段接线。
- 数字字段按描述的 `integer`、`exclusiveMin`、`min`、`max` 依次校验：不合法时就地报错、不派发，框里保留输入；失焦时越出 `min` / `max` 的值夹回端点。JSON 字段不能解析时同样就地报错。
- 绑定字段（`dataField`）的字段树先取描述里的 `fields`，没写时取面板的 `dataFields`。有字段树时是可搜索的树选择：按描述的 `kinds` 与 `base` 列出起点之下的字段，同 `listDataFields`（进入对象的子字段，不进入列表的子字段）；不能选的对象是禁用的分支，没有可选后代的字段不列，分支起初都展开。字段有 `label` 时条目显示它，下面一行是字段路径。选中写入字段路径的文字，清空即清除。没有字段树时是文本框，写法不对时就地报错、不派发。
- 四边（`sides`）是一组控件，整行 `role="group"`：「四边相同」开关加一个数字框，关掉后换成上、右、下、左四个（两列），每个框上方是这一边的名字、后缀是单位；四边相同时那一个框以「四边」为名。四边都按描述的数值约束校验，有边空着或违反约束时就地报错、不派发；打开开关时四边不同就按上边统一。换了取值的对象按四边是否相同摆开关；多个对象取值不同时开关禁用，只能四边一起改。
- 格式（`format`）是 `<xh-format-input>`：种类限在描述的 `kinds`，不是必填时种类里多一项「不设格式」，选它即清除；改动随输入派发，失焦时封口。多个对象取值不同时格式输入框标 `mixed`，种类显示「多个值」，选了种类就写给每个对象。
- 写了 `secret` 的文本是 `<xh-password-input>`：缺省不显示明文，可切换显隐，浏览器不代填也不记住。
- 颜色预设（`swatch`）是一组控件，整行 `role="group"`：上面是 `<xh-color-swatch-picker>`，一项一格，格子画选项的 `color`，选中写入选项的 `value`；描述写了 `custom` 时下面另有一个颜色框，填任意颜色。取值不在选项里时显示在颜色框里，色板不选中任何一格。描述写了 `none` 时色板前另有一颗开关钮（`<xh-toggle>`），文字就是它：取值没写时按下，按下即不写值（删掉这个键）；松开不算一种取值，等选了色板或填了颜色才松开。
- 选项列表（`options`）是 `<xh-field-array>` 的表格排布，放在这一行的字段里，字段的标题就是表格的名字。一项一行，三格依次是值、文字与禁用（描述写了 `allowDisabled: false` 时没有禁用这一列，写出的选项也不带 `disabled`），每格是一个字段，控件以「列名 + 第几项」为名（中文如「第 3 项的值」）；行号、拖动、上移、下移与删除把手和下面的新增把手由字段数组铺出：按住拖动把手把这一项拖到别处换位，键盘用上移、下移，新增与删除也都能按到。值与文字边输入边写入、失焦封口；勾选禁用，以及新增、删除与换序，各是一步。新增的一项只有空的 `value`，加好后焦点落到它的值上；文字为空、不禁用时不写这两个键，项上别的键（`tone`、`description`）原样留着；删掉最后一项即清除。值与文字两列有最小宽，数字、日期与日期时间的值列不窄过字段的压缩底线（`--xh-control-min-w`），放得下长一些的数与整个日期时间，禁用列放得下列头；格里的控件不超出自己那一格。面板放不下时表格横向滚动，行号钉在起始侧，把手随行一起滚动（字段数组的 `stickyActions` 关掉），滚到末端或 Tab 到时露出来，值格因此总有一个滚动位置整个看得见。值格按描述的 `valueType` 换控件：`"string"`（缺省）是文本框；`"number"` 是数字框，写回数值，清空即去掉 `value`，新增的一项是空对象；`"date"` / `"datetime"` 是日期框（到日 / 到分），写回 `YYYY-MM-DD` / `YYYY-MM-DDTHH:mm`；`"boolean"` 固定 `true`、`false` 两行，值格只读、显示「是 / 否」（随面板语言），没有新增、删除与换序，文字与禁用照常可改，写回时两项都写、`true` 在前。多个对象取值不同时没有行，新增的一项整体写给这几个对象。
- 选项树（`treeOptions`）是 `<xh-table>` 的树形表（声明了 `tree`，平铺的各项也报 `role="treegrid"`），单元格级导航（`navigation="cell"`），整行按一组控件排，表格的名字是这一行的标题。一项一行，四格依次是值、文字、禁用与操作（描述写了 `allowDisabled: false` 时没有禁用这一列），各行报层级与层内位次；值格按层缩进，有下一层的项带展开把手；操作列里是「加子项」与「删除」两颗钮，钉在行尾，面板放不下时表格横向滚动、操作列留在原处；表格下面是「新增一项」，加在顶层末尾。键盘照表格的单元格导航：方向键在格子之间走，Enter 或 F2 进格内编辑（输入框里的左右键归输入框），Esc 或 F2 回到格子，焦点在行上时左右键收起与展开；Alt + 上下键在同一层换序，Alt + 左右键改一层缩进（往里是认上一项当上级，各项还是平铺时也行），也可以按住行拖动，拖到哪一项的中段就放进那一项下面（叶子项也行）；叶子项不带 `aria-expanded`；写回整棵树，焦点留在原来那一格。格里的控件以「列名 + 大纲号」为名（中文如「第 1.2 项的值」），两颗钮也按大纲号起名（「给第 1.2 项加子项」「删除第 1.2 项」）。值与文字边输入边写入、失焦封口；勾选禁用，以及加子项、新增、删除与换位，各是一步。新的一项只有空的 `value`，加好后焦点落到它的值上；删掉一项连同它的下一层，下一层删空时不再写 `children`；项上别的键（`tone`、`description`、`hasChildren`）原样留着。问题按路径标到那一项那一格，如 `[0, "children", 1, "value"]` 标在第 1.2 项值那一格。多个对象取值不同时没有行，新增的一项整体写给这几个对象。
- 选项列表与选项树自己不另做校验：值为空、值重复、缺了要求的文字这些问题由 designer-kit 的取值检查报（`checkProperties` 与 `findPropertyValueIssue`，路径落在那一项的那个键上），设计器照常把它们交给面板的 `errors`。编辑器按路径把问题标到格上：`[i, "value"]`、`[i, "label"]`、`[i, "disabled"]` 落在那一格（选项树先按 `children` 找到那一层那一项），项上别的键与这一项本身落在它的值上；那一格的控件 `aria-invalid="true"`，错误文字显示在格子里、经 `aria-describedby` 接上。两种编辑器都写了 `nestedIssues`，只有里层问题时行下不重复。
- 条件树（`filter`）是 `<xh-filter-builder>`：字段先取描述里的 `fields`，没写时由面板的 `dataFields` 按 `listFilterFields` 列出值字段（字段没写 `type` 的按文本）；参数与子组层数取描述的 `parameters`、`maxDepth`，`ids` 为 true 时新建的条件与组按 `c1`、`g1` 这样取树里没用过的 id。一次增删改就是一步：写入即封口。多个对象取值不同时显示空树，空态写「多个值」，在上面加的条件整体写给这几个对象。
- 错误按路径段归到行：路径以某一行属性的路径开头（含相等）就属于那一行，有嵌套描述时归路径最长的那一行；按段比较，`options` 不沾 `optionsExtra` 的错误。哪一行都不沾的不显示。
- 行下的文字依次取：控件自己发现的错误、恰好落在这一行的错误；只有里层错误时显示第一条，宿主编辑器的实例写了 `nestedIssues: true` 的不显示，由编辑器自己标到子项上。
- 宿主编辑器与内建编辑器的上下文都带 `issues`（designer-kit 的 `PropertyIssue`）：这一行的错误，路径相对这个属性，按路径排；多选时合并各对象的，同一路径只留先出现的一条。四边按 `["top"]` 这类路径把那一边的数字框标成无效（四边相同时标那一个框），文字仍在行下。
- 插槽 `header` 在标题下方（如部位导航），`footer` 在字段之后（如「删除列」）。
- `focusField(path)` 把焦点交给该属性的字段，找不到时返回 `false`。

### 复合编辑器里的字段

宿主编辑器常要拼几个字段，比如四边边框的每一边有线宽、线型与颜色。`createPropertyField` 按一种内建编辑方式建出一行字段，控件、单位后缀、数字约束与 JSON、字段路径的就地校验、空值、「多个值」与只读，都和属性面板里的同一套。复合编辑器在 `setValue` 里拼出整个值，再交给自己的 `setValue`：

```ts
import type { DesignerPropertyEditor } from "@xihan-ui/designer-shell";
import { createPropertyField } from "@xihan-ui/designer-shell";

const stroke: DesignerPropertyEditor = (initial) => {
  let context = initial;
  const current = (): Record<string, unknown> => ({ ...(context.value as Record<string, unknown> | undefined) });
  const width = createPropertyField({
    ownerDocument: document,
    control: { kind: "number", min: 0, step: 0.05, unit: "mm" },
    label: "线宽",
    setValue: value => context.setValue({ ...current(), width: value ?? 0 }),
    commit: () => context.commit(),
  }, { value: current().width as number | undefined });
  const element = document.createElement("div");
  element.append(width.element);
  return {
    element,
    update: (next) => {
      context = next;
      width.update({ value: current().width as number | undefined, readonly: next.readonly });
    },
  };
};
```

| 选项 | 说明 |
| --- | --- |
| `control` | 内建的编辑方式；别的种类抛 `TypeError` |
| `label` / `required` | 字段的标题与必填标记 |
| `setValue` / `commit` | 写入新值（`undefined` 为清除）与一次编辑结束；只读时不调用 |
| `optionLabel` / `unitLabel` / `dataFields` / `toggleLimit` | 同属性面板的同名属性 |
| `translations` | 压在配置文案之上；配置取字段所在位置的（`xh-designer-properties` 那一桶） |

`update(state)` 每次整份给状态：`value`、`readonly`、`mixed`（多个值）、`label`（给了就换掉建字段时的标题，如切换语言后）、`hint`（说明）、`error`（外面给的错误，控件自己发现的错误优先显示）与 `issues`（落在这个字段值里层的问题，路径相对字段的值，四边按它标出对应那一边；行下的文字仍取 `error`）。返回的 `element` 是一整行：控件在 `<xh-field>` 里，标题、说明与错误由字段接上；四边（`sides`）这类一组控件时整行是 `role="group"`。

复合编辑器把里层的问题标到子项上（如选项表某一行的错）：读 `context.issues`，按路径分给子项，实例上写 `nestedIssues: true`，行下就不重复。读屏与 UI 字段接线同一个约定：

- 子项控件的名字仍是子项自己的标题（「选项 3」），问题文字不并进名字。
- 问题落在子项控件可聚焦的部件上：`aria-invalid="true"`，错误文字经 `aria-describedby` 接上，与 `<xh-field>` 的 `error-text` 一样。子项用 `createPropertyField` 拼时把那一项的问题交给它的 `error`，字段会接好；自己铺的控件就自己写这两个属性，错误文字放在那一项旁边看得见的地方。
- 问题清掉后收回 `aria-invalid` 与描述。写了 `nestedIssues` 的编辑器必须自己显示这些问题，不然它们就看不到了。

```ts
const options: DesignerPropertyEditor = (initial) => {
  let context = initial;
  const element = document.createElement("div");
  let rows: PropertyField[] = [];
  const render = (): void => {
    const items = Array.isArray(context.value) ? context.value : [];
    if (rows.length !== items.length) {
      rows = items.map((_, index) => createPropertyField({
        ownerDocument: document,
        control: { kind: "text" },
        label: `选项 ${index + 1}`,
        setValue: value => context.setValue(items.map((item, i) => (i === index ? { ...item, label: value } : item))),
        commit: () => context.commit(),
      }, { value: undefined }));
      element.replaceChildren(...rows.map(row => row.element));
    }
    rows.forEach((row, index) => row.update({
      value: items[index]?.label,
      readonly: context.readonly,
      error: context.issues.find(issue => issue.path[0] === index)?.message,
    }));
  };
  render();
  return { element, nestedIssues: true, update: (next) => { context = next; render(); } };
};
```

## 问题列表

`<xh-designer-issues>` 列出结构问题。文字由设计器换好，零件只管排列、过滤与定位。

```ts
const list = document.createElement("xh-designer-issues");
list.items = issues.map(issue => ({ issue, message: t(issue), subject: nameOf(issue.target) }));
list.addEventListener("issue-activate", event => select(event.detail.issue.target));
list.addEventListener("issue-hover", event => highlight(event.detail.issue?.target));
```

| 属性 | 说明 |
| --- | --- |
| `items` | `{ issue, message, subject?, source? }[]`：`issue` 是 `SchemaIssue`，`subject` 是对象名，`source` 显示为来源小标签 |
| `group-by` | `severity`（缺省）错误在前、警告在后；`target` 按问题所在对象分组；`none` 按传入顺序 |
| `empty-text` | 没有问题时的提示 |
| `readonly` | 列表没有修改类操作，只读时照常浏览与定位 |
| `headless` | 放进外框的卡片时写：不画自己的标题，由面板头显示，列表仍以标题为名；严重程度的过滤照旧显示，要放进面板头见下文 `summary` |
| `activate` | 哪些条目能点：`target`（缺省）只有落在对象上的问题能点，设计器据此选中对象；`path` 凡有路径的都能点，JSON 编辑框据此把光标移过去 |

| 只读属性 | 说明 |
| --- | --- |
| `summary` | 头部那组带计数的严重程度开关 |

| 事件 | detail |
| --- | --- |
| `issue-activate` | `{ issue, index }`：点击或回车；`index` 是在 `items` 里的下标 |
| `issue-hover` | `{ issue }`：指针移到条目上；移出列表时 `issue` 为 `undefined` |

- 头部的错误、警告两个开关带条数，过滤状态在换 `items` 后保留。
- 放进外框的卡片时，可以把 `summary` 移到面板头的操作区：写上 `slot="<区名>-actions"` 交给外框。零件照样更新计数与开关状态，不再把它收回头部；`headless` 时头部随之收起。

  ```ts
  issues.headless = true;
  issues.summary.slot = "issues-actions";
  frame.append(issues.summary);
  ```
- 按对象分组时，组按对象在 `items` 里第一次出现的先后排列，组内错误在前。组标题取组内第一条的 `subject`，都没有时显示对象的 `id`；条目里不再重复对象名。没有 `target` 的问题归在最后一组，标题取文案 `noTarget`。
- 有 `target` 的条目是按钮，方向键、Home、End 在它们之间移动焦点；没有 `target` 的条目只显示，不可激活。`activate="path"` 时每一条都是按钮。

## 小地图

`<xh-designer-minimap>` 按比例画出设计器给的图形与当前视口的范围。按下或拖动时派发 `navigate`，由设计器把视口中心移过去。

```ts
const map = document.createElement("xh-designer-minimap");
map.shapes = nodes.map(node => ({ kind: "rect", rect: node.rect }));
map.viewport = viewport;
map.canvasSize = { width: canvas.clientWidth, height: canvas.clientHeight };
map.addEventListener("navigate", event => setViewport(centerOn(viewport, event.detail.center, map.canvasSize)));
```

| 属性 | 说明 |
| --- | --- |
| `shapes` | 世界坐标的图形：`{ kind: "rect", rect, tone? }`（`tone` 为 `muted` 时取淡色）或 `{ kind: "path", d }` |
| `bounds` | 内容范围，缺省取全部矩形的外包；路径伸出矩形之外时由设计器给出 |
| `viewport` / `canvasSize` | 画布的视口与屏幕尺寸，两者都给时画出视口框 |
| `readonly` | 小地图只做导航，只读时照常可用 |

- 比例把内容与视口范围一并装下；拖动期间比例与位置保持不变，松手后重新适配。
- 没有图形时收起（`data-empty`），整块 `aria-hidden`，不进 Tab 顺序。
- 零件只画自身的框，摆在画布的哪个角由设计器决定。

## 物料面板与拖放

`<xh-designer-palette>` 按分组列出物料：每组是组名一行、下面是物料的方形小卡片，图标在上、名称在下，按面板宽度自动排成几列。点击、回车、空格或触屏轻点派发 `item-activate`，设计器一般把物料加到视口中央；按下拖动（触屏长按）经下面的通用拖放拖向画布。

```ts
const palette = document.createElement("xh-designer-palette");
palette.groups = [{ id: "human", label: "人工处理", items: [{ id: "approve", label: "审批", payload: { type: "approve" } }] }];
palette.addEventListener("item-activate", event => addAtCenter(event.detail.payload));
```

| 属性 | 说明 |
| --- | --- |
| `groups` | `{ id, label, items }[]`，物料为 `{ id, label, icon?, description?, disabled?, browseOnly?, payload?, children? }`；`icon` 是卡片上的图标，`description` 是名称之外的一句说明（卡片上不显示，悬停提示里与名称一起显示，读屏作为说明念出），`children` 是下级物料 |
| `searchable` | 显示搜索框，按名称与说明过滤；命中的条目连同它的上级一起展开显示 |
| `collapsible` | 分组可折叠，折叠状态按分组 id 保留；搜索时匹配的分组一律展开 |
| `readonly` | 物料只能浏览，不派发 `item-activate`、不能拖出 |
| `headless` | 放进外框的卡片时写：不画自己的标题，由面板头显示；外框的区已是这块地标，正文不再是地标，搜索框照旧 |

| 事件 | detail |
| --- | --- |
| `item-activate` | `{ id, payload }` |

- 卡片的边长不小于两倍 md 控件高（随密度变），列宽按面板宽度均分；名称只占一行，放不下就截断。悬停或用键盘走到一张卡片时，提示显示「名称 · 说明」，没有说明的只显示名称。
- 读屏照旧是带组名的一组按钮，整块一个 Tab 位：卡片的名字只有名称，说明另行念出。没有改用 grid 角色：列数随面板宽度变，网格的行列不是物料本身的结构，读屏念「第几行第几列」没有意义。
- 左右键按排列的先后走（右到左排列时对调），上下键走到上一行、下一行里与当前卡片对得最齐的那张，跨组也是；Home、End 到第一张、最后一张。禁用的物料也能停留，读屏照样念出。
- 搜索时平铺的组只留命中的卡片，照样排成网格；一张都没命中的组整组不显示。
- 从物料拖出时的载荷是 `{ source: "palette", id, payload }`。
- 扩展往面板里加的分组（如「我的物料」）经物料来源接进来，见下文「扩展的面板与命令」的「物料来源」。
- `disabled` 是用不了的物料：显示为禁用，不派发 `item-activate`、不能拖出。`browseOnly` 是只作浏览的物料：照常显示、能用方向键走到，同样不派发、不能拖出，用于只起分组作用的上级与只供查看的下级。

### 带下级的物料

组里有物料带了 `children` 时，这一组用 [`<xh-tree>`](../components/tree) 一行一个地显示，不排成卡片：层级与展开收起要靠缩进与箭头读出来，字段名通常也比卡片放得下的长。没有下级的组照样是卡片。适合字段树这类有层级的物料：

```ts
palette.groups = [{
  id: "fields",
  label: "字段",
  items: [
    { id: "no", label: "单号", description: "no", payload: { field: "no" } },
    { id: "items", label: "明细", description: "items", payload: { list: "items" }, children: [
      { id: "items.qty", label: "数量", browseOnly: true },
    ] },
  ],
}];
```

- 键盘与读屏按树的约定：这一组是一个 Tab 停靠点，上下键在看得见的物料间移动，右键展开、左键收起，回车与空格激活；层级、展开态与禁用报给读屏。
- 带下级的物料缺省收起，展开状态按物料 id 保留，换了 `groups` 仍在；搜索时命中的物料连同上级一起展开，清空后回到原来的展开状态。
- 点选与确认键只派发 `item-activate`，树上不留选中的痕迹；按在展开箭头上只展开、收起，不起拖。
- 上级与下级都能激活、拖出，不需要的写 `browseOnly` 或 `disabled`。

### 通用拖放

物料面板之外的拖动源（如字段树）也用这两个函数。坐标一律是浏览器视口坐标，设计器自己换算成世界坐标。

```ts
import { registerDropTarget, startDrag } from "@xihan-ui/designer-shell";

const unregister = registerDropTarget(canvas, {
  over: (point, payload) => ({ accept: payload.source === "palette", ghost: "hide" }),
  drop: (point, payload) => addAt(clientToWorld(point), payload.payload),
  leave: () => clearDropPreview(),
});
canvas.addEventListener("pan-request", event => setViewport(panBy(viewport, -event.detail.dx, -event.detail.dy)));

field.addEventListener("pointerdown", event => startDrag(event, { payload: { source: "field", path } }));
```

| 函数 | 说明 |
| --- | --- |
| `startDrag(event, { payload, source?, preview?, onEnd? })` | 从一次指针按下开始拖动，返回 `{ active, cancel }`。`preview` 缺省为拖动源的缩小副本，按下处保持在指针下；给 `null` 不显示。`onEnd` 收到 `{ dragged, dropped }`，拖过之后可借它吞掉随后的点击 |
| `registerDropTarget(element, { over, drop, leave? })` | 把元素登记为放置目标，返回取消登记的函数。`over(point, payload)` 答复 `{ accept, ghost? }`，`ghost` 为 `hide` 时藏起预览、由目标自己画落点；`leave` 在指针离开、取消或在不接受处松手时调用 |

- 鼠标与笔移动过激活距离才开始拖；触屏长按开始拖，长按前先移动即视为滚动，开始拖之后不再滚动页面。
- 命中取指针下最内层的放置目标，预览不挡命中。
- 贴着接受的目标边缘时逐帧在目标上派发 `pan-request` `{ dx, dy }`：视口要朝哪个方向看过去多少屏幕像素，贴右边缘时 `dx` 为正。
- Esc、指针离开窗口、在不接受处松手即取消。

## 页面结构

`<xh-designer-outline>` 按树列出模板里的内容（容器、分组与元素），像图层面板一样定位、删除与挪动。零件只吃节点、吐事件：选中、在画布上标出、删除与挪动都由设计器翻成自己的操作，进撤销栈也归设计器。

```ts
const outline = document.createElement("xh-designer-outline");
outline.nodes = [
  { id: "name", label: "姓名", description: "name" },
  { id: "grid", label: "栅格", children: [
    { id: "col-1", label: "第 1 列", movable: false, deletable: false, children: [{ id: "phone", label: "手机号" }] },
  ] },
];
outline.selection = designer.getSelection().nodes;
outline.allowMove = move => canMove(move);
outline.addEventListener("node-select", event => designer.select({ nodes: event.detail.ids }));
outline.addEventListener("node-highlight", event => markOnCanvas(event.detail.id));
```

| 属性 | 说明 |
| --- | --- |
| `nodes` | `DesignerOutlineNode[]`：`{ id, label, description?, icon?, children?, expanded?, selectable?, movable?, deletable? }`。`children` 是数组就是分支（空数组也能放进东西），没有就是叶子；分支缺省展开，`expanded` 为 false 的第一次出现时先收起，之后随用户展开收起，选中它下面的行时照样展开；`selectable` 为 false 的行只作分组，点了只展开、收起；`movable` 为 false 的行自己不能挪（按住拖不起来，Alt + 方向键也挪不动），仍能当落点，区域、页、页眉页脚这类行就这样写；`deletable` 为 false 的行没有删除钮，Delete 不删它 |
| `selection` | 选中的行 id，受控、可以多个：在树上改选中只派发 `node-select`，等设计器换上新值。从外面换的（不是照着 `node-select` 写回的）把新选上的第一行滚进可见区，按住 Shift 点击也从新选上的最后一行连起 |
| `allowMove` | `(move) => boolean`，一次挪动许不许；不给就不能拖。`movable` 为 false 的行先被拦下，不问它 |
| `searchable` | 显示搜索框，按名字与副文本过滤；命中的行连同上级一起展开显示，过滤时不能拖 |
| `readonly` | 能选、能标出，不能删、不能挪 |
| `headless` | 放进外框的卡片时写：不画自己的标题，由面板头显示；标题仍给树命名 |

| 事件 | detail |
| --- | --- |
| `node-select` | `{ ids }` 用户在树上改了选中，`ids` 是整份新的选中，可能为空 |
| `node-highlight` | `{ id \| null }` 悬停或焦点所在的行变了，离开整棵树时为 `null`；同一行不重复派发 |
| `node-delete` | `{ ids }` 按了删除钮或 Delete / Backspace |
| `node-move` | `{ id, parent, index }` 拖动或 Alt + 方向键挪了一行，已经过 `allowMove` 判定；`parent` 为 `null` 即顶层，`index` 已按先摘后插修正 |

- 树用 [`<xh-tree>`](../components/tree)，键盘与读屏照它的约定：整棵树一个 Tab 位，上下键走行，右键展开、左键收起，Enter 与 Space 选中，连打检索；多选照文件管理器（树的 `selection-mode="extended"`）：点击换成这一行，按住 Ctrl（macOS 为 ⌘）点击或按 Ctrl / ⌘ + Space 加选与取消，按住 Shift 点击从锚点选一段，一段里夹着的分组行（`selectable` 为 false）不算；Alt + 上下键在同一层挪一位，Alt + 左右键改一层缩进，挪动的结果由树的播报区念出。分支缺省展开，展开状态按节点 id 保留；`selection` 换了新值时，被收起的上级跟着展开。
- 删除：Delete 或 Backspace 删焦点所在的一行；焦点在选中的行上时，删全部可删的选中项。行尾的删除钮只接指针，悬停或焦点在这一行时出现（粗指针设备常显），对读屏隐藏、不占 Tab 位，按下不夺焦点；可及名取 `translations.remove(名字)`。
- 换了 `nodes` 时整棵树重新铺，焦点原在树里的回到同一 id 的行上。
- 文案键 `xh-designer-outline`：`title`、`help`（面板头里的帮助）、`search`、`empty`、`noMatches`、`remove(label)`。

### 页面结构面板

各款不必自己接零件的事件：写一个适配器交给 `createOutlinePanel`，得到一块面板，放进内置扩展的 `panels`。

```ts
import { createOutlinePanel } from "@xihan-ui/designer-shell";
import { ListTreeIcon } from "@xihan-ui/icons";

const outline = createOutlinePanel<MyContext>({
  nodes: context => toOutlineNodes(context.designer.schema),
  selection: context => context.designer.getSelection(),
  select: (context, ids) => context.designer.select(ids),
  highlight: (context, id) => context.designer.highlight(id),
  remove: (context, ids) => context.designer.remove(ids),
  canMove: (context, move) => context.designer.canMoveTo(move),
  move: (context, move) => context.designer.moveTo(move),
}, { region: { icon: ListTreeIcon }, readonly: context => context.designer.readonly });

const builtin = { id: "my-designer", panels: [outline] };
```

| 适配器 | 说明 |
| --- | --- |
| `nodes(context)` | 整棵树，每次刷新都会再取；同一份文档要给出稳定的 id |
| `selection(context)` | 画布上当前选中的行 id |
| `select(context, ids)` | 换成这些行：`ids` 是整份新的选中，空数组为全部取消；新选上的行里至少把一个滚进画布的可见区（必要时切页、切页签、展开折叠项）。设计器的选择分种类、不能混选时，按新选上的那一行取舍 |
| `highlight(context, id)` | 在画布上标出这一行对应的东西，`null` 撤掉；不改选择、不滚动 |
| `remove(context, ids)` | 删除这些行，通常是先选中再走设计器自己的删除 |
| `canMove(context, move)`、`move(context, move)` | 一次挪动许不许、执行挪动（记为一步撤销）；两个要么都给，要么都不给，不给就不能挪 |

| 选项 | 说明 |
| --- | --- |
| `region` | 面板登记里要换的项，如 `position`、`icon`、`defaultHidden`；缺省区名 `outline`、停在左栏 |
| `searchable` | 显示搜索框，缺省 `true` |
| `readonly(context)` | 返回 `true` 时只读：能选、能标出，不能删、不能挪 |
| `translations()` | 这块面板自己的文案，压在零件文案之上：标题、帮助与零件里的搜索框、空状态都用它，没给的项照旧取零件文案；读的时候现取。同一页面放几款设计器时，各款经它换掉自己那块的说法，不改全局的那一桶 |

- 面板的标题与帮助取零件文案 `xh-designer-outline` 的 `title`、`help`（给了 `translations` 时它压在上面），读的时候按全局配置现取：设计器每次把区交给外框时跟着语言变。
- 每次 `update(context)` 重取树与选中的行，内容没变时不重设，树的展开与焦点不受影响；树上的事件转给适配器，用的是最近一次刷新的上下文。
- 同一行不重复调 `highlight`；面板撤掉时撤掉标出。
- 一个面板对象可以放进各款共用的内置扩展：每个设计器实例各建一份零件，互不相干。
- 适配器只给了 `canMove`、`move` 之一时，`createOutlinePanel` 抛 `TypeError`。

## 历史记录

`<xh-designer-history>` 按先后列出撤销栈里的每一步，标出当前位置；选一行就跳回那一步。零件只吃 designer-kit 历史的快照、吐事件，跳转与清空都由设计器调历史栈，零件不碰文档。

```ts
import { snapshotHistory } from "@xihan-ui/designer-kit";

const panel = document.createElement("xh-designer-history");
const refresh = () => (panel.snapshot = snapshotHistory(editor.history));
editor.history.subscribe(refresh); // 换语言时也调一次：说明按当时的语言取成字符串
panel.addEventListener("history-go", event => editor.history.goTo(event.detail.position));
panel.addEventListener("history-clear", () => runCommand(commands, "clear-history", context));
```

| 属性 | 说明 |
| --- | --- |
| `snapshot` | designer-kit 的 `snapshotHistory(history)`：`{ entries, position, origin, truncated, originSaved }`。历史变了、换了语言都重交一份 |
| `readonly` | 能浏览，不能跳转，清空钮禁用 |
| `headless` | 放进外框的卡片时写：不画自己的标题与清空钮，标题由面板头显示；标题仍给列表命名 |
| `announce` | `(message) => void`，读屏播报：从这里选一行、跳转完成后礼貌级地读一句「跳到哪一步、走了几步」；不给就不播 |

| 事件 | detail |
| --- | --- |
| `history-go` | `{ position }` 用户选了起点或某一步，`position` 是快照里的 `origin` 或那一步的 `position` |
| `history-clear` | `{}` 用户按了头部的清空钮；设计器转给 `clear-history` 命令，先确认再清空 |

- 第一行是起点：打开、重新载入或清空之后的状态，写「打开时」；起点之前有被步数上限丢掉的步骤时写「更早的步骤已丢弃」。其后按先后列出各步，最新的在最下面；没写说明的一步写「编辑」，已撤销的一步字色减淡、副文本写「已撤销」，保存点那一行副文本写「已保存」。
- 列表用 [`<xh-listbox>`](../components/listbox)，单选，选中的就是当前位置：整张列表一个 Tab 位，上下键与 Home、End 只移焦点、不跳转，Enter 与 Space 跳到焦点那一行，点一行同样跳。选中受控：选了一行只派发 `history-go`，列表仍选在当前位置，等设计器交来新快照。
- 头部的清空钮在列表之前占一个 Tab 位；没有步骤或只读时禁用。
- 快照换了时按位置号复用行，只改文字与状态，焦点所在的行不被换掉；当前位置变了就把它滚进可见区。
- 文案键 `xh-designer-history`：`title`、`help`（面板头里的帮助）、`origin`、`originTruncated`、`untitled`、`undone`、`saved`、`empty`、`clear`，清空确认框的 `clearConfirmTitle`、`clearConfirmContent`、`clearConfirmOk`，播报的 `announceUndo(label)`、`announceRedo(label)`、`announceJump(label, steps)`、`announceCleared`。

撤销、重做与清空历史三条命令由 `designerHistoryCommands` 统一给出，见下文「命令」。

### 历史记录面板

各款不必自己接零件：写一个适配器交给 `createHistoryPanel`，得到一块面板，放进内置扩展的 `panels`。

```ts
import { createHistoryPanel } from "@xihan-ui/designer-shell";
import { HistoryIcon } from "@xihan-ui/icons";

const history = createHistoryPanel<MyContext>({
  snapshot: context => context.designer.historyState,
  goTo: (context, position) => context.designer.goToHistory(position),
  announce: (context, message) => context.frame?.announce(message),
}, { region: { icon: HistoryIcon }, readonly: context => context.designer.readonly });

const builtin = { id: "my-designer", commands: [...designerHistoryCommands(options)], panels: [history] };
const host = createPanelHost(frame, { commands: context => commandTable });
```

| 适配器 | 说明 |
| --- | --- |
| `snapshot(context)` | 此刻的快照，说明已按此刻的语言取成字符串（`snapshotHistory`）；每次刷新都会再取 |
| `goTo(context, position)` | 跳到某一步或起点（快照里的位置号）；只读、预览这类不许改的状态由各款自己挡住 |
| `announce(context, message)` | 读屏播报，通常交给外框的 `announce`；不给就不播 |

| 选项 | 说明 |
| --- | --- |
| `region` | 面板登记里要换的项，如 `icon`、`position`、`defaultHidden`；缺省区名 `history`、停在右栏、缺省隐藏 |
| `readonly(context)` | 返回 `true` 时只读：只能看，不能跳 |

- 缺省隐藏，从「面板」菜单打开；登记在右栏的内置面板之后，打开后在属性下面。外壳不依赖图标包，图标由各款经 `region.icon` 给。
- 面板头是清空历史：面板登记了 `headerCommands: ["clear-history"]`，设计器的命令表里要有这条命令（`designerHistoryCommands`），`createPanelHost` 要给 `commands` 才铺得出来。零件是 headless 的，不画自己的清空钮。
- 面板的标题与帮助取零件文案 `xh-designer-history` 的 `title`、`help`，读的时候按全局配置现取：设计器每次把区交给外框时跟着语言变。
- 每次 `update(context)` 重取快照，内容没变时不重设；选一行转给适配器的 `goTo`，跳到以后零件经适配器的 `announce` 读一句。用的都是最近一次刷新的上下文。清空、保存这类不改文档的变化也要刷新面板。
- 一个面板对象可以放进各款共用的内置扩展：每个设计器实例各建一份零件，互不相干。

## 变换覆盖层

`<xh-designer-transform>` 叠在画布上方，画选中框、控制柄、旋转柄、对齐线、框选框、悬停框与尺寸徽标，并跑移动、缩放、旋转与框选的手势。命中判断归设计器：设计器在选中项上按下后调 `startMove`，在空白处按下后调 `startMarquee`；控制柄由覆盖层自己接。覆盖层盖满画布、左上角就是视口的屏幕原点，除控制柄外不挡指针。

```ts
const overlay = document.createElement("xh-designer-transform");
canvas.append(overlay);
overlay.viewport = viewport;
overlay.items = selection.map(node => ({ id: node.id, rect: node.rect, rotatable: false }));
overlay.getSnap = () => ({ targets: others.map(node => node.rect), lines: guides, grid: 8 });
canvas.addEventListener("pointerdown", (event) => {
  const hit = hitTest(clientToWorld(event), rects);
  if (hit >= 0)
    overlay.startMove(event);
  else
    overlay.startMarquee(event, { additive: event.shiftKey });
});
overlay.addEventListener("transform", (event) => {
  const { phase, rects, copy } = event.detail;
  if (phase === "end")
    commit(rects, copy);
});
```

| 属性 | 说明 |
| --- | --- |
| `viewport` | 画布的视口 |
| `items` | 选中项 `{ id, rect, handles?, rotatable?, keepAspect?, minSize? }`。`handles` 缺省 `true` 为八向，`false` 不能缩放，数组为只给这些方向；`rotatable` 缺省不显示旋转柄；`keepAspect` 为总是等比；`minSize` 是缩放的下限 |
| `hover` | 悬停框，世界坐标 |
| `getSnap(kind)` | 每次手势开始时取一次吸附选项，交给 `snapRect`；`threshold` 不给时取屏幕上的固定像素除以 `zoom` |
| `measure` | 尺寸徽标何时显示：`gesture`（缺省）只在拖动、缩放中只读显示；`selection` 选中即常驻，单选能缩放时可以直接改宽高，见下文「尺寸徽标」 |
| `measureOptions` | 徽标的单位、换算、精度与步长 `{ unit?, displayUnit?, convert?, unitLabel?, fractionDigits?, step?, largeStep? }`；不给不显示徽标 |
| `rotate-step` | 按住 Shift 旋转时吸附的角度，缺省 15 |
| `readonly` | 不画控制柄，`startMove` 不起作用，徽标只显示不能改；框选照常 |
| `translations` | 覆盖 `xh-designer-transform` 桶里的文案：`measure`（徽标这一组的名字）、`width`、`height`（两个数字框的名字）、`measureText(width, height, unit)`（只读显示的整句） |

| 方法 | 说明 |
| --- | --- |
| `startMove(event, { copy? })` | 越过激活距离后移动全部选中项 |
| `startMarquee(event, { additive? })` | 越过激活距离后开始框选 |
| `cancel()` | 取消进行中的手势，派发 `cancel` |
| `focusToolbar()` | 把焦点交给上下文工具条：先交给工具条里 roving 的当前条目，没有就交给第一个能聚焦的；工具条没显示时什么都不做。返回是否交了 |
| `focusMeasure()` | 把焦点交给尺寸徽标里第一个能改的数字框；徽标没显示数字框时什么都不做。返回是否交了 |

| 事件 | detail |
| --- | --- |
| `transform` | `{ phase, kind, rects, guides, copy? }`：`phase` 为 `start`、`move`、`end`、`cancel`，`kind` 为 `move`、`resize`、`rotate`，`rects` 是 id 到新矩形的表，`cancel` 时为开始时的矩形；`copy` 只在移动时有 |
| `marquee` | `{ phase, rect, mode, additive }`：`rect` 是世界坐标的选框，`mode` 自左向右拖为 `contain`、反向为 `intersect`，交给 `selectInMarquee` |
| `pan-request` | `{ dx, dy }`：拖到画布边缘时逐帧派发，含义与通用拖放相同 |
| `measure-change` | `{ id, rect, axis, source }`：用户在徽标里改了宽或高。`rect` 是改后的模型矩形，左上角不动；`axis` 为 `width` 或 `height`；`source` 为 `step`（加减钮、方向键）或 `input`（输入后确认）。设计器按自己的编辑命令改模型、记撤销，再更新 `items` |

- 修饰键：缩放时 Shift 等比、Alt 以中心为基准；旋转时 Shift 按 `rotate-step` 吸附；移动时 Shift 锁定水平或竖直、Alt 为复制。修饰键在拖动中按下也算。Esc 取消。
- 设计器在 `move` 阶段是只看预览还是执行事务自行决定；手势进行中覆盖层按自己算出的矩形画框，不等 `items` 更新。
- 单选按该项的能力出控制柄。多选画各自的细框与整体包围框，可以整体移动；每一项都能八向缩放时，包围框上出八个控制柄（不出旋转柄），拖动按包围框等比缩放全部选中项：位置与尺寸乘同一比例，旋转角不变，Alt 以中心为基准，任一项缩到 `minSize` 即停。`transform` 事件的 `kind` 为 `resize`，`rects` 带全部选中项。
- 缩放时只吸附被拖动的那条边；单选时旋转过的矩形缩放时不吸附。
- 控制柄是固定的屏幕尺寸，按旋转后的方向画，指针形状随角度换；粗指针设备放大命中区。
- 画的框、线、控制柄与只读显示的徽标都是 `aria-hidden`；上下文工具条与带数字框的徽标不是。

### 上下文工具条

写 `slot="toolbar"` 的子节点是选中时浮在选中框上的一条工具条，内容由各款放，通常是一条横排的命令工具栏：各款按当前选中算出主体（如 `element`、`text`、`node`、`multiple`），用 `arrangeCommands("selection:<主体>", …)` 排出分组，宿主经 `commandLayout` 改排列，扩展登记命令时在 `placement` 里写 `selection:<主体>` 就会出现在这里。

- 位置：在选中框（多选时是整体包围框）上方居中，有旋转柄时让开它；上方放不下时翻到下方，尺寸徽标显示着就排在徽标下面；左右夹在覆盖层里。落在哪一侧写在工具条部件的 `data-placement` 上（`top` 或 `bottom`）。
- 宽度：最宽到覆盖层的宽减去两侧间距。里面放的是带「更多」的命令工具栏时，画布窄得放不下，多的钮收进「更多」，工具条不伸出画布；画布或工具条的大小变了随即重排。
- 显示：有选中才显示；只读、手势进行中（移动、缩放、旋转、框选）或没有内容时收起，松手后再出现。工具条跟着画布裁剪，不进浮层。
- 外观：实体底、描边与一层柔和投影，接指针。
- 键盘：各款在画布的 keydown 里认 Alt+F10，调 `focusToolbar()` 把焦点交过去；在工具条里按 Esc，焦点回到交之前的位置。

```ts
const format = document.createElement("xh-toolbar");
format.slot = "toolbar";
overlay.append(format);
canvas.addEventListener("keydown", (event) => {
  if (event.altKey && event.key === "F10" && overlay.focusToolbar())
    event.preventDefault();
});
```

### 尺寸徽标

给了 `measureOptions` 时，选中框（多选时是整体包围框）底边下方居中有一块尺寸徽标，与上下文工具条一样左右夹在覆盖层里，元素贴着画布边缘时也不被裁掉：

- `measure` 为 `gesture`（缺省）：只在拖动、缩放中显示实时尺寸，只读。
- `measure` 为 `selection`：选中即常驻。单选、不是只读、这一项能缩放时，宽、高各一个数字框（库内 `<xh-number-field>`，带加减钮），整块接指针；多选时写整体包围框的尺寸，`handles: false` 的项与只读时写元素自己的宽高，都只读。拖动、缩放中只读显示实时尺寸，松手回到数字框。只给了某些方向的控制柄时，只有能缩放的那一边可以改。
- 单位：`unit` 是模型坐标的长度单位，`displayUnit`（缺省同 `unit`）是显示单位，数值按 designer-kit 的 `convertLength` 换算、`formatLength` 按 locale 写出，最多 `fractionDigits`（缺省 1）位小数；单位文字缺省取显示单位的符号。不是长度的设计器不给 `unit`，徽标直接显示模型数值，单位文字写在 `unitLabel` 里。单选写元素自己的宽高，不是旋转后的外接框。
- 逐轴换算：模型坐标与显示值不是同一种长度、两轴换算还不一样时（如按格计的看板，模型是画布像素，显示格数，列距与行距不同、还要扣掉间隙），给 `convert: { toDisplay(value, axis), toModel(value, axis) }`。给了它，数值只按它换算，`unit`、`displayUnit` 只用来取缺省的单位文字；显示、步进、取整与 `minSize` 的下限都在显示值上算，交出的 `rect` 按 `toModel` 换回模型。不给时照旧按 `unit`、`displayUnit` 换算。
- 单位文字随语言：`unitLabel` 由设计器按自己的语言包给（如「格」「cells」），换了语言重交一份 `measureOptions`，徽标跟着刷新；外壳不写死任何单位文字。
- 改值：加减钮、上下方向键按 `step`（缺省 1），Shift 加上下方向键与 PageUp / PageDown 按 `largeStep`（缺省 10），马上派发 `measure-change`；输入数字后按 Enter 或离开数字框才派发，输入途中不派发，Esc 放弃输入。新值按精度取整、不小于 `minSize`；`keepAspect` 的项改一边，另一边按比例跟着变；值没变不派发。覆盖层不改 `items`，由设计器改完模型后更新。
- 键盘与指针：工具条在徽标之前，Alt+F10 交给工具条后，在工具条里按 Tab 接着进到徽标的数字框；没有工具条时各款可以让 Alt+F10 改调 `focusMeasure()`。在徽标里按 Esc，焦点回到交之前的位置。徽标里的按键与按下不冒泡到画布，打字时的 Delete 不会删掉元素。
- 外观：带数字框时与上下文工具条同一种实体面，数字框按内容定宽；只读显示时是一枚品牌色的小标签。

```ts
overlay.measure = "selection";
overlay.measureOptions = { unit: "mm", fractionDigits: 1, step: 1, largeStep: 10 };
overlay.addEventListener("measure-change", (event) => {
  const { id, rect } = event.detail;
  resize(id, rect);
});
```

按格计的看板：模型是画布像素，列距、行距各含一道间隙。

```ts
const pitch = { width: metrics.column, height: metrics.row };
const gap = { width: metrics.columnGap, height: metrics.rowGap };
overlay.measureOptions = {
  convert: {
    toDisplay: (value, axis) => (value + gap[axis]) / pitch[axis],
    toModel: (value, axis) => value * pitch[axis] - gap[axis],
  },
  unitLabel: t.cells, // 设计器自己的文案，换语言时重交
  fractionDigits: 0,
};
```

## 标尺与参考线

`<xh-designer-ruler>` 包住画布：上、左两条标尺，左上角角块，中间是作者内容，画布上方一层参考线。不带 `slot` 的子节点进画布区，`slot="corner"` 的进角块。画布区左上角就是视口的屏幕原点，覆盖层等放在画布区里即可对齐。画布区是只有一格的网格：子节点不写尺寸也撑满整块，多个子节点叠在同一块上。标尺的样式只认标尺自己生成的部件，画布区与角块里的作者内容即使也用了 `data-part="tick"`、`"marker"`、`"guide"` 之类的部件名，也不受标尺样式影响。

```ts
const ruler = document.createElement("xh-designer-ruler");
ruler.append(canvasContent);
ruler.viewport = viewport;
ruler.unitSize = 1;
ruler.guides = page.guides;
ruler.snap = (axis, value) => snapToGrid(value, 1);
ruler.addEventListener("guides-change", event => setGuides(event.detail.guides));
```

| 属性 | 说明 |
| --- | --- |
| `viewport` | 画布的视口 |
| `unit-size` | 一个刻度单位等于多少世界单位，只管刻度显示，缺省 1 |
| `guides` | `{ x, y }`：竖向（x 等于定值）与横向参考线的位置，世界单位；受控，零件不自己改 |
| `highlight` | 在两条标尺上画淡底的范围，世界坐标，如选中项的包围框 |
| `format(value)` | 刻度与参考线数值的文字，入参是刻度单位；缺省按主刻度间隔取整数或所需的小数位 |
| `snap(axis, value)` | 拖动参考线时的吸附，入参与返回值都是世界单位 |
| `readonly` | 照常显示参考线，不能新建、挪动或删除 |

| 事件 | detail |
| --- | --- |
| `guides-change` | `{ guides, change }`：`guides` 是改后的整组参考线，`change` 为 `{ type, axis, index }`，`type` 为 `add`、`move`、`remove`，新增的 `index` 在末尾 |

- 从上标尺拖进画布新建横向参考线，从左标尺拖出竖向参考线；松手时还在标尺上即取消。
- 拖动已有参考线挪动，拖回对应的标尺即删除，拖到别处不变；拖动中显示预览线与数值。
- 点参考线选中并取得焦点，Delete 或 Backspace 删除；Esc 放弃进行中的拖动。
- 指针在标尺或画布上时，两条标尺上画跟随的细线；参考线在对应标尺上另画一道标记。
- 参考线是带名称的 `separator`，名称取文案 `horizontalGuide` / `verticalGuide`。

## 外框

`<xh-designer-frame>` 是设计器的整体版式：最上一条菜单栏，下面一条工具栏，中间一行左、中、右三栏，中间一栏的下方再分一栏，最下一条状态栏。版式按命名区排，缺省登记菜单栏 `menubar`、工具栏 `toolbar`、物料 `palette`、画布 `canvas`、属性 `properties`、问题 `issues`、状态栏 `status` 七个区。作者内容用 `slot="<区名>"` 标在直接子节点上，没写 `slot` 的进中间区。

左、右、下三栏里的区是面板：停在哪一栏、先后、显隐、收成标题条、浮出成小窗，都记在一份布局 `layout` 里。外框改了布局就换成改完的整份，并派发 `layout-change`；设计器把它存进设置的 `layout.panels`。栏与栏、同一栏的面板之间是 `<xh-splitter>` 的分隔条，可以拖动或用键盘调整大小。

```ts
import { DESIGNER_SETTING_KEYS } from "@xihan-ui/designer-shell";

const frame = document.createElement("xh-designer-frame");
frame.append(toolbar, palette, canvas, properties, issues); // 各自写好 slot="toolbar" 等
frame.layout = settings[DESIGNER_SETTING_KEYS.layout]; // 上次存下的布局，没有就用缺省布局
frame.addEventListener("layout-change", event => save(DESIGNER_SETTING_KEYS.layout, event.detail.layout));
```

| 属性 | 说明 |
| --- | --- |
| `regions` | 产品登记的命名区，缺省为 `DESIGNER_FRAME_REGIONS` |
| `layout` | 面板布局 `DesignerLayout`，见下文「面板布局」；不给即缺省布局 |
| `defaultLayout` | 宿主的缺省布局：用户没存过布局时用它，「恢复默认布局」也回到它；写了的字段整项覆盖内置缺省 |
| `layoutPolicy` | 宿主对布局的管控 `{ locked?, panels? }`，通常由 `designerLayoutPolicy(settingsPolicy)` 换算得来 |
| `resolvedLayout` | 只读：此刻的整份布局，每个字段都在 |
| `narrow` | 只读：视口窄于断点、左右两栏收进抽屉时为 `true`，见下文「窄屏」 |
| `openDrawer` | 窄屏时开着的那侧抽屉（`start` 或 `end`），都收着时为 `undefined`；赋值开、关抽屉，不是窄屏时读出 `undefined`、赋值不起作用 |
| `canvasTool` | 画布上此刻的工具：`select`（缺省，点选与框选）或 `pan`（拖动：按住拖动平移画布）。拖动时画布区标上 `data-canvas-tool="pan"`、显示手形光标；外框里按 Esc（里面的元件没接走）退回 `select`；换了就派发 `canvas-tool-change`。怎么平移由各款在自己的画布上接，见下文「拖动工具」 |

| 方法 | 说明 |
| --- | --- |
| `showsPanel(name)` | 这个区是否显示：中间区与工具栏总是显示，菜单栏与状态栏看有没有内容，面板与画布浮动件看布局（浮出的也算），没登记的区为否 |
| `panelEntries()` | 面板菜单的数据：能停靠的面板与画布浮动件，按登记顺序，`closable: false` 的不列。每项 `{ name, label, icon?, shown, dock?, minimized, floating, locked, movable, floatable, minimizable }`（后三项是此刻能不能换栏、浮出、收起，算上了管控）；`label` 依次取 `title`、`label`、`name`，`shown` 是它此刻看得见：没隐藏，所在栏没在分隔条上收起，窄屏时左右两栏的面板还要它所在的抽屉开着 |
| `togglePanel(name)` | 开关一块面板：显示着就隐藏、隐藏着就显示。所在栏在分隔条上收起着时是把那一栏放回收起前的大小；窄屏时左右两栏的面板是开关它所在那一侧的抽屉 |
| `setPanelVisible(name, visible)` | 显示或隐藏一块面板 |
| `movePanel(name, dock, index?)` | 停到某一栏的第 `index` 位（按布局里那一栏的先后算，含隐藏的；缺省末尾），浮着的一并吸回 |
| `setPanelMinimized(name, minimized)` | 收成标题条或展开 |
| `floatPanel(name, rect?)` | 浮出成小窗；`rect` 是相对外框左上角的像素位置与大小，不给时按卡片此刻的大小（不小于 280 × 240，不超过外框的八成）放在中间一行的中央 |
| `dockPanel(name)` | 把小窗吸回原来的栏与位置 |
| `revealPanel(name)` | 把显示着的面板亮出来：收在窄屏抽屉里的打开抽屉，所在栏在分隔条上收起的放回，收成标题条的展开；面板隐藏着时返回 `false`。引导与问题定位用 |
| `toggleAllPanels()` | 有面板显示着就全部隐藏，否则放回全部隐藏前的那一组；不动菜单栏、工具栏与状态栏 |
| `restorePanels()` | 各面板的显隐回到缺省，位置与大小不动 |
| `resetLayout()` | 整份布局回到缺省：显隐、停靠、先后、大小、收起、浮出一起复原 |
| `announce(message)` | 礼貌级地读一句，经 core 的页面级播报器（[`announce`](../guide/behavior#页面级播报)）；外框自己在挪动、浮出、停靠、收起与隐藏之后各读一句 |

宿主锁定了整份布局或某块面板时，改那块面板的方法什么都不做。

| 事件 | detail |
| --- | --- |
| `canvas-tool-change` | `{ tool }`：画布上的工具换了（写 `canvasTool`、`pan-tool` 命令或按 Esc 退出拖动）。设计器收到时重画工具栏，让「拖动」钮的按下状态跟上 |
| `layout-change` | `{ layout, reason }`：布局变了，`layout` 是改完的整份（`ResolvedDesignerLayout`，可以直接存）。`reason` 取 `toggle`、`move`、`minimize`、`float`、`dock`、`resize`、`reset`。指针拖分隔条只在松手时派发，方向键调的、在分隔条上收起或放回的当场派发；拖小窗的标题栏挪动在松手时派发，用键盘挪动与改尺停 300 毫秒后派发。调方法改布局时先按新布局排好再派发：新的分隔条在随后的微任务里接好线，在这个事件里排下的更新量到的就是排好以后的大小。重排前后焦点留在原来持有它的元素上 |

命名区就是面板的登记，是 `{ name, position, size?, minSize?, label?, title?, subtitle?, help?, icon?, anchor?, defaultHidden?, closable?, movable?, floatable?, minimizable? }`：

- `position` 取 `menubar`、`top`、`start`、`center`、`end`、`bottom`、`status`、`overlay`。`start`、`end`、`bottom` 上的区是面板，这里写的是它缺省停的栏；同一栏的多块面板按登记顺序上下排列，共用一栏的大小，之间有分隔条，可拖动，也可聚焦后用上下方向键调整（Shift 加大步长）。`overlay` 是画布浮动件，见下文「画布区的浮动条」。
- `size` 是那一栏的缺省大小：左右两栏占中间一行的宽度，下栏占中间一栏的高度；`minSize` 是拖动的下限，缺省 10。都取那一栏第一块面板的值。中间区至少留 20。外框还按尺寸槽给的像素下限折算，两者取大的，见下文「尺寸槽」。
- `label` 是一栏里两块面板之间那条分隔条名称里的区名，缺省用 `title`，再缺省用 `name`，名称取文案 `resize`；左右两栏与画布之间、下栏与画布之间的分隔条按栏命名，取文案 `resizeLeft`、`resizeRight`、`resizeBottom`（左右按看到的方向，从右往左书写时开头那一栏在右边）；分隔条所在的布局取文案 `layout`。
- `icon` 是面板菜单与浮出小窗标题栏里的图标。`defaultHidden` 的面板缺省不显示。`closable`、`movable`、`floatable`、`minimizable` 缺省都是 `true`，写 `false` 就不出对应的钮与菜单项；没给 `title` 的区没有面板头，只能显示或隐藏。
- 隐藏的面板移出文档，内容保留，再显示时原样放回。
- 区的结构变了（比如换了一份不带标题的区表，卡片变回普通区）时，已经搬进去的作者内容跟着挪到新结构里；新结构里没有对应位置的（面板头操作区里的内容），收进外框里一个不显示的停放处（`data-part="parked"`），等结构里再有这个位置时自动放回。从 `regions` 里去掉的区（如关掉状态栏、切到预览时不登记的区），里面的作者内容同样收进停放处，不论内容自己的 `display` 怎么写都不显示，区再登记时放回。带 `slot` 而外框没有对应位置的作者内容也收在那里。
- 外框自己生成的结构（上方条、中间行、栏、分隔条、区容器、小窗与落点层）都带 `data-scope="designer-frame"`，区容器另带 `data-region`（区名）与 `data-position`（所在的栏或位置，浮出的写 `float`）。外框的样式只认这个 scope，区里的作者内容即使也用了 `data-part="region"` 之类的部件名，也不受外框样式影响。

### 面板布局

`DesignerLayout` 是一份 JSON，除 `version` 外都可以不写：

| 字段 | 说明 |
| --- | --- |
| `version` | 恒为 `1`（`DESIGNER_LAYOUT_VERSION`）；读到别的版本按缺省布局 |
| `docks` | `{ start?, end?, bottom? }`：三栏里各面板 id 的先后。浮出的面板也留在原来的栏里，记着吸回去的位置；没列到的面板按缺省位置排在那一栏的后面 |
| `hidden` | 隐藏的面板与画布浮动件 |
| `minimized` | 收成标题条的面板 |
| `floating` | 面板 id → `{ x, y, width, height }`：浮出的小窗相对外框左上角的像素位置与大小 |
| `sizes` | `{ start?, end?, bottom?, panels? }`：三栏的大小（百分比），以及同一栏里各面板分到的份额（百分比，键为面板 id） |
| `collapsed` | 在分隔条上收起的栏 |

- 写了的字段整项覆盖缺省布局，没写的取缺省：缺省布局是宿主的 `defaultLayout`，再缺省是各面板按登记顺序停在 `position` 那一栏、`defaultHidden` 的隐藏。
- 认不得的面板 id、不合法的值去掉，不报错：存下的布局里可能有已经卸掉的扩展面板。不能挪的面板只认它缺省的那一栏。登记了却没出现在布局里的面板（后装的扩展）按缺省位置放。
- 同一栏当前显示的面板按 `sizes.panels` 的比例分高度，合计不必是 100，外框按比例归一；没有记录的面板按等分值（100 ÷ 面板数）补上，都没有记录时即等分。每块至少占 10%（面板多到放不下时取等分），归一后低于下限的定在下限，其余按比例分剩下的。隐藏其中一块时，其余按各自的比例分掉它的高度；记录仍在，再显示时恢复。
- 外框派发的 `layout` 总是整份、只含登记着的面板，同一份布局派发出去又赋回来不会重排。

宿主的管控：

| `layoutPolicy` | 效果 |
| --- | --- |
| `{ locked: true }` | 整份布局只读：面板头不出收起、更多与关闭钮，不能拖，面板菜单里的面板不可点，改布局的方法什么都不做 |
| `{ panels: { <id>: "hidden" } }` | 这块面板不存在：不显示、不进面板菜单，布局里写了也不认 |
| `{ panels: { <id>: "locked" } }` | 这块面板固定：不能隐藏、挪动、浮出、收起，别的面板照常 |

`designerLayoutPolicy(settingsPolicy)` 从设置的管控换算：`layout.panels`（或整个 `layout` 分区）被藏或锁时整份锁定，`layout.panels.<面板 id>` 管一块面板。

布局的纯函数不碰 DOM，设计器或宿主改布局、读布局时可以直接用：

| 函数 | 说明 |
| --- | --- |
| `resolveDesignerLayout(regions, layout?, defaults?, policy?)` | 合成此刻的整份布局 |
| `defaultDesignerLayout(regions, defaults?, policy?)` | 缺省布局 |
| `designerLayoutEquals(a, b)` | 两份布局是不是同一份 |
| `designerPanelAbilities(region, policy?)` | 一块面板此刻能做的事：`{ closable, movable, floatable, minimizable }` |
| `designerPanelDock(layout, id)` | 面板停在哪一栏 |
| `withDesignerPanelVisible`、`withDesignerPanelMoved`、`withDesignerPanelMinimized`、`withDesignerPanelFloating`、`withDesignerDockSize`、`withDesignerPanelShares` | 几种改法，返回新的一份 |

### 菜单栏

菜单栏是最上整宽的一条，在工具栏上面，不可拖动，不是面板，按段放内容：

| 区 | 段与插槽 | 只写区名时进 |
| --- | --- | --- |
| `menubar` | `menubar-start`（菜单栏本身，`createCommandMenubar` 建的那一条）、`menubar-center`（宿主的标题，如模板名称与编码）、`menubar-end`（宿主的其他内容） | `menubar-start` |

- 各段有内容才显示这一条，内容拿走就收起。菜单栏常开，设置里没有关掉它的开关；宿主没有菜单栏时不登记 `menubar` 区，里面的内容收进停放处不显示，再登记时放回。
- 行首一段按内容宽；行尾一段按内容宽、贴右，放不下时先收窄，里面的作者内容自己截断（如写 `text-overflow: ellipsis`）；行尾一段的文字取弱一档的颜色。
- 正中一段按整条菜单栏的宽度居中，不随两边内容的宽窄偏。行首、行尾两段的内容各挡住一边，外框取离中线近的那一边，定出以中线对称的空当：内容放得下照原宽；放不下截到空当的宽，里面的作者内容（这一段的直接子元素）截断加省略号；空当窄过几个字宽就整段藏起，变宽了再出来。窄屏菜单栏收成「菜单」钮时照同一个规矩，不压那颗钮。文字取正常字色、小一号。
- 键盘：设计器里有焦点时按 F10（不带修饰键），焦点交给菜单栏里第一个看得见、能用 Tab 走到的元素（宽屏是菜单栏，窄屏是那颗「菜单」钮）；再按 F10，或在菜单栏里按 Esc（菜单收着时），回到按 F10 之前持有焦点的地方。用 Tab 走进菜单栏的，Esc 不带回去。Shift+F10 仍是右键菜单，Alt+F10 仍是选中工具条。外框在自己身上接这个键，各款不用另接；里面的元件已经接走（`preventDefault`）的 F10 与 Esc 外框不管。
- 外框由设计器自己建在设计器元素里，宿主够不着它的段：设计器用 `forwardFrameSlots(设计器元素, 外框, ["menubar-center", "menubar-end", "status-end"])` 把宿主写在设计器元素上、`slot` 在名单里的子元素搬进外框，后来加的跟着搬，宿主就能往菜单栏正中放模板标题、往状态栏右端放保存状态。名单里只写要转交的段，别的子元素不动；转过去的内容在同一段里排在设计器自己放的内容前面（状态栏右端的缩放比例这类各款自己的状态项留在最右）。返回停止转交的函数，已经搬过去的不搬回来。
- 菜单栏本身怎么从命令表铺，见下文「扩展的面板与命令」的「菜单栏」。

### 状态栏

状态栏是最下整宽的一条，不可拖动，不是面板，按段放内容：

| 区 | 段与插槽 | 只写区名时进 |
| --- | --- | --- |
| `status` | `status-start`（选中对象的信息）、`status-end`（缩放、保存与连接状态；宿主经设计器转来的排在设计器自己的前面） | `status-start` |

- 各段有内容才显示这一条，内容拿走就收起。不要状态栏（比如设置里关掉了）时从 `regions` 里去掉 `status` 区，里面的状态项收进停放处不显示，再登记时放回。
- 段用 `data-part="zone"` 与 `data-zone` 标出，左段贴左、右段贴右；状态栏的文字取弱一档的颜色与小一号的字。放不下时左段先收窄、截掉多出来的，右段按内容宽整段留着；同一段里相邻两样之间一道细分隔，宿主直接写的文字也一样。
- 状态栏上的每一项用 `createStatusItem` 建，标签、值与分隔四款一致：

  ```ts
  import { createStatusItem } from "@xihan-ui/designer-shell";

  const selection = createStatusItem(document, { label: "已选", value: "2 个节点" });
  const zoom = createStatusItem(document, { label: "缩放", value: "80%", action: () => designer.zoomToActual() });
  selection.element.slot = "status-start";
  zoom.element.slot = "status-end";
  frame.append(selection.element, zoom.element);
  zoom.update({ label: "缩放", value: "100%" });
  ```

  | 选项 | 说明 |
  | --- | --- |
  | `label` | 标签，取弱一档的颜色显示在值前面；不给只显示值 |
  | `value` | 值 |
  | `tone` | 值的语气，如保存失败写 `danger` |
  | `action` | 给了这一项就是一颗 ghost 小按钮（`<xh-button>`），点了调用它；建好之后不能再改成纯文字或反过来 |

  返回 `{ element, update(state) }`，`update` 换标签、值与语气。同一段里相邻两项之间一道细分隔。

### 面板卡片

三栏里的区给了 `title` 就画成一张卡片：承载面的底、描边与圆角，四周留出间距，上面是面板头，下面是可以滚动的正文，作者内容放进正文。

- 面板头左边是标题与一行副标题（`subtitle`，不给不显示）；右边依次是操作区、帮助钮、收起钮、「更多」钮与关闭钮。标题至少留四个字宽（`--xh-designer-frame-title-min`），窄了先让操作区：面板头命令条放不下的钮收进「更多」菜单，排在布局条目的前面，点了照点钮那样执行。
- 操作区放 `slot="<区名>-actions"` 的作者内容，没有内容时收起。扩展的面板给 `headerCommands` 时，面板宿主在这里铺一小条命令，见下文「扩展的面板与命令」。操作区里有不会自己收起的内容（命令条以外的，如问题列表挪进来的严重程度开关 `summary`），和标题、面板头的钮挤一行放不下时，操作区排到面板头末尾、另起一行占满，键盘顺序跟着在钮后面；放得下了回到标题后面。
- `help` 给了才出帮助钮，悬停或聚焦时用 `<xh-tooltip>` 弹出这段说明，按钮的名字取文案 `panelHelp`。
- 收起钮把面板收成标题条：只剩面板头，留在原位、照旧占满这一栏的宽度，同一栏的其余面板分剩下的高度；一栏全收起时几条面板头贴着栏顶，下栏全收起时下栏只剩面板头那么高。再点展开。双击面板头也是收起与展开。名字取文案 `minimizePanel` / `expandPanel`，带 `aria-expanded`。
- 「更多」钮打开一张 `<xh-menu>`，按此刻的布局列出能做的事：移到左栏、右栏、下栏，上移、下移，浮出或停靠，收成标题条或展开，隐藏。键盘与读屏挪面板靠它。从右往左写时左右两栏对调叫法。选了一项菜单就收起，焦点回到这块面板的「更多」钮（面板挪到别的栏也一样）；窄屏抽屉里的菜单先收起，再动布局。
- 关闭钮隐藏这块面板，名字取文案 `closePanel`。
- 卡片是 `role="region"`，以标题为名。区后来加了或去掉标题，外框连同已经搬进去的内容一起换成新的结构。
- 物料、属性、问题三个零件放进卡片时写 `headless`：不画自己的标题，由面板头显示。

### 拖动面板与浮出

- 按住面板头（不在按钮与操作区上）拖动，越过激活距离才开始，跟手的是面板头的副本。外框盖上一层落点层：左、右、下三条停靠条，栏空着也能停；拖进一栏两块面板之间画一条插入线；拖到画布上画出浮出的落位框。松手在停靠条上停到那一栏末尾，在插入线处插在那里，在画布上就地浮出；停回原处不算。Esc 取消。窄屏不拖。
- 浮出的面板放进一个 `<xh-floating-panel>` 小窗：标题栏是图标、标题与拖动把手，加停靠、收拢与关闭三颗钮，八个边角可以改尺。卡片的标题、收起、更多与关闭由小窗的标题栏代替，帮助钮也挪到小窗的标题栏上，面板头只留副标题与操作区，两样都没有就整条收起。小窗里卡片的正文按小窗的高度滚动。
- 小窗限在外框里：挪出去、改得比外框大时夹回框内；外框变小、页面滚动时跟着外框重新落位。位置按外框左上角记，`floating` 里存的就是这个。
- 拖着小窗的标题栏时外框同样盖上落点层：松在停靠条上停到那一栏末尾，松在一栏两块面板之间插在那里，小窗随之收起；松在别处就是挪动，松手时派发。停靠钮把小窗吸回浮出前的栏与位置；收拢就是小窗的收拢形态，记在 `minimized` 里；关闭是隐藏这块面板，再显示时仍是小窗。

### 画布区的浮动条

中间区的四角与右侧中间各有一个落点，放浮动在画布内容之上的小工具条或小地图：

| 插槽 | 落点 |
| --- | --- |
| `<中间区名>-top-start` / `-top-end` | 左上、右上 |
| `<中间区名>-bottom-start` / `-bottom-end` | 左下、右下 |
| `<中间区名>-end` | 右侧中间，竖排 |

缺省中间区名是 `canvas`，所以插槽是 `canvas-top-start` 等。落点没有内容时不占位置。右侧中间的竖条不超出中间区，里面放竖排的命令工具栏（`createCommandToolbar(document, { orientation: "vertical" })`）时，画布矮了放不下的条目按高度收进「更多」。

要能在面板菜单里开关的浮动件（小地图、翻页条）登记成画布浮动件：`{ name: "minimap", position: "overlay", anchor: "bottom-end", label: "小地图" }`，内容写 `slot="minimap"`。外框把它放进 `anchor` 那个落点（缺省 `bottom-end`），排在作者在同一落点写的内容后面；它跟着布局的 `hidden` 显示或隐藏，进面板菜单，不能挪、浮出或收起。

### 尺寸槽

外框上的几个 CSS 自定义属性，缺省取 UI 的语义令牌：

| 尺寸槽 | 缺省 | 作用 |
| --- | --- | --- |
| `--xh-designer-frame-start-min` | `--xh-layout-col-min-sm` | 左栏拖动的下限 |
| `--xh-designer-frame-end-min` | `--xh-layout-col-min-md` | 右栏拖动的下限 |
| `--xh-designer-frame-bottom-min` | `--xh-layout-col-min-xs` | 下栏拖动的下限 |
| `--xh-designer-frame-gap` | `--xh-space-2` | 卡片与四周、画布浮动条与边缘的间距 |
| `--xh-designer-frame-panel-px` / `-py` | `--xh-space-3` / `--xh-space-2` | 面板头与状态栏的内边距 |
| `--xh-designer-frame-status-h` | `--xh-control-h-sm` | 状态栏的最小高度 |

- 三个下限是像素宽度，外框量出后按自己当前的宽高折成百分比交给分隔条，外框变宽变窄时重新折算。收成标题条的面板同样按量出的面板头高度折算。
- 三栏在分隔条上可以收起：双击分隔条，或聚焦后按 Enter，收起它旁边那一栏，再来一次按收起前的大小放回；左边那条管左栏，右边那条管右栏，中间一栏下方那条管下栏。
- 收着期间外框重排（换了显示的面板、外框变宽变窄、窄屏来回）后仍收着，再双击或按 Enter 照样放回收起前的大小，焦点留在那条分隔条上。布局的 `sizes` 记的是收起前的大小，不记 0，收起的栏记在 `collapsed` 里。

### 拖动工具

工具栏与「视图」菜单里的「拖动」（内置命令 `pan-tool`，快捷键 `H`）把外框的 `canvasTool` 切成 `pan`，再按一次或按 Esc 退回 `select`。外框只管模式、光标与 Esc，平移由各款在自己的画布上接：

- 拖动开着时，在画布任意处（节点、元素上也一样）按住拖动都是平移画布，不选中、不挪对象；只点一下什么都不改。
- 画布区的光标是手形（`grab`）；画布里自己设了光标的内容（节点、控制柄）按 `[data-canvas-tool="pan"]` 改回手形，拖动中换成握拳（`grabbing`）。
- 滚轮、缩放与键盘照旧；画布浮动件（小地图、翻页条）照旧能点。
- 收到 `canvas-tool-change` 时重画工具栏，「拖动」钮的按下状态跟着变。

### 窄屏

视口窄于断点令牌 `--xh-breakpoint-md` 时外框进窄屏，外框上写 `data-narrow`，`narrow` 为 `true`：

- 中间一栏占满整行，下栏照旧在中间一栏下面；左右两栏收进从两边滑出的 `<xh-drawer>`，缺省收着。抽屉在外框里面（`contained`）、非模态，压在画布上，不挤窄画布。
- 「面板」命令与 `togglePanel` 开关抽屉，同时只开一侧，开另一侧时这一侧收起，不改布局；隐藏着的面板开抽屉时先显示并派发一次 `layout-change`。
- 面板头的关闭钮与 Esc 只收起抽屉，布局不变。抽屉以它里面各面板的标题为名，从右往左写时两侧对调。
- 浮出的面板窄屏时按停靠显示在原来那一栏的抽屉里，不改存下的布局，回到宽屏再浮出来。窄屏不能拖动面板，「更多」菜单里不出换栏与浮出。
- 菜单栏（`createCommandMenubar` 建的）收成行首一颗「菜单」钮，点开一张 `<xh-menu>`，每张菜单是它的一个子菜单。焦点在菜单栏里时宽窄一换，焦点落到此刻看得见的入口上（变窄落到「菜单」钮，变宽落到菜单栏）。
- 视口变宽回到三栏，抽屉收起；再变窄时两侧都收着。
- 没有 `matchMedia` 或断点令牌缺席时不进窄屏。

## 设置

设计器的设置是用户偏好，每人每机一份，不是模板数据：主题、主题色与状态栏，语言，工具栏的显示方式与按钮，面板布局，再加各款与扩展自己的条目。`<xh-designer-settings>` 是设置对话框；`createDesignerSettingsHost` 把主题、主题色与语言落到设计器上，并读写存储。主题色与语言清单都是内置的，宿主不传。

```ts
import { collectSettingsSections, createDesignerSettingsHost } from "@xihan-ui/designer-shell";
import { loadDesignerLocale } from "@xihan-ui/designer-shell/language";
import { mergeXhConfig } from "@xihan-ui/web-components";

const host = createDesignerSettingsHost({
  root: designerRoot,
  // 选了语言时：UI 与 designer-shell 的同语言包，再并上本款自己的
  locale: async language => mergeXhConfig(await loadDesignerLocale(language), productLocales[language]),
  onLocaleChange: () => designerRoot.requestUpdate(),
  storageKey: "flow-designer:settings",
  onStorageError: detail => console.warn(detail),
});
// 设计器根把 host.localeConfig 作为自己的 xhConfig 交出去：get xhConfig() { return host.localeConfig }

const dialog = document.createElement("xh-designer-settings");
dialog.sections = collectSettingsSections([productSettings, ...extensions]);
dialog.settings = host.load();
host.apply(dialog.settings);
dialog.addEventListener("settings-change", (event) => {
  host.apply(event.detail.settings);
  host.save(event.detail.settings, dialog.sections);
});
designerRoot.append(dialog);
dialog.show();
```

### 分区与条目

- 分区是 `{ id, label, order?, items }`，对话框左边一页。`order` 小的在前，内建的「基础」是 0、「语言」是 1、「布局」是 2、「工具栏」是 3，各款从 100 起，扩展从 200 起，900 以后留给内建的「帮助」「快捷键」「关于」，同值按登记顺序。
- 条目就是 `@xihan-ui/designer-kit` 的属性描述：`path` 只写一段条目 id，`label` 是标签，`default` 是缺省值，说明写在 `meta.description`。
- 值是扁平的键值：键是 `<分区 id>.<条目 id>`，没写的键取条目的 `default`。
- 内建编辑方式与属性面板同一套字段；别的种类交给对话框的 `editors`，被编辑的对象是整份设置。
- 条目的 `enabledWhen`（designer-kit 属性描述的可用条件）按此刻生效的整份设置求值，键是扁平的，path 只写一段，如 `{ path: ["general.developer"], equals: true }`；不满足时条目照样显示、只读，说明照旧。

| 函数 | 说明 |
| --- | --- |
| `collectSettingsSections(sources)` | 合起各来源（`{ id, settings? }`，扩展的 `settings` 字段就是这个形状）的分区。分区 id 重名时抛 `DesignerExtensionError`，名字空间 `settings-section`；`general`、`language`、`layout`、`toolbar`、`help`、`shortcuts`、`about` 留给内建 |
| `sortSettingsSections(sections)` | 按 `order` 排好，同值按传入顺序 |
| `settingKey(section, item)` | 条目的键 |
| `settingValue(settings, section, item)` | 条目此刻的值：写了用写的，没写取缺省值 |
| `resolveSettings(sections, settings)` | 此刻生效的设置：写了的键原样保留，各分区里没写的条目取缺省值（没有缺省值的不写）。交给命令、面板与扩展的上下文用这一份；`sections` 通常是 `collectSettingsSections` 合出的分区，基础分区要缺省值时把 `designerGeneralSettings` 的分区也传进来 |
| `settingPolicy(policy, section, item)` | 条目在宿主管控下的状态：先看条目键，再看分区 id |
| `designerGeneralSettings(t, options?)` | 内建的「基础」分区；对话框自己会生成，各款要单独拿条目时用 |
| `designerLanguageSettings(t)` | 内建的「语言」分区（`DESIGNER_LANGUAGE_SETTINGS`）：一条 `locale`；对话框自己生成 |
| `designerLayoutSettings(t)` | 内建的「布局」分区（`DESIGNER_LAYOUT_SETTINGS`）：一条 `panels`，编辑方式 `PANEL_LAYOUT_CONTROL`；对话框给了 `frame` 时自己生成 |
| `designerToolbarSettings(t, { layout? })` | 内建的「工具栏」分区（`DESIGNER_TOOLBAR_SETTINGS`）：按钮显示方式、显示工具栏，`layout` 为真时加按钮表（编辑方式 `TOOLBAR_LAYOUT_CONTROL`）；对话框自己生成 |

### 「基础」分区

| 条目 | 键 | 编辑方式 | 缺省 | 何时出现 |
| --- | --- | --- | --- | --- |
| 主题 | `general.theme` | 分段：跟随页面、跟随系统、亮色、暗色 | `follow` | 总有 |
| 主题色 | `general.brand` | 色板：「跟随页面」钮、UI 的 8 个预设品牌（`@xihan-ui/tokens` 的 `BRAND_PRESETS`，格子画 `BRAND_PRESET_COLORS`，名字随语言）、自定义颜色 | 不写即跟随页面 | 总有 |
| 状态栏 | `general.statusBar` | 开关 | `true` | 总有 |
| 自动保存 | `general.autoSave` | 开关：有未保存的修改时停手约一秒，在这台浏览器里存一份草稿 | `false` | 总有 |
| 开发者模式 | `general.developer` | 开关：关闭后将隐藏 JSON / Blob 调试查看入口 | `false` | 总有 |
| 分页调试日志 | `general.debugPagination` | 开关：开启后在控制台输出分页拆分与回流日志，建议仅在排查问题时使用 | `false` | 总有，开发者模式开着才能改 |
| 渲染调试日志 | `general.debugRender` | 开关：开启后在控制台输出各渲染环节的耗时，用于性能优化 | `false` | 总有，开发者模式开着才能改 |

开发者模式是调试总开关，本身不加功能：`developerModeOf(settings)` 只有写了 `true` 才为真，各款的调试查看入口（如编辑 JSON、查看生成的打印数据）写成 `visible` 跟着它的命令；宿主可以在 `settings` 里预先写开，或用 `settingsPolicy` 锁住。

自动保存只存这台浏览器里的草稿（localStorage），宿主不参与；Ctrl / ⌘ + S 照旧派发 `save`，与它无关。外壳出 `createDesignerAutosave`，各款接上：

```ts
import { autoSaveOf, createDesignerAutosave } from "@xihan-ui/designer-shell";

const autosave = createDesignerAutosave({
  root: designerRoot,
  kind: "xh-flow-designer",
  key: () => designerRoot.draftKey, // 宿主给的草稿键；不给按页面地址区分
  enabled: () => autoSaveOf(resolvedSettings),
  snapshot: () => designerRoot.schema,
  restore: document => designerRoot.replaceDocument(document), // 整份替换，进撤销栈
  confirm: options => dialogService.confirm(options),
  translations: () => commandTranslations,
});
autosave.changed(designerRoot.dirty); // 模板或保存状态每次变了都调
await autosave.loaded(designerRoot.schema); // 宿主载入一份模板时调
```

- `changed(dirty)`：有未保存的修改且开着自动保存，停手约一秒（`delay`，缺省 1000 毫秒）把整份模板写成草稿，连着改只写最后一次；变干净了（宿主存完把 dirty 置回，或撤销回到保存点）删掉草稿；关着自动保存时不写，也不删已有的草稿。
- 草稿的键是 `xh-designer-draft:<kind>:<草稿键>`；`key()` 返回 `undefined` 时用页面地址（路径、查询与锚点）。读写都包在 try/catch 里，存不了就安静跳过，不影响编辑。
- `loaded(document)`：同一个草稿键下有和它不一样的草稿就调 `confirm` 问，标题是「发现未保存的草稿（时间）」（时间按设计器那棵子树的语言写），确认按钮是恢复、取消按钮是丢弃；恢复交给 `restore`，丢弃即删掉草稿；一样就悄悄删掉。问着的时候再调不会再问一次。
- 文案在 `xh-designer-commands` 那一桶：`draftFound(time)`、`draftFoundDescription`、`draftRestore`、`draftDiscard`。

两条调试日志只在开发者模式开着时生效，关掉开发者模式随即都停。四款都显示这两个开关；没有分页的款开了也没有分页日志。日志内容写在各款里，外壳出记日志的小工具：

```ts
import { createDesignerDebugLogger } from "@xihan-ui/designer-shell";

const debug = createDesignerDebugLogger({ name: "xh-print-designer", settings: () => resolvedSettings });
debug.log("pagination", "第 2 页放不下，拆到第 3 页", () => ({ page: 2, height }));
const dom = debug.measure("render", "生成 DOM", () => buildPages());
const end = debug.start("render", "出图");
await renderImages();
end(() => ({ pages: dom.length }));
```

- 每次调用都按 `settings()` 此刻的值判断这一路开没开（`debugLogOf(settings, channel)`：开发者模式与这一路的开关都写了 `true`）。
- 开着时写到浏览器控制台，折叠成一组，组名是「[设计器名] 这一路 · 标题」，`measure`、`start` 记的组名末尾带耗时（毫秒，一位小数）；`details` 是现取的函数，结果写在组里。
- 关着时不碰控制台、不调 `details`；`measure` 只跑 `run` 并返回它的结果，`start` 返回什么都不做的函数。标题本身要算很久时先问 `enabled(channel)`。
- 渲染日志记哪次重画、因为什么、用了多久，把原因写进标题；分页日志记分页的每一步，内容由各款自己定。

键也在 `DESIGNER_SETTING_KEYS` 里。主题与主题色由 `createDesignerSettingsHost` 落到设计器上；状态栏由各款自己接，例如状态栏关掉时从外框的 `regions` 里去掉 `status` 区。面板布局也存在设置里，键是 `layout.panels`（`DESIGNER_SETTING_KEYS.layout`），对话框里对应「布局」页，见下文与「外框」的「面板布局」。

### 「语言」分区

| 条目 | 键 | 编辑方式 | 缺省 | 何时出现 |
| --- | --- | --- | --- | --- |
| 界面语言 | `language.locale` | 下拉：跟随页面、跟随系统，再是外壳自带的全部语言 | `follow` | 总有 |

- 语言清单是外壳自带的 `DESIGNER_LANGUAGES`，与 UI 组件库的内建语言包一一对应，名字是各自的本名：简体中文、繁體中文、English、日本語、한국어、Deutsch、Français、Español、Português (Brasil)、Русский。宿主不再传语言清单。
- 只作用于设计器：设计器根把语言配置作为自己的 `xhConfig` 交出去，根下的元素（含搬进浮层根的对话框、菜单）按它取 `locale` 与文案，页面别处照旧。设计器自己的文案、外壳零件的文案与 UI 元素的文案（日期、分页、确认框之类）一起换。
- `designerLanguageOf(settings, preferred?)`：设置里的语言此刻落成哪一种。没写、跟随页面或不认识的值是 `undefined`；跟随系统按 `preferred`（缺省取 `navigator.languages`）挑，挑不到用 `en-US`；写了一种语言就是它。
- `matchDesignerLanguage(preferred)`：按语言偏好的先后挑最接近的一种：完全一致的优先，否则取同一语言的那一种；中文按书写系统定简繁（`Hant` 繁、`Hans` 简），没写书写系统时台湾、香港、澳门是繁体。挑不到是 `undefined`。
- 语言包按需加载：子入口 `@xihan-ui/designer-shell/language` 的 `loadDesignerLocale(language)` 取这种语言的 UI 组件库与 designer-shell 语言包，并成一份配置（`locale` 与各桶文案）。各款再并上自己这一款的同语言包，交给设置宿主的 `locale` 选项，见下文「落到设计器上」。

### 「工具栏」分区

| 条目 | 键 | 编辑方式 | 缺省 | 何时出现 |
| --- | --- | --- | --- | --- |
| 按钮显示方式 | `toolbar.display` | 分段：图标、文字、图标和文字 | `icon` | 总有 |
| 显示工具栏 | `toolbar.visible` | 开关 | `true` | 总有 |
| 按钮 | `toolbar.layout` | 按钮表（`toolbarLayout`） | 不写即缺省排列 | 对话框给了 `toolbar` 的缺省排列与命令 |

工具栏只走设置，各款不另设属性：`toolbarDisplayOf(settings)` 取显示方式（没写或不认识的值是 `icon`），交给命令工具栏的 `setDisplay`；`toolbarVisibleOf(settings)` 只有写了 `false` 才是不显示，各款这时从外框的 `regions` 里去掉工具栏的区，命令照样能经快捷键与菜单执行。菜单栏常开，没有显示菜单栏的设置；设置命令在「文件」菜单里，还有快捷键 Mod+,。

按钮表只管顶部工具栏：菜单栏、右键菜单与选中工具条都不进用户定制，只由宿主的 `commandLayout` 改。

- **列什么**：对话框的 `toolbar` 是 `{ defaults, commands }`：`defaults` 是缺省排列（各款 `arrangeCommands("toolbar", …)` 排出的分组，已含宿主 `commandLayout` 与扩展追加的那一组），`commands` 是其中每条命令的短文字、图标与快捷键。各款每轮更新时用 `toolbarSettingsSource(defaults, 命令表, 上下文)` 现算，交给对话框；文字取 `commandShortLabel`（撤销这类文字随下一步变的命令写固定的短名），按此刻的语言取，所以每编辑一步算出来的数据不变、表不重铺。
- **样子**：一组一块，组头是三态勾选框（全选、部分、全不选）与拖动把手，下面每条命令一行：勾选框（图标与名字）、快捷键、拖动把手。组与组之间、组里的命令都能拖，命令能从一组拖进另一组；键盘在把手上用空格拿起、方向键挪、空格放下（竖排的命令列表用左右键挪到相邻的组）。表下一颗「恢复默认」删掉这个键。组这一层是一个 `<xh-sortable>`，组里的命令各是一个同 `group` 的 `<xh-sortable>`。
- **值**：`DesignerToolbarCustomization`，`{ groups, hidden? }`：`groups` 按用户的先后列出全部命令（含藏起的），藏起的写进 `hidden`，重新勾上时回到原位；整组藏起就是组里每条都在 `hidden` 里。
- **生效**：先 `arrangeCommands("toolbar", 命令表, 缺省排列, commandLayout)`，再 `applyToolbarCustomization(上一步的分组, toolbarCustomizationOf(settings))`。用户值里有、命令表里已经没有的命令跳过，不抛错（宿主 `commandLayout` 写错 id 照旧抛错）；命令表里新有、用户值里没有的命令（后装的扩展）放在缺省排列里同组前面最近一条之后，没有就放在后面最近一条之前，整组都新就另起一组。
- **管控**：`toolbar.layout` 锁定时按钮表只读，藏掉时没有这张表；显示方式与显示工具栏照常。整个 `toolbar` 分区也能藏或锁。

| 函数 | 说明 |
| --- | --- |
| `toolbarCustomizationOf(settings)` | 设置里的 `toolbar.layout`；没写或形状不对时为 `undefined` |
| `mergeToolbarCustomization(arranged, customization)` | 合起缺省排列与用户定制，列出全部命令（含藏起的），规则如上；按钮表用它 |
| `applyToolbarCustomization(arranged, customization)` | 合起来以后去掉藏起的命令与空组，就是工具栏此刻的分组 |
| `toolbarSettingsSource(defaults, commands, context)` | 交给对话框 `toolbar` 的数据，命令表里没有的跳过 |
| `toolbarVisibleOf(settings)` | 显示工具栏，只有写了 `false` 才为 `false` |

### 「帮助」「快捷键」「关于」分区

对话框给了 `help`、`shortcuts`、`about` 才有这三页，排在最后（900、910、920）。它们由只显示、不存值的条目组成：没有缺省值，编辑器不写设置，`resolveSettings` 里也不出现。

| 页 | 对话框的属性 | 内容 |
| --- | --- | --- |
| 帮助 | `help: { notes?, actions? }` | `notes` 是几段操作说明（各款的文案，按语言取好）；`actions` 是几颗钮 `{ command, label }`，如「开始引导」（`start-tour`）、「打开文档」（`help`），点了先收起对话框，等焦点回到打开它的元素再派发 `settings-command { command }`，由设计器跑这条命令；这时开始的引导收起后焦点回到那里。两样都没有时没有这一页 |
| 快捷键 | `shortcuts: { groups }` | 一张快捷键表，从命令表生成，不手写：各款用 `shortcutSettingsSource(命令表, 上下文, { extensionCommands?, keys?, commonKeys? })` 现算。凡有快捷键的命令一行（名字取 `commandShortLabel`，第二快捷键写在同一行），designer-shell 内置的命令归「通用」，四款共有的编辑命令（`DESIGNER_EDIT_COMMANDS`）归「编辑」，扩展的归「扩展」，其余归「本设计器」；`keys` 是本设计器不是命令的按键，排在「本设计器」末尾。对话框给「通用」补上四款都有的按键（`DESIGNER_COMMON_KEYS`：方向键微移、Shift 加方向键大步微移、按住空格拖动画布、F10 进出菜单栏、Alt+F10 聚焦选中工具条、Esc 取消），各款经 `commonKeys` 换掉这几行，见下文。键铺成 `<xh-kbd>`，按平台写 |
| 关于 | `about: { product, version, license?, rows? }` | 产品、版本、界面库（XiHan.UI，即 `DESIGNER_SHELL_VERSION`）的版本与许可证，后面接 `rows`：扩展的 `about` 字段（附加包的版本与授权）由各款接在这里。各款的版本号也从构建时注入的常量取（如流程的 `FLOW_VERSION`） |

各款与扩展的分区也能用这几种条目：

| `control.kind` | 形状 |
| --- | --- |
| `note` | `{ kind: "note", paragraphs }`：几段纯文本 |
| `action` | `{ kind: "action", command, text }`：一颗钮，点了派发 `settings-command`；宿主锁定这一条时不可用 |
| `info` | `{ kind: "info", rows }`：名字与值的几行 |
| `shortcutTable` | `{ kind: "shortcutTable", groups }`：几组 `{ label, rows }`，每行 `{ label, keys }` |

| 函数 | 说明 |
| --- | --- |
| `designerHelpSettings(t, help)`、`designerShortcutSettings(t, shortcuts)`、`designerAboutSettings(t, about)` | 三页的分区（`DESIGNER_HELP_SETTINGS`、`DESIGNER_SHORTCUT_SETTINGS`、`DESIGNER_ABOUT_SETTINGS`）；对话框自己生成 |
| `shortcutSettingsSource(commands, context, options?)` | 交给对话框 `shortcuts` 的快捷键表，规则如上 |
| `isDesignerDisplayControl(control)` | 这条条目只显示、不存值（`DESIGNER_DISPLAY_CONTROL_KINDS`） |

「通用」组末尾四款共有的那几行，各款可以换掉：在导出的 `DESIGNER_COMMON_KEYS` 基础上去掉本设计器没有的操作、改写说法不同的那一行，或另加几行，经 `shortcutSettingsSource` 的 `commonKeys` 交进去。

- 一行是 `{ id, keys, label? }`（`DesignerCommonKey`）：`id` 是内建的几种（`DesignerCommonKeyId`：`nudge`、`nudgeLarge`、`pan`、`selectionToolbar`、`cancel`）时可以不写 `label`，名字由对话框按语言取；写了 `label` 就用它，取各款自己的文案（按此刻的语言取好），外壳不写死。另加的行必须写 `label`，不写时类型报错，`shortcutSettingsSource` 也抛 `TypeError`。
- 不给 `commonKeys` 时照旧是 `DESIGNER_COMMON_KEYS`；给空数组就没有这几行。

```ts
import { DESIGNER_COMMON_KEYS, shortcutSettingsSource } from "@xihan-ui/designer-shell";

// 看板上没有按住空格拖动画布；Shift 加方向键是把卡片改大或改小一格
const commonKeys = DESIGNER_COMMON_KEYS
  .filter(key => key.id !== "pan")
  .map(key => (key.id === "nudgeLarge" ? { ...key, label: t.shortcutResize } : key));
settingsDialog.shortcuts = shortcutSettingsSource(commands, context, { commonKeys });
```

### 「布局」分区

对话框给了 `frame`（设计器的外框）且外框里有面板时，「基础」后面多一页「布局」：一张面板表，逐块面板一行，列出显示开关、位置（左栏、右栏、下栏、浮动）、上移下移与收成标题条，表下一颗「恢复默认布局」。它和面板头的「更多」菜单一样，是不靠拖动也能改布局的路。

- 表直接调外框的方法改布局（`setPanelVisible`、`movePanel`、`floatPanel`、`dockPanel`、`setPanelMinimized`、`resetLayout`），外框派发 `layout-change`，设计器照常把它写进设置；这一页自己不派发 `settings-change`。
- 三栏按布局里的先后排，画布浮动件排在最后、只有显示开关；不能挪的面板位置与上下移不可用，不能浮出的没有「浮动」，不能收起的收起开关不可用；浮着的面板不能上下移。从右往左写时左右两栏的叫法对调。
- 管控：`layout.panels`（或整个 `layout` 分区）`hidden` 时没有这一页，`locked` 时表只读、说明换成文案 `locked`；锁定一块面板（外框的 `layoutPolicy`）只锁那一行。

### 设置对话框

`<xh-designer-settings>` 里是 `<xh-dialog>`，左边竖排的分区页，右边按正文行宽逐条列出条目；分区页定高，换页时对话框不跳。宿主元素不占盒。

| 属性 | 说明 |
| --- | --- |
| `sections` | 各款与扩展的设置分区；没有可显示条目的分区不出现 |
| `general` | `false` 不要「基础」这一页。主题色与语言清单都是内置的，不用传。「语言」页总有，不要时用 `policy` 把 `language` 藏掉 |
| `frame` | 设计器的外框（`DesignerSettingsFrame`，外框元素本身即可）；给了且有面板时有「布局」页 |
| `help` | 「帮助」页：几段操作说明与几颗跑命令的钮，见上文 |
| `shortcuts` | 「快捷键」页：`shortcutSettingsSource` 现算的快捷键表 |
| `about` | 「关于」页：产品、版本、许可证与扩展给的几行 |
| `toolbar` | 「工具栏」页：`{ defaults, commands }`（`toolbarSettingsSource` 现算）给了才有按钮表；不给只有显示方式与显示工具栏两条；`false` 不要这一页 |
| `settings` | 设置的值 |
| `policy` | 宿主的管控：键是条目键或分区 id，值 `hidden` 不显示、`locked` 只读并把说明换成文案 `locked` |
| `editors` | 内建编辑方式之外的条目按 `control.kind` 用这里的编辑器；没登记的只显示值 |
| `open` | 对话框打开。同名 attribute |
| `section` | 当前显示的分区 id；不写或那一页不显示时显示第一页。同名 attribute |
| `translations` | 元素自己的文案，压在全局配置之上 |

| 方法 | 说明 |
| --- | --- |
| `show(section?)` | 打开对话框，给了分区 id 就显示那一页 |

| 事件 | 说明 |
| --- | --- |
| `settings-change` | `{ key, value, settings }`：改了一条，`value` 为 `undefined` 表示删掉这个键、回到缺省值；`settings` 是改过之后的整份值，元素已经换成它 |
| `open-change` | `{ open }`：按 Esc、点遮罩或关闭钮时对话框要关上，元素已经换成这个状态 |
| `settings-command` | `{ command }`：点了只显示条目里跑命令的钮（帮助页的开始引导、打开文档），由设计器跑这条命令。对话框开着时先收起，退场完、焦点回到打开它的元素后才派发；设计器在事件里再写 `open = false` 不起作用，可以不写 |

对话框打开时内容搬到浮层根：主题、主题色等视觉轴经视觉桥跟着设计器根走；标题、字段与对话框自己的文案照它们在设计器里的原位取配置，设计器外面包一层局部 `<xh-config>` 时用的是那一层的语言与文案。

### 落到设计器上

`createDesignerSettingsHost(options)` 返回 `{ load, save, apply, localeConfig, dispose }`：

| 选项 | 说明 |
| --- | --- |
| `root` | 设计器根：主题写成它的 `data-theme`，主题色写成它的 `data-brand`，只作用于设计器 |
| `locale` | `(language) => 配置或它的 Promise`：选了语言（「语言」分区不是跟随页面）时这台设计器用的配置，通常是 `loadDesignerLocale(language)` 再并上本款的同语言包。不给时语言那一条不生效 |
| `onLocaleChange` | `localeConfig` 换了时调用（语言换了、跟随系统时系统语言变了、`dispose` 时回到跟随页面），设计器据此重画自己 |
| `storageKey` | 设置存在根所在窗口 localStorage 的哪个键下；不给就不读写 |
| `onStorageError` | 读写失败（无痕窗口、配额满、内容不是对象）时回调 `{ operation, key, error }`，设置留在内存里。给了 `storageKey` 就必须给，否则抛 `TypeError` |

- `apply(settings)`：主题跟随页面时把根的 `data-theme` 还原成接手前的值，跟随系统时按 `prefers-color-scheme` 写、系统改了跟着改；主题色是 UI 的预设品牌就直接写它；别的颜色经 `@xihan-ui/tokens` 的 `registerBrand` 在根所在的文档里注册成这台设计器自己的品牌（一份 `[data-brand]` 取值块），换走时撤销；取不出品牌梯度的值不生效，按跟随页面处理。
- `data-brand` 要与 `data-theme` 在同一个元素上才换得动品牌：主题跟随页面又选了主题色时，根上照抄外层的 `data-theme`（外层没写就是亮色）。根上新写了主题时，语义令牌在这里重新声明，外层的 `data-contrast` 也一并照抄。外层这两个属性变了，根上跟着改。
- `apply(settings)` 也按语言那一条换 `localeConfig`：跟随页面当场换回空对象；选了语言或跟随系统时调 `locale` 取配置，取到后记下、通知根下的子树重画，再调 `onLocaleChange`；取的期间又换了语言，只落最后要的那一种。跟随系统时盯着窗口的 `languagechange`，浏览器的语言偏好变了跟着换。
- `localeConfig`：设计器根此刻的语言配置，跟随页面时是空对象。设计器根声明 `xhConfig` 返回它，根下的元素就按它取 `locale` 与文案。
- `save(settings, sections?)`：`sections` 里标了 `secret` 的文本条目不存。
- `load()`：没给存储键、没存过或读不出时是空对象。
- `dispose()`：撤掉跟随系统与外层的监听、注册的主题色，根上的 `data-theme`、`data-brand`、`data-contrast` 还原成接手前的样子，`localeConfig` 回到空对象。

## 导入字段

`<xh-designer-field-import>` 从一份 JSON 样例或一份 JSON Schema 导入字段树。里面是 `<xh-dialog>`：上面一排来源页签，下面是预览表，用户勾选、改显示名与类型后按「导入」。推断用 designer-kit 的 `@xihan-ui/designer-kit/field-inference`，全在本机做，不发请求。对话框不改设计器的字段，派发 `fields-import`，由设计器自己换上。宿主元素不占盒。

```ts
const dialog = document.createElement("xh-designer-field-import");
dialog.fields = designer.fields; // 现有字段：不为空时出「合并 / 替换」
dialog.contents = ["text", "image", "barcode", "qrcode"]; // 给了才有「内容」列
dialog.inference = { detectImages: true };
dialog.offerSample = true;
dialog.addEventListener("fields-import", (event) => {
  designer.fields = event.detail.fields;
  if (event.detail.sample !== undefined)
    designer.sampleData = event.detail.sample;
});
dialog.show();
```

| 属性 | 说明 |
| --- | --- |
| `sources` | 扩展登记的字段来源（designer-kit 的 `DesignerFieldSource`，见那一页的「字段来源」），按 `order` 排在内置两页之后；id 与内置页重名时抛 `TypeError` |
| `fields` | 现有字段：不为空时出「合并 / 替换」，合并时预先标出同名而种类不同的字段 |
| `contents` | 给了才有「内容」列，值字段的内容种类只能在这几种里选；不给时保留推断出的内容 |
| `inference` | 推断选项，交给 `inferDataFields`；JSON Schema 只用其中的 `rootName` 与 `maxDepth` |
| `offerSample` | 内容带样例时出「同时作为示例数据」，缺省勾上。attribute 是 `offer-sample` |
| `open` | 对话框打开。同名 attribute |
| `source` | 当前显示的页：`sample`、`json-schema`（`DESIGNER_FIELD_IMPORT_SOURCES`）或字段来源的 id；不写或找不到时显示第一页。同名 attribute |
| `translations` | 元素自己的文案，压在全局配置之上 |

| 方法 | 说明 |
| --- | --- |
| `show(source?)` | 打开对话框，给了页 id 就显示那一页 |

| 事件 | 说明 |
| --- | --- |
| `fields-import` | `{ fields, mode, source, sample?, annotations }`：用户按了「导入」，对话框随即关上。`fields` 已按勾选、显示名、类型、内容与合并 / 替换算好；`mode` 在现有字段为空时恒为 `replace`；`sample` 只在内容带样例、又勾了「同时作为示例数据」时有；`annotations` 是推断出的注解（说明、必填、候选值等），键是 `formatJsonPath(字段路径)` |
| `open-change` | `{ open }`：按 Esc、点遮罩、关闭钮、取消或导入时对话框关上，元素已经换成这个状态 |

- 内置两页各有一个多行输入框，下面是读文件的投放区：把 `.json` 文件拖进来或点它选一个，文件在本机读进输入框。输入一变就解析；解析失败时写出第几行第几列与原因（core/json 的 `parseJsonText`），预览表收起，导入钮不可用。
- 字段来源页切到时才建，切走或对话框关上时中止并销毁，它交来的内容一并清掉；`fail(message)` 给的话写在页下。
- 预览表一个字段一行，下级按层级缩进：勾选框、字段名、显示名输入框、类型下拉（值字段才有，对象与列表写种类）、内容下拉。去掉一行就连同它的下级一起不导入，下级的控件不可用。内容换了时，路径没变的行保留用户改过的显示名、类型与内容。表下列出推断说明（如「列表里是单个值，导入为没有子字段的列表」）与合并时种类不同的字段。
- 每次打开都从空白开始。
- 文案键 `xh-designer-field-import`，英文表 `DESIGNER_FIELD_IMPORT_EN_US`；推断说明按 designer-kit 的说明码各一条。

内置命令 `import-fields` 打开它，见下文「命令」的 `designerShellCommands`。

## JSON 编辑

`<xh-designer-json-editor>` 编辑整份模板的 JSON。里面是 `<xh-dialog>`：一个等宽字体、不折行的多行编辑框，下面是解析失败的说明与问题列表（`<xh-designer-issues>`），底边是格式化、复制、取消与应用。对话框不改设计器的文档，派发 `json-apply`，由设计器自己换上；四款把它作为一步进撤销栈，说明写「编辑 JSON」。宿主元素不占盒。

```ts
const editor = document.createElement("xh-designer-json-editor");
editor.value = designer.schema; // 每次打开都从它写起，缩进两格
editor.validate = value => issuesOf(migrate(value)).map(issue => ({ issue, message: t(issue) }));
editor.readonly = designer.readonly;
editor.addEventListener("json-apply", event => designer.replaceDocument(event.detail.value));
editor.show();
```

| 属性 | 说明 |
| --- | --- |
| `value` | 打开时编辑框里的 JSON（设计器此刻的整份文档）；只走 property |
| `validate` | `(value) => DesignerIssueItem[]`：各款先走读入迁移、再走 core 的校验，与粘贴整份模板同一套，换好文字交回来。不给时只查能不能解析 |
| `readonly` | 只读：能看、能格式化、能复制，不能改，也没有「应用」。同名 attribute |
| `open` | 对话框打开。同名 attribute |
| `translations` | 元素自己的文案，压在全局配置之上 |

| 方法 | 说明 |
| --- | --- |
| `show()` | 打开对话框 |

| 事件 | 说明 |
| --- | --- |
| `json-apply` | `{ value }`：用户按了「应用」，对话框随即关上。只有文字解析得了、没有错误级问题、又与打开时的值不同时「应用」才可用 |
| `open-change` | `{ open }`：按 Esc、点遮罩、关闭钮、取消或应用时对话框关上，元素已经换成这个状态 |

- 文字一变就重新解析（core/json 的 `parseJsonText`）并交给 `validate`。解析失败时编辑框标成 invalid，写出第几行第几列与原因，后面一颗「转到出错处」把光标放过去。
- 点问题列表的一条，光标选中那个路径在文字里的值（core/json 的 `locateJsonPath`，见下），编辑框滚到那一行；路径在文字里没有时退到最近的上级。整块的对象或数组只选它起头的那一行。
- 打开时落焦在编辑框，光标在开头、滚到顶，不全选。
- 复制把编辑框里的文字写进剪贴板（core/clipboard 的 `writeToClipboard`，要安全上下文），钮旁写一句「已复制」或「复制失败」，再改文字时清掉。
- 每次打开都从 `value` 重新写起，没应用的改动丢掉。
- 文案键 `xh-designer-json-editor`，英文表 `DESIGNER_JSON_EDITOR_EN_US`。

`locateJsonPath(text, path)`（`@xihan-ui/core/json`）在 JSON 文本里找路径指向的值，返回 `{ start, end, line, column }`：值在文本里的起止下标与起点的行列（从 1 数起，换行的算法同 `parseJsonText`）。路径写法同 `getJsonAt`，空路径指整个值；文本不是合法 JSON 或路径走不通时为 `undefined`；对象里键重复时取最后一个，与 `JSON.parse` 一致。

内置命令 `edit-json` 打开它，见下文「命令」的 `designerShellCommands`。

## 新手引导

`<xh-designer-tour>` 是设计器的新手引导：库内 `<xh-tour>` 包一层，designer-shell 的通用步骤加上各款与扩展的步骤，按 `order` 排，一步步高亮外框里的面板、区或工具栏上的命令。放在设计器元素里、外框旁边，和设置对话框一样；宿主元素不占盒。

```ts
import { collectTourSteps, resolveTourSteps, tourDoneOf } from "@xihan-ui/designer-shell";

const steps = collectTourSteps([productExtension, ...extensions]); // id 重名时抛 DesignerExtensionError
const tour = document.createElement("xh-designer-tour");
tour.frame = frame;
tour.steps = resolveTourSteps(steps, context); // 每轮按上下文取文字、过一遍 when
designerRoot.append(tour);
tour.addEventListener("tour-end", () => writeSetting("help.tourDone", true));
if (autoTour && !tourDoneOf(settings))
  tour.start(); // 第一次连上文档、画布铺好之后；同一页已有引导开着时不开始
// 用户手动开始（start-tour、帮助页的「开始引导」）写 tour.start({ force: true })，先收起同一页别的引导
```

### 步骤

| 字段 | 说明 |
| --- | --- |
| `id` | 全局唯一：designer-shell 的写 `shell.<名>`，各款写 `<产品>.<名>`，扩展写扩展 id 加点 |
| `target` | 要高亮的目标，不给就不锚定、浮层居中：`{ panel, part? }` 面板卡片（给了 `part` 就是面板里 `data-part` 为它的节点）；`{ command }` 工具栏上这条命令的按钮，收在「更多」里时是「更多」钮；`{ region }` 外框的区（`menubar`、`toolbar`、`canvas`、`status`）；`{ menubar }` 菜单栏上这张菜单的入口（菜单 id，如 `file`，或各款自己的 `insert`、`data`），窄屏菜单栏收成「菜单」钮时是那颗钮，菜单栏上没有这张菜单或菜单栏没显示时那一步跳过；`{ selector }` 设计器里的任意节点 |
| `title`、`description` | 标题与说明，可以是按上下文现算的函数 |
| `placement` | 浮层相对目标的首选位置，缺省 `bottom` |
| `order` | 排序：designer-shell 的通用步骤 0–60 与收尾的 900，各款 100 起，扩展 200 起；同值按登记顺序 |
| `when` | 返回 `false` 时跳过，如只读模式下的编辑步骤 |

通用步骤：`shell.welcome`（居中，0）、`shell.menubar`（菜单栏区，5：各张菜单里有什么，F10 进出菜单栏）、`shell.toolbar`（工具栏区，10）、`shell.palette`（物料面板，20）、`shell.canvas`（画布区，30）、`shell.properties`（属性面板，40）、`shell.issues`（问题面板，50）、`shell.status`（状态栏，60）、`shell.settings`（900，排在各款与扩展的步骤之后收尾：指向「文件」菜单的入口，说设置在「文件」菜单里、引导能从「帮助」重新开始；外框没有菜单栏时跳过），文案在 `xh-designer-tour` 那一桶。目标面板隐藏、区不在外框里或没有内容、命令没有按钮、菜单不在菜单栏上的那一步跳过，所以没有物料面板的报表自然少一步，各款补自己的步骤即可；各款自己的菜单（如打印的「插入」「页面」、报表的「数据」）用 `{ menubar: "<菜单 id>" }` 指到它的入口。

| 函数 | 说明 |
| --- | --- |
| `resolveTourSteps(steps, context)` | 按上下文取好文字、过一遍 `when`，得到交给零件的 `DesignerTourStepView[]`；顺序不变 |
| `collectTourSteps(sources)` | 合起各来源（`{ id, tourSteps? }`，扩展的 `tourSteps` 字段就是这个形状）的步骤，保持登记顺序。id 重名或用了留给 designer-shell 的 `shell.` 前缀时抛 `DesignerExtensionError`，名字空间 `tour-step` |
| `tourDoneOf(settings)` | 设置里 `help.tourDone`（`DESIGNER_TOUR_DONE_KEY`）为 `true`：引导已经完成或跳过过，不再自动开始。这个键不对应设置对话框里的条目 |

### 零件 `<xh-designer-tour>`

| 属性 | 说明 |
| --- | --- |
| `frame` | 设计器的外框：解析目标、判断面板显隐，进入一步前经 `revealPanel` 把面板亮出来（展开分隔条上收起的栏、标题条，窄屏时开抽屉） |
| `steps` | 各款与扩展的步骤（`resolveTourSteps` 取好的） |
| `builtin` | 带上通用步骤，缺省 `true`；同名 attribute 写 `"false"` 不带 |
| `translations` | 元素自己的文案，压在全局配置之上 |

| 方法与只读属性 | 说明 |
| --- | --- |
| `start(options?)` | 从第一步开始；没有能走的步骤时返回 `false`。同一页里已有别的引导开着时缺省不开始、返回 `false`（自动开始用这个）；`{ force: true }` 先收起那一个再开始（用户手动开始用这个） |
| `stop()` | 收起引导 |
| `plannedSteps()` | 此刻会走的各步：排好序、去掉了走不了的 |
| `running` | 引导此刻开着 |

| 事件 | 说明 |
| --- | --- |
| `tour-end` | `{ reason, step }`：引导收起了。`reason` 是 `complete`（走完）、`skip`（跳过或 Esc）或 `close`（关闭钮或 `stop()`）；`step` 是收起时那一步的 id。各款收到后把 `help.tourDone` 写成 `true` |

- 浮层里依次是标题、说明、「第几步，共几步」、一步一个的圆点，底部一行跳过、上一步与下一步（最后一步写「完成」），右上角关闭钮；键盘与读屏照 `<xh-tour>`。
- 引导限在外框里（`<xh-tour>` 的 `boundary` 是外框）：遮罩只盖外框，高亮框连同暗幕裁在外框里，居中的那步摆在外框中间，气泡以外框为界避让；页面别处照常可读可点，焦点不困在气泡里。同一页同时只有一个引导开着。
- 窄屏时，目标面板收在抽屉里的那步把抽屉打开，抽屉排在引导之下，不盖住提示框，Esc 仍先收引导；抽屉滑进来之后高亮框按面板滑到的位置重新量。换到目标不在抽屉里的一步（不是面板，或面板在下栏）、以及引导收起时，抽屉还原成开始引导时的样子。元素从文档上摘下时引导一并收起。
- 收起时焦点回到开始引导时持有它的元素；那个元素已不在文档里时，退回外框画布区里能聚焦的第一个（画布区没有就取外框里的第一个）。
- 宿主不要自动开始时设计器给 `autoTour = false`；内置命令 `start-tour`（`designerShellCommands` 的 `startTour` 选项）与帮助页里的「开始引导」随时重新开始。

## 扩展的面板与命令

设计器扩展的骨架、合并查重与装卸在 `@xihan-ui/designer-kit`（见那一页的「设计器扩展」）。这里放跟界面有关的几样：面板登记到外框的区，命令铺成工具栏按钮、菜单栏与右键菜单条目，粘贴与拖放的数据列成导入来源，设置分区放进设置对话框，物料来源接进物料面板。

### 面板

```ts
import { createPanelHost } from "@xihan-ui/designer-shell";

// 内置区缺省为 DESIGNER_FRAME_REGIONS，产品有自己的就传 regions；给了 commands，面板头的命令按它铺
const panels = createPanelHost(frame, { regions, commands: () => commandTable, actionsLabel: (context, title) => title });
panels.assign(host.list, context); // 每次 extensions 变化后调用
panels.update(context); // 设计器状态变化后刷新
panels.dispose();
```

- 扩展的 `panels` 是 `{ region, create(context) => { element, update?, destroy? }, headerCommands? }`：`region` 是外框的命名区，也就是面板的登记（名字、缺省停的栏、标题、图标、能不能挪与浮出等，见「外框」），追加在内置区之后，同一栏按扩展顺序上下排；`element` 以 `slot` 交给外框，放进那个区。
- 区名与内置区或别的扩展重名时 `assign` 抛 `DesignerExtensionError`（名字空间 `panel`），什么都不变。
- 按面板对象的引用比对：留下来的不重建，去掉的调 `destroy` 后撤掉。
- `headerCommands` 是面板头操作区里的命令 id（或按上下文现算的函数）：面板宿主按选项 `commands` 给的命令表铺成一小条只显示图标的工具栏，放进 `slot="<区名>-actions"`，每次 `update` 刷新，命令表里没有的 id 跳过；一条命令都没有时整条藏起，里面不放 `<xh-toolbar>`，有了命令再放回。内置面板（物料、属性、问题这类不是扩展登记的面板）用 `createPanelActions(document, 面板 id)` 建同样的一条，返回 `{ element, update(ids, commands, context, label) }`，由各款放进外框。这条命令条放不下的钮不收进自己的「更多」，由外框列进面板头的「更多」菜单。
- 扩展登记的面板与内置面板一样进布局：能换栏、浮出、收起、隐藏，记在 `layout` 里。宿主写在 HTML 里的内容照样用 `slot="<区名>"` 交给外框，不必经扩展。

### 命令

工具栏与右键菜单的排列用 `commandLayout`：位置 → 若干组命令 id，内置命令与扩展命令混排。

```ts
import { arrangeCommands, createCommandToolbar, renderCommandMenu, runCommand } from "@xihan-ui/designer-shell";

const commands = extensionCommands(host.list); // designer-kit，内置在前
const toolbar = createCommandToolbar(document, { display: "icon" }); // 显示方式缺省 icon，快捷键的平台缺省当场测
toolbar.update(arrangeCommands("toolbar", commands, BUILTIN_TOOLBAR, designer.commandLayout), commands, context, t.toolbar);

renderCommandMenu(menuContent, arrangeCommands("menu:node", commands, BUILTIN_NODE_MENU, designer.commandLayout), commands, context, { platform });
menu.addEventListener("item-select", event => runCommand(commands, event.detail.value, context));
```

| 函数 | 说明 |
| --- | --- |
| `arrangeCommands(placement, commands, defaults, layout?)` | 排出某个位置的分组（工具栏、`menu:<主体>` 的右键菜单、`selection:<主体>` 的选中工具条都用它；菜单栏的 `menubar:<菜单 id>` 用下文的 `arrangeMenubar`）：`layout` 写了这个位置就只用它；否则用 `defaults`（各款内置的缺省排列），再把 `placement` 含这个位置、又不在缺省排列里的命令按登记顺序追加成一组。排列里写了没登记的命令 id 时抛 `TypeError` |
| `createCommandToolbar(document, { display?, orientation?, platform?, overflow? })` | 一条 `<xh-toolbar>`，外面包一个委托模式的 `<xh-tooltip>`（`element` 是这层外壳，布局上不占盒子；`toolbar` 是里面那条工具栏）。`update(groups, commands, context, label)` 分组变了才重铺按钮，文字、图标、`aria-label`、`aria-keyshortcuts`（快捷键按 `platform` 写成规范写法，如 `Control+Shift+Z`；命令有第二快捷键时依次接在后面，提示只显示第一条）、可用、`aria-pressed`（开关式命令）与 `data-tone`（命令的语气）每次刷新；点击按钮执行命令，放不下的收进行尾的「更多」菜单，图标与语气随按钮带进菜单项。`display` 是 `icon`（缺省）、`text` 或 `both`，没有图标的命令在 `icon` 档照样显示文字，写的是短文字（`shortLabel`，没给就是 `label`），名字仍是全名；`setDisplay(display)` 换显示方式不重铺按钮，「更多」里的条目按新的宽度重新收放。悬停或键盘聚焦到按钮时提示显示命令的文字与快捷键；文字看得见时只给带快捷键的按钮提示。`orientation` 缺省 `horizontal`；`vertical` 时按钮上下排，提示、弹层与菜单在按钮的行首一侧弹出（从左往右写时在左边），放不下的按高度收进「更多」。`overflow` 缺省 `menu`；写 `external` 时放不下的钮由调用方列在别处，自己的「更多」钮不占位、看不见（只留作弹层与菜单的锚点），收起的条目变了时外壳派发冒泡的 `overflow-change`；`overflowed()` 是此刻收起的命令 `{ id, label, disabled }`，`activate(id)` 照点按钮那样执行一条。弹层命令与菜单命令见下文 |
| `renderCommandMenu(content, groups, commands, context, { platform? })` | 把分组铺成 `<xh-context-menu>` content 里的条目，组间一条分隔线；不可用的写 `aria-disabled`，命令的语气写 `data-tone`，带图标的在文字前铺 `item-icon`，带快捷键的在行尾写提示（只写主快捷键）并写进 `aria-keyshortcuts`（第二快捷键接在后面）。没有 `run` 的弹层命令与菜单命令只能放在工具栏上，排进右键菜单时抛 `TypeError` |
| `runCommand(commands, id, context)` | 命令存在、有 `run` 且此刻可用才执行，返回是否执行了 |
| `commandLabel(command, context)` / `commandShortLabel(command, context)` / `commandEnabled(command, context)` | 命令的文字；短文字（没给 `shortLabel` 时同 `label`；短文字要出现在 `label` 里，开发期工具栏发现不在时报一条 `core.warn` 告警，一条命令只报一次）；此刻能否执行 |
| `designerHistoryCommands({ history, disabled?, translations, historyTranslations, confirm, announce?, icons? })` | 撤销、重做与清空历史，四款共用：`history` 返回设计器的历史栈（designer-kit 的 `History` 直接合用），返回 `undefined`、在事务中（如拖动）或 `disabled` 返回 true 时三条都不可用。`undo`（Mod+Z）与 `redo`（Mod+Shift+Z，另认 Ctrl+Y）缺省放在工具栏上，全名带上下一步的说明，如「撤销：添加卡片」，按钮上看得见的短文字仍是「撤销」；`clear-history` 是危险语气，不上工具栏，由历史面板或 `commandLayout` 放置，没有步骤时不可用，执行时先经 `confirm(context, { title, content, okText, tone })` 弹确认框（交给各款的 `DialogService.confirm`），确定后才清空。三条做完都经 `announce(context, message)` 礼貌级地读一句。文案取 `translations`（`xh-designer-commands` 那一桶的 `undo`、`redo`、`undoWith`、`redoWith`、`clearHistory`）与 `historyTranslations`（`xh-designer-history` 那一桶）。id 与各款原有的 `undo`、`redo` 相同，替换后宿主的 `commandLayout` 不用动 |
| `designerShellCommands({ translations, save?, frame?, openSettings?, helpUrl?, openFieldImport?, fieldImportDisabled?, openJsonEditor?, startTour?, settings?, icons? })` | designer-shell 内置的命令。给了 `save` 有 `save`（保存，`Mod+S`），通常派发各款的 `save` 事件，各款原来在画布上自己接的 Ctrl / ⌘ + S 改走这条命令。给了 `frame`（返回设计器的外框）有五条：`panels` 点开一张菜单，逐块面板一项（外框的 `panelEntries()`，勾选的显示，锁定的不可点，选中经 `togglePanel` 开关），分隔线后列出另外三条；`panels-toggle-all`（显示或隐藏所有面板，`Mod+\`）、`panels-restore`（还原面板显隐，`Mod+Shift+\`）与 `layout-reset`（恢复默认布局）只在菜单与快捷键上，全部面板都锁定时不可用；`pan-tool`（拖动，`H`）是开关式，按下状态跟着外框的 `canvasTool`，执行时在 `select` 与 `pan` 之间切换。给了 `openSettings(context, section?)` 有三条：`settings`（打开设置对话框，`Mod+,`）、`shortcuts`（翻到快捷键页）与 `about`（翻到关于页）。给了 `helpUrl` 有 `help`（在新窗口打开各款文档站的帮助页，返回 `undefined` 时不可用），给了 `openFieldImport` 有 `import-fields`（打开导入字段对话框，`fieldImportDisabled` 返回 true 时不可用），给了 `openJsonEditor` 有 `edit-json`（打开 JSON 编辑框，`Mod+Shift+J`；只读时也能打开，编辑框里只能看与复制；同时给了 `settings` 时只在开发者模式开着时存在，关着时菜单栏、工具栏、右键菜单都不列它，快捷键也不响应），给了 `startTour` 有 `start-tour`（开始新手引导）。给了 `settings: { read, change, policy? }` 有两条开关式命令 `show-toolbar`、`show-status-bar`：勾选读 `toolbar.visible`、`general.statusBar`，执行时把那一条取反经 `change(context, key, value)` 写回；`policy` 里藏起或锁定了那一条（或它所在的分区）时不可用；另有一条菜单命令 `appearance`（外观），点开就是这两条。菜单栏常开，没有它的开关。落点：`save`、`settings` 在「文件」菜单，`edit-json` 在「编辑」菜单，`panels`、`pan-tool` 与 `appearance` 在「视图」菜单（`panels`、`pan-tool` 同时上工具栏），两条显示开关只在「外观」子菜单里，`start-tour`、`help`、`shortcuts`、`about` 在「帮助」菜单；`import-fields` 不排位置，各款放进面板头或菜单。文案取 `xh-designer-commands` 那一桶，图标由各款从 `@xihan-ui/icons` 传入。各款把它们并进自己的内置扩展；宿主不要哪一条，用 `commandLayout` 排掉 |
| `designerPanelCommands({ panels, frame })` | 每块面板一条开关命令 `panel:<面板 id>`（`designerPanelCommandId(id)`）：文字取面板标题，`checked` 是它此刻看得见，执行即 `togglePanel`；不上工具栏、不带快捷键，给 `commandLayout`、引导与扩展用。外框里没有这块面板或宿主锁定了它时不可用。`panels` 列设计器登记的面板与画布浮动件，含扩展登记的 |

两个铺法用到的 `<xh-toolbar>`、`<xh-context-menu>`、`<xh-tooltip>`、`<xh-icon>`，以及弹层命令与菜单命令用到的 `<xh-popover>`、`<xh-menu>` 按需注册。快捷键的命中用 designer-kit 的 `commandForShortcut`。

命令工具栏上的弹层命令与菜单命令（命令的 `panel` 与 `menu`，见 designer-kit 那一页的「弹层命令与菜单命令」）：

- 点按钮打开锚在它上面的 `<xh-popover>` 或 `<xh-menu>`（用两个组件的 `anchor`），再点一下收起，点别的弹层或菜单命令是换过去。弹层的 content 与菜单都以命令文字命名；弹层里放 `panel` 建出的元素，开着时每次 `update` 调它的 `update`，收起后调 `destroy`；菜单每次 `update` 按上下文重算条目与勾选。
- 按钮收在「更多」里时，从「更多」菜单里点它，打开的是同一块面板或同一张菜单，锚在「更多」钮上。开着的时候工具栏变窄把它收进「更多」、或变宽又放回来，弹层与菜单跟着换锚点，不关掉。
- 锚点按钮上的 `aria-haspopup`、`aria-expanded`、`aria-controls` 由弹层与菜单在展开期间写上，收起后还原；Escape 或点在外面收起时焦点回到锚点。
- 重铺按钮（分组变了）、命令不在了或此刻不可用时，开着的弹层与菜单关掉。
- 菜单里写成命令 id 的开关式命令（有 `checked`）是复选条目，勾照那条命令此刻的状态，点了执行它。
- 菜单里点了复选条目、菜单仍开着时，按点过之后的上下文重算条目与勾选，不必等设计器下一次 `update`。
- `open(id)` 打开一条弹层命令或菜单命令，给快捷键用：命令的 `run` 里调它；不是这两类命令、不在工具栏上或此刻不可用时返回 `false`。`close()` 关掉开着的那一个，`opened()` 是开着的命令 id。

四款都有的通用命令，文案收在 designer-shell 语言包的 `xh-designer-commands` 一桶里：撤销、重做（以及带上下一步说明的 `undoWith`、`redoWith`）、清空历史、剪切、复制、粘贴、创建副本、删除、全选，六种对齐、两种分布、四种层级，放大、缩小、适合窗口、实际大小，设计与预览，内置命令的保存、面板、拖动、设置、快捷键、关于、帮助、导入字段、编辑 JSON、开始引导与工具栏、状态栏两条显示开关及收着它们的「外观」，命令工具栏的名字 `toolbar`，以及菜单栏的名字 `menubar`、窄屏那颗钮上的 `menu` 与四张菜单的名字 `menuFile`、`menuEdit`、`menuView`、`menuHelp`。各款引用这一桶，不再各写一份；产品专属的命令仍写在各款自己的语言包里。

```ts
import { DESIGNER_COMMANDS_EN_US, DESIGNER_HISTORY_EN_US } from "@xihan-ui/designer-shell";
import { XhConfigController } from "@xihan-ui/web-components/authoring";

const config = new XhConfigController(designer);
const t = config.translations("xh-designer-commands", DESIGNER_COMMANDS_EN_US); // t.undo、t.alignCenter……
const history = config.translations("xh-designer-history", DESIGNER_HISTORY_EN_US); // 给 designerHistoryCommands 的 historyTranslations
```

### 菜单栏

菜单栏放通用的功能：保存、设置、关于、帮助这类，按菜单分组，下面是工具栏。命令照样来自命令表，用 `placement` 的 `menubar:<菜单 id>` 或排列落进某张菜单。

```ts
import { arrangeMenubar, collectMenubarMenus, createCommandMenubar, designerMenubarLayout, designerMenubarMenus } from "@xihan-ui/designer-shell";

const menubar = createCommandMenubar(document, { menuIcon: MenuIcon }); // 快捷键提示的平台缺省当场测
menubar.element.slot = "menubar";
frame.append(menubar.element);

// 内置四张在前，扩展的在后；每轮更新时排一次、铺一次
const menus = collectMenubarMenus(designerMenubarMenus({ translations: () => t }), host.list);
menubar.update(arrangeMenubar(menus, commands, designerMenubarLayout(commands), designer.commandLayout), commands, context, t);
```

| 函数 | 说明 |
| --- | --- |
| `designerMenubarMenus({ translations })` | 内置的四张菜单 `{ id, label, order }`：文件 `file`（0）、编辑 `edit`（10）、视图 `view`（20）、帮助 `help`（90），名字取 `xh-designer-commands` 的 `menuFile`、`menuEdit`、`menuView`、`menuHelp`；id 也在 `DESIGNER_MENUBAR_MENUS` 里 |
| `designerMenubarLayout(commands)` | 外壳认得的命令在四张菜单里的缺省排列，只留命令表里有的，空组去掉：文件是保存 / 打开文件 / 设置；编辑是撤销、重做 / 剪切、复制、粘贴、删除、创建副本 / 全选 / 编辑 JSON；视图是设计、预览 / 放大、缩小、适合窗口、实际大小 / 拖动 / 面板、外观（工具栏、状态栏两条显示开关收在这个子菜单里）；帮助是开始引导、帮助、快捷键 / 关于 |
| `arrangeMenubar(menus, commands, defaults, layout?)` | 排出菜单栏，返回 `{ menu, groups }[]`：菜单按 `order` 排（不写按 50，同值按登记顺序）；每张菜单照 `arrangeCommands` 的规则，位置是 `menubar:<菜单 id>`：`layout` 写了就只用它（给空数组就不要这张菜单），否则用 `defaults` 里这张菜单的排列，`placement` 落在这张菜单、又不在排列里的命令按登记顺序成一组，排在缺省排列的最后一组之前（最后一组是收尾，如文件菜单的设置；缺省排列不到两组时接在后面）。没有命令的菜单不出现；排列里写了没登记的命令 id 时抛 `TypeError` |
| `collectMenubarMenus(builtins, sources)` | 合起内置菜单与各来源（`{ id, menubarMenus? }`，扩展的 `menubarMenus` 字段就是这个形状）登记的菜单，内置在前。菜单 id 与内置的或彼此重名时抛 `DesignerExtensionError`，名字空间 `menubar-menu` |
| `createCommandMenubar(document, { platform?, menuIcon? })` | 一条数据模式的 `<xh-menubar>`（`menubar`），外面一层外壳（`element`，`data-scope="designer-menubar"`）。`update(menus, commands, context, labels)` 按排好的菜单铺：每张菜单一个入口，条目带图标、快捷键提示（按 `platform` 写，如 `Ctrl+S`、`⌘S`）、读屏念的 `aria-keyshortcuts`（同样按平台写，含第二快捷键）与不可用，组与组之间一道分隔线；开关式命令是勾选条目，选中即收起；菜单命令（如「面板」「外观」）是子菜单，里面就是它原来那张菜单，勾选与单选照菜单命令此刻的状态（写成命令 id 的开关式命令同样带勾），勾选条目选中即收起；弹层命令不进菜单栏（菜单条目当不了弹层的锚点），开发期报一条 `core.warn` 告警。选中条目执行命令（此刻不可用的不执行），子菜单的条目交给菜单命令的 `select`。数据没变时不重设；换了数据时开着的菜单不收、焦点不丢。每次打开菜单（换到另一张、点开窄屏那颗钮也算）都用最近一次 `update` 交来的命令表与上下文，按此刻的状态重算勾选与可用：状态变了而设计器没有刷新菜单栏时（如外框变窄收起面板），打开的菜单里也是对的。`labels` 是 `{ menubar, menu }`：整条菜单栏的名字与窄屏那颗钮上的字，直接交 `xh-designer-commands` 那一桶 |

- 条目的名字用命令的 `label`，不用 `shortLabel`。
- 菜单栏不进用户定制：设置的「工具栏」页只管顶部工具栏，菜单栏只由宿主的 `commandLayout` 改。菜单栏常开，设置里没有关掉它的开关。
- 窄屏（外框写着 `data-narrow`）时这一条收起，换成一颗「菜单」钮（`menu-trigger` 部件，文字取 `labels.menu`，给了 `menuIcon` 在前面铺图标），点开一张 `<xh-menu>`，每张菜单是它的一个子菜单，开关式命令的勾照样跟着状态，选中照样执行。
- 键盘照 `<xh-menubar>`：整条一个 Tab 位，左右键在菜单之间走，下键、Enter、Space 展开，展开后左右键换到相邻的菜单，Esc 收起回到入口；F10 进出菜单栏由外框接，见「外框」的「菜单栏」。

宿主自己的操作（新建、预览、打印、返回列表）写成一个扩展的命令，`placement` 写 `menubar:file` 就进「文件」菜单，常用的同时写 `toolbar` 上工具栏；保存用内置的 `save`，照旧接各款的 `save` 事件；模板标题写成设计器元素的子元素 `slot="menubar-center"`，保存状态写成 `slot="status-end"`，其他要常显的写 `slot="menubar-end"`，各款经 `forwardFrameSlots` 转进外框；状态栏在设置里关掉时，宿主放在状态栏里的内容跟着不显示。这样设计器外面不必另起一条操作条。

```ts
designer.extensions = [...presets, {
  id: "acme.host",
  commands: [
    { id: "acme.new", label: "新建", shortcut: ["Mod", "Alt", "N"], placement: ["menubar:file"], run: () => createTemplate() },
    { id: "acme.preview", label: "预览", placement: ["menubar:file", "toolbar"], run: () => preview() },
  ],
}];
```

没写进排列的宿主命令在「文件」菜单里另起一组，排在收尾的设置之前；要定位置时写 `commandLayout["menubar:file"]` 的整份排列。某张菜单不要时把它的排列写成空数组。

扩展的 `menubarMenus` 往菜单栏上加菜单 `{ id, label, order? }`，如打印的「插入」「页面」、报表的「数据」，`order` 写在 30–80 之间；命令经 `placement` 的 `menubar:<菜单 id>` 落进去，命令落到哪张菜单只看 `placement` 与排列，不看菜单由谁登记。

### 设置分区

扩展的 `settings` 是若干设置分区，形状见上文「设置」。用 `collectSettingsSections` 把各款自己的分区与扩展的合起来交给设置对话框；分区 id 与内建的 `general`、`layout`、`toolbar` 或别的扩展重名时抛 `DesignerExtensionError`（名字空间 `settings-section`）。

### 引导步骤

扩展的 `tourSteps` 是若干引导步骤，形状见上文「新手引导」，`order` 从 200 起，排在各款的步骤之后。用 `collectTourSteps` 把各款自己的步骤与扩展的合起来，按上下文用 `resolveTourSteps` 取好交给 `<xh-designer-tour>`；步骤 id 重名或用了 `shell.` 前缀时抛 `DesignerExtensionError`（名字空间 `tour-step`）。

### 关于

扩展的 `about` 是「关于」页里的几行 `{ label, value }`，如附加包的版本与授权；各款把它们接在自己那几行后面，交给设置对话框的 `about.rows`。

### 物料来源

扩展的 `paletteSources` 往物料面板里加几组，排在各款内置分组之后，如专业版的「我的物料」、行业模板。开源版不登记，就没有这几组。

```ts
import { collectPaletteSources, resolvePaletteSources } from "@xihan-ui/designer-shell";

const sources = collectPaletteSources([builtinExtension, ...extensions]); // id 重名时抛 DesignerExtensionError
const view = resolvePaletteSources(BUILTIN_GROUPS, sources, context); // 每轮刷新现取
palette.groups = view.groups;
palette.addEventListener("item-activate", (event) => {
  if (!view.insert(event.detail.id, context))
    insertKind(event.detail.payload); // 内置的物料照旧
});
// 画布放下时一样先问来源：view.insert(payload.id, context, 落点)
```

| 字段 | 说明 |
| --- | --- |
| `id` | 全局唯一，写法同命令 id；名字空间 `palette-source` |
| `order` | 先后：各款内置的分组在前，来源按它排在后面，不写按 100；同值按登记顺序 |
| `groups(context)` | 这一来源此刻的分组，形状同物料面板的 `groups`；组 id 与条目 id（含下级）在整个物料面板里唯一 |
| `insert(item, context, at?)` | 这一来源的条目被激活或拖到画布上放下：`at` 是放下处，激活时没有。插入怎么做由来源自己定，通常调设计器的 `paste(clip, { at })` |

| 函数 | 说明 |
| --- | --- |
| `collectPaletteSources(sources)` | 合起各来源（`{ id, paletteSources? }`，扩展本身就是这个形状）的物料来源，按 `order` 排；id 重名时抛 `DesignerExtensionError`，名字空间 `palette-source` |
| `resolvePaletteSources(builtin, sources, context)` | 返回 `{ groups, insert(itemId, context, at?) }`：`groups` 是内置分组在前、各来源按上下文现取的接在后面；`insert` 在条目（含下级）属于某个来源时交给它的 `insert` 并返回 `true`，内置条目返回 `false`。组 id 或条目 id 重名时抛 `TypeError` |

落点 `at` 的形状由各款定（流程是画布坐标，打印还带页与带区），在扩展类型上写：`DesignerShellExtension<Ctx, Editor, Doc, RuleCtx, At>` 的最后一个类型参数。

### 导入来源

`importSources(data, kind)` 把粘贴事件的 `clipboardData` 或拖放事件的 `dataTransfer` 列成导入来源：先是每个文件（带类型与文件名），再按链接、HTML、纯文本的顺序列出不为空的文本。交给 designer-kit 的 `findImporter`，挑出第一个接下的导入器。

```ts
import { findImporter } from "@xihan-ui/designer-kit";
import { importSources } from "@xihan-ui/designer-shell";

canvas.addEventListener("drop", (event) => {
  const found = findImporter(model.importers, importSources(event.dataTransfer!, "drop"));
  if (!found)
    return;
  event.preventDefault();
  void found.importer.import(found.source, context).then(place);
});
```