TCYM.UI 0.1.1.23

TCYM.UI

介绍

TCYM.UI 是一个跨平台 UI 框架，面向桌面端场景，内置基础组件、布局与样式系统，便于快速构建应用界面。

文档地址

https://tcym.top:8035/tcym/UI/Doc/index.html

UI 架构

• 平台与窗口层：基于 SDL3 负责窗口创建、输入事件、显示信息与跨平台宿主能力；事件模型、窗口标志与本地库加载均已按 SDL3 调整。
• 渲染层：基于 SkiaSharp 负责文本、图形、图片、SVG 与组件内容绘制。
• 样式与布局层：通过 UIStyle、UIStyleParser、UIElement.Layout 等实现类 CSS 的样式解析、布局测量与渲染更新。
• 组件层：Elements 目录提供按钮、标签、表格、树、输入框、下拉等基础 UI 组件。
• 应用与系统层：UIApp、UISystem、UIWindow、Routing 等负责应用生命周期、路由切换、原生能力与页面组织。
• 绑定与生成层：Binding 与 TCYM.UI.Generator 用于属性访问器生成、数据绑定和通知更新。

功能特性

• 跨平台渲染与窗口管理
• 组件化 UI（按钮、标签、表格、下拉、树等）
• 布局与样式系统（CSS/样式解析）
• 动画与过渡效果
• 数据绑定与通知

目录结构

• TCYM.UI/：核心 UI 框架源码
• TCYM.UI.Example/：示例工程与组件演示入口
• Binding/：数据绑定与属性访问器
• Core/：渲染、布局、样式、系统基础能力
• Elements/：内置 UI 组件
• Helpers/：通用辅助工具
• PageDome/：示例页面
• TCYM.UI.Generator/：代码生成器

.NET 版本与依赖

• 目标框架：TCYM.UI 与 TCYM.UI.Pro 支持 net8.0 与 net10.0；示例项目当前仍使用 net8.0。
• 建议 SDK：使用 .NET 10 SDK 进行还原、构建与运行。
• 语言版本：项目启用了 latest C# 语言版本、Nullable 与 ImplicitUsings。
• 图形依赖：使用 SkiaSharp 4.151.2 作为渲染基础。
• 平台依赖：项目内置 SDL3 本地库，当前仓库已包含 Windows 与 Linux 的 x64/arm64 运行库，并保留 macOS 的 SDL3 动态库加载路径。
• 发布特性：示例工程启用了 AOT 发布配置，主库保留了可裁剪与 AOT 兼容相关设置。

运行环境

• 操作系统：当前仓库内已明确配置 Windows 和 Linux 运行所需的 SDL3 本地库；Windows 使用 SDL3.dll，Linux 使用 libSDL3.so.0。
• 处理器架构：当前按 x64 / arm64 组织 SDL3 本地库，建议优先在 x64 环境运行与验证。
• 图形环境：需要具备可用的桌面图形环境，能够正常创建 SDL3 窗口并完成 SkiaSharp 绘制。
• macOS：SDL3 加载器会查找 libSDL3.dylib、Libs/Osx/<arch>/libSDL3.dylib 与 Libs/Osx/libSDL3.dylib；发布 macOS 应用时请确认对应动态库随包带出。
• 多媒体能力：如使用摄像头、录像等扩展功能，还需要确保相关原生依赖可用。

构建与运行

以下为推荐步骤，默认使用 .NET 10 SDK；TCYM.UI 与 TCYM.UI.Pro 会同时生成 net8.0 和 net10.0 产物。

1. 安装 .NET 10 SDK。
2. 打开解决方案 TCYM.UI.sln，或直接在仓库根目录执行 dotnet restore。
3. 执行 dotnet build TCYM.UI.sln 生成整个解决方案；如只验证核心库，可执行 dotnet build TCYM.UI.Pro/TCYM.UI.Pro.csproj。
4. 执行 dotnet run --project TCYM.UI.Example/TCYM.UI.Example.csproj 运行示例工程。
5. 如需验证核心库功能，可从 TCYM.UI.Example 或 TCYM.UI/PageDome 中查看对应页面入口。

使用说明

• 在项目中引用 TCYM.UI，并在入口创建 UI 应用实例
• 按需创建窗口、布局与组件
• 通过样式与绑定系统管理 UI 行为

窗体圆角与外阴影

Windows 可在创建窗口前分别配置圆角与外阴影偏好。Windows 11 Build 22000 及更高版本使用 DWM 原生圆角并保留系统阴影；Windows 10 使用 DPI 感知窗口 Region 与主窗拥有的透明分层外阴影：

UISystem.DefaultWindowCornerPreference = UIWindowCornerPreference.Round;
UISystem.DefaultWindowShadowPreference = UIWindowShadowPreference.Enabled;
UISystem.Initialize("My App", 1200, 800, resizable: true);

Windows 10 在创建时已配置 Round/RoundSmall 且 GPU 可用时，默认申请 8-bit Alpha 透明缓冲， 并在完整帧结束后一次性应用 Skia 抗锯齿圆角蒙版；宽松 HRGN 仅作为极角命中与兼容兜底。 CPU、GL Alpha 不可用，或初始为直角/Default 后才在运行时切换圆角时，会安全退回 HRGN 硬边路径。 遇到透明窗口不兼容的混合显卡驱动，可在初始化前设置：

