mirror of
https://github.com/AtomUI/AtomUI.git
synced 2026-10-26 03:00:28 +08:00
feat(Semantic): add Spin parts and align Ant Design demo
This commit is contained in:
chinboy
@@ -87,7 +87,7 @@ Skeleton 的公共契约由 public/protected 类型成员、Avalonia 属性、
|
||||
Gallery key：`ExamplesContent` / item `0`
|
||||
|
||||
```axaml
|
||||
<atom:Skeleton IsLoading="True"/>
|
||||
<atom:Skeleton IsLoading="True" />
|
||||
```
|
||||
|
||||
### 复杂组合
|
||||
@@ -97,7 +97,7 @@ Gallery key：`ExamplesContent` / item `0`
|
||||
Gallery key：`ExamplesContent` / item `1`
|
||||
|
||||
```axaml
|
||||
<atom:Skeleton IsShowAvatar="True" ParagraphRows="4" IsLoading="True"/>
|
||||
<atom:Skeleton IsShowAvatar="True" ParagraphRows="4" IsLoading="True" />
|
||||
```
|
||||
|
||||
### 动态效果
|
||||
@@ -107,12 +107,12 @@ Gallery key：`ExamplesContent` / item `1`
|
||||
Gallery key：`ExamplesContent` / item `2`
|
||||
|
||||
```axaml
|
||||
<atom:Skeleton IsActive="True" IsLoading="True"/>
|
||||
<atom:Skeleton IsActive="True" IsLoading="True" />
|
||||
```
|
||||
|
||||
### 包含子组件
|
||||
|
||||
来源：`controlgallery/AtomUIGallery/ShowCases/Feedback/Skeleton/Views/SkeletonShowCase.axaml:222`
|
||||
来源：`controlgallery/AtomUIGallery/ShowCases/Feedback/Skeleton/Views/SkeletonShowCase.axaml:243`
|
||||
|
||||
Gallery key：`ExamplesContent` / item `4`
|
||||
|
||||
@@ -120,12 +120,16 @@ Gallery key：`ExamplesContent` / item `4`
|
||||
<StackPanel Orientation="Vertical" Spacing="10">
|
||||
<atom:Skeleton IsLoading="{Binding SkeletonLoading}">
|
||||
<StackPanel Orientation="Vertical" Spacing="20">
|
||||
<atom:TextBlock FontWeight="Bold" Text="AtomUI，一套设计语言" />
|
||||
<atom:TextBlock TextWrapping="Wrap" Text="我们提供一系列设计原则、实用模式和高质量设计资源（Sketch 和 Axure），帮助人们高效而优雅地创建产品原型。" />
|
||||
<atom:TextBlock FontWeight="Bold"
|
||||
Text="AtomUI，一套设计语言" />
|
||||
<atom:TextBlock TextWrapping="Wrap"
|
||||
Text="我们提供一系列设计原则、实用模式和高质量设计资源（Sketch 和 Axure），帮助人们高效而优雅地创建产品原型。" />
|
||||
</StackPanel>
|
||||
</atom:Skeleton>
|
||||
<atom:Button IsEnabled="{Binding SkeletonLoading, Converter={x:Static BoolConverters.Not}}"
|
||||
Click="HandleLoadingButtonClicked" Content="显示骨架屏" />
|
||||
<atom:Button
|
||||
IsEnabled="{Binding SkeletonLoading, Converter={x:Static BoolConverters.Not}}"
|
||||
Click="HandleLoadingButtonClicked"
|
||||
Content="显示骨架屏" />
|
||||
</StackPanel>
|
||||
```
|
||||
|
||||
|
||||
@@ -44,7 +44,7 @@ Spin 的公共契约由 public/protected 类型成员、Avalonia 属性、事件
|
||||
| --- | --- | --- |
|
||||
| 内容与数据 | `CustomIndicatorTemplate` | 定义控件展示内容、输入数据、模板或业务对象入口。 |
|
||||
| 交互与状态 | `IsMaskBackgroundEnabled`、`IsMaskBlurEnabled`、`IsMotionEnabled`、`IsSpinning`、`IsTipVisible` | 表达用户可观察状态、可用性、清除、加载或反馈语义。 |
|
||||
| 视觉与布局 | `DotSize`、`IndicatorSize`、`SizeType` | 影响尺寸、位置、颜色、形状、密度和模板视觉变量。 |
|
||||
| 视觉与布局 | `DotBgBrush`、`DotSize`、`IndicatorSize`、`SizeType` | 影响尺寸、位置、颜色、形状、密度和模板视觉变量。 |
|
||||
| 动效与异步 | `MotionDuration`、`MotionEasingCurve` | 约束动效开关、异步加载、播放速度、超时和任务边界。 |
|
||||
| 其他稳定入口 | `CustomIndicator`、`Tip` | 保留为 public surface，变更前需确认 Gallery 和用户 XAML 依赖。 |
|
||||
|
||||
@@ -76,7 +76,7 @@ Spin 的公共契约由 public/protected 类型成员、Avalonia 属性、事件
|
||||
|
||||
### 基础用法
|
||||
|
||||
来源：`controlgallery/AtomUIGallery/ShowCases/Feedback/Spin/Views/SpinShowCase.axaml:36`
|
||||
来源：`controlgallery/AtomUIGallery/ShowCases/Feedback/Spin/Views/SpinShowCase.axaml:97`
|
||||
|
||||
Gallery key：`ExamplesContent` / item `0`
|
||||
|
||||
@@ -86,7 +86,7 @@ Gallery key：`ExamplesContent` / item `0`
|
||||
|
||||
### 尺寸
|
||||
|
||||
来源：`controlgallery/AtomUIGallery/ShowCases/Feedback/Spin/Views/SpinShowCase.axaml:47`
|
||||
来源：`controlgallery/AtomUIGallery/ShowCases/Feedback/Spin/Views/SpinShowCase.axaml:108`
|
||||
|
||||
Gallery key：`ExamplesContent` / item `1`
|
||||
|
||||
@@ -99,12 +99,45 @@ Gallery key：`ExamplesContent` / item `1`
|
||||
</StackPanel>
|
||||
```
|
||||
|
||||
### 自定义描述
|
||||
### 嵌入模式
|
||||
|
||||
来源：`controlgallery/AtomUIGallery/ShowCases/Feedback/Spin/Views/SpinShowCase.axaml:63`
|
||||
来源：`controlgallery/AtomUIGallery/ShowCases/Feedback/Spin/Views/SpinShowCase.axaml:125`
|
||||
|
||||
Gallery key：`ExamplesContent` / item `2`
|
||||
|
||||
```axaml
|
||||
<StackPanel Orientation="Vertical" Spacing="10">
|
||||
<atom:Spin IsSpinning="{Binding IsLoadingSwitchChecked}"
|
||||
IsTipVisible="True"
|
||||
HorizontalAlignment="Stretch"
|
||||
Tip="加载中...">
|
||||
<atom:Alert Message="提示消息标题"
|
||||
Description="关于这条提示上下文的更多详细信息。"
|
||||
Type="Info" />
|
||||
</atom:Spin>
|
||||
|
||||
<atom:Spin IsSpinning="{Binding IsLoadingSwitchChecked}"
|
||||
IsTipVisible="True"
|
||||
Tip="加载中..."
|
||||
HorizontalAlignment="Stretch"
|
||||
IsMaskBlurEnabled="True">
|
||||
<atom:Alert Message="提示消息标题"
|
||||
Description="关于这条提示上下文的更多详细信息。"
|
||||
Type="Info" />
|
||||
</atom:Spin>
|
||||
<StackPanel Orientation="Horizontal" Spacing="10">
|
||||
<atom:TextBlock Text="加载状态：" />
|
||||
<atom:ToggleSwitch IsChecked="{Binding IsLoadingSwitchChecked}" />
|
||||
</StackPanel>
|
||||
</StackPanel>
|
||||
```
|
||||
|
||||
### 自定义描述
|
||||
|
||||
来源：`controlgallery/AtomUIGallery/ShowCases/Feedback/Spin/Views/SpinShowCase.axaml:159`
|
||||
|
||||
Gallery key：`ExamplesContent` / item `3`
|
||||
|
||||
```axaml
|
||||
<StackPanel Orientation="Vertical" Spacing="10">
|
||||
<StackPanel Orientation="Horizontal" Spacing="10">
|
||||
@@ -134,39 +167,6 @@ Gallery key：`ExamplesContent` / item `2`
|
||||
</StackPanel>
|
||||
```
|
||||
|
||||
### 嵌入模式
|
||||
|
||||
来源：`controlgallery/AtomUIGallery/ShowCases/Feedback/Spin/Views/SpinShowCase.axaml:121`
|
||||
|
||||
Gallery key：`ExamplesContent` / item `4`
|
||||
|
||||
```axaml
|
||||
<StackPanel Orientation="Vertical" Spacing="10">
|
||||
<atom:Spin IsSpinning="{Binding IsLoadingSwitchChecked}"
|
||||
IsTipVisible="True"
|
||||
HorizontalAlignment="Stretch"
|
||||
Tip="加载中...">
|
||||
<atom:Alert Message="提示消息标题"
|
||||
Description="关于这条提示上下文的更多详细信息。"
|
||||
Type="Info" />
|
||||
</atom:Spin>
|
||||
|
||||
<atom:Spin IsSpinning="{Binding IsLoadingSwitchChecked}"
|
||||
IsTipVisible="True"
|
||||
Tip="加载中..."
|
||||
HorizontalAlignment="Stretch"
|
||||
IsMaskBlurEnabled="True">
|
||||
<atom:Alert Message="提示消息标题"
|
||||
Description="关于这条提示上下文的更多详细信息。"
|
||||
Type="Info" />
|
||||
</atom:Spin>
|
||||
<StackPanel Orientation="Horizontal" Spacing="10">
|
||||
<atom:TextBlock Text="加载状态：" />
|
||||
<atom:ToggleSwitch IsChecked="{Binding IsLoadingSwitchChecked}" />
|
||||
</StackPanel>
|
||||
</StackPanel>
|
||||
```
|
||||
|
||||
## 状态模型
|
||||
|
||||
Spin 的状态流按以下路径收敛：
|
||||
@@ -217,6 +217,7 @@ Spin Token 只表达组件级视觉变量，例如尺寸、间距、颜色、圆
|
||||
资源和 AOT 约束：
|
||||
|
||||
- 不通过运行时反射扫描 public API、Token 或 Gallery 示例数据。
|
||||
- 不通过 VisualTree 扫描维护 Semantic Part；Gallery Preview 使用生成 descriptor 和 owner-scoped marker 解析。
|
||||
- 不把可静态声明的模板结构迁移到 C# 动态创建。
|
||||
- 异步加载、上传、弹层和窗口生命周期必须能取消或释放。
|
||||
- 缓存对象必须与控件、窗口、弹层或数据 owner 生命周期一致。
|
||||
@@ -239,6 +240,8 @@ Spin Token 只表达组件级视觉变量，例如尺寸、间距、颜色、圆
|
||||
- `src/AtomUI.Desktop.Controls/Spin/Spin.cs`
|
||||
- `src/AtomUI.Desktop.Controls/Spin/SpinIndicator.cs`
|
||||
- `src/AtomUI.Desktop.Controls/Spin/SpinToken.cs`
|
||||
- `src/AtomUI.Desktop.Controls/Spin/Spin.SemanticParts.cs`
|
||||
- `src/AtomUI.Desktop.Controls/Spin/SpinIndicator.SemanticParts.cs`
|
||||
- `src/AtomUI.Desktop.Controls/Spin/Themes/SpinIndicatorTheme.axaml`
|
||||
- `src/AtomUI.Desktop.Controls/Spin/Themes/SpinTheme.axaml`
|
||||
|
||||
@@ -248,11 +251,13 @@ Spin Token 只表达组件级视觉变量，例如尺寸、间距、颜色、圆
|
||||
- Theme 文件负责静态视觉结构、template part、selector 和资源绑定。
|
||||
- Token 文件只提供组件视觉变量，不保存实例状态。
|
||||
- Gallery 文件只展示用法和示例，不作为运行时逻辑 owner。
|
||||
- Semantic descriptor 由各 public owner 的 `[SemanticPart]` 声明生成；模板只使用静态 `Classes.semantic-*="True"` marker。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- 源设计文档：`docs/controls/desktop/feedback/spin/overview.md`
|
||||
- 实现文档：`docs/controls/desktop/feedback/spin/implementation.md`
|
||||
- Semantic Part 文档：`docs/controls/desktop/feedback/spin/semantic-part.md`
|
||||
- Token 文档：`docs/controls/desktop/feedback/spin/token.md`
|
||||
- 变更记录：`docs/controls/desktop/feedback/spin/changelog.md`
|
||||
- 语义结构：`./semantic-cn.md`
|
||||
|
||||
@@ -4,13 +4,38 @@
|
||||
|
||||
## Semantic Parts
|
||||
|
||||
| Part | AtomUI 节点 | 职责 | 相关 API | 相关 Token | 稳定性 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| `root` | `Spin` | 反馈控件根语义区域，承载 public API、反馈状态和主题入口。 | 见 API 与契约模型 | 见视觉与主题模型 | stable |
|
||||
| `host` | `宿主或弹层区域` | 承载 overlay、popup、portal、message host、drawer 或 modal 容器。 | 见 API 与契约模型 | 见视觉与主题模型 | stable |
|
||||
| `surface` | `反馈表面` | 承载背景、边框、阴影、尺寸、placement 和视觉状态。 | 见 API 与契约模型 | 见视觉与主题模型 | stable |
|
||||
| `content` | `内容区域` | 承载标题、正文、图标、进度、结果、操作或关闭入口。 | 见 API 与契约模型 | 见视觉与主题模型 | stable |
|
||||
| `motion` | `动效区域` | 表达进入退出、loading、progress、skeleton 或水印刷新反馈。 | 见 API 与契约模型 | 见视觉与主题模型 | stable |
|
||||
Spin 主控件公开 `root`、`container`、`mask`、`section`、`indicator`、`description` 六个职责区域，与上游稳定语义
|
||||
保持同名。`mask` 是 AtomUI 扩展区域，承载嵌套模式的遮罩背景层职责：上游体系的遮罩语义已折叠进全屏模式的根区域，
|
||||
AtomUI 没有全屏模式，遮罩层是嵌套模式下独立的真实节点。`SpinIndicator` 是独立的公开子控件，
|
||||
公开 `root` 与 `content`。
|
||||
|
||||
### 1.1 `Spin`
|
||||
|
||||
| Part | Selector | ContractType | Cardinality | Customization | CrossVisualRoot | RuntimeCreated |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| `root` | owner | `Spin` | `Single` | `Root` | `false` | `false` |
|
||||
| `container` | `.semantic-container` | `ContentPresenter` | `Single` | `Selector` | `false` | `false` |
|
||||
| `mask` | `.semantic-mask` | `Border` | `Single` | `Selector` | `false` | `false` |
|
||||
| `section` | `.semantic-section` | `StackPanel` | `Single` | `Selector` | `false` | `false` |
|
||||
| `indicator` | `.semantic-indicator` | `SpinIndicator` | `Single` | `Selector` | `false` | `false` |
|
||||
| `description` | `.semantic-description` | `TextBlock` | `Single` | `Selector` | `false` | `false` |
|
||||
|
||||
`container` 承载用户内容的 `ContentPresenter`，spinning 时承担透明度或高斯模糊反馈；`mask` 是遮罩背景层，只在
|
||||
`IsMaskBackgroundEnabled` 时呈现 `ColorBgMask`；`section` 是加载区域，承载 `indicator` 与 `description` 并居中；
|
||||
`indicator` 是主控件模板直接拥有的公开 `SpinIndicator` 子控件，其尺寸分支、动效时长和圆点填充
|
||||
（`DotBgBrush`）均可经 Semantic Style 定制；`description` 是提示文本节点，对应公共 API
|
||||
`Tip` / `IsTipVisible`。`root` 不声明 `.semantic-root` marker。
|
||||
|
||||
### 1.2 `SpinIndicator`
|
||||
|
||||
| Part | Selector | ContractType | Cardinality | Customization | CrossVisualRoot | RuntimeCreated |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| `root` | owner | `SpinIndicator` | `Single` | `Root` | `false` | `false` |
|
||||
| `content` | `.semantic-content` | `Control` | `Multiple` | `Selector` | `false` | `false` |
|
||||
|
||||
`content` 使用 `Multiple` 是 AtomUI 模板实现的状态替代语义：内置四点指示器 `SpinIndicatorDotPanel` 与自定义指示器
|
||||
`PART_CustomIndicatorPresenter` 是两个静态 marker target，由 `IsCustomIndicator` 决定同一时刻只有一个可见。
|
||||
Preview 只高亮当前可见 target；Semantic Style 同时作用于两个替代实现，保证切换自定义指示器后定制仍然存在。
|
||||
|
||||
## Abstract AXAML Structure
|
||||
|
||||
@@ -79,7 +104,7 @@ Spin
|
||||
| --- | --- | --- |
|
||||
| 内容与数据 | `CustomIndicatorTemplate` | 定义控件展示内容、输入数据、模板或业务对象入口。 |
|
||||
| 交互与状态 | `IsMaskBackgroundEnabled`、`IsMaskBlurEnabled`、`IsMotionEnabled`、`IsSpinning`、`IsTipVisible` | 表达用户可观察状态、可用性、清除、加载或反馈语义。 |
|
||||
| 视觉与布局 | `DotSize`、`IndicatorSize`、`SizeType` | 影响尺寸、位置、颜色、形状、密度和模板视觉变量。 |
|
||||
| 视觉与布局 | `DotBgBrush`、`DotSize`、`IndicatorSize`、`SizeType` | 影响尺寸、位置、颜色、形状、密度和模板视觉变量。 |
|
||||
| 动效与异步 | `MotionDuration`、`MotionEasingCurve` | 约束动效开关、异步加载、播放速度、超时和任务边界。 |
|
||||
| 其他稳定入口 | `CustomIndicator`、`Tip` | 保留为 public surface，变更前需确认 Gallery 和用户 XAML 依赖。 |
|
||||
|
||||
|
||||
@@ -21238,7 +21238,7 @@ Skeleton 的公共契约由 public/protected 类型成员、Avalonia 属性、
|
||||
Gallery key：`ExamplesContent` / item `0`
|
||||
|
||||
```axaml
|
||||
<atom:Skeleton IsLoading="True"/>
|
||||
<atom:Skeleton IsLoading="True" />
|
||||
```
|
||||
|
||||
### 复杂组合
|
||||
@@ -21248,7 +21248,7 @@ Gallery key：`ExamplesContent` / item `0`
|
||||
Gallery key：`ExamplesContent` / item `1`
|
||||
|
||||
```axaml
|
||||
<atom:Skeleton IsShowAvatar="True" ParagraphRows="4" IsLoading="True"/>
|
||||
<atom:Skeleton IsShowAvatar="True" ParagraphRows="4" IsLoading="True" />
|
||||
```
|
||||
|
||||
### 动态效果
|
||||
@@ -21258,12 +21258,12 @@ Gallery key：`ExamplesContent` / item `1`
|
||||
Gallery key：`ExamplesContent` / item `2`
|
||||
|
||||
```axaml
|
||||
<atom:Skeleton IsActive="True" IsLoading="True"/>
|
||||
<atom:Skeleton IsActive="True" IsLoading="True" />
|
||||
```
|
||||
|
||||
### 包含子组件
|
||||
|
||||
来源：`controlgallery/AtomUIGallery/ShowCases/Feedback/Skeleton/Views/SkeletonShowCase.axaml:222`
|
||||
来源：`controlgallery/AtomUIGallery/ShowCases/Feedback/Skeleton/Views/SkeletonShowCase.axaml:243`
|
||||
|
||||
Gallery key：`ExamplesContent` / item `4`
|
||||
|
||||
@@ -21271,12 +21271,16 @@ Gallery key：`ExamplesContent` / item `4`
|
||||
<StackPanel Orientation="Vertical" Spacing="10">
|
||||
<atom:Skeleton IsLoading="{Binding SkeletonLoading}">
|
||||
<StackPanel Orientation="Vertical" Spacing="20">
|
||||
<atom:TextBlock FontWeight="Bold" Text="AtomUI，一套设计语言" />
|
||||
<atom:TextBlock TextWrapping="Wrap" Text="我们提供一系列设计原则、实用模式和高质量设计资源（Sketch 和 Axure），帮助人们高效而优雅地创建产品原型。" />
|
||||
<atom:TextBlock FontWeight="Bold"
|
||||
Text="AtomUI，一套设计语言" />
|
||||
<atom:TextBlock TextWrapping="Wrap"
|
||||
Text="我们提供一系列设计原则、实用模式和高质量设计资源（Sketch 和 Axure），帮助人们高效而优雅地创建产品原型。" />
|
||||
</StackPanel>
|
||||
</atom:Skeleton>
|
||||
<atom:Button IsEnabled="{Binding SkeletonLoading, Converter={x:Static BoolConverters.Not}}"
|
||||
Click="HandleLoadingButtonClicked" Content="显示骨架屏" />
|
||||
<atom:Button
|
||||
IsEnabled="{Binding SkeletonLoading, Converter={x:Static BoolConverters.Not}}"
|
||||
Click="HandleLoadingButtonClicked"
|
||||
Content="显示骨架屏" />
|
||||
</StackPanel>
|
||||
```
|
||||
|
||||
@@ -21454,7 +21458,7 @@ Spin 的公共契约由 public/protected 类型成员、Avalonia 属性、事件
|
||||
| --- | --- | --- |
|
||||
| 内容与数据 | `CustomIndicatorTemplate` | 定义控件展示内容、输入数据、模板或业务对象入口。 |
|
||||
| 交互与状态 | `IsMaskBackgroundEnabled`、`IsMaskBlurEnabled`、`IsMotionEnabled`、`IsSpinning`、`IsTipVisible` | 表达用户可观察状态、可用性、清除、加载或反馈语义。 |
|
||||
| 视觉与布局 | `DotSize`、`IndicatorSize`、`SizeType` | 影响尺寸、位置、颜色、形状、密度和模板视觉变量。 |
|
||||
| 视觉与布局 | `DotBgBrush`、`DotSize`、`IndicatorSize`、`SizeType` | 影响尺寸、位置、颜色、形状、密度和模板视觉变量。 |
|
||||
| 动效与异步 | `MotionDuration`、`MotionEasingCurve` | 约束动效开关、异步加载、播放速度、超时和任务边界。 |
|
||||
| 其他稳定入口 | `CustomIndicator`、`Tip` | 保留为 public surface，变更前需确认 Gallery 和用户 XAML 依赖。 |
|
||||
|
||||
@@ -21486,7 +21490,7 @@ Spin 的公共契约由 public/protected 类型成员、Avalonia 属性、事件
|
||||
|
||||
### 基础用法
|
||||
|
||||
来源：`controlgallery/AtomUIGallery/ShowCases/Feedback/Spin/Views/SpinShowCase.axaml:36`
|
||||
来源：`controlgallery/AtomUIGallery/ShowCases/Feedback/Spin/Views/SpinShowCase.axaml:97`
|
||||
|
||||
Gallery key：`ExamplesContent` / item `0`
|
||||
|
||||
@@ -21496,7 +21500,7 @@ Gallery key：`ExamplesContent` / item `0`
|
||||
|
||||
### 尺寸
|
||||
|
||||
来源：`controlgallery/AtomUIGallery/ShowCases/Feedback/Spin/Views/SpinShowCase.axaml:47`
|
||||
来源：`controlgallery/AtomUIGallery/ShowCases/Feedback/Spin/Views/SpinShowCase.axaml:108`
|
||||
|
||||
Gallery key：`ExamplesContent` / item `1`
|
||||
|
||||
@@ -21509,12 +21513,45 @@ Gallery key：`ExamplesContent` / item `1`
|
||||
</StackPanel>
|
||||
```
|
||||
|
||||
### 自定义描述
|
||||
### 嵌入模式
|
||||
|
||||
来源：`controlgallery/AtomUIGallery/ShowCases/Feedback/Spin/Views/SpinShowCase.axaml:63`
|
||||
来源：`controlgallery/AtomUIGallery/ShowCases/Feedback/Spin/Views/SpinShowCase.axaml:125`
|
||||
|
||||
Gallery key：`ExamplesContent` / item `2`
|
||||
|
||||
```axaml
|
||||
<StackPanel Orientation="Vertical" Spacing="10">
|
||||
<atom:Spin IsSpinning="{Binding IsLoadingSwitchChecked}"
|
||||
IsTipVisible="True"
|
||||
HorizontalAlignment="Stretch"
|
||||
Tip="加载中...">
|
||||
<atom:Alert Message="提示消息标题"
|
||||
Description="关于这条提示上下文的更多详细信息。"
|
||||
Type="Info" />
|
||||
</atom:Spin>
|
||||
|
||||
<atom:Spin IsSpinning="{Binding IsLoadingSwitchChecked}"
|
||||
IsTipVisible="True"
|
||||
Tip="加载中..."
|
||||
HorizontalAlignment="Stretch"
|
||||
IsMaskBlurEnabled="True">
|
||||
<atom:Alert Message="提示消息标题"
|
||||
Description="关于这条提示上下文的更多详细信息。"
|
||||
Type="Info" />
|
||||
</atom:Spin>
|
||||
<StackPanel Orientation="Horizontal" Spacing="10">
|
||||
<atom:TextBlock Text="加载状态：" />
|
||||
<atom:ToggleSwitch IsChecked="{Binding IsLoadingSwitchChecked}" />
|
||||
</StackPanel>
|
||||
</StackPanel>
|
||||
```
|
||||
|
||||
### 自定义描述
|
||||
|
||||
来源：`controlgallery/AtomUIGallery/ShowCases/Feedback/Spin/Views/SpinShowCase.axaml:159`
|
||||
|
||||
Gallery key：`ExamplesContent` / item `3`
|
||||
|
||||
```axaml
|
||||
<StackPanel Orientation="Vertical" Spacing="10">
|
||||
<StackPanel Orientation="Horizontal" Spacing="10">
|
||||
@@ -21544,39 +21581,6 @@ Gallery key：`ExamplesContent` / item `2`
|
||||
</StackPanel>
|
||||
```
|
||||
|
||||
### 嵌入模式
|
||||
|
||||
来源：`controlgallery/AtomUIGallery/ShowCases/Feedback/Spin/Views/SpinShowCase.axaml:121`
|
||||
|
||||
Gallery key：`ExamplesContent` / item `4`
|
||||
|
||||
```axaml
|
||||
<StackPanel Orientation="Vertical" Spacing="10">
|
||||
<atom:Spin IsSpinning="{Binding IsLoadingSwitchChecked}"
|
||||
IsTipVisible="True"
|
||||
HorizontalAlignment="Stretch"
|
||||
Tip="加载中...">
|
||||
<atom:Alert Message="提示消息标题"
|
||||
Description="关于这条提示上下文的更多详细信息。"
|
||||
Type="Info" />
|
||||
</atom:Spin>
|
||||
|
||||
<atom:Spin IsSpinning="{Binding IsLoadingSwitchChecked}"
|
||||
IsTipVisible="True"
|
||||
Tip="加载中..."
|
||||
HorizontalAlignment="Stretch"
|
||||
IsMaskBlurEnabled="True">
|
||||
<atom:Alert Message="提示消息标题"
|
||||
Description="关于这条提示上下文的更多详细信息。"
|
||||
Type="Info" />
|
||||
</atom:Spin>
|
||||
<StackPanel Orientation="Horizontal" Spacing="10">
|
||||
<atom:TextBlock Text="加载状态：" />
|
||||
<atom:ToggleSwitch IsChecked="{Binding IsLoadingSwitchChecked}" />
|
||||
</StackPanel>
|
||||
</StackPanel>
|
||||
```
|
||||
|
||||
## 状态模型
|
||||
|
||||
Spin 的状态流按以下路径收敛：
|
||||
@@ -21627,6 +21631,7 @@ Spin Token 只表达组件级视觉变量，例如尺寸、间距、颜色、圆
|
||||
资源和 AOT 约束：
|
||||
|
||||
- 不通过运行时反射扫描 public API、Token 或 Gallery 示例数据。
|
||||
- 不通过 VisualTree 扫描维护 Semantic Part；Gallery Preview 使用生成 descriptor 和 owner-scoped marker 解析。
|
||||
- 不把可静态声明的模板结构迁移到 C# 动态创建。
|
||||
- 异步加载、上传、弹层和窗口生命周期必须能取消或释放。
|
||||
- 缓存对象必须与控件、窗口、弹层或数据 owner 生命周期一致。
|
||||
@@ -21649,6 +21654,8 @@ Spin Token 只表达组件级视觉变量，例如尺寸、间距、颜色、圆
|
||||
- `src/AtomUI.Desktop.Controls/Spin/Spin.cs`
|
||||
- `src/AtomUI.Desktop.Controls/Spin/SpinIndicator.cs`
|
||||
- `src/AtomUI.Desktop.Controls/Spin/SpinToken.cs`
|
||||
- `src/AtomUI.Desktop.Controls/Spin/Spin.SemanticParts.cs`
|
||||
- `src/AtomUI.Desktop.Controls/Spin/SpinIndicator.SemanticParts.cs`
|
||||
- `src/AtomUI.Desktop.Controls/Spin/Themes/SpinIndicatorTheme.axaml`
|
||||
- `src/AtomUI.Desktop.Controls/Spin/Themes/SpinTheme.axaml`
|
||||
|
||||
@@ -21658,11 +21665,13 @@ Spin Token 只表达组件级视觉变量，例如尺寸、间距、颜色、圆
|
||||
- Theme 文件负责静态视觉结构、template part、selector 和资源绑定。
|
||||
- Token 文件只提供组件视觉变量，不保存实例状态。
|
||||
- Gallery 文件只展示用法和示例，不作为运行时逻辑 owner。
|
||||
- Semantic descriptor 由各 public owner 的 `[SemanticPart]` 声明生成；模板只使用静态 `Classes.semantic-*="True"` marker。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- 源设计文档：`docs/controls/desktop/feedback/spin/overview.md`
|
||||
- 实现文档：`docs/controls/desktop/feedback/spin/implementation.md`
|
||||
- Semantic Part 文档：`docs/controls/desktop/feedback/spin/semantic-part.md`
|
||||
- Token 文档：`docs/controls/desktop/feedback/spin/token.md`
|
||||
- 变更记录：`docs/controls/desktop/feedback/spin/changelog.md`
|
||||
- 语义结构：`./semantic-cn.md`
|
||||
|
||||
@@ -14428,13 +14428,38 @@ Source: ./controls/spin/semantic-cn.md
|
||||
|
||||
## Semantic Parts
|
||||
|
||||
| Part | AtomUI 节点 | 职责 | 相关 API | 相关 Token | 稳定性 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| `root` | `Spin` | 反馈控件根语义区域，承载 public API、反馈状态和主题入口。 | 见 API 与契约模型 | 见视觉与主题模型 | stable |
|
||||
| `host` | `宿主或弹层区域` | 承载 overlay、popup、portal、message host、drawer 或 modal 容器。 | 见 API 与契约模型 | 见视觉与主题模型 | stable |
|
||||
| `surface` | `反馈表面` | 承载背景、边框、阴影、尺寸、placement 和视觉状态。 | 见 API 与契约模型 | 见视觉与主题模型 | stable |
|
||||
| `content` | `内容区域` | 承载标题、正文、图标、进度、结果、操作或关闭入口。 | 见 API 与契约模型 | 见视觉与主题模型 | stable |
|
||||
| `motion` | `动效区域` | 表达进入退出、loading、progress、skeleton 或水印刷新反馈。 | 见 API 与契约模型 | 见视觉与主题模型 | stable |
|
||||
Spin 主控件公开 `root`、`container`、`mask`、`section`、`indicator`、`description` 六个职责区域，与上游稳定语义
|
||||
保持同名。`mask` 是 AtomUI 扩展区域，承载嵌套模式的遮罩背景层职责：上游体系的遮罩语义已折叠进全屏模式的根区域，
|
||||
AtomUI 没有全屏模式，遮罩层是嵌套模式下独立的真实节点。`SpinIndicator` 是独立的公开子控件，
|
||||
公开 `root` 与 `content`。
|
||||
|
||||
### 1.1 `Spin`
|
||||
|
||||
| Part | Selector | ContractType | Cardinality | Customization | CrossVisualRoot | RuntimeCreated |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| `root` | owner | `Spin` | `Single` | `Root` | `false` | `false` |
|
||||
| `container` | `.semantic-container` | `ContentPresenter` | `Single` | `Selector` | `false` | `false` |
|
||||
| `mask` | `.semantic-mask` | `Border` | `Single` | `Selector` | `false` | `false` |
|
||||
| `section` | `.semantic-section` | `StackPanel` | `Single` | `Selector` | `false` | `false` |
|
||||
| `indicator` | `.semantic-indicator` | `SpinIndicator` | `Single` | `Selector` | `false` | `false` |
|
||||
| `description` | `.semantic-description` | `TextBlock` | `Single` | `Selector` | `false` | `false` |
|
||||
|
||||
`container` 承载用户内容的 `ContentPresenter`，spinning 时承担透明度或高斯模糊反馈；`mask` 是遮罩背景层，只在
|
||||
`IsMaskBackgroundEnabled` 时呈现 `ColorBgMask`；`section` 是加载区域，承载 `indicator` 与 `description` 并居中；
|
||||
`indicator` 是主控件模板直接拥有的公开 `SpinIndicator` 子控件，其尺寸分支、动效时长和圆点填充
|
||||
（`DotBgBrush`）均可经 Semantic Style 定制；`description` 是提示文本节点，对应公共 API
|
||||
`Tip` / `IsTipVisible`。`root` 不声明 `.semantic-root` marker。
|
||||
|
||||
### 1.2 `SpinIndicator`
|
||||
|
||||
| Part | Selector | ContractType | Cardinality | Customization | CrossVisualRoot | RuntimeCreated |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| `root` | owner | `SpinIndicator` | `Single` | `Root` | `false` | `false` |
|
||||
| `content` | `.semantic-content` | `Control` | `Multiple` | `Selector` | `false` | `false` |
|
||||
|
||||
`content` 使用 `Multiple` 是 AtomUI 模板实现的状态替代语义：内置四点指示器 `SpinIndicatorDotPanel` 与自定义指示器
|
||||
`PART_CustomIndicatorPresenter` 是两个静态 marker target，由 `IsCustomIndicator` 决定同一时刻只有一个可见。
|
||||
Preview 只高亮当前可见 target；Semantic Style 同时作用于两个替代实现，保证切换自定义指示器后定制仍然存在。
|
||||
|
||||
## Abstract AXAML Structure
|
||||
|
||||
@@ -14503,7 +14528,7 @@ Spin
|
||||
| --- | --- | --- |
|
||||
| 内容与数据 | `CustomIndicatorTemplate` | 定义控件展示内容、输入数据、模板或业务对象入口。 |
|
||||
| 交互与状态 | `IsMaskBackgroundEnabled`、`IsMaskBlurEnabled`、`IsMotionEnabled`、`IsSpinning`、`IsTipVisible` | 表达用户可观察状态、可用性、清除、加载或反馈语义。 |
|
||||
| 视觉与布局 | `DotSize`、`IndicatorSize`、`SizeType` | 影响尺寸、位置、颜色、形状、密度和模板视觉变量。 |
|
||||
| 视觉与布局 | `DotBgBrush`、`DotSize`、`IndicatorSize`、`SizeType` | 影响尺寸、位置、颜色、形状、密度和模板视觉变量。 |
|
||||
| 动效与异步 | `MotionDuration`、`MotionEasingCurve` | 约束动效开关、异步加载、播放速度、超时和任务边界。 |
|
||||
| 其他稳定入口 | `CustomIndicator`、`Tip` | 保留为 public surface，变更前需确认 Gallery 和用户 XAML 依赖。 |
|
||||
|
||||
|
||||
@@ -9,6 +9,17 @@
|
||||
- Docs
|
||||
- Document ancestor visibility tracking and Compositor cleanup ownership.
|
||||
|
||||
## 2026-08-16
|
||||
|
||||
- Semantic Parts
|
||||
- Add Ant Design-aligned Semantic Part descriptors for `Spin` and the public `SpinIndicator` owner.
|
||||
- Add static template markers and generated owner-scoped style contracts without runtime discovery.
|
||||
- Document the dual static content targets used by built-in and custom SpinIndicator implementations.
|
||||
- API
|
||||
- Promote `AbstractSpinIndicator.DotBgBrush` to public so the built-in indicator color is customizable through the `indicator` Semantic Part.
|
||||
- Gallery
|
||||
- Add the Semantic Parts Preview and Ant Design-aligned custom styling example using AtomUI `v6.1.3` version metadata.
|
||||
|
||||
## 2026-06-26
|
||||
|
||||
- Docs
|
||||
|
||||
@@ -16,6 +16,8 @@
|
||||
- `src/AtomUI.Desktop.Controls/Spin/Spin.cs`
|
||||
- `src/AtomUI.Desktop.Controls/Spin/SpinIndicator.cs`
|
||||
- `src/AtomUI.Desktop.Controls/Spin/SpinToken.cs`
|
||||
- `src/AtomUI.Desktop.Controls/Spin/Spin.SemanticParts.cs`
|
||||
- `src/AtomUI.Desktop.Controls/Spin/SpinIndicator.SemanticParts.cs`
|
||||
- `src/AtomUI.Desktop.Controls/Spin/Themes/SpinIndicatorTheme.axaml`
|
||||
- `src/AtomUI.Desktop.Controls/Spin/Themes/SpinTheme.axaml`
|
||||
|
||||
@@ -25,6 +27,7 @@
|
||||
- Theme 文件负责静态视觉结构、template part、selector 和资源绑定。
|
||||
- Token 文件只提供组件视觉变量，不保存实例状态。
|
||||
- Gallery 文件只展示用法和示例，不作为运行时逻辑 owner。
|
||||
- Semantic descriptor 由各 public owner 的 `[SemanticPart]` 声明生成；模板只使用静态 `Classes.semantic-*="True"` marker。
|
||||
|
||||
## 3. 核心类职责
|
||||
|
||||
@@ -57,7 +60,7 @@ Public API / ItemsSource / Command / Event
|
||||
|
||||
- 内容与数据：`CustomIndicatorTemplate`。
|
||||
- 交互与状态：`IsMaskBackgroundEnabled`、`IsMaskBlurEnabled`、`IsMotionEnabled`、`IsSpinning`、`IsTipVisible`。
|
||||
- 视觉与布局：`DotSize`、`IndicatorSize`、`SizeType`。
|
||||
- 视觉与布局：`DotBgBrush`、`DotSize`、`IndicatorSize`、`SizeType`。
|
||||
- 动效与异步：`MotionDuration`、`MotionEasingCurve`。
|
||||
- 其他稳定入口：`CustomIndicator`、`Tip`。
|
||||
|
||||
@@ -82,6 +85,15 @@ Public API / ItemsSource / Command / Event
|
||||
|
||||
- `PART_CustomIndicatorPresenter`：展示用户内容、文本、图标或模板化数据。
|
||||
|
||||
`SpinTheme` 的模板使用两层叠加结构：`ContentPresenter.semantic-container` 承载用户内容，`MaskLayout` 面板在
|
||||
`IsSpinning=True` 时可见，其内部 `Border.semantic-mask` 提供遮罩背景，`StackPanel.semantic-section` 承载
|
||||
`SpinIndicator.semantic-indicator` 与 `TextBlock.semantic-description` 并居中。遮罩层组与内容容器是同一根面板下的
|
||||
sibling，确保 Semantic Preview 高亮 `container` 时只覆盖用户内容区域。
|
||||
|
||||
`SpinIndicatorTheme` 的模板由两个静态替代实现构成：`SpinIndicatorDotPanel.semantic-content` 承载四个内置圆点，
|
||||
`PART_CustomIndicatorPresenter.semantic-content` 承载自定义指示器；`IsCustomIndicator` 决定当前可见 target，两个
|
||||
target 都保持 marker。四个圆点（`Ellipse.SpinIndicatorDot`）是内部 Composition 节点，不属于任何 Semantic Part。
|
||||
|
||||
## 6. 交互与事件处理
|
||||
|
||||
Spin 的交互事件应从输入源收敛到控件级语义事件：
|
||||
@@ -102,6 +114,10 @@ Spin 的交互事件应从输入源收敛到控件级语义事件：
|
||||
- 主题资源、Token 和 SharedToken 计算后的视觉更新。
|
||||
- 内容、命令和视觉状态在模板节点之间的同步。
|
||||
- 动效启停、初始加载阶段 transition 抑制和卸载取消。
|
||||
- Semantic Part marker 不参与状态切换；`IsSpinning`、`IsTipVisible` 和 `IsCustomIndicator` 只改变目标节点的
|
||||
`IsVisible`，marker 身份和数量保持不变。
|
||||
- 指示器旋转与圆点透明度动画由 `AbstractSpinIndicator` 通过 Composition 动画直接拥有；动画目标从
|
||||
`IsCustomIndicator` 推导，状态切换只重启动画，不增删 marker 节点。
|
||||
|
||||
`AbstractSpinIndicator` 的旋转和内置 dot opacity 由 Compositor 无限动画驱动。Compositor 不提供控件级有效可见性暂停语义，因此 indicator 在 attach 后跟踪自身及 Visual 祖先链；有效不可见时停止所有目标动画并复位视觉状态，恢复可见时重新解析当前 built-in/custom target 并启动动画。detach 时必须释放可见性订阅和所有 Compositor target。
|
||||
|
||||
@@ -112,6 +128,7 @@ Spin 的交互事件应从输入源收敛到控件级语义事件：
|
||||
资源和 AOT 约束：
|
||||
|
||||
- 不通过运行时反射扫描 public API、Token 或 Gallery 示例数据。
|
||||
- 不通过 VisualTree 扫描维护 Semantic Part；Gallery Preview 使用生成 descriptor 和 owner-scoped marker 解析。
|
||||
- 不把可静态声明的模板结构迁移到 C# 动态创建。
|
||||
- 异步加载、上传、弹层和窗口生命周期必须能取消或释放。
|
||||
- 缓存对象必须与控件、窗口、弹层或数据 owner 生命周期一致。
|
||||
|
||||
@@ -42,7 +42,7 @@ Spin 的公共契约由 public/protected 类型成员、Avalonia 属性、事件
|
||||
| --- | --- | --- |
|
||||
| 内容与数据 | `CustomIndicatorTemplate` | 定义控件展示内容、输入数据、模板或业务对象入口。 |
|
||||
| 交互与状态 | `IsMaskBackgroundEnabled`、`IsMaskBlurEnabled`、`IsMotionEnabled`、`IsSpinning`、`IsTipVisible` | 表达用户可观察状态、可用性、清除、加载或反馈语义。 |
|
||||
| 视觉与布局 | `DotSize`、`IndicatorSize`、`SizeType` | 影响尺寸、位置、颜色、形状、密度和模板视觉变量。 |
|
||||
| 视觉与布局 | `DotBgBrush`、`DotSize`、`IndicatorSize`、`SizeType` | 影响尺寸、位置、颜色、形状、密度和模板视觉变量。 |
|
||||
| 动效与异步 | `MotionDuration`、`MotionEasingCurve` | 约束动效开关、异步加载、播放速度、超时和任务边界。 |
|
||||
| 其他稳定入口 | `CustomIndicator`、`Tip` | 保留为 public surface，变更前需确认 Gallery 和用户 XAML 依赖。 |
|
||||
|
||||
@@ -144,17 +144,22 @@ Spin 的视觉选项通过 public API 归一为 theme variables、伪类或模
|
||||
|
||||
- [Spin 桌面版实现原理](implementation.md)
|
||||
- [Spin Token 设计](token.md)
|
||||
- [Spin Semantic Part 契约](semantic-part.md)
|
||||
- [Spin Changelog](changelog.md)
|
||||
|
||||
LLMS 语义区域：
|
||||
|
||||
| Part | AtomUI 节点 | 职责 | 相关 API | 相关 Token | 稳定性 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| `root` | `Spin` | 反馈控件根语义区域，承载 public API、反馈状态和主题入口。 | 见 API 与契约模型 | 见视觉与主题模型 | stable |
|
||||
| `host` | `宿主或弹层区域` | 承载 overlay、popup、portal、message host、drawer 或 modal 容器。 | 见 API 与契约模型 | 见视觉与主题模型 | stable |
|
||||
| `surface` | `反馈表面` | 承载背景、边框、阴影、尺寸、placement 和视觉状态。 | 见 API 与契约模型 | 见视觉与主题模型 | stable |
|
||||
| `content` | `内容区域` | 承载标题、正文、图标、进度、结果、操作或关闭入口。 | 见 API 与契约模型 | 见视觉与主题模型 | stable |
|
||||
| `motion` | `动效区域` | 表达进入退出、loading、progress、skeleton 或水印刷新反馈。 | 见 API 与契约模型 | 见视觉与主题模型 | stable |
|
||||
| `root` | `Spin` | 主控件根区域，承载加载状态、遮罩选项和主题入口。 | 见 API 与契约模型 | `SpinToken` | stable |
|
||||
| `container` | `ContentPresenter` | 嵌套模式的用户内容容器，spinning 时承担透明度或模糊反馈。 | `IsSpinning`、`IsMaskBlurEnabled` | 无 | stable |
|
||||
| `mask` | `Border` | 遮罩背景层，spinning 时覆盖内容区域。 | `IsMaskBackgroundEnabled` | `ColorBgMask` | stable |
|
||||
| `section` | `StackPanel` | 加载区域，承载指示器和提示文本并居中。 | `SizeType` | `SpacingXXS` | stable |
|
||||
| `indicator` | `SpinIndicator` | 主控件模板拥有的加载指示子控件。 | `CustomIndicator`、`DotBgBrush` | `IndicatorSize*`、`DotSize*` | stable |
|
||||
| `description` | `TextBlock` | 提示文本区域。 | `Tip`、`IsTipVisible` | `ColorPrimary` | stable |
|
||||
|
||||
`SpinIndicator` 的 `root/content` descriptor 与主控件分开维护，完整契约见
|
||||
[Spin Semantic Part 契约](semantic-part.md)。
|
||||
|
||||
LLMS 导出来源：
|
||||
|
||||
|
||||
@@ -0,0 +1,99 @@
|
||||
# Spin Semantic Part 契约
|
||||
|
||||
本文档定义 Spin 家族公开的 Semantic Part、选择器、类型约束、数量语义和定制边界。Spin 的整体设计见
|
||||
[Spin 桌面版架构设计](overview.md)，真实模板与生命周期见 [Spin 桌面版实现原理](implementation.md)，系统级规则见
|
||||
[AtomUI Semantic Part 系统设计](../../../../architecture/systems/theming/semantic-parts.md)。
|
||||
|
||||
## 1. Semantic Parts
|
||||
|
||||
Spin 主控件公开 `root`、`container`、`mask`、`section`、`indicator`、`description` 六个职责区域，与上游稳定语义
|
||||
保持同名。`mask` 是 AtomUI 扩展区域，承载嵌套模式的遮罩背景层职责：上游体系的遮罩语义已折叠进全屏模式的根区域，
|
||||
AtomUI 没有全屏模式，遮罩层是嵌套模式下独立的真实节点。`SpinIndicator` 是独立的公开子控件，
|
||||
公开 `root` 与 `content`。
|
||||
|
||||
### 1.1 `Spin`
|
||||
|
||||
| Part | Selector | ContractType | Cardinality | Customization | CrossVisualRoot | RuntimeCreated |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| `root` | owner | `Spin` | `Single` | `Root` | `false` | `false` |
|
||||
| `container` | `.semantic-container` | `ContentPresenter` | `Single` | `Selector` | `false` | `false` |
|
||||
| `mask` | `.semantic-mask` | `Border` | `Single` | `Selector` | `false` | `false` |
|
||||
| `section` | `.semantic-section` | `StackPanel` | `Single` | `Selector` | `false` | `false` |
|
||||
| `indicator` | `.semantic-indicator` | `SpinIndicator` | `Single` | `Selector` | `false` | `false` |
|
||||
| `description` | `.semantic-description` | `TextBlock` | `Single` | `Selector` | `false` | `false` |
|
||||
|
||||
`container` 承载用户内容的 `ContentPresenter`，spinning 时承担透明度或高斯模糊反馈；`mask` 是遮罩背景层，只在
|
||||
`IsMaskBackgroundEnabled` 时呈现 `ColorBgMask`；`section` 是加载区域，承载 `indicator` 与 `description` 并居中；
|
||||
`indicator` 是主控件模板直接拥有的公开 `SpinIndicator` 子控件，其尺寸分支、动效时长和圆点填充
|
||||
（`DotBgBrush`）均可经 Semantic Style 定制；`description` 是提示文本节点，对应公共 API
|
||||
`Tip` / `IsTipVisible`。`root` 不声明 `.semantic-root` marker。
|
||||
|
||||
### 1.2 `SpinIndicator`
|
||||
|
||||
| Part | Selector | ContractType | Cardinality | Customization | CrossVisualRoot | RuntimeCreated |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| `root` | owner | `SpinIndicator` | `Single` | `Root` | `false` | `false` |
|
||||
| `content` | `.semantic-content` | `Control` | `Multiple` | `Selector` | `false` | `false` |
|
||||
|
||||
`content` 使用 `Multiple` 是 AtomUI 模板实现的状态替代语义：内置四点指示器 `SpinIndicatorDotPanel` 与自定义指示器
|
||||
`PART_CustomIndicatorPresenter` 是两个静态 marker target，由 `IsCustomIndicator` 决定同一时刻只有一个可见。
|
||||
Preview 只高亮当前可见 target；Semantic Style 同时作用于两个替代实现，保证切换自定义指示器后定制仍然存在。
|
||||
|
||||
## 2. Selector 用法
|
||||
|
||||
应用侧只使用 owner-scoped selector 和生成的 Style 类型，不复制 `/template/` 路径：
|
||||
|
||||
```xml
|
||||
<Style Selector="atom|Spin.semantic-style-demo">
|
||||
<atom:SpinSectionStyle x:SetterTargetType="StackPanel">
|
||||
<Setter Property="Spacing" Value="12" />
|
||||
</atom:SpinSectionStyle>
|
||||
<atom:SpinIndicatorStyle x:SetterTargetType="atom:SpinIndicator">
|
||||
<Setter Property="DotBgBrush" Value="#00d4ff" />
|
||||
</atom:SpinIndicatorStyle>
|
||||
<atom:SpinDescriptionStyle x:SetterTargetType="TextBlock">
|
||||
<Setter Property="FontSize" Value="14" />
|
||||
</atom:SpinDescriptionStyle>
|
||||
</Style>
|
||||
```
|
||||
|
||||
`SpinContainerStyle`、`SpinIndicatorStyle` 与 `SpinIndicator` owner 的 `SpinIndicatorContentStyle` 使用同一规则。
|
||||
Semantic Style 只覆盖视觉属性和布局属性，不改变 `IsSpinning`、SizeType 分支、`CustomIndicator` 内容或动画状态。
|
||||
|
||||
## 3. Template 与状态边界
|
||||
|
||||
- 主控件的 `container`、`mask`、`section`、`indicator` 和 `description` marker 都由 Spin 自己模板提供。
|
||||
`container` 与遮罩层组是根布局的 sibling；`mask` 与 `section` 是遮罩层组内的 sibling，`section` 是
|
||||
`indicator` 和 `description` 的唯一父容器。
|
||||
- 所有 marker 节点在模板中静态存在；`IsSpinning` 只切换遮罩层组的 `IsVisible`，`IsTipVisible` 只切换
|
||||
`description` 的 `IsVisible`，都不改变 descriptor、marker 身份或数量。
|
||||
- `indicator` Part 的契约边界止于公开 `SpinIndicator` 控件本身；其模板内的四个圆点
|
||||
（`Ellipse.SpinIndicatorDot`）、内置布局面板和自定义指示器 presenter 都是 `SpinIndicator` owner 的内部结构，
|
||||
不由 `Spin` owner 公开。
|
||||
- `SpinIndicator` 的 `content` marker 位于静态内置点阵面板和静态自定义 presenter；不公开 `PART_*` 名称，四个圆点
|
||||
不作为独立 Part，Composition 动画对象不属于任何 Part。
|
||||
- 模板重套用后由新模板重新提供同一 marker 契约；隐藏遮罩层组或切换指示器实现不改变 Part 数量。
|
||||
|
||||
## 4. 尺寸与布局基线
|
||||
|
||||
`SpinIndicator` 的 Large/Middle/Small 分支由 `SizeType` 与 `SpinToken`（`IndicatorSizeLG/IndicatorSize/IndicatorSizeSM`
|
||||
和对应 `DotSize*`）控制；`SizeType=Custom` 默认回落到 Middle 尺寸，显式设置 `IndicatorSize` 或 `DotSize` 时以本地值
|
||||
优先。Semantic Style 不以固定 Width/Height 替代这些完整分支；需要定制尺寸时应设置公开尺寸 API。
|
||||
|
||||
主控件的根默认 `HorizontalAlignment=Left`、`VerticalAlignment=Top`；嵌套模式下 `container` 按用户内容测量，
|
||||
遮罩层组与 `container` 同区域叠加。`description` 默认前景色由主题从 `ColorPrimary` 投影，`section` 间距来自
|
||||
`SpacingXXS`；Semantic Style 覆盖这些值时作用于同一节点，不创建平行样式入口。
|
||||
|
||||
Spinning 反馈在 `container` 上有两条互斥路径：`IsMaskBlurEnabled=True` 时对 `container` 应用高斯模糊，否则把
|
||||
内容透明度降为 `0.5`（经 `MaskOpacity` transition）。Semantic Style 作用于 `container` 时应保留这两条状态路径，
|
||||
不改写透明度状态机。
|
||||
|
||||
## 5. 验证不变量
|
||||
|
||||
- `Spin` descriptor 只包含 `root/container/mask/section/indicator/description`。
|
||||
- `SpinIndicator` descriptor 只包含 `root/content`，`content` 为两个静态替代 target。
|
||||
- Desktop 所有叶子 Spin 主题均声明静态 `Classes.semantic-*="True"`，不使用 Binding 或 `False` marker。
|
||||
- 默认主题不消费 `.semantic-*` selector；Semantic Part 只增加静态 class、descriptor 和生成 Style。
|
||||
- Gallery Semantic Parts Tab 延迟创建主控件和 `SpinIndicator` Preview；Examples Tab 的既有示例树保持不变。
|
||||
- Semantic 示例标题使用 `Custom Semantic Part styling`，文案只描述 AtomUI owner-scoped Style；Tag 使用当前版本
|
||||
`GalleryVersionInfo.DisplayVersion`（`v6.1.3`）。
|
||||
Reference in New Issue
Block a user