dsh-fluent-theme
Verified@shellraining/dsh-fluent-theme · v0.1.8 · MIT · Web UI
Windows 10-inspired acrylic backgrounds, Reveal lighting, and interaction animations for DSH.
Install
dsh plugin add @shellraining/dsh-fluent-theme Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Readme
Win10 Fluent 主题
English · 简体中文
Windows 10 风格主题,提供本地壁纸、Acrylic 亚克力材质、Reveal 光效、按压反馈和侧栏动效。沿用 DSH 设计变量(--dsw-*),跟随明暗主题与外观设置;这是网页近似,不是原生 Windows 控件的完整复刻。
从旧包迁移
本包原名 @shellraining/dsh-acrylic-wallpaper。备份 profile 配置,移除旧包后再安装新包,不要同时启用两者。保持相同的浏览器来源和用户数据,已有壁纸和设置会继续使用原来的本地存储,无需重新导入。Cordis 配置 ID acrylic-wallpaper 和已有主题 DOM 标记保持不变。
安装
dsh plugin --profile web add @shellraining/dsh-fluent-theme
需要 DSH 0.2.2-rc.1 及以上的 0.2.x 版本(engines.dsh 为 >=0.2.2-rc.1 <0.3.0)。插件依赖 0.2.2 起才有的宿主结构,例如 HoverCard 的 portal 包裹层、右键菜单的阶段属性和窄屏侧栏抽屉。
官方界面覆盖
「Win10 风格」同样覆盖下面几类官方界面,用户可以用它们代替原来的自研插件:
- 插件管理页的更新入口:卡片和版本列表上的「可更新」「预发布」等标签改为 Win10 直角;「更新到某版本」按钮、版本面板、更新对话框和进度状态沿用主题已有的按钮、卡片与对话框样式,带 Reveal 和按压反馈。
- 侧栏会话与工作区悬浮卡:深色亚克力底,保留宿主的三级白色文字层级,使用 Win10 的弹出和收起动效。
- 引用聊天文本(dsh-message-quotes):选中文本后浮出的「引用文本」按钮使用亚克力和直角,带 Reveal;输入框里的引用和已发送消息中的引用预览改为浅强调色底的直角标签。
- 右键菜单:沿用宿主自己的淡入淡出,不叠加 Win10 弹出动效,避免关闭时闪烁。
输入区底部信息栏
壁纸模式下,主对话和嵌入式对话的输入栏背后铺一层应用内亚克力:与输入框等宽,从输入框顶边向下延伸到对话栏底边,底部统计信息落在这层材质上。上方的待办面板等内容不在这层范围内。宿主原本用一段 36px 渐变遮住滚到输入区下面的正文,壁纸模式清空底色后渐变失效,这里改用亚克力恢复遮挡,而不是给统计栏单独加一块底板。浏览器不支持背景模糊时,退回为接近不透明的同色底。
这一取舍参考微软 Acrylic 材质规范:会被滚动内容压在下面的辅助界面使用应用内亚克力,并延伸到界面边缘(这里是底边),避免相邻小块亚克力之间出现接缝。该文档现已更新为新版 Windows 应用指南。高对比度或减少透明度模式沿用插件原有策略,关闭壁纸材质并恢复宿主底色。
Reveal 光效
开启「Win10 风格」和「悬停与按压光效」后,鼠标或笔靠近控件时会照亮边缘,悬停时显示局部表面光。主聊天已发送的用户消息(含 steering 消息)、侧边聊天消息、输入卡片和待办卡片只显示边缘光,不改变文本选择、复制或焦点行为。
按钮、菜单项等可交互控件还会显示独立的按压光:短按后扩散淡出,持续按住时缓慢扩散,松手后加快消退。光效参考 WinUI 2 的 Reveal 实现,采用 66ms 点亮、200/266ms 快速淡出及 1000/1500ms 慢速淡出;网页渐变的半径和亮度是近似值。离开控件、取消操作、失焦或关闭插件会清理按压光。光效与下文的实体按压反馈独立。
光效跟随明暗主题。减少动态效果、高对比度或减少透明度模式下会关闭;触摸和键盘操作不触发装饰光,保留宿主原有反馈。现有 reveal 设置同时控制悬停与按压,无需迁移配置。
控件按下状态
「Win10 风格」还会补齐宿主 outline、toolbar 和 primary 按钮缺少的 Pressed 底色。底色由原生 :active 状态控制,按住时保持、松开时恢复,与短暂的按压光独立;关闭光效或开启减少动态效果后,按钮仍保留底色反馈。ghost 按钮沿用宿主已有的 active 配色,不重复叠色。toolbar 保留原有底色并叠加状态色;primary 没有专用 pressed token,暂用原底色与前景色的小比例混合作为网页近似,仍需在实际主题下检查对比度。消息正文和输入框不增加按压底色。
实体反馈参考微软的 PointerDown/PointerUp 主题动画:按压靠左、靠右或靠边时,对应一侧向内倾斜;中心按压以轻微收缩为主。旋转中心始终在控件中心,方向取首次按下的位置,按住后不追随鼠标拖动。控件越大,倾角越小;缩放比例由中心的 97% 过渡到角落的 100%。键盘操作使用居中反馈。
依据是微软公开的原生实现和指针位置插值。源码将这套行为标注为从 Windows 10 开始的调整,但它来自较新的公开原生代码,不代表逐一验证了所有 Win10 系统版本。插件沿用其中的尺寸曲线、10ms 按下延迟及松手后的 150ms 保持、200ms 恢复,恢复曲线为 cubic-bezier(.1,.25,.75,.9)。CSS 透视采用 999px 近似,没有完整移植原生相机矩阵;早于按下延迟就释放的操作不会补播形变。普通 WinUI 按钮也不全都使用倾斜动画,因此这里是统一交互风格,不宣称所有控件都与系统默认模板一致。
覆盖按操作语义统一识别,不再依赖基础 Button 类名:
| 元素 | 处理 |
|---|---|
| 普通按钮、工具栏图标、个人菜单、确认卡片选项 | 同一套按压生命周期,适合变换时使用方向性形变 |
| 侧边栏会话与项目行、搜索结果、文件按钮、子任务树行 | 整行或实际按钮响应;行内按钮优先,不同时按下父行 |
| 菜单项、选项、导航链接、标签页、日历日期格 | 按语义接入;已有下划线伪元素、裁剪路径或变换时保留几何并补底色 |
| 会话拖拽行、Dock 标签 | 按下可以反馈;移动达到每轴 4px 阈值或实际开始拖拽时立即清理 |
| 轨迹表行、市场卡片的扩展点击区域、滚动容器、固定定位后代等不适合变换的结构 | 使用瞬时按压底色,不替换宿主伪元素或强行变形 |
| 消息正文、输入框、原生表单字段、编辑器、拖拽空白区和尺寸手柄 | 不添加实体形变,不改变选择、编辑或拖拽行为 |
形变跟随「Win10 风格」,独立于光效开关;减少动态效果时只保留底色反馈。只在入场时播放动画的控件(如侧栏的视图选项)在动画结束后同样形变。鼠标、笔、触摸和聚焦操作元素的空格 / Enter 键均可触发,不阻止默认事件、不合成点击、不接管指针捕获。关闭插件、失焦、取消、移除控件或布局变化时清理临时样式。
Reveal 与控件使用同一透视映射,光点转换到控件局部坐标。透明逆变换伪元素保留外层原始命中边界,但行内子按钮仍随外观移动,并不保证各个子节点的命中区域固定。新会话这类 overflow: hidden 的按钮会把这个伪元素一起裁掉,因此按下时先试算最大形变:按压点仍落在按钮上才变形,贴着边缘按下则只显示按压底色;按住后移到收缩露出的边缘会提前结束形变,松手仍点在按钮上。带弹出层或展开语义的触发器在宿主处理点击前恢复,避免用形变后的边界定位;没有这些语义的自定义弹出层仍需实际验证。宿主列表没有统一的内容容器,因此这里变换整行,而原生 ListViewItemPresenter 可以只变换内容子层,这也是网页近似的边界。
侧栏开合
0.2.1 的宿主先提交新的三栏宽度,下一次 React 提交才加上 data-animating,开合经常直接跳变。0.2.2 起两者在同一次提交中生效,宿主自己的宽度过渡已能正常播放。
开启「Win10 风格」后,宿主标记了 data-animating 的开合仍由插件按框架当前声明的时长和缓动重放,替换宿主的过渡。保留重放是为了下面的正文定宽:只有插件自己驱动动画,才能在开始前量出最终栏宽。拖动分隔条、窗口尺寸变化,以及宿主标记为全屏或瞬时的切换照旧不动画;开启减少动态效果时宿主关掉了过渡,插件也不重放。
对话正文的宽度由栏宽推算:宿主每次尺寸变化后都把栏宽写到对话外层,整段对话继承这个值,动画的每一帧都要重算全部消息的样式、重新折行,长对话会明显卡顿。重放期间,插件先在对话正文上写好开合结束时的栏宽,宿主逐帧的写入只影响外层:点击后正文直接换成最终宽度,之后只随栏位平移,动画结束后再交还宿主的值。开合后的对话区放不下这个宽度时(比如打开右侧栏),正文仍会在后半段随栏位收窄。
右侧栏收起时宿主会立即去掉栏位。栏宽过渡期间,滑出的面板贴着变宽的对话区,不会盖住对话,所以沿用打开时的壁纸淡色,不再变成深色底板。从全屏退出这类不动画的收起仍会盖住对话,继续使用亚克力底。
偏好
在「设置 → Win10 Fluent 主题 → 偏好」中,可以关闭「隐藏变更文件悬浮预览」,恢复宿主的悬浮 diff 预览。默认保持隐藏,沿用旧版本行为;已有设置无需迁移。
此偏好独立于主题与光效开关,只控制悬浮预览的显示,不阻止宿主加载比较内容。设置保存在当前浏览器来源的本机 IndexedDB 中,同源窗口会同步;「恢复默认」也会重置此偏好,停用插件后恢复宿主显示。
开发
使用 Node 24.9+ 和 pnpm 12.6.0。运行时的 Node / DSH 版本范围以包清单为准。构建工具、源码和锁文件均在本仓库,不依赖原 monorepo、相邻仓库或 submodule。
pnpm install --frozen-lockfile
pnpm typecheck
pnpm build
pnpm pack
tools/build-plugin.ts 使用 Vite 生成根目录的 index.js 和 client.js。React 和宿主组件保持 external。build.ts 还检查未知设计变量和写死的宿主 hash 选择器。依赖版本直接在包清单维护,不使用 workspace catalog。
设置菜单、偏好、提示和导航标题跟随 DSH 语言设置,支持中文和英文。错误摘要翻译,底层浏览器或存储错误保留在「技术详情」中。元数据由 locale/en.json 和 locale/zh.json 提供。
pnpm dev 仅监听源码并重新构建,不做类型检查,也不会安装插件。若需本地预览,由维护者将 profile 链接到本仓库,确认宿主加载此处产物后刷新现有 DSH 页面;不要另起独立 Vite 页面。单独构建不代表当前页面已更新,客户端热替换还取决于宿主开发 watcher。不要提交本机路径或修改其他贡献者的 profile。
样式协作与兼容边界
本包通过宿主 theme.overrideTokens 和 CSS 提供主题,不要求安装 Mermaid 或行内代码复制。第三方插件可继承 --dsw-* 变量;body[data-acrylic-wallpaper] 表示壁纸材质启用,body[data-acrylic-fluent] 表示 Win10 风格启用。关闭主题、辅助功能限制或停用插件时,标记按当前功能状态移除。不要把这些标记当成必须安装主题的理由。
主聊天使用 data-message-bubble,部分宿主控件仍需要通过 CSS module ID、类名格式和规则签名识别。侧栏过渡由插件重放;这些并非稳定的公开主题 API。DSH 升级后要复核弹层、设置、侧栏、引用、输入区、长对话滚动及启停,类型检查不能证明新宿主运行时兼容。
发布前检查
- 在实际 DSH 页面切换中英文、明暗主题,检查导航与设置内容。
- 验证图片选择、移除、重载、同源窗口同步,以及不支持的图片和存储失败提示。
- 验证「隐藏变更文件悬浮预览」开关、刷新后的偏好、恢复默认和停用恢复。
- 检查 Reveal、按压、菜单、悬浮卡、对话框、侧栏开合、文本选择、减少动态效果及高对比度。
- 单独启用主题,再与 Mermaid、行内代码复制组合验收。不开主题时另外两个插件应保持可用。
- 依次运行类型检查、构建和打包,检查归档包含入口、客户端、patch、图标、双语元数据、README 和 LICENSE。
- 查看源码与生成产物差异;未完成页面验收时,不把构建成功写成已验证界面稳定。
CI 只检查,不在推送到 main 时发布。release.yml 仅可手动触发,要求 main 分支并输入与包清单相同的版本;使用 npm OIDC 发布已打包归档,不保存 npm token。
迁移时保留 npm 名称、ModuleLoader ID、Cordis ID 和 IndexedDB 名称。已有 npm 版本不能覆盖,发布前由维护者明确决定新版本并重新构建、提交。目标仓库名确认后核对包清单链接,并把本仓库登记到组织维护者列表。npm trusted publisher 必须重新绑定最终仓库与 release.yml,不要把改 GitHub 地址当成发布权限也已迁移。可以由 npm 包所有者执行:
npm trust github @shellraining/dsh-fluent-theme --repo omdsh-dev/dsh-fluent-theme --file release.yml --allow-publish
绑定后按 npm 当时的有效期要求完成发布,确认新仓库可以发布后,再撤销旧仓库对本包的发布权限。旧 monorepo 的发布流水线不会因拆分自动停止,不应继续在那里修改本包版本。回滚使用此前已发布的 npm 版本,不删除浏览器数据。
实际页面验收需单独完成,不能用 CI 与归档检查代替。
许可
MIT