企业官网建设流程全解析

• 桌面应用
• 虚拟化

本篇技术指南以 WinBoat 仓库内置的 Xel 组件工具包变更日志 src/renderer/public/xel/CHANGELOG.md 为主线，结合仓库内实际源码、主题文件与使用场景，系统梳理 Xel 从 0.9.0 重写至 0.36.2 的完整演进脉络。读完本文，你将掌握 Xel 各版本的主题体系、组件 API、破坏性变更、国际化与颜色系统等关键知识点，并能在 WinBoat 的 Electron 渲染进程中正确使用与维护这套以x-前缀自定义元素为核心的桌面级 UI 方案。

一、CHANGELOG 定位：Xel 是什么，为什么 WinBoat 要内置它

Xel 是一个用于构建"类原生"体验的 HTML5widget 工具包，面向 Web、Electron 与 Hybrid 应用。其官方说明（见 src/renderer/public/xel/README.md）强调它遵循 Keep It Simple 原则，仅用原生 JavaScript、HTML 与 CSS 编写，不依赖任何预处理器或重型抽象层。仓库内的 package.json 记录其当前版本为0.36.2，核心产物为浏览器入口xel.js。

WinBoat 正是以 Electron 渲染进程的方式引入 Xel 的：在 src/renderer/index.html 中通过<script src="./public/xel/xel.js" type="module">加载运行时，并通过三个<meta>标签声明主题、图标集与强调色：

<meta name="xel-theme" content="./xel/themes/fluent-dark.css" /> <meta name="xel-icons" content="./xel/icons/fluent.svg" /> <meta name="xel-accent-color" content="#A78AF9" />

也就是说，CHANGELOG 记录的是 WinBoat 桌面 UI 的"地基"——每个版本号背后，都对应着界面元素行为与样式的真实变化。因此这份日志不仅是 Xel 上游的发布记录，也是 WinBoat 前端排障、升级与定制时的第一手参考资料。

二、版本脉络总览：一条从 "重写" 到 "桌面级" 的演进线

CHANGELOG 的开端是0.9.0 (2021-04-06)："Project rewrite using the latest Web Platform APIs"——使用最新的 Web 平台 API（自定义元素、Shadow DOM、Pointer Events 等）重写整个项目，这是后续所有能力的基础。此后演进可以归纳为几条主线：

从源码结构看（src/renderer/public/xel/themes/ 目录），Xel 采用base.css基础样式 + 8 个平台主题 CSS（adwaita / cupertino / fluent / material 及其 dark 变体）的组合方式；图标方面（src/renderer/public/xel/icons/ 目录）则内置 fluent、fluent-outlined、material、material-outlined 四套 SVG 图标集，WinBoat 选用的是 fluent 图标集。

三、主题体系演进：从 GTK 风格到 Win11 视觉规范

Xel 的主题发展在 CHANGELOG 中线索清晰，也是 WinBoat 选用fluent-dark.css的原因所在：

• 0.12.0：新增Adwaita / Adwaita Dark主题，同时移除 Vanilla 主题——主题体系从"自有风格"转向拥抱 GNOME 平台规范。
• 0.29.0：Fluent 主题更新以匹配最新 Windows 11 UI 指南，同时支持宽色域（wide gamut）强调色。WinBoat 的界面呈现正是建立在这次对齐之上。
• 0.31.0：新增Material 与 Material Dark主题，补齐 Google 设计语言阵营。

主题细节上的持续打磨同样体现在日志中：

• 0.32.0：使用Adwaita Sans（Inter）替换 Cantarell 字体族——通过替换默认字体影响所有主题的观感。
• 0.33.2：字体尺寸单位从px全面切换为rem，使字号能随根元素缩放，利于无障碍与高 DPI 场景。
• 0.33.4：简化 Material 主题的 slider 样式，并允许 Material 主题使用灰色强调色（此前被排除）。
• 0.33.5：修复 Material 主题更换强调色时标题栏颜色未同步更新的问题。
• 0.34.6：修复Material 主题子主题颜色错误的问题——除非子主题文件名以material开头，否则颜色会不正确。这提示我们在引入自定义子主题时必须遵守命名约定。
• 0.32.1：修复压缩（minified）版主题缺少部分样式的问题；0.33.3修复 Firefox 下滚动条未应用样式的问题。

