CodeWF.Avalonia.Controls 12.1.4.18

CodeWF.Avalonia

面向 Avalonia 12 的 UI 控件与能力库合集：基础自定义控件、表格增强、Dock 布局、Markdown 渲染与编辑、思维导图、国际化、日志查看，均以 CodeWF.Avalonia.* 前缀发布，XAML 命名空间统一挂 https://codewf.com。

A suite of UI control and capability libraries for Avalonia 12, published with the CodeWF.Avalonia.* prefix and a unified XAML namespace https://codewf.com.

版本号前三位跟随 Avalonia（当前 12.1.4），第四位为本仓修订号。

这个仓库解决什么 / What it solves

包一览 / Packages

「依赖」列只列第三方与本仓包依赖；所有包均面向 net10.0（Lang.Generator 为 netstandard2.0）。只有 4 个包直接依赖 Semi.Avalonia。

从 12.1.4.11 起，国际化的 JSON/XML/RESX 解析、文化回退与全局状态由 NuGet 包 CodeWF.Toolkit.Lang 提供，无需获取另一个仓库源码。CodeWF.Avalonia.Lang 保留 XAML 绑定和旧接口兼容层，两种命名空间的管理器共用同一状态；已有应用可继续使用原来的插件、自定义 ILangPlugin 和语言下拉框类型。控制台、服务及基础库直接安装 CodeWF.Toolkit.Lang，无需引入 Avalonia。

资源分发按角色区分：NuGet 库把 JSON 嵌入程序集，自行读取默认文案；Demo 和桌面应用将自己的 JSON 输出到 I18n/，沿用已有语言初始化。应用可选添加同名资源键定制库文案，覆盖与缺键回退由 Lang 引擎处理，无需逐库注册、合并 JSON 或提供 resolver。C# 强类型资源键使用 T4 或 CodeWF.Avalonia.Lang.Generator，不手写维护映射；Demo 的 T4 映射由 pwsh scripts/sync_localization_keys.ps1 更新，CI 使用 -Check 校验。

* 标注的依赖由对应包经传递引用带入，无需单独安装；它们本身不依赖 Semi，见 主题与依赖。

快速开始 / Quick start

# 最小可用：控件 + 官方 DataGrid 增强
dotnet add package CodeWF.Avalonia.Controls
dotnet add package CodeWF.Avalonia.DataGrid

App.axaml（注意 xmlns:semi，缺少它 <semi:SemiTheme/> 无法解析）：

<Application xmlns="https://github.com/avaloniaui"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:semi="https://irihi.tech/semi"
             xmlns:codewf="https://codewf.com">
  
  <Application.Styles>
    
    <semi:SemiTheme Locale="zh-CN" />
    
    <codewf:ACSemiTheme />
    
    <codewf:DataGridSemiTheme />
  </Application.Styles>
</Application>

上面三行按需增删即可，下面是几种常见的最小组合：

主题与依赖 / Themes and dependencies

六个主题入口分别属于哪个包、是否依赖 Semi、能否省略：

八套常规配色 × 三态模式：在 Semi 与控件样式之后加载 <codewf:StudioTheme />，由 CodeWF.Avalonia.Controls.Themes.StudioThemeController 统一管理。

每套配色均有独立浅色和深色资源。模式使用 StudioThemeMode.System/Light/Dark；跟随系统会订阅平台主题变化，固定模式保持用户选择。应用退出时释放控制器。

using CodeWF.Avalonia.Controls.Themes;

// 由应用持有，退出时调用 Dispose()。
_themeController = new StudioThemeController(Application.Current!)
{
    Palette = StudioPalette.DotNet,
    Mode = StudioThemeMode.System,
};

现有 SemiTheme.Aquatic/Desert/Dusk/NightSky 和日志的 CodeWFLogTheme.HighContrast 仍可直接使用；高对比属于独立无障碍主题，不计入八套常规配色。

改色时的两个事实

• CodeWFLogTheme 是 sealed：它只能整体引入，不支持继承后覆盖配色。若需要自定义日志配色，请在应用资源里覆盖同名画笔键（Application.Resources 的优先级高于主题）。
• MarkdownThemes 可以继承：它是 public 无参构造的 Styles，MarkdownFullThemes 就是这么来的；排版主题/尺寸也支持运行时切换：

