版本记录与迁移

当前源码相对 1.11.3 的改动，尚未确定发布版本。

新增输入框尾部内容、Transfer 双栏选择和光标补全示例，修复可编辑字段与 Gallery 兼容性问题。

• LineEdit 与 ComboBox 支持独立于编辑值的文字尾缀和自定义尾部控件，并保留调用方的所有权约定。
• 可编辑 ComboBox 在选项和模型变化后保持文字区域稳定，NumberBox 拖动指示器在不同显示倍率下垂直居中。
• Transfer 支持两侧搜索与批量移动，通过稳定键记录选择，保留源模型和禁用状态。
• TextEdit 光标几何接口支持保持编辑焦点的成员补全示例，提供键盘导航与撤销；编辑命令示例保留高度动画。
• Gallery 示例预览和代码块采用统一框架，输入示例保留响应式布局，并修复旧版 Qt 的重定向裁剪。
• 构建和发布验证复用编译结果、共享测试可执行程序，提供成对性能测量并保留现有检查覆盖。

修复 Windows 无界面环境下的窗口句柄处理，C++ 和 PySide6 Gallery 新增禁用复选框示例。

• Windows 上使用 offscreen 或 minimal 插件时，Qt 分配的模拟窗口 ID 不再传给原生窗口样式和背景效果接口。
• 两个 Gallery 的双态复选框示例均展示禁用状态下选中和未选中的控件。
• 官网在人民币打赏方式旁提供 Ko-fi 页内打赏面板和二维码。
• WebAssembly 浏览器检查基于同一次构建并行运行，发布 CI 复用兼容的 Python wheel 和候选构建。

新增 RangeSlider 和 ImageViewer，桌面 Gallery 支持保存界面缩放和分页搜索，并修复文字对齐、浮层和低倍率绘制问题。

• RangeSlider 提供上下限、最小间距、键盘步长和可访问的双手柄，与 Slider 共用外观。
• ImageViewer 支持围绕指针缩放、平移、适应视口、键盘与捏合操作和缩略图缓存，也可用于 FlipView。
• 桌面 Gallery 可保存 50%–200% 的界面缩放，保持原生窗口外框和恢复位置，显示缩放控件时保留编辑器焦点。
• 分数倍率和低 DPR 绘制修复保留局部刷新，纯 GPU 帧不会强制触发整窗控件重绘。
• Gallery 分页显示组件和示例搜索结果，取消过期请求，并同步浏览器无障碍几何信息。
• 修正文字与可编辑输入框对齐、菜单图标位置、SelectorBar 溢出焦点、浮层效果截图和原生窗口几何。
• 从源码构建桌面 Gallery 需要与 Qt 配套的内部开发头文件；基础 Widgets 库仍支持 Qt 5.15+ 和 6.2+，不增加该依赖。
• 预览工具统一使用 UTF-8，未变化的 Python 生成封装保留时间戳，本地 WSL 验证复用 Linux 原生工作目录。
• 官网项目更新统一在“版本记录与迁移”查看。独立路线图页已移除，旧地址跳转到对应语言的版本记录。
• 文档侧栏按层级组织：控件分类归入“组件”，图标归入“基础能力”，扩展模块的概述与组件放在一起。搜索自动展开匹配分支，清空后恢复原来的展开状态。
• 组件文档里的实时示例会按示例内容自动调整高度，图表、表格和选择器不再挤在过矮的窗口里滚动。对话框、菜单和窗口类示例仍保留浮层所需的空间。
• GitHub 的 Sponsor 小爱心现在为每个投喂档位列出一个短链接，点开后按浏览器语言打开官网，并自动选好对应档位。

Desktop Gallery with public Qt development headers only

# Debian / Ubuntu, matching the selected Qt version:
sudo apt install qtbase5-private-dev
# or:
sudo apt install qt6-base-private-dev
# Library-only alternative:
-DFLUENT_QT_BUILD_GALLERY=OFF -DFLUENT_QT_BUILD_PYSIDE6_GALLERY=OFF

粒子特效拆为可选模块，FontIcon 支持应用字体，3D 渲染减少重复工作；Python 改用稳定 ABI wheel，官网新增双语版本与迁移说明。