在 WinBoat 仓库中，主题文件真实存在于 src/renderer/public/xel/themes/（base.css+ 8 个平台主题），渲染进程通过xel-thememeta 标签指向fluent-dark.css，对应 CHANGELOG 中 Fluent 主题与 Win11 指南对齐的定位。

四、组件 API 演进：新增、重构与破坏性变更

CHANGELOG 的最大价值在于完整记录了组件生态的演进。以下按类型归纳。

4.1 新增组件时间线

4.2 破坏性变更汇总（升级必读）

CHANGELOG 中以[Changed API]、[Changed API]或移除说明标注的变更，是升级时最容易踩坑的部分：

• 0.11.0：移除<x-doctabs>与<x-doctab>。
• 0.14.0：<x-icon>由name+iconset属性改为href="path#id"；<x-message>由name="id"改为href="#id"；新增Xel.queryIcon()/Xel.queryMessage()，并将Xel.iconsetElements与Xel.localesBundle转为私有。
• 0.16.0：<x-input>/<x-texteditor>的error与validate()被重构——error变为只读布尔，自定义错误改由setCustomValidity()设置；validate()改名为reportValidity()（0.16.1 起返回布尔校验状态）；<x-numberinput>/<x-tagsinput>移除required与error。
• 0.22.0：移除全局尺寸体系——<meta name="xel-size">、Xel.size、Element.computedSize及smaller/larger相对尺寸全部删除。
• 0.27.0：图标集更名——<meta name="xel-iconsets">→<meta name="xel-icons">，Xel.iconsets→Xel.icons，Xel.whenIconsetsReady→Xel.whenIconsReady，事件iconsetschange→iconschange。
• 0.29.0：<x-tab>的selected改名为toggled；移除<x-numberinput>的condensed、<x-throbber>的type、<x-button>的circular与nav皮肤。
• 0.30.0：移除<dialog>元素的手动定位支持。
• 0.31.0：移除<x-slider>的vertical与buffer属性。
• 0.32.0：内边距由子元素<main>直接设置到<x-card>/<x-popover>/<dialog>本体；<x-accordion>不再强制要求子<main>才能展开；强调色预设graphite更名为gray；按钮皮肤default更名为normal，<x-button>的size默认值改为normal。

这些条目提示：当 WinBoat 升级 Xel 时，应重点检查x-元素的属性拼写与默认值，例如 WinBoat 在 App.vue 中通过@buttonclick事件处理标题栏按钮（对应 0.30.0 新增的<x-titlebar>），其事件语义与属性名必须与新版本 API 保持一致。

4.3 菜单与菜单栏：投入修复最多的组件

菜单系列是 CHANGELOG 中占比最高的修复对象，侧面说明它是桌面类应用 UI 中最复杂、最敏感的部件：

• 0.28.0：<x-menubar>新增expand/collapse事件。
• 0.34.0：顶层菜单项放不下时显示省略号；无子菜单的<x-menubar>子项按按钮行为处理。
• 0.34.1 / 0.34.2 / 0.34.5：修复<x-menubar>无子节点时报错、多种边界情况下不更新布局的问题；0.34.4修复省略号可能溢出窗口边界；0.34.7增加两次菜单栏更新之间的间隔。
• 0.36.0：新增aside命名插槽，并将省略号字符替换为 "Midline Horizontal Ellipsis"；0.36.2（当前最新版本）修复 Firefox 下slot="aside"更新失败。
• 0.33.6：当后代菜单项被程序化触发时高亮对应顶层菜单项。
• 0.35.2：修复触屏输入下<x-contextmenu>阻止部分指针事件的问题；0.33.8修复关闭已断开连接的<x-contextmenu>时抛错；0.17.2修复短时间频繁打开上下文菜单导致应用冻结；0.25.7修复 WebKit 下无法关闭模态 popover。

