JadeView WinUi 原生版规划讨论｜JadeView 开发者社区

JadeView WinUi 原生版规划讨论

开头先言：本项目为开源项目，由JadeView 主导，欢迎各位大佬参与本项目的开发。

定位：纯原生 WinUI3 跨语言 UI 运行时，Rust 核心编译为标准 DLL，多语言通过 C ABI 接入；与现有 JadeView WebView2 版为两条独立产品线，非 WebUI、无浏览器内核；完全开源。

一、项目概述

1.1 项目背景

现有 JadeView 核心能力聚焦于 WebView2 封装与虚拟文件系统（JAPK），面向跨平台 Web 渲染桌面应用场景。但在 Windows 平台，大量系统工具、高性能客户端、原生体验类应用存在「想用原生 WinUI 控件、不想引入 Web 技术栈、同时希望多语言接入」的需求。

WinUI3 作为微软官方现代桌面 UI 框架，具备 Fluent Design、系统级集成、高性能渲染等优势，但原生开发门槛高（COM/WinRT 概念复杂、C#/.NET 运行时重、C++ 开发效率低），且缺乏跨语言轻量接入方案。

1.2 项目目标

打造基于 Rust + windows-rs 构建的 JadeView WinUI 原生运行时：

•
封装 WinUI3 完整窗口与控件能力，屏蔽 COM/WinRT 底层复杂度
•
核心层编译为标准 Windows DLL，导出稳定 C ABI，支持 Rust / Go / C / C# / Python 等主流语言直接调用
•
纯原生渲染、无 WebView2 依赖、无 HTML/CSS 解析，与现有 WebView2 版 JadeView 完全独立
•
完全开源，采用宽松协议，社区驱动迭代，保留 JadeView 一贯的轻量、静态编译、低内存占用特性

1.3 核心价值

•
原生体验：完整 WinUI3 Fluent Design 风格，云母/亚克力材质、系统级动画、原生控件交互
•
轻量高性能：无浏览器内核开销，内存占用仅为 WebView 方案的 1/5~1/3
•
跨语言友好：各语言无需掌握 WinRT/COM 技术栈，通过熟悉的 API 即可构建原生 Windows 应用
•
全 Rust 底座：内存安全、无 GC，DLL 输出无额外运行时依赖，兼容现有 JadeView 工程体系
•
开源开放：核心代码完全开源，社区可扩展控件、贡献绑定、共同迭代

二、核心定位与差异化

2.1 与现有 JadeView WebView2 版的本质区别

维度	JadeView WebView2 版	JadeView WinUI 原生版
渲染内核	WebView2（Edge 浏览器内核）	WinUI3 原生 WinRT 控件（DirectX 渲染）
UI 技术栈	HTML / CSS / JavaScript	原生控件 / 代码构建 UI / 可选 XAML
核心能力	Web 页面渲染、虚拟资源、JS 互操作	原生窗口、原生控件、系统深度集成
分发形式	可单 exe 内嵌	核心 DLL + 各语言绑定；Rust 可静态链接
内存占用	中等\~偏高（浏览器内核基础开销）	极低（原生控件，无额外运行时）
跨平台性	Windows / macOS / Linux	仅 Windows（深度适配 Win10/11）
适用场景	跨平台桌面应用、Web 生态复用	Windows 原生工具、高性能客户端、系统级应用
产品线关系	并行独立产品线，互不依赖	并行独立产品线，互不依赖

明确界定：本项目不是 WebView2 套 WinUI 外壳，也不是 WebUI 方案；所有 UI 元素均为 WinUI3 原生控件，不存在浏览器内核与 HTML 解析。

2.2 同类方案对比

方案	语言接入方式	原生程度	内存	开发门槛	开源
本项目（JadeView WinUI）	标准 DLL + C ABI，多语言薄绑定	100% 原生 WinUI3	极低	低（屏蔽 WinRT 复杂度）	是
微软官方 C# WinUI3	.NET 原生，仅 C#	100% 原生	中（.NET 运行时）	中	部分开源
微软官方 C++/WinRT	C++ 原生，仅 C++	100% 原生	极低	高（COM/WinRT 心智负担重）	是
Wails / Tauri	WebView + 原生窗口外壳	Web 渲染 + 原生窗口	中高	低	是
Qt	C++ 核心 + 各语言绑定	Qt 自绘控件	高	中	是（部分协议）

