AtomUI/docs/Core/MediaAndDrawing.md

AtomUI 媒体与绘图系统（Media & Drawing System）

概述

媒体与绘图系统位于 src/AtomUI.Core/Media/ 目录，为 AtomUI 提供了丰富的图形处理基础设施。该系统覆盖了从颜色科学计算、几何图形构建到 CSS 变换解析等多个领域，是 UI 渲染层的核心支撑。

在整体架构中的位置

UI 控件渲染层
    ↓ 使用
Media & Drawing System（本文档 — 颜色/几何/变换/排版）
    ↓ 基于
Avalonia.Media（底层渲染引擎）

目录结构

Media/
├── ColorUtils.cs                      # 颜色科学计算（WCAG 无障碍）
├── ColorExtensions.cs                 # 颜色操作流式 API
├── CommonShapeBuilder.cs              # 通用图形构建器
├── DrawingContextExtensions.cs        # 绘图上下文扩展
├── TransformParser.cs                 # CSS transform 解析器
├── PenUtils.cs                        # 画笔工具
├── GeometryUtils.cs                   # 几何计算工具
├── BoxShadowExtensions.cs             # 阴影扩展
├── TextUtils.cs                       # 文本测量工具
├── FontUtils.cs                       # 字体工具
├── Transitions/
│   ├── ColorTransition.cs             # 颜色过渡
│   ├── RectTransition.cs              # 矩形过渡
│   └── PixelPointTransition.cs        # 像素点过渡
└── TextFormatting/
    ├── FormattedTextSource.cs                          # 格式化文本源
    └── TextParagraphPropertiesReflectionExtensions.cs  # 段落属性反射

核心组件

1. ColorUtils — 颜色科学与 WCAG 无障碍

ColorUtils 提供了基于色彩科学标准的颜色处理能力，特别关注 WCAG 2.0 无障碍标准。

WCAG 可读性计算

// 计算两个颜色之间的对比度（WCAG 2.0 标准）
double ratio = ColorUtils.Readability(foreground, background);

// 检查是否满足可读性要求
bool ok = ColorUtils.IsReadable(fg, bg, ReadabilitySize.AA_Large);

// 从候选颜色中选择最佳可读色
Color best = ColorUtils.MostReadable(background, candidates, 
    includeFallbackColors: true);

可读性等级

等级	最小对比度	场景
AA_Small	4.5:1	正常文字
AA_Large	3.0:1	大号文字（18px+ 或 14px+ 粗体）
AAA_Small	7.0:1	增强正常文字
AAA_Large	4.5:1	增强大号文字

HSL/HSV 颜色空间操作

// RGB ↔ HSL 互转
HslColor hsl = ColorUtils.RgbToHsl(r, g, b);
Color rgb = ColorUtils.HslToRgb(h, s, l);

// RGB ↔ HSV 互转
HsvColor hsv = ColorUtils.RgbToHsv(r, g, b);
Color rgb = ColorUtils.HsvToRgb(h, s, v);

CSS 颜色解析

// 支持多种 CSS 颜色格式
Color c1 = ColorUtils.FromCssString("#ff6600");    // Hex
Color c2 = ColorUtils.FromCssString("rgb(255,0,0)"); // RGB
Color c3 = ColorUtils.FromCssString("hsl(120,50%,50%)"); // HSL

2. ColorExtensions — 流式颜色操作 API

为 Color 类型提供丰富的扩展方法链式调用：

Color result = baseColor
    .Lighten(20)       // 增加亮度 20%
    .Desaturate(10)    // 降低饱和度 10%
    .Spin(30)          // 色相旋转 30°
    .SetAlpha(0.8);    // 设置透明度

可用操作

方法	说明
Desaturate(amount)	降低饱和度
Saturate(amount)	增加饱和度
Lighten(amount)	增加亮度
Darken(amount)	降低亮度
BrightenColor(amount)	增加明度
Spin(degrees)	色相旋转
GetBrightness()	获取感知明度
GetLuminance()	获取相对亮度（WCAG）
Mix(other, amount)	两色混合
TintColor(amount)	添加白色调
ShadeColor(amount)	添加黑色调

3. CommonShapeBuilder — 通用图形构建器

使用 StreamGeometry 高效构建常用的 UI 图形：

// 构建对勾图形（用于 Checkbox 等）
Geometry checkmark = CommonShapeBuilder.BuildCheckMark(width, height);