值得特别指出的是，WinBoat 仓库中 WBContextMenu.vue 与 WBMenuItem.vue 正是为绕开 Xel 上下文菜单组件缺陷而写的重实现（其头部注释明确写着 "Replacement for broken xel contextmenu component ... which has bugs in the library that prevent proper functionality"）。这与 CHANGELOG 中x-contextmenu频繁出现修复条目的记录相互印证——即便到了 0.35.2，触屏场景仍有问题，WinBoat 因此选择在组件层自行接管上下文菜单的定位、点击关闭与越界修正逻辑。

4.4 输入类控件：交互细节的持续打磨

• <x-numberinput>：0.19.2 使用步长精度（大于值精度时）；0.21.2 修复数字字形宽度不一致；0.27.1 内边距可配置；0.28.3 正确丢弃无效值；0.28.5 修复禁用态仍可编辑；0.33.3 修复失焦抛错；0.33.9 值溢出可视区域时显示省略号；0.18.1 与 0.09.11 修正与<x-input>/<x-stepper>的一致性；0.09.1 修复焦点切到<x-stepper>时值未正确设置。
• <x-tagsinput>：0.28.14 与<x-input>外观统一；0.28.15 退格删除标签时停止键盘事件传播；0.20.8 修复遗留尾随逗号；0.33.2 修复输入值时内边距变化；0.24.1 修复 WebKit 无法聚焦。
• <x-texteditor>：0.28.6 修复修改值后光标位置错误；0.33.3 失焦时清除当前文本选区；0.16.2 修复边界情况下 tooltip 不显示。
• <x-checkbox>：0.28.8 修复 WebKit 下边界情况更新失败；<x-select>：0.33.3 修复边界情况下 z-index 错误。
• <x-slider>：0.33.0 新增ticks；0.33.4 简化 Material 主题样式；0.33.6 修复 WebKit 下宽度错误；0.21.1 修复禁用态仍可聚焦。
• <x-stepper>：0.20.2 修复左右键同时按下卡住；0.33.0 修复 Fluent 主题下<x-numberinput>内过大。
• <x-throbber>：0.28.4 修复改变hidden属性时动画冻结；0.21.3 修复 WebKit 下环形动画渲染。
• <x-input>：0.24.4 修复 WebKit 下type="search"不派发change事件；0.17.3 修复<x-tooltip>置于<x-input>内时不显示。

4.5 弹层与指针事件：桌面体验的关键细节

• <x-drawer>：0.33.7 修复 Firefox 与 Safari 下的错误位置；0.33.0 修复 Fluent Dark 下背景误为白色。
• <dialog>：0.20.6 修复 Safari 下打开造成布局偏移；0.20.9 移除聚焦轮廓；0.33.10 修复永久覆盖<html>/<body>的overflow内联样式；0.09.8 修复点击 popover 背景误关闭对话框。
• <x-popover>：0.19.3 在所有open事件监听器触发后解析几何；0.20.1 点击背景自动关闭独立模态 popover；0.20.3 修复置于 shadowRoot 内时行为异常；0.24.2 修复切换主题时箭头样式未更新。
• 指针事件：0.22.2 修复因 Chromium bug #1166044 导致pointerup不触发；0.22.3 / 0.22.4 / 0.22.5 / 0.22.6 一系列指针捕获与光标图像修复；0.35.1 修复合成lostpointercapture事件丢失event.isPrimary；0.33.7 修复触屏输入无法展开菜单；0.22.1 修复数字小键盘回车键检测。

五、国际化、本地化与消息系统

0.13.0 是国际化里程碑：引入Xel.localesAPI 与<x-message>元素，支持 FTL（Fluent）本地化文件；<meta name="xel-iconset">随之更名为复数形式xel-iconsets。后续演进：

