Seelen UI 核心库seelen-core完全指南Rust 核心 TypeScript/Deno 绑定的混合架构与 Widget/插件/主题开发【免费下载链接】Seelen-UIThe Fully Customizable Desktop Environment for Windows 10/11.项目地址: https://gitcode.com/GitHub_Trending/se/Seelen-UI导读本指南围绕 Seelen-UI 仓库中的核心库libs/core即 readme.md 中所述的Seelen UI Library展开它并非应用本体而是 Seelen UI 用于创建和管理 Widget、插件plugin、主题theme的基础库core library。Seelen UI 是一个面向 Windows 10/11 的高度可定制桌面环境README 中描述为 The Fully Customizable Desktop Environment for Windows 10/11.而本库正是其扩展生态的基石。读完本文你将理解该库Rust 核心 TypeScript/Deno 绑定的混合架构、如何通过 JSR/npm 安装与构建、命令/事件/状态的调用模型以及它在设置、主题、插件、Widget、系统状态等模块中的落地形态。定位Seelen UI 的核心库而非应用本体仓库根目录的 libs/core/readme.md 明确界定了该库的职责为 Seelen UI 提供创建和管理Widget控件/小组件、插件Plugin、主题Theme所必需的工具与类型。它是 Seelen UI 应用内 Widget 渲染与插件机制的类型契约和运行时桥接层其 TypeScript 侧包描述也直接写为 Seelen UI Library for Widgets见 libs/core/deno.json。从包元数据看Cargo 包名为seelen-core版本2.8.5libs/core/Cargo.toml与 libs/core/deno.json 中seelen-ui/lib的版本保持一致——Rust 核心与 TS 绑定同源同版本发布这是理解该库版本策略的关键。混合架构Rust 核心 TypeScript/Deno 绑定该库的核心设计是同一套领域模型用 Rust 定义、向 TypeScript 导出类型从而在保证类型安全的同时兼顾性能。源码布局清晰反映了这一分层Rust 侧libs/core/src/lib.rs暴露模块constants、error、handlers、rect、resource、state、system_state、utils并 re-export 了chrono、SeelenLibError与rect相关类型。TS 侧libs/core/src/lib.ts以同名模块 re-export 为主并额外导出与 Tauri 后端通信的关键 APIinvoke、SeelenCommand、SeelenEvent、subscribe等。值得注意的设计细节入口文件是 mod.ts 而非 src/lib.ts。由于deno/dnt存在一个已知 bug循环依赖检测问题libs/core/mod.ts 作为 re-export 中转层存在并提醒开发者使用madge --circular ./mod.ts检测循环依赖。类型生成走cargo test而非构建二进制。见 libs/core/scripts/rust_bindings.ts 中的注释yeah cargo test generates the typescript bindings, why? ask to aleph-alpha/ts-rs即通过cargo test --features gen-binds触发ts-rs生成 TS 绑定与 JSON Schema。Rust 侧对应测试为 libs/core/src/lib.rs 的generate_schemas它会生成settings.schema.json、settings_by_app.schema.json、theme.schema.json、plugin.schema.json、widget.schema.json、icon_pack.schema.json六份 JSON Schema并调用SeelenEvent::generate_ts_file与SeelenCommand::generate_ts_file生成 src/handlers/events.ts 与 src/handlers/commands.ts这两个文件头部都标注This file was generated via rust macros. Dont modify manually.。这解释了为什么命令/事件枚举在 Rust 宏中定义、在 TS 中以枚举形式出现——单点定义、双端生效。Cargo features 控制生成能力gen-binds引入ts-rs与salvo引入 salvo web 框架用于 HTTP 服务场景均为可选 featurelibs/core/Cargo.toml默认构建不携带避免无关依赖膨胀。安装JSR 与 npm 双通道原文档给出的安装方式如下这是使用该库的官方途径# JSRDeno 生态推荐在 Deno 项目中使用 deno add seelen-ui/lib # NPMNode 生态 npm install seelen-ui/lib包的实际入口与子路径在 libs/core/deno.json 中定义.→./src/lib.ts主入口导出所有类型与 API./types→./gen/types/mod.ts由 Rust 生成的类型绑定入口./tauri→./src/re-exports/tauri.tsTauri 相关 re-export。此外构建脚本 libs/core/scripts/build_npm.ts 使用deno/dnt将 Deno 源码转译为 npm 包输出到./npm并做了三件额外的事把LICENSE与readme.md复制进 npm 包手动复制styles/下的 CSS 资产并在 package.json 中注入./styles/*导出因为 dnt 只处理 TS/JS移除 npm 包中的src目录源码不随包分发只发布构建产物。因此 npm 包除了类型与 JS还带有seelen-ui/lib/styles/*的样式资源入口可供 Widget 直接引用基础样式styles 目录包含 colors.css、reset.css、shadows.css、spacings.css。核心 API命令、事件与订阅TS 侧对外暴露的三件套位于 libs/core/src/handlers/mod.tsimport { invoke, subscribe, SeelenCommand, SeelenEvent } from seelen-ui/lib;invoke —— 向后台进程发起调用invoke是对 Tauriinvoke的类型安全封装通过SeelenCommand字面量类型约束命令名并通过条件类型让无参命令无需传参、有参命令强制传入对应参数返回值也按命令映射AllSeelenCommandReturns同时把 Rust 侧的null映射为void/undefined避免类型空洞。// 示例切换工作区 await invoke(SeelenCommand.SwitchWorkspace, { id: 2 }); // 示例查询系统语言 const langs await invoke(SeelenCommand.SystemGetLanguages);命令枚举src/handlers/commands.ts覆盖面很广可归纳为几大类类别代表命令字符串值说明工作区/虚拟桌面get_virtual_desktops、switch_workspace、create_workspace、destroy_workspace、move_window_to_workspace多桌面管理壁纸wallpaper_next、wallpaper_prev、set_as_wallpaper、wallpaper_save_thumbnail壁纸轮换与设置系统外观get_system_colors、set_system_accent_color、get_system_dark_mode、set_system_dark_mode、get_foreground_window_color主题色/深色模式联动夜间模式get_system_night_light_settings、set_system_night_light_enabled、set_system_night_light_color_temperatureWindows 夜灯控制状态读写state_get_settings、state_write_settings、state_get_themes、state_get_plugins、state_get_widgets、state_get_wallpapers、state_get_icon_packs各资源的状态查询工具/调试run、open_file、select_file_on_explorer、log_from_webview、debug_open_dev_tools、debug_get_widgets_statuses实用工具与 Widget 调试Widget 运行时trigger_widget、trigger_context_menu、trigger_dialog、set_current_widget_status、set_self_position、get_self_window_handleWidget 自身的生命周期控制subscribe —— 订阅后台推送事件subscribe封装了 Tauri 的listen返回UnSubscriber取消订阅函数并通过AllSeelenEventPayloads保证事件名与负载类型一一对应。const unsub await subscribe(SeelenEvent.GlobalFocusChanged, ({ payload }) { // 前台窗口变化时执行逻辑 }); // 组件卸载时取消订阅 unsub();事件枚举src/handlers/events.ts同样覆盖系统与状态两大维度global-focus-changed、global-mouse-move、system::monitors-changed、colors-changed、dark-mode-changed、media-sessions、power-status、bluetooth-devices-changed、clipboard::data-changed、settings-changed、themes、plugins-changed、widgets-changed、UserResources::wallpapers-changed等。Widget 开发者既可通过事件驱动 UI 刷新也可与invoke组成读-订阅-更新的响应式数据流。状态模型settings、theme、plugin、widget、wallpaper 与 icon packlibs/core/src/state/mod.tsTS 侧与 libs/core/src/state/mod.rsRust 侧共同定义了 Seelen UI 的全部可配置资源类型。Rust 侧模块划分如下libs/core/src/state/mod.rsmod icon_pack; // 图标包 mod placeholder; // 占位资源 mod plugin; // 插件含 twm 窗口管理器 / weg 桌面组件等子类型 pub mod settings; // 设置按显示器/主题/壁纸/Widget 拆分 按应用覆盖 settings_by_app 快捷键 mod theme; // 主题config.rs 定义结构tests.rs 提供测试 mod wallpaper; // 壁纸 mod weg_items; // 桌面组件条目 mod widget; // Widgetdeclaration/dialog/context_menu/positioning 等 mod wm_layout; // 窗口管理器布局 mod workspaces; // 工作区其中settings子模块的分层设计非常典型libs/core/src/state/settings/by_monitor.rs、by_theme.rs、by_wallpaper.rs、by_widget.rs把设置按显示器、主题、壁纸、Widget 四个维度拆分允许同一功能在不同场景下有不同的配置覆盖settings_by_app.rs按应用粒度覆盖对应 JSON Schema 中的settings_by_app.schema.json即VecAppConfigshortcuts.rs快捷键配置。theme 模块除结构定义config.rs外还自带 tests.rs 与 TS 侧 theming.ts说明主题不仅是数据还包含可运行的主题化逻辑。widget 模块的 TS 侧组织libs/core/src/state/widget/体现了 Widget 抽象的渐进式分层abstractions/目录下0_core.ts、1_rect.ts、2_triggering.ts、3_autosize.ts按依赖顺序组织加上positioning.ts定位、performance.ts性能、interfaces.ts接口外加 Rust 侧的declaration.rs、dialog.rs、context_menu.rs——可以说 Widget 开发所需的一切契约都在这里。系统状态monitors、ui_colors、language、user 与 bluetoothlibs/core/src/system_state/ 承载运行时系统快照类型TS 侧入口 libs/core/src/system_state/mod.ts 导出monitors、ui_colors、language、user与bluetooth。值得展开的两点ui_colorsui_colors.rs 与 ui_colors.ts把 Windows 的 Mica/亚克力、强调色等系统取色结果结构化为UiColors配合事件colors-changed与命令get_system_colors让 Widget 能跟随系统主题动态取色这是动态主题色 Widget 的数据来源。bluetoothsystem_state/bluetooth/通过build_enums.rs从class_of_device.yml、appearance_values.yml等 YAML 清单构建枚举如ClassOfDevice、LowEnergyAppearance再生成对应 Rust 枚举class_of_device_enums.rs、low_energy_enums.rs。这套YAML 驱动代码生成的模式保证了蓝牙设备分类的枚举与规范同步最终同样通过generate_schemas导出到 TS 侧bluetooth/mod.ts。工具函数与运行时能力libs/core/src/utils/mod.ts 提供三个开箱即用的工具import { Rect, isSeelenUIRuntime, RuntimeStyleSheet } from seelen-ui/lib; const r new Rect(); // 默认全 0表示一个矩形区域 if (isSeelenUIRuntime()) { // 仅在 Seelen UI Widget 运行时内为 true }Rect矩形数据结构left/top/right/bottom对应 Rust 侧 libs/core/src/rect.rsisSeelenUIRuntime()通过检测globalThis.window.__SLU_WIDGET判断当前环境是否为 Seelen UI Widget 运行时注意该函数与 TypeScript 的instanceof不同它不检查某个类而是检查全局标记返回布尔值文档示例中用globalThis.window as any断言是因为部分环境类型定义未声明该属性RuntimeStyleSheet来自 utils/DOM.ts用于在 Widget 中动态注入/管理样式表。此外 libs/core/src/utils/ 还包含List.ts、State.ts、async.ts等 TS 工具以及 Rust 侧的slug.rsslug 化、traits.rs。而 libs/core/src/constants/mod.ts 定义了SupportedLanguages常量数组与SupportedLanguagesCode类型覆盖 80 余种语言含zh-CN、zh-TW是语言选择器与 i18n 的基础。构建与开发工作流开发者若要从源码构建该库可依据 libs/core/deno.json 中的 tasks# 1. 生成 Rust → TS 绑定与 JSON Schema内部调用 cargo test --features gen-binds deno task build:rs # 2. 使用 deno/dnt 构建 npm 包到 ./npm deno task build:npm # 或者一步到位 deno task build测试配置test字段会运行src/**/*.test.ts下的 TS 测试仓库中已有 libs/core/src/lib.test.ts、icon_pack.test.ts 等测试文件lint 强制explicit-function-return-type规则显式函数返回类型这也是该库强调类型安全的一个佐证。运行时集成从核心库到 Seelen UI 应用libs/core的代码主要在以下两种场景被消费Seelen UI 应用内的 Widget/插件/主题它们在独立的 WebView 中运行通过invoke/subscribe与后台 Rust 进程通信。src/ui/应用内置 UI与src/static/widgets/内置 Widget 目录下的代码即是这些契约的直接消费者。第三方扩展开发者通过 JSR/npm 安装seelen-ui/lib复用类型与 API 编写自己的 Widget、插件、主题再放入 Seelen UI 的资源目录如src/static/widgets/所示的 Widget 结构、src/static/plugins/所示的插件结构、src/static/themes/所示主题结构供应用加载。总结libs/core的价值在于用 Rust 单点定义领域模型通过宏与ts-rs/schemars自动生成 TS 类型与 JSON Schema再以invoke/subscribe桥接 Tauri 前后端。它同时为 Widget、插件、主题三类扩展提供类型安全的基础设施是理解 Seelen UI 扩展机制的关键入口。对开发者而言掌握命令/事件两张枚举表commands.ts、events.ts即可对接 Seelen UI 的绝大多数能力——从工作区管理、壁纸控制到系统取色、夜间模式与状态读写无需深入底层 Windows API。【免费下载链接】Seelen-UIThe Fully Customizable Desktop Environment for Windows 10/11.项目地址: https://gitcode.com/GitHub_Trending/se/Seelen-UI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考