SOUI 帮助文档¶
关于本文档
SOUI 帮助文档面向所有希望使用 SOUI 进行界面开发的开发者，覆盖从安装、基础概念到跨平台与高级主题的完整内容。本页是文档的入口，建议先根据下方的「推荐学习路径」定位你需要的章节。
SOUI 是一套轻量级、跨平台的 C++ DirectUI 界面开发框架。它采用「XML 布局 + 图片资源 + 控制脚本（Lua / JavaScript）」的开发方式，形态上接近 Web 程序，但运行在原生层、发布时无需携带额外第三方依赖。
当前主版本为 SOUI5，通过内置的 swinx 模块在六个平台上复刻 Windows API，使同一份 C++ 业务代码即可覆盖：
桌面端：Windows / Linux / macOS
移动端：Android / iOS / 鸿蒙（HarmonyOS / OHOS）
对非 Windows 平台而言，Windows 与跨平台的代码差异几乎为零——这也是 SOUI 跨平台方案最突出的特点。
核心特性¶
| 特性 | 说明 |
|---|---|
| 轻量 DirectUI | 扁平化框架设计，消息传递链短；XML 描述界面层级与属性，发布包精简、无多余依赖 |
| 真正跨平台 | swinx 在各平台实现 Windows API，业务代码几乎无平台分支 |
| 智能渲染 | 精确剪裁区域控制 + 优化刷新策略，支持 Skia / GDI / D2D 渲染后端，可分层混合 |
| 模块化架构 | 渲染、图片解码、资源打包压缩清晰分离，可按需自定义替换 |
| 完整控件体系 | 基础 / 高级 / 容器 / MVC 虚表 / 菜单五大类控件，配套布局系统（linear / grid / anchor / flow / frame / SouiLayout） |
| 强扩展能力 | 自定义控件、动画系统、脚本（Lua / JS）、属性系统、国际化、IPC、异步任务、定时器、日志等 |
快速导航¶
-
快速开始 — 介绍与特性、系统要求、安装指南、快速入门、SOUI3→SOUI5 迁移
进入 → -
用户指南 — 基础概念、项目结构、资源管理、Soui Host、控件系统、SkinObj、布局系统
进入 → -
跨平台开发 — 概述、桌面端（Windows / Linux / macOS）、移动端（Android / iOS / 鸿蒙）及移动端专项优化
进入 → -
高级主题 — 高级控件、异步任务、IPC、窗口处理、控件优化、国际化、脚本、网络等
进入 → -
示例与案例 — 官方示例、典型应用场景参考
进入 → -
构建与部署 — 编译配置、部署指南
进入 → -
API 参考 — 框架接口查阅
进入 → -
故障排除 — 常见问题、调试技巧、社区支持
进入 → -
附录 — 更新日志、许可证、贡献指南
进入 →
推荐学习路径¶
如果你是第一次接触 SOUI，建议按以下顺序阅读：
- 介绍与特性 —— 弄清 SOUI 是什么、为什么选它，以及跨平台思路。
- 安装指南 —— 配置开发环境与 swinx。
- 快速入门教程 —— 实际创建一个可运行的项目。
- 用户指南 —— 掌握控件系统、布局系统、资源管理 与 Soui Host。
- 自定义控件 / 动画系统 —— 按需扩展界面能力。
- 跨平台开发 —— 当目标要覆盖多端时，了解各平台差异与移动端专项优化。
- 高级主题 与 示例与案例 —— 进阶用法与实战参考。
从 SOUI3 升级而来的开发者，请先阅读 SOUI3 到 SOUI5 迁移指南。
跨平台速览¶
SOUI 的跨平台能力来自 swinx：它在各平台把 Windows API 重新实现一遍，让 SOUI 核心以为自己始终运行在 Windows 上。
- Windows：直接使用系统 Win32 API，不编译 swinx。
- Linux / macOS / iOS：swinx 在模块内部自实现完整平台 API，进程拥有自己的入口与事件循环。
- Android / 鸿蒙：进程由 JVM / ArkTS 运行时启动，没有自己的启动器，因此通过
PlatformAPI_Init注册平台 API（详见 跨平台开发 › 概述）。
平台专属能力文档：
获取帮助¶
SOUI 是怎么来的？
SOUI 是目前为数不多的轻量级、可快速开发 Windows 桌面程序的开源 DirectUI 库，其前身为 Duiengine，更早期则源自金山卫士开源版本的 UI 库 Bkwin。经过作者多次开发、维护与升级后得此名称。
SOUI 寓意为「瘦 UI」「UI, just so so!」，目的就是能够快速开发，并且在产品发布时不需要携带其它额外的第三方依赖库，高度精简及集中；模块化使得渲染模块、图片解码模块、资源打包压缩模块得以清晰分离，更能够高度自定义。UI 解析目前采用 XML 布局，便于理解各控件之间的层级关系及其自身的属性设置。目前已有很多成功的商业产品，深受广大开发者及企业的青睐。