• 0.14.0：<x-message>改为href="#id"语法；Xel.queryMessage()提供按 id 查询。
• 0.15.0：<x-message>新增autocapitalize布尔属性。
• 0.17.0：新增Xel.localesIdsgetter 与 FTL 函数RELDATETIME；<x-message>新增ellipsis属性；修复向<x-message>参数注入不可见 Unicode 字符的问题。
• 0.18.0：Xel.localesIds替换为Xel.locale，返回解析后的 locale 标签（如en-US）。
• 0.19.0：消息参数新增os（操作系统标识）。
• 0.25.9 / 0.25.10：修复无法将完整 URL 作为<x-message>参数、blob URL 中语言参数被忽略的问题。
• 0.28.11：允许 Fluent 本地化文件中出现unknown选择器。
• 消息渲染细节：0.13.2 修复复合消息渲染、0.13.1 修复数值参数被当作字符串、0.14.0 修复置于等宽文本中时产生多余空白。

六、图标系统：从单集到多集再到xel-icons规范

图标 API 经历了两次关键变化：0.14.0 将<x-icon>从name+iconset改为href="path#id"的统一寻址方式，并新增Xel.queryIcon()；0.27.0 将iconsets相关命名统一收敛为icons（meta 标签、Xel.icons、Xel.whenIconsReady、iconschange事件）。0.36.1 修复<x-icon>无法渲染渐变填充图形的问题。此外 0.28.12 / 0.28.7 允许<x-tooltip>放置在<x-icon>与<x-checkbox>内部。

在 WinBoat 中，图标集通过xel-iconsmeta 标签指向 src/renderer/public/xel/icons/fluent.svg，配合 Iconify 图标组件使用；若自行扩展图标集，应遵循<svg id>符号寻址规范。

七、颜色系统与取色器：面向专业色彩管理的深度能力

取色器是 Xel 中技术含量最高的组件之一，CHANGELOG 完整记录了其专业化过程：

• 0.24.0：将<x-barscolorpicker>、<x-rectcolorpicker>、<x-wheelcolorpicker>三个组件统一为单个<x-colorpicker>；支持Display P3、Rec. 2020、A98 RGB、ProPhoto宽色域色彩空间；允许以任何合法 CSS 格式指定颜色。
• 0.26.0：色彩空间扩展至sRGB Linear、CIE LCH、OK LCH、CIE LAB、OK LAB、CIE XYZ D65、CIE XYZ D50；色彩空间选择器增加"Out of gamut"（超出色域）指示；新增色域提示（gamut hints）与通道标签显示选项。
• 0.24.2：支持用大写十六进制显示颜色值，且输入十六进制时#前缀变为可选。
• 0.28.3：聚焦时自动全选<x-colorinput>内容；0.28.4修复colorinput聚焦时退格/上下方向键事件冒泡问题。
• 0.28.9 / 0.28.10：适配 colorjs.io 开发版的破坏性变更；0.25.5修复清除 localStorage 时取色器抛错；0.25.2修复 sRGB 空间下颜色输入值格式不一致。
• 0.21.0：取色器新增disabled属性；0.34.3修复<x-colorpicker>在文档初始加载时更新失败；0.33.3修复 WebKit 下切换标签页时取色器弹出层位置变化；0.20.4修复<x-colorselect>无法打开。

八、浏览器兼容性：WebKit、Firefox 与 Safari 的适配记录

Xel 定位是 Web/Electron/Hybrid 三端通用，因此兼容性修复贯穿整个 CHANGELOG：

• 0.20.0：正式支持 WebKit 系浏览器；后续 0.28.8、0.33.6、0.33.7、0.25.6、0.24.1 等条目持续处理 WebKit 下的更新、宽度、位置与焦点问题。
• 0.23.0：Firefox 119 的初始支持；0.33.3 修复 Firefox 滚动条未样式化；0.36.2 修复 Firefox 下 menubaraside插槽更新。
• 0.33.1：修复嵌套 CSS 规则导致 Safari 18.3 崩溃的问题（Electron 升级 WebView 内核时需特别留意）。

