# core-ui (ghboke) **Repository Path**: xwadmin/core-ui-ghboke ## Basic Information - **Project Name**: core-ui (ghboke) - **Description**: 镜像加速 简化,重构的UI库 C API风格。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2026-04-17 - **Last Updated**: 2026-05-14 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README

CORE UI

English · 中文  ·  📖 在线文档

**Core UI** 是一个现代化的 Windows 桌面 UI 框架,从零重新设计以匹配 Microsoft **Fluent 2** 视觉语言,同时保持**原生级的性能**与**极小的分发体积**。底层基于 **Direct2D / Direct3D 11** 硬件加速渲染,把从按钮、文本框到 Flyout、Dialog、TitleBar 的 25+ 个内置控件统一在一套 **纯 C API** 之下(共 250+ 个导出函数)——Rust、Go、Python、C#、Delphi 乃至 Lua 都能直接调用,不需要写 C++ 绑定层。 推荐用 **`.uix` 单文件组件**(Vue 3 SFC 风格:`` + ` ``` - **Vue 3 Options API**:`data()` / `computed` / `methods`,QuickJS-NG (ES2020+) 求值 - **响应式系统**:Proxy + WatchEffect,模板里 `{{ expr }}` / `:attr` / `v-if` / `v-for` / `v-model` / `@click` 自动收集依赖、增量重渲染 - **CSS 子集**:类 / 标签 / 后代选择器、伪类(`:hover` / `:disabled`)、Flexbox、`var(--*)` CSS 变量主题 - **`` 标签**:声明式窗口配置(标题 / 尺寸 / 无边框 / 主题),无需写一行 C - **i18n 内置**:`{{ $t('welcome') }}` 自动查 `.lang` 文件,运行时 `ui_page_set_locale` 切语言 - **嵌套 `v-for > v-if > v-for` 安全**,keyed diff 跨 reorder 复用控件 - **声明式右键菜单**:`` + `` / `` ### 🌐 纯 C API,所有语言都能调 ```c #include ui_init_with_theme(UI_THEME_LIGHT); UiPage page = ui_page_load_file(L"app.uix"); ui_page_load_language_file(page, "zh", L"lang/zh.lang"); ui_page_set_locale(page, "zh"); UiWindow win = ui_page_open_window(page, NULL); /* 双向交换 reactive 状态 */ ui_page_set_int (page, "count", 42); ui_page_set_text(page, "name", L"Alice"); ui_page_set_json(page, "items", "[{\"id\":1,\"label\":\"a\"}]"); char* j = ui_page_get_json(page, "items"); ui_page_free(j); ui_run(); ui_page_destroy(page); ``` - **250+ 导出函数**,句柄全部 `uint64_t`,没有一个 C++ 类型泄漏 - Rust / Go / Python / C# / Delphi / Pascal / Lua 全部能直接绑定 - Page API(`ui_page_*`)为 `.uix` 而生;底层 widget 工厂(`ui_vbox`、`ui_button` ...)仍可过程式构造控件树 ### 🔍 自动化 / 调试:控件可编程驱动 从 1.1.0 起新增一整套 **`ui_debug_*` 事件注入 API** —— 无需真实鼠标键盘即可 驱动任意控件,为端到端测试、AI Agent 操作 UI、脚本化回归设计: ```c ui_debug_click(win, btn); // 完整 mouse down/up,触发 onClick ui_debug_combo_select(win, combo, 2); // 选中第 3 项 + 触发 onChanged ui_debug_right_click_at(win, 300, 200); // 右键弹出注册的 context menu int path[] = {2, 0}; ui_debug_menu_click_path(win, path, 2); // 点 submenu 里的叶子 ui_debug_type_text(win, L"hello"); // 逐字符键盘输入 ``` - **60+ 个 `ui_debug_*` 函数**:click / hover / drag / wheel / key / focus / 各控件 高层操作 / 子菜单 path 点击 / HWND `PostMessage` 通道 … - 内置 **Named Pipe IPC**(`\\.\pipe\ui_core_debug`)45+ 条命令,PowerShell / Python 一行能驱动;`ui_debug_server_start(win, NULL)` 启动 - **线程安全工具** `ui_window_invoke_sync` 把工作线程的调用 marshal 到 UI 线程 - 完整参考见 **[`docs/debug-simulation.md`](./docs/debug-simulation.md)** ## 📊 真实数据 | 指标 | 数值 | |------|------| | `core-ui.dll` 体积(全功能) | **8.4 MB** | | `ui-demo-uix.exe` 体积(静态链接) | **~1 MB** | | 空窗口内存占用 | **< 30 MB** | | 冷启动到首帧 | **< 200 ms** | | 60 fps 动画 CPU 占用 | **< 3%** | | 导出 C 函数数量 | **250+** | | 内置控件 | **25+** | | 脚本运行时 | **QuickJS-NG v0.14.0**(ES2020+) | | 支持的图片格式(ImageView) | PNG / JPG / BMP / GIF / WebP / SVG | ## 🚀 快速开始 ### 环境要求 - Windows 10 (1709+) - CMake 3.20+ - **MSVC 2019+ 或 clang-cl**(C++17)— 不支持 MinGW ### 构建 从 **Visual Studio Developer Command Prompt**(或先 source `vcvars64.bat`)开一个终端,然后: ```bash git clone https://github.com/ghboke/core-ui.git cd core-ui cmake -B build -G Ninja cmake --build build --target core-ui ``` 常用 target: | Target | 产物 | |---|---| | `core-ui` | `core-ui.dll` + `core-ui.lib` 导入库(默认) | | `core-ui-static` | `core-ui-static.lib` 自包含静态归档(含 QuickJS) | | `ui-demo-uix` | `ui-demo-uix.exe` 单文件 demo(资源烤进 exe) | 不指定 `--target` 就编全部。Visual Studio 17 2022 generator 也能用: ```bash cmake -B build -G "Visual Studio 17 2022" -A x64 cmake --build build --config Release ``` 单 exe 分发(无 DLL 依赖,所有代码 + QuickJS 静态链进 exe): ```bash cmake -B build -G Ninja -DUI_CORE_STATIC=ON cmake --build build ``` ### Hello World **hello.uix** ```vue ``` **main.cpp** ```cpp #include int WINAPI WinMain(HINSTANCE, HINSTANCE, LPSTR, int) { ui_init_with_theme(UI_THEME_LIGHT); UiPage page = ui_page_load_file(L"hello.uix"); if (!page) return 1; UiWindow win = ui_page_open_window(page, NULL); if (!win) { ui_page_destroy(page); return 2; } int ret = ui_run(); ui_page_destroy(page); return ret; } ``` 就这么多。**没有 .vcxproj、没有 moc 预处理器、没有 XAML 编译器、没有 IDL。** ### 单 exe 打包(资源烤进可执行文件) ```cmake include(cmake/UiCoreHelpers.cmake) add_executable(my-app WIN32 main.cpp) target_link_libraries(my-app PRIVATE core-ui) ui_core_embed_text(my-app FILE app.uix OUT app.embed.h VAR k_app) ui_core_embed_text(my-app FILE lang/zh.lang OUT lang_zh.embed.h VAR k_lang_zh) ``` ```cpp #include "app.embed.h" #include "lang_zh.embed.h" UiPage page = ui_page_load_string(k_app); ui_page_load_language_string(page, "zh", k_lang_zh); ``` `demo/ui_demo_uix.cpp` 就是这种用法的最小完整例子(57 行胶水 + 单 `.uix` 文件 12 页 demo)。 ### 🛠️ 故障排查 #### 1. ninja link 阶段卡死(Windows SDK rc.exe bug) **症状**:build 看似在 link / 资源编译阶段卡死、CPU 不动;查 `build/CMakeFiles/.dir/CMakeFiles/-version.rc.res` 是 **0 字节**,同目录有 9 KB 左右的 `RCa*` 临时文件。`tasklist` 看到 `cmake.exe` + `rc.exe` 进程在跑但内存恒定。 **原因**:某些 Windows SDK 版本的 `rc.exe` 在 ninja 子进程上下文里有死锁 bug。 **修复**:让 cmake 用 LLVM 的 `llvm-rc.exe` 替代系统 `rc.exe`: ```bash # 找到 llvm-rc.exe 路径(通常随 LLVM / clang-cl 一起装) where llvm-rc cmake -B build -G Ninja -DCMAKE_RC_COMPILER=C:/path/to/llvm-rc.exe ``` #### 2. `cmake -B build` 报 `core-ui only supports MSVC / clang-cl` **原因**:cmake 没识别到 MSVC 工具链——多半是终端没初始化 vcvars。 **修复**: - 用 **Visual Studio Developer Command Prompt** 开终端 - 或在普通 cmd 里先运行:`"C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars64.bat"`(路径按你装的 VS 版本调整) #### 3. 静态链接缺 `JS_*` 符号 **症状**:用 `core-ui-static.lib` 静态链接时报 `unresolved external __imp_JS_*` ~50 个。 **原因**:`core-ui-static.lib` 不含 QuickJS 实现。**用 install target 生成的 `lib/static/core-ui.lib`** 才是合并了 QuickJS 的胖归档: ```bash cmake --build build --target release-package # 产物在 release/core-ui-vX.Y.Z/lib/static/core-ui.lib ``` ## 🧩 内置控件 / 标签 `.uix` 模板里的标签直接映射到原生 widget: | 类别 | 标签 | |---|---| | **容器** | `div`(Flexbox:`flex-direction` / `flex` / `gap` / `padding`)| | **文本** | `label`(多行、自动换行)| | **按钮** | `button`、`IconButton` | | **输入** | `input`(type=`text` / `password` / `checkbox` / `radio` / `range` / `number`)、`textarea` | | **选择** | `toggle`、`combobox` | | **状态** | `progressbar`,`badge` 类(CSS)| | **弹出** | `menu` / `menuitem` / `separator`、`Flyout`、`Dialog`、`Toast` | | **图像** | `img`、`svg`(内联),底层 `ImageView` 支持缩放 / 平移 / 裁剪 | | **窗口** | `TitleBar`(仅 `frameless="true"` 时使用) | 需要程序化构造时,C API 也提供 `ui_vbox` / `ui_hbox` / `ui_label` / `ui_button` / `ui_text_input` / `ui_combobox` / `ui_slider` / `ui_progress_bar` / `ui_image_view` / `ui_dialog` / `ui_tab_control` / `ui_scroll_view` 等工厂函数。 ## 🎨 主题 内置 Fluent 2 深色 / 浅色主题,运行时一行切换: ```c ui_theme_set_mode(UI_THEME_DARK); ui_theme_set_mode(UI_THEME_LIGHT); ``` `.uix` 的 `