// 构建圆弧
Geometry arc = CommonShapeBuilder.BuildArc(center, radius, startAngle, endAngle);

// 构建箭头
Geometry arrow = CommonShapeBuilder.BuildArrow(direction, size);

4. TransformParser — CSS Transform 解析器

完整实现 CSS transform 属性字符串的解析，支持所有标准变换函数：

支持的变换函数

函数	示例
translate	translate(10px, 20px)
translateX/Y	translateX(50%)
scale	scale(1.5, 2.0)
scaleX/Y	scaleY(0.5)
rotate	rotate(45deg)
skew	skew(10deg, 20deg)
skewX/Y	skewX(15deg)
matrix	matrix(1,0,0,1,0,0)

角度单位支持

// 支持多种角度单位
TransformOperations ops = TransformParser.Parse("rotate(0.5turn)");
// deg（度）、rad（弧度）、grad（百分度）、turn（圈）

5. DrawingContextExtensions — 绘图上下文扩展

为 Avalonia 的 DrawingContext 提供自定义绘制方法：

// 绘制药丸形矩形（两端完全圆角）
context.DrawPilledRect(brush, pen, rect, orientation);

// 绘制圆弧
context.DrawArc(pen, center, radius, startAngle, sweepAngle);

6. PenUtils — 画笔智能管理

根据画笔的可变性状态智能选择复用或创建策略：

// 对于不可变画笔 → 直接复用
// 对于可变画笔 → 创建新实例
IPen pen = PenUtils.CreateOrReusePen(brush, thickness);

7. GeometryUtils — 几何计算

// 计算缩放后的矩形（保持渲染精度）
Rect scaled = GeometryUtils.CalculateScaledRect(original, renderScale);

// 获取 CornerRadius 的标量值
double radius = GeometryUtils.CornerRadiusScalarValue(cornerRadius);

8. BoxShadowExtensions — 阴影处理

// 将 BoxShadows 转换为等效的 Thickness（用于布局计算）
Thickness padding = boxShadows.ToThickness();

9. 文本与字体工具

TextUtils

// 测量文本渲染尺寸
Size size = TextUtils.MeasureText(text, fontSize, typeface);

FontUtils

// EM 单位到像素的转换
double px = FontUtils.ConvertEmToPixel(emValue, fontSize);

文本格式化（TextFormatting）

FormattedTextSource

实现 Avalonia 的 ITextSource 接口，提供字形感知（Grapheme-aware）的文本分段：

• 正确处理 Unicode 组合字符和 emoji
• 为每个文本段（TextRun）分配正确的排版属性
• 支持自定义的文本格式化流程

TextParagraphPropertiesReflectionExtensions

通过反射访问 Avalonia TextParagraphProperties 的 LineSpacing 属性（该属性在某些版本中未公开）。使用 [DynamicDependency] 确保 AOT 安全。

Media Transitions（媒体过渡）

系统还提供了三个专用的过渡动画类型，补充 Animations/Transitions/ 中的通用过渡：

过渡类型	说明
ColorTransition	Color 类型属性的平滑过渡
RectTransition	Rect 类型属性的平滑过渡（位置+尺寸）
PixelPointTransition	PixelPoint 类型属性的平滑过渡

设计模式

模式	应用
建造者模式	CommonShapeBuilder 使用 StreamGeometry 逐步构建复杂图形
解析器模式	TransformParser 实现完整的 CSS transform 字符串解析
策略模式	PenUtils 根据画笔状态选择复用或创建策略
扩展方法模式	ColorExtensions、DrawingContextExtensions 等提供流式 API
适配器模式	FormattedTextSource 将文本数据适配为 Avalonia 文本排版接口

与其他系统的关系

• 主题系统：ColorUtils 的颜色算法被主题算法（ThemeAlgorithm）大量使用来生成色板
• 图标系统：CommonShapeBuilder 构建的图形用于内置图标
• 动画系统：Media/Transitions/ 中的过渡类型补充了核心动画系统
• 控件渲染：DrawingContextExtensions 在控件的 Render 方法中使用

相关文档

• 架构概览 — AtomUI.Core 整体架构
• 图标系统 — 矢量图标系统
• 主题算法 — 使用颜色算法的主题生成
• 动画系统 — 核心动画与过渡