九、从源码看 WinBoat 对 Xel 的实际集成与本地化取舍

综合仓库源码，可以清晰还原 Xel 在 WinBoat 中的真实使用方式：

1. 运行时加载：在 src/renderer/index.html 引入xel.js，并通过xel-theme、xel-icons、xel-accent-color三个 meta 标签声明 fluent-dark 主题、fluent 图标集与紫色强调色#A78AF9（这三者分别对应 CHANGELOG 中 0.29.0 Fluent 对齐、0.27.0 图标命名规范与 0.29.0 宽色域强调色能力）。

2. 应用外壳：App.vue 使用<x-titlebar>承载窗口控制按钮（@minimize/@buttonclick事件），用<x-nav>+<x-navitem>构建侧边导航，用<dialog>、<x-progressbar>、<x-button>、<x-label>组织更新提示框——这些元素分别对应 0.30.0 新增的桌面级组件与 0.29.0 新增的导航组件。

3. 仪表盘卡片：Home.vue 使用<x-card>承载容器状态与 CPU/RAM/磁盘指标，容器操作加载中使用<x-throbber>（对应 0.21.3 / 0.28.4 对 throbber 渲染与动画的修复）。

4. 本地化取舍：WinBoat 的导航项高亮通过代码手动click()<x-navitem>实现（见 Home.vue 注释），避开了toggled属性的行为差异——这正是面对 CHANGELOG 中大量 API 变更时"以源码规避不确定性"的务实做法。

5. 上下文菜单重实现：如上文所述，WBContextMenu.vue 与 WBMenuItem.vue 以原生 div + Teleport 重写了x-contextmenu/x-menuitem，并通过 CSS 变量（--x-menu-background、--x-surface-background等）继续贴合 Xel 主题变量体系，实现"业务层接管、样式层复用"。

十、升级与维护实用建议

基于 CHANGELOG 的规律，给 WinBoat 或类似 Electron 项目升级 Xel 时提供以下检查清单：

1. 优先检索[Changed API]与移除声明：升级前在 CHANGELOG.md 中搜索两个版本区间内的破坏性变更，重点核对属性重命名（如 0.32.0 的graphite→gray、default→normal）与默认值变化（如size默认normal）。
2. 验证主题文件命名：若使用 Material 主题，确保子主题文件名以material开头（0.34.6 的约束）；WinBoat 当前使用 fluent-dark，应关注 0.29.0 起的 Win11 视觉规范变更。
3. 回归测试菜单与上下文菜单：该系列修复条目最多（0.34.x ~ 0.36.2），升级后必须回归菜单展开、省略号溢出、触屏与 Firefox 场景；已自行重实现x-contextmenu的项目可对照验证新版是否已修复其缺陷。
4. 核对字号单位与尺寸体系：0.33.2 起字体用rem，0.22.0 起全局尺寸体系已删除，依赖Xel.size或相对尺寸的代码必须迁移。
5. 关注 colorjs.io 依赖兼容：取色器 0.28.9 / 0.28.10 明确跟随 colorjs.io 的破坏性变更，升级 Xel 时应一并升级配套依赖。

结语

Xel 的 CHANGELOG 是一部浓缩的桌面级 Web UI 组件库工程史：从 2021 年的 Web Platform API 重写，到 2025 年 7 月 0.36.2 对 Firefox 菜单栏插槽的最后修补，每一次版本迭代都指向具体的组件行为、主题规范或跨浏览器兼容性。而 WinBoat 仓库以"内置 vendor 目录 + Vue 组件化消费 + 局部重实现"的方式使用 Xel，正好提供了一个真实、可验证的落地样本——研读 src/renderer/public/xel/CHANGELOG.md，再对照 src/renderer/index.html 与各视图组件的用法，你就能完整掌握这套x-前缀组件体系的演进规律与实战要点。

• 桌面应用
• 虚拟化