三、技术架构设计

3.1 整体分层架构

自底向上分为四层，核心原则：底层 Rust 实现 WinRT 封装，编译为标准 DLL 导出 C ABI，上层多语言薄绑定零逻辑。

┌─────────────────────────────────────────┐
│  语言绑定层（Go / Rust / C# / Python）  │  各语言原生风格 API，纯薄封装无逻辑
├─────────────────────────────────────────┤
│        JadeView FFI 接口层（C ABI）     │  稳定二进制接口，DLL 导出，跨语言通用
├─────────────────────────────────────────┤
│      JadeView WinUI 核心封装层          │  窗口管理、控件、布局、事件、调度
├─────────────────────────────────────────┤
│  windows-rs 官方绑定 + WinUI3 运行时    │  微软官方 WinRT 元数据自动生成
└─────────────────────────────────────────┘

3.2 核心分发形态

1.
核心产物：jadeview_winui.dll + jadeview_winui.h
- •
  Rust 编译为标准 Windows 动态链接库
- •
  导出纯 C 接口，无 C++ 符号、无 Rust 特有符号
- •
  依赖 WebView2 Runtime 以外的系统组件，无额外运行时
2.
Rust 语言：可直接静态链接 crate，也可调用 DLL
3.
其他语言：统一通过 FFI 调用 DLL，各语言仅提供语法糖封装

3.3 技术选型

•
底层绑定：windows-rs 0.52+（微软官方维护，WinRT/WinUI3 完整绑定）
•
核心实现：纯 Rust 编写，编译期内存安全，无 GC
•
UI 构建：优先代码式声明构建 UI，兼容 windows-reactor 声明式范式；不强制依赖 XAML
•
ABI 设计：标准 C 接口，字符串使用 UTF-8，所有权规则清晰，避免跨语言内存泄漏
•
窗口能力：支持 Win10/11 双兼容，自定义标题栏、云母材质、无边框、高 DPI 感知
•
开源协议：Apache 2.0（与 windows-rs 保持一致，降低合规风险）

3.4 关键技术点

1.
消息循环统一调度：封装 WinUI3 DispatcherQueue，提供跨线程安全的 UI 调度接口，屏蔽 COM 线程模型复杂度
2.
安全的控件封装：Rust 所有权机制包裹 WinRT 组件引用，自动管理引用计数，DLL 内部完成 COM 生命周期管理
3.
零成本 FFI 设计：批量操作减少跨语言调用次数，字符串与内存所有权清晰定义，附带完整的内存释放约定
4.
自定义标题栏原生支持：完整封装 ExtendsContentIntoTitleBar 与 AppWindowTitleBar 两套 API
5.
可选 WebView 嵌入：作为扩展组件可选集成 wry（非核心），满足「原生控件 + 网页区域」混合场景，核心版本不强制依赖

四、多语言绑定方案（修正版）

4.1 总体原则

•
唯一核心：所有语言共享同一个 jadeview_winui.dll，保证行为一致、bug 同步修复
•
薄绑定原则：语言层仅做语法糖 + 内存安全封装，不引入任何业务逻辑，降低维护成本
•
原生风格：各语言绑定遵循对应语言的命名规范与编程范式
•
自动生成：核心 C 头文件变更时，绑定代码通过脚本自动生成，减少人工维护

4.2 各语言接入方式

语言	接入方式	优先级	说明
Rust	① 静态链接 crate（推荐） ② 调用 DLL	P0	底层实现语言，提供最完整 API；静态链接无 DLL 依赖
C / C++	直接 include 头文件，链接 DLL	P0	基础原生支持，头文件即文档，供系统级开发使用
Go	`syscall` / `cgoless` 加载 DLL，标准 Go 风格封装	P1	核心目标语言，无需 cgo 也可加载，纯 Go 开发体验
C#	`DllImport` 封装，.NET Standard 2.0	P2	兼容 .NET 生态，无需 .NET 运行时即可调用原生 UI
Python	`ctypes` 封装	P2	脚本化快速原型开发

