# OpenDesktopUI

**Repository Path**: clfsky/open-desktop-ui

## Basic Information

- **Project Name**: OpenDesktopUI
- **Description**: 一款参考Flutter机制和渲染的.NET跨平台GUI，使用微软的FluentDesign2设计语言，支持Linux x64(wayland)与Windows x64
自用框架与项目，不接受任何PR，如果想扩充平台支持或者做生态，可以自行Fork任意处理，该仓库只用于服务我自身需求。
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-09-17
- **Last Updated**: 2026-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenDesktopUI

OpenDesktopUI 是一个面向工具型桌面应用的 **.NET 10 / C# 声明式 UI 框架**，支持 Windows 与 Linux Wayland。使用 C# 组合界面，通过 `Widget` / `State` 管理组件与状态，由 Skia 完成绘制，无需 XAML 或强制采用 MVVM。

框架机制以 Flutter 的组件、布局、生命周期与渲染管线为主要参考，视觉与交互规格参考 WinUI 3 Fluent 2。OpenDesktopUI 独立实现这些机制，不兼容 Flutter、WinUI 或 Avalonia 的 API 与项目格式。

**建议从 Gallery 开始体验。** 它是查看控件外观、交互和用法的统一入口，每张示例卡片可以通过 **Show Source / Hide Source** 查看对应的独立示例源码。

## 当前状态

当前版本为 **0.9.2.6**，版本以 [Directory.Build.props](Directory.Build.props) 为准。源码可直接构建和运行；框架包目前采用本地 NuGet 分发，尚未发布到 nuget.org。

本版统一了 Windows 10 / Linux 的窗口边框基础色 `FluentWindowBorder`，调整 InfoBar 四种状态图标的笔画粗细，并增加 `ShowMinimizeButton`、`ShowMaximizeButton` 配置（默认显示）。自定义 `FluentWindowChrome` 可使用同名的小写构造参数；这些开关只控制按钮显示，不禁用原生窗口操作。

- **声明式界面**：`Widget` / `State`、布局、状态更新、滚动、动画与页面导航。
- **Fluent 控件**：明暗主题、基础输入、ListView / TreeView 虚拟化、NavigationView、SplitView、TabView、Overlay、Flyout、Dialog 与静态 Image。
- **桌面能力**：窗口外壳、中文输入法、剪贴板、文件与文件夹选择、打开与保存对话框、扩展名过滤、外部 URI 打开。
- **渲染后端**：Windows 默认使用 ANGLE / D3D11；Wayland 默认使用 EGL / OpenGL ES。两端均提供显式选择的 CPU 后端。
- **开发工具**：项目模板、VS Code 代码片段、本地打包与包消费验证脚本。

当前围绕单窗口桌面应用演进，窗口内可使用页面导航。不支持 macOS、移动端、Web、X11、多窗口和辅助技术平台桥接；尚无可视化设计器、实时预览或框架级热重载工具。

### AI 支持尚未就绪

**当前缺少经过实际验证、可正式使用的 AI 开发支持。** 仓库保留了 `OpenDesktopUI.AIContext` 上下文查询工具与 Codex Skill 插件的探索性实现，但尚未完成真实 AI 接管评测，也不随常规框架包分发。它们不应被视为已交付能力。

现阶段请以 Gallery 示例、公开 API 和实际编译结果为准；VS Code 代码片段仅用于生成常见代码骨架，不提供 AI 能力。

## 从源码构建和运行

以下命令均在仓库根目录执行。**运行仓库中的 Gallery 不需要先打包、安装模板或配置本地 OpenDesktopUI NuGet 源。** 首次构建会还原第三方依赖，需要可用的 NuGet 源或已准备好的包缓存。

### 环境要求

- **.NET 10 SDK**：只安装运行时不足以编译。[global.json](global.json) 以 `10.0.100` 为起点，允许使用后续 .NET 10 SDK feature band。
- **Windows x64**：Windows 10 或更新版本，具备可用的图形驱动。
- **Linux x64**：运行于 Wayland 图形会话，提供所需协议和系统运行库，详见下文。仅支持 x64，不将发行版名称视为所有硬件均已验证的承诺。

可先执行 `dotnet --info` 确认 SDK。Windows 和 Linux 请使用各自独立的源码目录与 `bin/obj`，避免跨系统共用还原和构建产物。

### Windows Gallery

构建：

```powershell
dotnet build samples/OpenDesktopUI.Win32.Sample/OpenDesktopUI.Win32.Sample.csproj --configuration Release
```

