# soui-vsix

**Repository Path**: setoutsoft/soui-vsix

## Basic Information

- **Project Name**: soui-vsix
- **Description**: SOUI在VSCODE中实现预览的插件。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-09
- **Last Updated**: 2026-05-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SOUI Workbench

SOUI Workbench 是 `SOUI-Extension` 的下一版重构项目，目标是把 SOUI XML 编写、资源管理、原生预览和项目工具做成一个更完整、更可维护的 VS Code 扩展。

## 已实现能力

- SOUI XML 智能补全：控件标签、属性、枚举值、布尔值、布局尺寸模板、资源引用、系统 ID、样式类、字体、模板、布局名。
- 资源跳转与悬停预览：支持 `@string/`、`@color/`、`@skin/`、`@style/`、`img:name`、`icon:name:size`、`file:` 和 XML 文件引用。
- 可视化设计器：提供控件 Palette、图层树、设备画布、缩放、网格、边界显示、节点选中与源码联动。
- 设计器直接操控：支持从 Palette 拖放控件到画布落点，拖拽移动控件，使用尺寸手柄缩放控件，支持 10px 吸附、临时关闭吸附和实时尺寸反馈。
- 设计器多选编辑：支持 Ctrl/Shift 多选控件，批量拖拽移动、批量方向键微调，并用单次 XML 编辑写回多个 `pos` 属性。
- 设计器辅助线：移动控件时可对齐画布边缘、中心线和其他控件边/中心，显示临时参考线。
- 设计器写回 XML：可从 Palette 向当前节点插入控件，可把移动/缩放结果写回 `pos` 属性，也可在属性面板中修改或删除当前节点属性。
- 设计器编辑效率：支持画布方向键微调，`Shift` 加速移动/缩放，`Alt` + 方向键调整尺寸，并提供撤销/重做入口。
- 原生预览：`SOUI: Open Native Preview` 在 VS Code 面板内显示 SOUI native helper 的真实 runtime 渲染，当前输出 BMP 帧和控件矩形元数据，支持预览点击定位源码，也支持源码光标反向高亮预览元素；预览面板可切换 helper 控制的单会话 runtime 尺寸 preset。
- Runtime 尺寸矩阵：`SOUI: Capture Runtime Size Matrix` 会对当前 XML 注入 `data-preview-source-id` 后逐个启动 native helper 尺寸会话，保存每个 preset 的 BMP frame、metadata、source-id map 和 Markdown 报告，并基于 helper metadata 生成跨尺寸 runtime rect/children rect/LayoutParam 变化摘要；`SOUI: Open Latest Runtime Size Matrix Report` 和 `SOUI: Reveal Latest Runtime Size Matrix Output` 可重新打开最近一次捕获产物。这不是 Webview 缩放截图，也不会解释未由 SOUI runtime 输出证明的布局原因。
- 运行期元数据：`SOUI: Show Runtime Metadata for Selection` 可查看 helper 输出的 runtime class、layout、LayoutParam、控件矩形和子布局区域；`SOUI: Copy Runtime Metadata for Selection` 以及设计器 Inspector 的 Show runtime / Copy runtime 入口可打开或复制同一份 helper 原始映射报告，便于审查和回归记录。
- 运行期 skin 元数据：native helper 会通过 SOUI `GETSKIN` 解析控件的 `skin` / `ncskin` 属性，并在 runtime metadata 中输出 `ISkinObj` 的名称、类型、尺寸、状态数、alpha 和 scale；设计器 Inspector 会只读展示这些 helper 字段。这只是 SOUI runtime 对象 metadata，不模拟九宫格或 stretch 绘制。
- 运行期能力报告：`SOUI: Show Runtime Capability Report` 会列出当前已由 helper 支撑、仅受限支持和必须等待 helper/runtime 扩展的设计器能力；Workbench 自检也会输出同一份边界报告。
- SOUI 资源浏览器：从 `uires.idx`、`init.xml`、系统资源和当前打开的 XML 文档聚合资源索引。
- SOUI 资源管理：支持新建已确认 XML 资源文件、导入资源文件、安全重命名资源项、安全删除无引用资源项、引用扫描和删除影响分析；所有引用判断都复用 SOUI 资源解析目标。
- Include/Layout/Template 重构：支持打开 include/资源目标、分析 XML 重命名前影响，把单个非根 XML 元素安全提取为新的 `<include>` 布局资源，或追加到已解析的 SOUI `<template>` 资源池并替换为 `<t:name><data /></t:name>` 调用。
- 属性检查器：跟随编辑器光标显示当前 XML 节点属性，并可直接修改或删除属性。
- XML 诊断与定位：轻量检查标签闭合、重复属性和无法解析的资源引用；结构编辑入口会拒绝闭合标签不匹配、未闭合节点和多个顶层元素；资源/模板定义解析会保留 XML 声明和前置注释后的真实文件行号。
- 发布验证：提供 smoke、Webview contract、Webview DOM、Extension Host、VSIX 打包和 Windows CI 工作流，发布前会覆盖 native helper 真实 demo 成功矩阵、失败样例、Webview 消息/交互契约与核心命令注册。
- 项目工具：创建脚手架项目、选择 SDK、发现 `.soui-project.json`、调用项目 `build.bat`、编译后调试。
- 更清晰的模块拆分：语言服务、资源索引、元数据、预览、项目工具、视图、诊断分离。