4.3 调用示例（概念版）

Go 语言（加载 DLL 调用）

package main

import "jadeview/winui" // 内部自动加载 jadeview_winui.dll

func main() {
    app := winui.NewApp()
    app.OnLaunch(func() {
        w := winui.NewWindow("JadeView WinUI Demo", 800, 600)
        w.ExtendsContentIntoTitleBar(true)
        w.SetMicaEffect(true)
        
        grid := winui.NewGrid()
        grid.AddRow("auto").AddRow("*")
        
        title := winui.NewTextBlock("原生 WinUI 窗口")
        title.SetFontSize(18)
        grid.Children.Add(title, 0, 0)
        
        w.SetContent(grid)
        w.Show()
    })
    app.Run()
}

C 语言（直接调用 DLL）

#include "jadeview_winui.h"

int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow) {
    JV_App app = jv_app_create();
    jv_app_on_launch(app, on_launch, NULL);
    jv_app_run(app);
    return 0;
}

void on_launch(void* userdata) {
    JV_Window w = jv_window_create("Demo", 800, 600);
    jv_window_extends_content_into_titlebar(w, true);
    jv_window_set_mica(w, true);
    jv_window_show(w);
}

4.4 DLL 方案优势

1.
语言无关：任何支持 C ABI 的语言都能接入，扩展性强
2.
构建解耦：核心层独立编译迭代，各语言绑定无需重新编译 Rust 代码
3.
版本独立：DLL 向下兼容 ABI，业务方可以独立升级核心版本
4.
分发简单：单个 DLL + 对应语言绑定包，无额外安装依赖

五、核心功能模块

5.1 窗口系统模块

•
基础窗口创建：普通窗口、无边框窗口、模态对话框、工具窗口
•
视觉效果：云母/亚克力材质、深色/浅色主题跟随系统、自定义背景
•
标题栏自定义：内容延伸进标题栏、自定义拖拽区域、隐藏系统按钮、全自绘标题栏
•
窗口控制：最小化/最大化/关闭、置顶、窗口大小限制、居中、DPI 感知
•
窗口事件：尺寸变化、激活失活、关闭拦截、拖拽进入

5.2 布局与控件模块

布局系统

•
基础布局：Grid（网格）、StackPanel（栈布局）、DockPanel（停靠）、Canvas（绝对定位）
•
滚动与缩放：ScrollViewer、ViewBox

常用原生控件

•
基础控件：Button、TextBox、PasswordBox、CheckBox、RadioButton、ToggleSwitch
•
数据展示：TextBlock、Image、ListView、TreeView、DataGrid、ProgressBar
•
导航与菜单：TabView、MenuBar、ContextMenu、NavigationView
•
内容控件：Frame、ContentPresenter、SplitView

5.3 事件与绑定模块

•
统一事件注册机制：支持函数指针 + 用户数据的回调方式，跨语言通用
•
跨线程 UI 更新：提供 dispatch 接口，安全从后台线程更新 UI
•
属性绑定：基础双向绑定能力，支持控件属性与业务数据关联

5.4 系统集成模块

•
文件系统：原生文件打开/保存对话框、文件夹选择对话框
•
系统通知：Toast 通知、任务栏图标、系统托盘菜单
•
输入系统：快捷键注册、鼠标键盘事件、输入法支持
•
Shell 集成：文件关联、右键菜单扩展、启动参数解析

5.5 高级渲染模块

•
SwapChainPanel 封装：支持 Direct2D/Direct3D 自定义渲染，满足高性能绘图、视频、游戏场景
•
几何图形与画笔：Win2D 能力封装，提供 2D 矢量绘图接口

六、开源策略

6.1 协议与仓库

•
开源协议：Apache License 2.0
- •
  与 windows-rs 官方协议一致，商业友好，无传染风险