运行，默认使用 ANGLE / D3D11 GPU：

```powershell
dotnet run --project samples/OpenDesktopUI.Win32.Sample/OpenDesktopUI.Win32.Sample.csproj --configuration Release --no-build
```

显式使用 CPU / GDI：

```powershell
dotnet run --project samples/OpenDesktopUI.Win32.Sample/OpenDesktopUI.Win32.Sample.csproj --configuration Release --no-build -- --cpu
```

重新构建前请关闭正在运行的 Gallery，避免可执行文件或 DLL 被占用。

### Linux Wayland Gallery

Linux 的 Gallery 入口保留了 `OpenDesktopUI.Wayland.Skia.Probe` 项目名，但展示的是同一套 Gallery 内容。请在本机 Wayland 桌面的终端中运行，确保 `WAYLAND_DISPLAY` 与 `XDG_RUNTIME_DIR` 指向有效会话。

运行条件包括：

- compositor 提供 `wl_compositor` v4+、`xdg_wm_base` v3+，以及窗口、光标和 SHM 路径需要的 `wl_shm`。
- 系统提供 `libwayland-client.so.0`、`libwayland-cursor.so.0`、`libxkbcommon.so.0` 和 Skia 所需的 fontconfig 等运行库。
- GPU 路径还需要 `libwayland-egl.so.1`、`libEGL.so.1`、`libGLESv2.so.2` 与可用的 EGL / GLES 驱动；Skia、HarfBuzz 的原生资产由 NuGet 还原。
- 中文显示需要已安装的中文字库；中文输入法需要 compositor 的 `zwp_text_input_manager_v3` 支持，以及正确配置的输入法服务。只有字体并不足以启用 IME。

不同发行版的软件包名可能不同，请按系统提供的软件包安装这些运行库。WSLg 也需要核对协议版本，不能默认认为其直接会话满足要求。平台约束见 [Wayland 文档](docs/platforms/wayland/)。

构建：

```bash
dotnet build samples/OpenDesktopUI.Wayland.Skia.Probe/OpenDesktopUI.Wayland.Skia.Probe.csproj --configuration Release
```

运行，默认使用 EGL / OpenGL ES GPU：

```bash
dotnet run --project samples/OpenDesktopUI.Wayland.Skia.Probe/OpenDesktopUI.Wayland.Skia.Probe.csproj --configuration Release --no-build
```

显式使用 CPU / direct-SHM：

```bash
dotnet run --project samples/OpenDesktopUI.Wayland.Skia.Probe/OpenDesktopUI.Wayland.Skia.Probe.csproj --configuration Release --no-build -- --cpu
```

Wayland 也接受 `--shm`，与 `--cpu` 一样选择 CPU / direct-SHM。CPU 模式仍需要 Wayland 会话、字体及相关系统运行库。两端 GPU 出错时会明确报告，不会静默切换为 CPU。

## 在自己的项目中使用

源码体验与 NuGet 消费是两条独立流程。要通过模板创建应用，先生成框架包并准备自己的本地 NuGet 源。

### 生成本地包

以下为 Windows PowerShell 流程：

```powershell
.\scripts\Publish\publish-packages.ps1
```

脚本显示当前版本并等待输入：直接回车保留版本，输入新版本则在全部包生成成功后更新 `Directory.Build.props`。生成的 **15 个运行库包和 1 个模板包** 放在 `Output/`，不会上传远程服务，也不会自动复制到其他 feed。AI 工具不在这 16 个包中。

每个库有独立目录，例如 `Output/OpenDesktopUI.Core/OpenDesktopUI.Core.0.9.2.6.nupkg`。发布新版本时保留同一库的其他版本；同名同版本包会被本次产物替换。旧版脚本平铺在 Output 根目录的包会自动归入对应库目录；迁移发现同名但内容不同的包时停止并提示，不擅自丢弃。包内容改变时应使用新版本，避免 NuGet 缓存复用同一版本的旧内容。

下面以 `D:\CustomNuget` 为例，这不是固定路径，可以换成自己的目录：

```powershell
New-Item -ItemType Directory -Force D:\CustomNuget | Out-Null
Get-ChildItem .\Output -Recurse -Filter *.nupkg -File | Copy-Item -Destination D:\CustomNuget\
dotnet nuget list source
```

如果该目录尚未注册为源，再执行一次：

```powershell
dotnet nuget add source D:\CustomNuget --name opendesktopui-local
```

