ui / 界面扩展总览

文档：vjcad/doc/ui/index.md 示例：vjcad/example/ui/01ribbon.js ~ 16menucustom.js

UI 模块覆盖三类需求：

1. 现成 UI 组件 —— 用 Toast / 对话框 / 选择器与用户交互，不写 HTML
2. 可插拔扩展点 —— 把自己的按钮、面板、菜单插入到 vjcad 主界面
3. 整体外观与模式 —— 改主题、改状态栏、切换查看 / 编辑模式

1. 子文档结构

菜单与 Ribbon 由插件 / MainView 配置统一驱动，已在 plugin/menu-ribbon.md 详述，不再重复。

2. 入口 API 速查

// 消息提示（Toast）
message.info('完成');  message.success('保存成功');
message.warn('注意');  message.error('失败原因');

// 命令行打字（HTML 片段）
writeMessage('<br/>已创建实体');

// 对话框（输入 / 选择 / 确认 / 提示）
await showInputDialog({ title, label, defaultValue, validator });
await showSelectDialog({ title, options, defaultValue });
await showConfirm('确定删除？', '删除确认');
await showInfo('已完成');
await showWarningConfirm('不可撤销，确定？');
await showError('保存失败');

// 选择器
await new ColorPanelDialog().startColorDialog(opt);
await new LineTypeDialog().startLineTypeDialog(opt);
await new PatternPickerDialog().startPatternDialog(opt);
await new BlockNameDialog().showBlockNameDialog(name);       // 不是 startXxxDialog
await new LayerNameDialog().showLayerNameDialog(name);       // 不是 startXxxDialog

// 自己写组件
class MyDialog extends ModalDialogBase { /* renderContent */ }
class MyPanel extends ModelessPanelBase { /* renderContent */ }
class MySidebar extends BasePanelComponent { /* render */ }
const tb = createFloatingToolbar('id', { items: [...] });

// 主题 / 状态栏
Engine.THEME_MODE = 0;          // 画布主题 0=深色，1=浅色（自动 setBgc，不改 UI 外壳配色）
Engine.setThemeColors({ accent: '#2563eb' });   // UI 外壳配色（--theme-color-* 变量）
Engine.setBgc(0);               // 画布底灰度 0~255；0=默认深色 #212830，255=白
Engine.ORTHOMODE  = 1;          // 正交
Engine.GRIDMODE   = 1;          // 栅格
Engine.OSMODE     = 1023;       // 对象捕捉位掩码：1~512 全开；|= 16384 为关闭（0xFFFF 含此位=关）

// 整体模式
new MainView({ viewMode: 'viewer', showUcsIcon: false, showAxis: false });

3. 心智模型

flowchart TB
    subgraph 内置
        T[Toast / Message]
        D[Dialogs / Pickers]
        CM[ContextMenu]
    end
    subgraph 可扩展
        SR[SidebarPanel<br/>BasePanelComponent]
        FT[FloatingToolbar]
        PV[PreviewView]
        MD[ModalDialogBase / ModelessPanelBase]
    end
    subgraph 整体
        TH[Theme / StatusBar]
        VM[viewMode]
        MO[CadMapOverlay]
    end

    User[(开发者)] --> 内置
    User --> 可扩展
    User --> 整体

4. 共同的红旗

• 大多数对话框 / 弹层走 Lit + Shadow DOM，外部 CSS 选择器不能穿透；整体配色用 setThemeColors 改 --theme-color-* 变量，单个自定义组件在自己的 static styles 里改（见 dialogs）
• await showXxx / await dialog.show() 只能拿用户结果；想在对话框里继续与 CAD 交互（拾取点 / 选择实体），必须 baseDialog.suspend()/resume()，且对话框 必须在命令上下文里弹出
• viewMode: "viewer" 默认会把多个 UI 组件一并隐藏；若只想关菜单别忘了同时设置 enableContextMenu / showGrips
• Engine.THEME_MODE 是画布主题：setter 自动 setBgc(0|255)，但不改 UI 外壳颜色；UI 配色走 MainView themeColors 配置或 setThemeColors(partial)
• 浮动工具栏 / 侧边栏 / 模态对话框基于 Web Components，自定义元素 tagName 必须包含 -

参考（官方文档 MCP）

• 文档：vjcad/doc/ui/index.md
• 示例：vjcad/example/ui/01ribbon.js ~ 16menucustom.js