public class MyMarkdownThemes : MarkdownThemes
{
    public MyMarkdownThemes()
    {
        TypographyTheme = MarkdownTypographyThemes.TechnologyBlue; // 默认 Basic
        TypographySize = MarkdownTypographySizes.Small;            // 默认 Normal
    }
}

<codewf:MarkdownThemes TypographyTheme="TechnologyBlue" TypographySize="Small" />

排版主题共 18 套，Key 见 MarkdownTypographyThemes（Basic 为默认），尺寸见 MarkdownTypographySizes。

全局/局部切换还可调用 MarkdownThemes.OverrideTypographyResources(...)，无需重建控件。

注意：主题资源以程序集内绝对 URI（avares://CodeWF.Avalonia.*/Themes/...）引用，不要手动改写资源字典路径。

需要宿主自备的主题 / Host-provided theming

包 → 源码 → 文档索引 / Source & docs index

演示应用 / Demo

Demo 保留 Ribbon + Dock，按输入与选择、反馈与引导、数据展示、布局与导航、Markdown、开发工具分类；每个主菜单对应一个具体控件或 API。首页先展示目录，组合工作流集中到“综合示例”。新增展开动画独立页，块编辑、平面表格增强与状态卡片提供具体用例。共享主题接口、MVVM 约定与截图检查见 原生演示台文档。

文档内使用 Grid + GridSplitter 放置演示与独立属性面板，浮动时整体移动。命令区进一步按状态、引导、表格、窗口、布局动效、Markdown 阅读 / 编辑 / 导出等用途分组。参数与演示优先展示，源码按需打开；长 API 名保持完整，窄窗口可横向滚动。仓库通过 global.json 选择稳定版 .NET 10 SDK。

Each Dock document contains its demonstration and property panel; both move together when detached. See the linked guide for optional Studio themes, localization and validation.

Windows x64 NativeAOT Demo：标题栏支持主题色圈与下拉同步切换，默认 .NET 紫，共八套配色；浅色、深色与跟随系统分别选择。首页目录包含 32 个页面，实验区按需展开；完整功能与验收范围见上面的文档。

快捷入口采用 16×16 图标与 30×30 点击热区，Ribbon 主命令使用 32×32 图标。每个文档内的演示和属性面板通过 GridSplitter 调整宽度，属性默认行高 31px、名称列宽 118px；下列图片来自 12.1.4.18 的 Windows x64 NativeAOT 程序。

# 桌面演示台：Ribbon 页签 + Dock 工作区（左导航 / 文档内效果与属性 / 下日志），含 .NET 紫、AI 极光、AI 暖陶与原有六套 Semi 配色，支持深浅与双语切换
dotnet run --project demo/CodeWF.Avalonia.Demo -f net10.0

# 冒烟模式：逐页构建后逐色板渲染一遍再退出，退出码 0 表示全部页面构建 + 渲染通过（CI 使用）
dotnet run --project demo/CodeWF.Avalonia.Demo -f net10.0 -- --smoke

安装包由 GitHub Releases 提供（随 v* tag 构建）：Windows setup.exe / 便携 zip、Linux deb、macOS dmg，均附 .sha256 校验文件。

CI/CD 与版本策略 / CI and versioning

• ci.yml：dotnet build -c Release + dotnet test，外加 NativeAOT 发布并在 Windows 上运行 --smoke。
• publish-nuget.yml：推送 v* tag 时打包并发布 NuGet（Trusted Publishing）。
• release.yml：同一 tag 触发全平台演示应用发布（6 个 RID：win-x64/x86、linux-x64/arm64、osx-x64/arm64）。
• 版本号前三跟随 Avalonia，第四位为本仓修订，例如 v12.1.4.4。
• 变更记录见 UpdateLog.md。

许可与贡献 / License and contributing

MIT。Issue 与 PR 都欢迎，提交前请确保 dotnet build CodeWF.Avalonia.slnx -c Release 与 dotnet test 通过。

思维导图接入

CodeWF.Avalonia.MindView 的控件和主题合并为一个包，版本随本仓统一版本。宿主可使用 Semi、Ursa 或其它 Avalonia 主题。编辑型脑图使用 MindMapEditor / MindMapMiniMap，只读 Markdown 导图使用 MarkdownMindMapView。详细 API 和接入例子见 MindView README。