• FontIcon 新增 fontFamily() 和 setFontFamily()，支持应用自定义字体。传入该字体的 Unicode 字形即可；字体族为空时保持原有的内置 Fluent 图标绘制。C++ 和 PySide6 Gallery 均提供自定义字体示例。
• 粒子特效从核心库移到可选的 Particles 模块。
• Gallery 3D 只上传有变化的纹理行，交互停止后恢复清晰画面，缓存控制在内存预算内，渲染持续过慢时切回 2D。
• 桌面 Debug 构建默认链接 release 版 Qt。需要 debug 版 Qt 时，设置 FLUENT_QT_DEBUG_RELEASE_RUNTIME=OFF。
• 打开的浮层跟随宿主表面变化，滚动条绘制与原生命中区域对齐，PySide6 扩展控件加强创建和所有权检查。
• 原生 wheel 由 17 次独立编译缩为 6 个稳定 ABI 构建，仍保留 17 组平台／Python 安装验证。发布复用不可变候选产物，CI 限制编译并行度并按改动选择网站验证。
• 官网新增双语版本记录、迁移对照、路线图和 API 未发布提示，由源码生成并检查译文是否及时更新。

FluentQt::FluentQt
#include <FluentQt/Layout.h>
fluent::layout::ParticleBackdrop
from fluentqt.layout import ParticleBackdrop

find_package(FluentQt CONFIG REQUIRED COMPONENTS Particles)
target_link_libraries(app PRIVATE FluentQt::Particles)
#include <FluentQt/Particles.h>
fluent::particles::ParticleBackdrop
from fluentqt.particles import ParticleBackdrop

新增数值与属性编辑、图表导出和几种选择控件，官网文档改版。

• NumberBox 可以拖动调值，拖动过程可以取消。PropertyPanel 支持分组、按名称查找和恢复默认值。
• 图表可以保存为 PNG，或把源数据导出为 CSV，范围可选当前视图或全部数据。
• AutoSuggestBox 支持异步建议，并丢弃过期结果。新增 TagInput（带稳定 ID 的标签）和 TreeSelect（从树形模型中选择）。
• DataGrid 支持固定列，DataGridToolBar 提供搜索、筛选和列设置。
• 官网每个组件页都有可操作的示例、C++ 与 PySide6 代码和公开 API，提供中英文版本。

新增 CommandPalette、FormController 和 CodeBlock。Popup、Dialog 与 DrawerView 使用同一套背景模糊和遮罩选项，模态层会拦截背后的点击和快捷键。

CommandBar 和 CommandBarFlyout 支持带多级子菜单的 action。新增 TextEdit::appendPlainText()，追加日志时保留选区和撤销记录。未选中的复选框和单选按钮描边更清楚。

新增 DateTimeRangePicker；QmlBridge 可以在 Widgets 窗口中嵌入应用自己的 QML 页面；可选的 Plugins 模块负责扩展的依赖、启用和清理。Python Live Scene 改为在原窗口内重新加载预览。

修复窗口启动和切换材质时的背景问题。深色模式下新窗口不再闪白；从 Mica 或 Acrylic 切走时，旧材质会保留到新背景画好为止。

新增 Timeline 和 Stepper。Gallery 在非 100% 显示缩放下的图片和文字更清晰。

修复打包后的 3D Gallery：Python wheel 补上了 Spatial，Windows ARM64 改用 Direct3D 11 渲染，没有硬件加速时回退到 2D 界面。

• 1.9.0 的 wheel 缺少 Spatial。请把 FluentQt 和 FluentQt-Gallery 一起升级到 1.9.1，才能使用 3D Gallery。

新增可选的 Spatial 模块。SpatialView 把普通控件放到带透视的 3D 平面上，控件的输入和信号照常工作。桌面版和浏览器版 Gallery 都加入了 3D 模式。

新增图表模块（折线、面积、柱状、饼图、环形、散点和迷你图），用 Qt Widgets 绘制，不依赖 Qt Charts；另新增 FileDropZone 和 FileListView。Toast 换了卡片样式，并可显示关闭按钮。

SplashScreen 在展开动画中的重绘更少。Gallery 更换了应用图标、安装器图片和官网截图。

新增 ParticleBackdrop（CPU 绘制的粒子背景）和可复用的 SplashScreen。修复键盘选择和文本编辑问题，Gallery 源码也更方便阅读和复制。

UserTheme::applyOverrides() 可以全局修改颜色、圆角和字体，setThemeOverrides() 只修改单个组件。ComboBox 下拉列表现在会使用自定义字体。另修复了回调、导航和滑块在各 Qt 版本上的问题。

新增 ToggleSwitch::visualScale。修复集合视图的输入信号、删除行后 FlowView 的布局，以及 NumberBox 回调中删除控件导致的问题。

新增 HighContrast 主题和全局 MotionPolicy（Full、Reduced、Disabled），C++、PySide6 和浏览器 Gallery 都能使用。TextEdit 获得焦点时，自动高度变化带过渡动画。