本地源提供 `OpenDesktopUI.*`，第三方依赖仍需要 nuget.org 或可用镜像。生成的包可复制到 Linux 上的本地目录使用；在 Linux 消费时，需在该系统中单独注册实际目录，不能照搬 Windows 路径。包分发与两端验证详见[本地 NuGet 说明](docs/tooling/distribution/local-nuget.md)。

### 安装模板

在已配置本地源的环境中执行：

```powershell
dotnet new install OpenDesktopUI.Templates --nuget-source D:\CustomNuget
dotnet new list odui
```

如果安装过旧版模板，先运行 `dotnet new uninstall OpenDesktopUI.Templates` 再安装；卸载模板不会影响已创建的应用。Linux 上将 `--nuget-source` 后的目录替换为已准备好的 Linux 本地源路径。

| 平台 | 加入已有解决方案 | 创建独立解决方案 |
| --- | --- | --- |
| Windows x64 | `odui-win32` | `odui-win32-slnx` |
| Linux Wayland x64 | `odui-wayland` | `odui-wayland-slnx` |

创建并运行独立 Windows 应用：

```powershell
dotnet new odui-win32-slnx -n MyDesktopApp -o MyDesktopApp
dotnet build MyDesktopApp/MyDesktopApp.slnx
dotnet run --project MyDesktopApp/MyDesktopApp.csproj
```

在 Linux Wayland 环境创建并运行独立应用：

```bash
dotnet new odui-wayland-slnx -n MyDesktopApp -o MyDesktopApp
dotnet build MyDesktopApp/MyDesktopApp.slnx
dotnet run --project MyDesktopApp/MyDesktopApp.csproj
```

向已有解决方案添加项目时，使用纯项目模板。例如 Windows：

```powershell
dotnet new odui-win32 -n MyGui -o src/MyGui
dotnet sln ExistingApp.slnx add src/MyGui/MyGui.csproj
dotnet build ExistingApp.slnx
```

请将 `ExistingApp.slnx` 换成自己的解决方案路径；Linux 应用改用 `odui-wayland`。模板默认引用与模板包一致的框架版本，可用 `--OpenDesktopUIVersion <版本>` 覆盖，或用 `--skipRestore` 暂缓还原。

### VS Code 代码片段

[上手代码片段](.vscode/opendesktopui.code-snippets)提供 `stless`、`stful`、`oninit`、`ondispose` 等前缀，用于生成组件和生命周期方法骨架。需要时将 `opendesktopui.code-snippets` 复制到自己在 VS Code 中打开的项目或工作区目录下的 `.vscode/` 中；模板不会自动携带这份文件。

## 构建检查与测试

Windows 上的完整检查命令：

```powershell
dotnet build OpenDesktopUI.slnx --configuration Debug
dotnet test OpenDesktopUI.slnx --configuration Debug
dotnet format OpenDesktopUI.slnx --verify-no-changes
```

Linux **不要直接执行整个解决方案的 `dotnet test`**，其中含有 Win32 专用测试。应按 [AGENTS.md](AGENTS.md) 的清单选择 13 个跨平台 / Wayland 测试项目逐项运行，例如：

```bash
dotnet test tests/OpenDesktopUI.Skia.Tests/OpenDesktopUI.Skia.Tests.csproj --configuration Debug
```

本地包与模板消费验证可分别运行：

```powershell
.\scripts\Publish\verify-local-packages-win32.ps1
```

```bash
bash scripts/Publish/verify-local-packages-wayland.sh
```

这些脚本会重建各自 `artifacts/local-nuget/<RID>/` 下的验证产物。包消费检查不能替代 Gallery 的视觉、输入法和窗口交互验证。

## 项目维护与 Fork

**本项目不接受任何 Pull Request（PR）。** 项目由作者按自身需求维护，不采用社区 PR 合并流程。

如果你希望扩展控件、增加平台支持、集成其他工具或建设更大的生态，建议自行 **Fork**，在自己的仓库中维护和发布。请不要以 PR 的方式请求将这些改动合并回本仓库。

## 进一步了解

- [文档导航](docs/README.md)：架构、组件、平台与工具的维护入口。
- [架构概览](docs/architecture/overview.md)：框架分层与职责。
- [跨层能力索引](docs/capabilities/README.md)：组合功能与各模块的关系。
- [设计系统](docs/architecture/styling/design-system.md)：Fluent 视觉契约。
- [Flutter 上游同步账本](docs/upstream/flutter/README.md)：机制参考与版本追踪。
- [第三方依赖](docs/governance/repository/third-party-dependencies.md)与[第三方声明](THIRD-PARTY-NOTICES.md)：依赖及来源信息。