## 使用方式

```powershell
npm install
npm run compile
npm run compile:native
npm run test:smoke
npm run test:webview-contract
npm run test:webview-dom
npm run test:extension-host
npm run package:vsix
npm run verify:release
```

在 VS Code 中按 `F5` 启动扩展开发宿主，然后打开 SOUI 工程或 SOUI XML 文件。

## 运行时约定

- 默认从 Workbench 自带 `metadata` 或配置项 `souiWorkbench.metadataDir` 加载控件元数据；动态提取脚本也内置在 Workbench 的 `tools/` 目录中，只把当前 SOUI workspace 当作源码输入。
- 设计器 Webview 只作为结构和几何编辑面板，不作为 SOUI 真实效果来源。
- 真实预览的主体验必须留在 VS Code 面板内；后续优化应优先把截图文件轮询升级为 helper-backed 帧流和输入桥接，而不是把外部原生窗口作为默认设计器体验。
- 真实像素效果、控件矩形和源码映射必须来自 SOUI runtime/native helper；未找到 helper 时预览命令会明确失败，不会降级为近似效果。
- 原生预览需要 `soui-native-preview-helper.exe` 以及包含 `soui-sys-resource.zip`、`simsun.ttc` 的 SOUI SDK/source 根目录；可通过 `souiWorkbench.helperPath` 和 `souiWorkbench.sdkRoot` 显式配置。
- C++ helper 源码位于 `native-helper/`，默认构建 target 为 `soui-workbench-native-preview-helper`，输出到 `bin/win32-x64/soui-native-preview-helper.exe`，扩展会优先发现该位置。
- 不确定的布局、资源、皮肤或控件行为必须查 SOUI 源码或 helper 输出后再实现。
- `SOUI: Show Runtime Capability Report` 是当前 runtime 边界的可运行清单；其中标为 blocked 的项目不能通过 Webview 近似效果绕过。

## 仍受源码/helper 边界约束的方向

- skin 基础运行期对象 metadata 已由 helper 输出；九宫格、stretch、每个状态对应的源图区域等最终绘制语义仍需要 SOUI runtime/helper 暴露更多字段，不能用 Webview 模拟 skin 渲染。
- 跨容器移动、包裹/解包时的 LayoutParam 自动转换仍保持禁用，直到每种父布局之间的转换规则完成源码和 runtime 双重验证。
- 当前原生预览支持单个 helper 会话的 runtime 尺寸 preset，也支持按 preset 顺序捕获 helper-backed 尺寸矩阵；并行“多设备 live 预览”只能在 helper 提供多会话生命周期编排后实现，Webview 设备画布不会冒充 SOUI runtime 多设备渲染。