MultiSelectComboBox 改用“、”连接选中项，不再出现翻译出来的连接词。选择器和命令栏去掉了重复实现，行为不变；TabView 的纯图标按钮补上了无障碍名称。发布流程使用的 Actions 固定到已审查的版本。

按钮、开关和日期/时间选择器统一遵循 fontRole，显式调用 setFont() 仍然优先。Gallery 示例在 C++、PySide6 和 WebAssembly 中行为一致。build-fluentqt-gui Skill 覆盖从项目分析到独立评审的完整流程。

原生 Gallery 预览可以在截图前回放鼠标和键盘操作，报告附带控件几何信息和 Inspector 检查结果。菜单动画期间访问键不再失效。本地构建会按 CPU 和内存自动选择并行数。

Live Scene 让 PySide6 预览窗口保持打开，保存后自动刷新。CalendarView 的选中框改为圆角，选择器弹出层与输入框对齐，TeachingTip 阴影四周均匀。

新增 MultiSelectComboBox，以及 fluentqt doctor、create、trial 命令，用于检查本机 Qt 环境并生成 C++ 或 PySide6 起步项目。另修复了选择器和列表在不同平台上的若干问题。

库 API 没有变化。官网拆分出中英文两个首页，GitHub Discussions 增加了提问和建议模板，正式版会等所有 Python wheel 构建完成后再发布。

移除 Material 和 Cupertino 设计语言，只保留 Fluent。新增 Field 和 DataGrid，并明确了所有浮层的打开、关闭和模态行为。

FluentElement::DesignLanguage
StyleTheme / StyleThemeCatalog
current_design_language()
apply_style_theme()

FluentElement::Theme
fluent::UserTheme
current_theme()
apply_user_theme()

浏览器版 Gallery 的示例代码可以在 C++ 和 PySide6 之间切换。TextEdit 正确应用自定义内容边距。build-fluentqt-gui Skill 会按应用规模调整检查项。

随包提供面向编程助手的 build-fluentqt-gui Skill，以及把 C++/PySide6 API 对应到 Gallery 示例的组件目录。ListView 增加默认委托；安装包不再写入构建机的 SDK 路径。

新增可选的 WebAssembly 支持（FLUENT_QT_BUILD_WEBASSEMBLY_SUPPORT）。官网直接嵌入在浏览器中运行的 C++ Gallery。桌面和 PySide6 构建不受影响。

FluentQt 和 FluentQt-Gallery 的 PyPI 页面补上了完整说明和项目链接。组件和 Python API 没有变化。

首个 PySide6 版本。FluentQt wheel 提供组件库的 Python 绑定，FluentQt-Gallery 可单独安装 Gallery。C++ 库和 Qt 5.15 构建保持不变。

按钮按下时不再遮住底边框。macOS 上 Qt 丢失触控板事件时，自定义标题栏改用系统原生拖动。

新增 CommandBar、CommandBarFlyout，以及统一处理撤销、复制、粘贴等操作的 EditingCommandRouter。Toast 支持操作按钮、悬停暂停和原位更新。

公开 Card、Divider、Expander、Accordion、FontIcon、CompoundButton、Avatar 和 Toast，应用可以直接使用 Gallery 中的这些控件。

新增按类别拆分的头文件（如 <FluentQt/BasicInput.h>），字体角色和选择模式改为强类型，托管控件需要显式指定所有权。选择器和开关的文字改由应用提供本地化内容。

"Body"
FlowSelectionMode / GridSelectionMode
ListSelectionMode / TreeSelectionMode

Typography::FontRole::Body
fluent::collections::SelectionMode
fluent::WidgetOwnership

修复 AnchorLayout 右/下锚点、QMLPlus 状态切换，以及在 QApplication 创建前访问内置资源的问题。TextEdit 正确转交焦点，重新设置文本时保留撤销记录。

控件在 300% 以内的分数缩放下保持清晰。Dialog 和 CoachMark 改为在所属窗口内以浮层显示，不再创建独立的原生窗口，修复了 macOS 上输入卡住的问题。

内置字体和 Fluent System Icons，不再依赖系统安装 Segoe。Gallery 增加排版、颜色、图标和间距页面，并跟随系统显示缩放。

安装包只导出明确列出的公开头文件。Gallery 组件页显示头文件、C++ 类型和 CMake 目标，页面切换更快。

组件库只依赖 Qt Widgets，spdlog 只留在 Gallery 中。发布页新增仅含库代码的源码压缩包，Gallery 安装包去掉了用不到的 Qt 模块。

支持 Linux（X11 与 Wayland，x64 与 ARM64），并提供 Debian 安装包。Window::setBackdropEffect() 在所有平台上提供同一套 Mica/Acrylic 接口。