维声 文档
dotnet9
维声 / 文档 / Vox 原型与 Avalonia 实现对齐清单

Vox 原型与 Avalonia 实现对齐清单

⏱ 预计阅读 8 分钟 平台:windows / macos / linux 同步于 2026-11-08 来源: Vox · docs/原型实现对齐清单.md ✎ 在 GitHub 编辑此页

基准:design/Vox.html + design/assets/tokens.css + design/assets/app.css;Markdown 源码/阅读/脑图控件实现以 dotnet9/Vex 的 main 分支最新固定实现为共享控件基线。 本清单区分“代码中存在对应功能/结构”与“已通过截图证明像素一致”。后者必须在相同窗口尺寸、主题、密度和内容数据下运行应用并截图比对;静态读代码不能替代视觉验收。

视觉基线

项目 原型基准 当前实现核对
主窗口 1280 × 830,圆角窗口容器 MainWindow 默认尺寸 1280 × 830;最小尺寸 1080 × 660。Avalonia 窗口外框、系统缩放与网页容器并非同一渲染环境,需截图验收
标题栏 42px;品牌、文件/帮助菜单、当前文件与发布状态、MCP/搜索/外观/语言、窗口按钮 42px 自绘标题栏与对应操作存在;已补回 MCP 快捷入口和运行状态点;需继续核对图标、间距、菜单弹层宽度与标题栏项目压缩行为
左导航 展开 196px、折叠 56px;七个工作区;圆角卡片 已有七工作区与展开/折叠;宽度 196/56。计数徽标、选中态和导航内边距需截图比对
页面基准 页面常规内边距 18px;暖白/浅灰背景、细边框、轻阴影 各页面主要容器多使用 18px;需逐页检查滚动区、页头与卡片之间的垂直节奏
字体 Geist / Inter / Segoe UI;代码 Cascadia Code / Geist Mono;根字号 13px,密度 12/13/14px VoxTheme 提供字号密度令牌,代码字体有回退链;需核对实际字体是否随包部署、缺字回退和各页硬编码字号
Arc / Pixel 外观弹层有 Arc / Pixel 两种风格 已新增持久化风格选择;Pixel 将 VoxStyles 中已接入令牌的控件圆角置零。代码中直接设置的个别圆角与 Arc 控件内部模板尚未完全覆盖,列为视觉回归项
明暗/强调色/动效 亮/暗/跟随系统;八种强调色;完整/减弱/关闭 已通过 ArcTheme / ArcMotion 与 VoxTheme 桥接;需检查所有自绘图表、代码编辑器和 Markdown 预览在暗色下的对比度

七个工作区

工作区 原型元素 当前实现代码 当前判断
写作 250px 文件列表;源码/分屏/预览/导图四态;自动保存状态;AI 助手;正文排版;导图布局/样式;大纲/任务/跳转面板 WritePage.cs:与 Vex 共用 CodeWF MarkdownEditorView、MarkdownViewer、MarkdownMindMapView;四态模式;排版字号与主题持久化;导图布局/样式选择;文件列表和可拖动大纲 功能结构基本齐全。文件列表/大纲宽度与间距、编辑器行高/行号/语法色、预览排版细节、导图节点/连线/画布背景必须截图验收
文章库 页头、四张统计卡、年份/分类/文章状态/平台状态筛选、全文搜索、文章表格、平台发布状态、分页/行操作 LibraryPage.cs:统计卡桌面四列/窄窗两列、Arc Select 筛选、Arc Input 搜索、DataGrid、状态列与行操作 对应主要功能已存在;统计卡已按原型实现桌面四列、900px 以下两列。原型表格列宽、行高、筛选栏高度和分页视觉需核对
图片库 页头操作、四张统计卡、年份/引用/格式筛选、搜索、缩略图网格、引用详情面板、孤儿清理 ImagesPage.cs:统计卡桌面四列/窄窗两列、Arc Select/Input、自适应 minmax(150px,1fr) 缩略图卡片、详情与引用列表、清理流程 对应主要功能已存在;统计卡已与原型同步为桌面四列、窄窗口两列。原型缩略图卡片尺寸/列间距、右侧详情宽度、选中边框与空状态需核对
发布中心 网站 Git 同步、多平台矩阵、发布前检查、发布历史;变更列表/diff/提交面板/最近提交 PublishPage.cs:四个分页、Git 同步与 diff、提交/推送、平台矩阵、预检、历史 对应主要功能已存在。两栏比例、右侧提交表单、矩阵行高/列宽、状态颜色、日志密度需截图验收
站点数据 左侧 JSON 文件导航;右侧表格/编辑器;新增、编辑、校验与保存 SiteDataPage.cs:文件选择、JSON 数据编辑与保存 业务结构存在。需逐种 JSON 形态核对原型的导航宽度、表格列宽、编辑表单和校验反馈
MCP 服务 服务状态/配置、授权范围、客户端、工具目录、调用审计 McpPage.cs:服务、客户端、工具目录、审计等分页和真实 MCP 状态 对应主要功能存在。配置双栏、代码片段、状态徽标、表格和危险操作区需截图验收
设置 写作保存、仓库、链接策略、Git/凭据、平台账户、LLM、MCP、外观 SettingsPage.cs:对应设置分组、Arc 按钮/Input 与配置操作;外观快捷入口在标题栏 需核对分组宽度、行高、标签/描述比例、表单控件高度和各设置区块垂直间距