- •
  允许闭源商用、修改、分发，仅需保留版权声明
•
仓库结构：Monorepo 管理
- •
  /core：Rust 核心实现 + DLL 导出
- •
  /bindings：各语言绑定（go、csharp、python 等）
- •
  /examples：各语言示例代码
- •
  /docs：官方文档与 API 参考

6.2 社区治理

•
核心维护：核心团队负责 ABI 稳定、核心控件封装、架构迭代
•
社区贡献：鼓励社区贡献冷门控件、语言绑定优化、示例与文档
•
版本策略：语义化版本号；ABI 层保证向下兼容，大版本升级才允许 break C 接口
•
Issue 响应：核心功能 bug 优先处理，控件扩展类需求社区驱动

6.3 开源价值

1.
技术透明：核心实现完全开源，无黑盒，安全可控，适合系统级工具采用
2.
生态共建：控件长尾由社区补充，降低核心团队维护成本
3.
标准形成：推动形成多语言 WinUI 接入的事实标准
4.
与 JadeView 生态联动：可与开源的 JadeView WebView2 版共享工具链、打包脚本、JAPK 资源体系（可选组件）

七、里程碑规划

M1 核心窗口阶段（4 周）

•
完成 WinUI3 应用模型与窗口核心封装
•
实现窗口创建、自定义标题栏、云母效果、基础事件
•
编译为标准 DLL，导出稳定 C ABI
•
完成 Rust / C 语言绑定验证
•
交付：可运行的原生窗口 Demo，基础 FFI 接口头文件

M2 控件与布局阶段（6 周）

•
完成核心布局系统（Grid/StackPanel/ScrollViewer）
•
实现 15+ 常用原生控件与事件绑定
•
完善样式、主题、DPI 适配
•
交付：控件库 Demo，完整布局能力

M3 系统集成阶段（4 周）

•
文件对话框、系统通知、托盘、快捷键等系统能力
•
SwapChainPanel 自定义渲染封装
•
跨线程调度、生命周期管理完善
•
交付：系统集成 Demo，高性能渲染示例

M4 多语言与开源发布（6 周）

•
发布 Go 语言正式绑定
•
发布 C# / Python 绑定预览版
•
完善文档、示例、最佳实践
•
正式开源发布 0.1 版本
•
交付：多语言 SDK、GitHub 仓库、官方文档站

M5 正式版与优化（4 周）

•
性能优化、体积优化、Windows 10 兼容性打磨
•
可视化设计器原型 / 打包工具集成
•
1.0 正式版发布
•
交付：正式版 SDK、配套工具链

八、风险评估与应对

风险点	影响等级	应对方案
WinUI3 Windows 10 兼容性差异	中	基于 windows-rs 官方兼容层，功能降级适配，明确标注版本差异
COM 线程模型与跨语言调用坑	中	DLL 内部统一调度，封装线程安全接口，避免业务层接触 COM 细节
ABI 稳定性与向后兼容	中	严格的接口版本管理，新增功能用扩展接口，不修改原有函数签名
多语言绑定维护成本高	中	绑定代码自动生成，核心逻辑只在 Rust 层实现一次
控件覆盖度需求长尾	低	按优先级迭代，提供扩展点支持用户直接传入原生 WinRT 对象
编译速度与 DLL 体积	低	feature 裁剪，按需生成 WinRT 绑定，发布优化构建脚本

九、预期价值

1.
产品线补全：形成「Web 跨平台版 + Windows 原生版」双产品线，覆盖不同桌面场景
2.
技术壁垒：填补多语言 WinUI3 轻量封装的开源空白，发挥 Rust 安全 + 原生性能的组合优势
3.
生态复用：与现有 JadeView 打包、分发、JAPK 资源体系（可选）打通，降低工具链重复建设
4.
目标用户：Go/Rust 后端开发者、系统工具作者、高性能桌面应用团队，以及希望摆脱 Web 技术栈的 Windows 客户端开发者
5.
社区影响力：成为 Windows 原生多语言 UI 开发的主流开源方案

JadeView 开发者社区

40成员