UISystem.EnableWindowCornerAntialiasing = false;

例如，圆角但无阴影可设置 Round + Disabled；直角但保留阴影可设置 DoNotRound + Enabled。UIWindowShadowPreference.Default 保留兼容行为：Windows 10 显式 Round/RoundSmall 时自动带阴影。

多窗口可在创建时使用 UIApp.CreateWindowWithAppearance(UIWindowCornerPreference, UIWindowShadowPreference, ...)， 也可以通过 UIWindow.CornerPreference、UIWindow.ShadowPreference、 UISystem.SetWindowCornerPreference(...) 或 UISystem.SetWindowShadowPreference(...) 在运行时独立切换。 最大化和全屏期间会临时使用直角，恢复窗口后自动重新应用配置。

UIWindowCornerPreference.Default 保留既有平台行为；可通过 UIWindow.IsCornerPreferenceSupported 或 UISystem.IsWindowCornerPreferenceSupported 查询。Windows 10 回退阴影随窗口移动、缩放、 置顶、最小化、最大化和全屏状态同步；最大化或全屏时暂停圆角与阴影，恢复后自动重建。 阴影窗口归属主窗且不覆盖主窗有效区域，Alt+Tab、应用最小化及恢复由 Windows 按同一 owner group 管理；原生文件对话框显示期间会临时隐藏阴影。 可通过 UIWindow.IsShadowPreferenceSupported 或 UISystem.IsWindowShadowPreferenceSupported 查询显式阴影控制能力。 Windows 11、macOS/Linux 的系统阴影由窗口管理器控制，框架会安全保存偏好但不承诺覆盖； 界面内部的可控阴影仍使用元素 BoxShadow 样式。

源码预览配置

• 如需让 VS Code 源码预览/热重载适配自定义项目结构，可在宿主项目的 .csproj 中声明以下属性。
• TCYMSourcePreviewComponentRoot：组件 Demo 根目录，默认值为 Page/component。
• TCYMSourcePreviewDefaultEntry：非组件文件的回退预览入口，默认值为 Page/Layout/Layout.cs。
• TCYMSourcePreviewGlobalCss：全局 CSS 文件路径，默认值为 Page/com.css。
• TCYMSourcePreviewGlobalCssResourcePath：当 EmbeddedResource 的资源名不是默认规则时，可显式指定 res://... 资源路径。

<PropertyGroup>
	<TCYMSourcePreviewComponentRoot>Features/Preview</TCYMSourcePreviewComponentRoot>
	<TCYMSourcePreviewDefaultEntry>AppShell/MainPreview.cs</TCYMSourcePreviewDefaultEntry>
	<TCYMSourcePreviewGlobalCss>Styles/preview.css</TCYMSourcePreviewGlobalCss>
	<TCYMSourcePreviewGlobalCssResourcePath>res://MyApp/Styles.preview.css</TCYMSourcePreviewGlobalCssResourcePath>
</PropertyGroup>

• 组件源码预览仍会优先在组件根目录内向上寻找同目录或父目录的 *Demo.cs。
• 默认入口类型名现在会优先读取源码中声明的 namespace，并使用文件名推断类型名；如果无法解析，再回退到旧的 RootNamespace + 相对路径规则。

Visual Studio 实时预览

• 安装 TCYM.UI.VisualStudio.vsix 后，可通过 View > TCYM.UI Preview 打开预览工具窗口。
• 在 Visual Studio 中打开继承 TCYM.UI/TCYM.UI.Pro 的 .cs 页面或组件源码后，可通过 Debug > Run Current TCYM.UI Live Preview 直接启动当前源码的实时预览宿主。
• Debug > Use TCYM.UI Live Preview For F5 用于切换 F5/Debug.Start 的去向；关闭时保留 Visual Studio 原生调试，开启后 F5 会改为启动当前源码的 TCYM.UI 实时预览。
• Tools > Options > TCYM.UI > Preview > Enable Touch Mouse Events 用于控制 Visual Studio 的 .cs 源码静态预览和实时预览宿主是否保留 SDL 的触摸转鼠标事件。
• 实时预览启动后由 TCYM.UI.DesignHost --preview-source <当前源码> 独立开窗运行，保存当前源码或相邻样式文件后会在同一进程内热重建当前页。
• 实时预览宿主现在会额外回放 Program.cs 中对 manager.Root/root.SetStyle(...) 的外壳样式设置，尽量保持与项目实际运行时一致的根容器样式。

许可证

本仓库中的示例代码和二进制库使用不同授权，请注意区分：

• TCYM.UI.Example 示例工程源码采用 MIT License，允许免费商用、修改和分发，详见 TCYM.UI.Example/LICENSE。
• TCYM.UI.Example/Libs 目录中的 TCYM.UI.dll 以二进制库形式提供，允许免费用于个人、内部、教育和商业应用，并可作为已编译应用程序的运行依赖随应用一起分发，详见 TCYM.UI.Example/Libs/LICENSE-TCYM.UI.txt。
• 未经许可，不得对 TCYM.UI.dll 进行反向工程、反编译、反汇编、修改、重新打包、转售、转授权，或作为独立文件、SDK、框架、组件库、NuGet 包、开发工具包及竞争产品进行二次分发。
• TCYM.UI 核心框架源码与其他二进制文件的授权范围请以单独发布的核心库授权协议为准。