Markdown 编辑器与阅读体验

能力 原型表现 当前实现 待验证/差距
Markdown 源码 独立源码卡、等宽字体、行号/语法高亮、滚动与编辑 CodeWF MarkdownEditorView(与 Vex 同控件);沿用控件默认 Cascadia Mono 字体栈、15px 字号和默认行高,24/22/24/60 内边距;MarkdownEditorPalette 的背景/前景/当前行/语义 token/行号/当前行号/Marker 资源键均由 VoxTheme 同名资源覆盖 已核对 CodeWF 12.2.44 的真实资源键:CodeWFMarkdownEditorLineNumberBrush、CodeWFMarkdownEditorCurrentLineNumberBrush、CodeWFMarkdownEditorMarkerBrush 均已接入 VoxTheme;Vox 的 CodeWF.Avalonia.Lang 与 DataGrid 包版本也已提升到 Vex 当前基线 12.2.44 / 12.2.31。仍需截图核对行号、缩进、选区/光标、暗色和语法 token 的实际效果
实时预览 Markdown 正文排版,标题/段落/列表/引用/代码/表格/图片 CodeWF MarkdownViewer,绑定 Vox 语义画刷与增量渲染;非演示阅读/分屏态统一按 Vex 当前实际执行规则使用 max(800px, 42vw) 与 32/24/32/56 留白;正文密度 13/15/17px 同步映射共享控件 Compact/Normal/Relaxed 档,标题按正文 1.7/1.25/1.1 倍缩放,代码字号 12.5px,代码行高沿用共享控件默认值 已移除固定 780px/30px 几何,改为随窗口尺寸与阅读/分屏模式更新,模式切换和预览尺寸变化时重新计算;仍需在目标窗口尺寸截图核验居中、窄窗边距和内容宽度,并继续对照段距、标题层级、引用背景、表格和图片边距及暗色主题
阅读样式 简约等排版主题选择;字号紧凑/标准/宽松 MarkdownTheme + MarkdownSize 持久化,预览控件应用 TypographyTheme / ParagraphFontSize / ParagraphLineHeight 已按原型修正行距:常规主题 1.85、书卷(InkBlack)2.0;H1/H2/H3 按正文的 1.7/1.25/1.1 倍缩放,紧凑/正常/宽松切换时同步更新。五种主题的标题强调色已解除全局 VoxAccent 覆盖并对齐原型:简约跟随正文色、文档/技术蓝 #376C9A、书卷 #70604F、公众号 #24766B;书卷主题已切换 Noto Serif SC / Songti SC / SimSun 衬线字体栈;正文行宽、书卷首行缩进、文档 H2 下划线、公众号标题居中和代码/引用细节仍需逐项核对
导图 点阵画布、标题/内容节点图例、拖拽/缩放/节点编辑提示、布局与节点样式菜单 MarkdownMindMapView,绑定 Vox 颜色资源,支持六种布局和六种节点样式;MindMapLayout、MindMapStyle、MapZoomPercent 持久化,默认 Right + Quiet + 100%;缩放范围 1%–200% 已补齐与 Vex 一致的布局/样式/缩放设置键;用户调整画布缩放后即时保存,重启恢复;Accent/Success/Warning 色值和缩放边界已接入。仍需核对各布局/样式实际渲染、节点尺寸/连线和空白布局,并在运行环境截图验收
分屏 源码与阅读预览并排,6px 分隔条可拖 Grid 双栏 + 6px splitter 检查初始比例、最小宽度、拖动手感、窄窗口降级行为和滚动同步

已发现并已补齐

  • 外观弹层缺少原型中的 Arc / Pixel 风格选项:新增 VoxSettings.UiStyle、持久化切换和四语标签。
  • Pixel 模式已接入 Vox 自有控件圆角令牌(按钮、输入框、分段、导航、菜单、弹层、卡片、缩略图等);不覆盖 Arc 控件模板。尚有直接写死圆角的少数自绘元素待逐项纳入,不能将 Pixel 视为完整 CSS 选择器移植。
  • 写作页大纲面板默认宽度已从 292px 调整为原型 300px。
  • Markdown 源码编辑器已接入 Vox 明暗/强调色调色板,并按原型调整字号、行距、上下留白和行号区宽度;主窗口现在先应用主题资源再构造页面,避免首屏落入默认蓝色配色。
  • Arc Select/Input 已替换文章/图片/发布等页面的部分自定义筛选和搜索控件。
  • 文章库与图片库统计卡均为桌面四列、窄窗口两列;图片缩略图按可用宽度动态计算列数与卡片宽度。

下一轮视觉验收顺序

  1. 在 1280 × 830、100% 缩放、Arc 风格、标准密度、亮色主题下,分别截取七个工作区。
  2. 写作页再分别截取源码、分屏、预览、导图四态;预览逐一截取排版主题,导图逐一截取布局与样式。
  3. 对每张截图与原型同视口截图做叠图/差异图;优先修正大区块边界、宽高、内外边距,再修字体、行高、图标、边框和阴影。
  4. 再覆盖 Pixel、紧凑/宽松、暗色和不同窗口宽度;检查控件焦点、悬停、禁用、空状态、弹层和滚动状态。
  5. 每轮修改后运行 dotnet restore、dotnet build 与相关测试;如果环境无法运行桌面 UI,则明确记录“未做截图验收”,不能把静态尺寸核对说成像素级通过。