AtomUI/docs/Desktop.Controls/Upload/UploadStyling.md

Upload 自定义样式指南

Upload 的视觉表现通过 ControlTheme + Design Token 系统控制。Upload 是一个复合控件，包含多个内部子组件，以下介绍常见的自定义方式。

---

1. 使用属性直接控制

最简单的方式是通过 Upload 的公共属性来控制外观和行为：

<!-- 不同列表类型 -->
<atom:Upload ListType="Text">
    <atom:Button Icon="{antdicons:AntDesignIconProvider UploadOutlined}">Upload</atom:Button>
</atom:Upload>

<atom:Upload ListType="Picture">
    <atom:Button Icon="{antdicons:AntDesignIconProvider UploadOutlined}" ButtonType="Primary">Upload</atom:Button>
</atom:Upload>

<atom:Upload ListType="PictureCard">
    <StackPanel Orientation="Vertical">
        <antdicons:PlusOutlined />
        <TextBlock Margin="0, 8, 0, 0">Upload</TextBlock>
    </StackPanel>
</atom:Upload>

<atom:Upload ListType="PictureCircle">
    <StackPanel Orientation="Vertical">
        <antdicons:PlusOutlined />
        <TextBlock Margin="0, 8, 0, 0">Upload</TextBlock>
    </StackPanel>
</atom:Upload>

<!-- 控制显示/隐藏 -->
<atom:Upload IsShowUploadList="False">
    <atom:Button>Upload (no list)</atom:Button>
</atom:Upload>

<atom:Upload IsShowUploadTrigger="False" />

📖 完整示例参考：controlgallery/AtomUIGallery/ShowCases/Views/DataEntry/UploadShowCase.axaml

---

2. 自定义拖拽区域

UploadDefaultDropArea 提供了多个可自定义的属性：

<!-- 自定义图标、标题和副标题 -->
<atom:Upload>
    <atom:UploadDefaultDropArea
        Header="拖拽文件到此处上传"
        SubHeader="支持单个或批量上传，严禁上传公司内部资料或其他违禁文件">
        <!-- DropIcon 默认为 InboxOutlined -->
    </atom:UploadDefaultDropArea>
</atom:Upload>

<!-- 使用模板自定义标题内容 -->
<atom:Upload>
    <atom:UploadDefaultDropArea>
        <atom:UploadDefaultDropArea.HeaderTemplate>
            <DataTemplate>
                <TextBlock Text="Custom Header" FontWeight="Bold" />
            </DataTemplate>
        </atom:UploadDefaultDropArea.HeaderTemplate>
    </atom:UploadDefaultDropArea>
</atom:Upload>

---

3. 自定义 PictureCard/PictureCircle 触发内容

PictureCard 和 PictureCircle 类型的触发区完全可自定义：

<!-- 带加载状态切换的触发按钮 -->
<atom:Upload ListType="PictureCard">
    <StackPanel Orientation="Vertical">
        <Panel>
            <antdicons:PlusOutlined
                IsVisible="{Binding IsTaskRunning,
                            RelativeSource={RelativeSource AncestorType=atom:Upload},
                            Converter={x:Static BoolConverters.Not}}" />
            <antdicons:LoadingOutlined
                IsVisible="{Binding IsTaskRunning,
                            RelativeSource={RelativeSource AncestorType=atom:Upload}}"
                LoadingAnimation="Spin" />
        </Panel>
        <TextBlock Margin="0, 8, 0, 0">Upload</TextBlock>
    </StackPanel>
</atom:Upload>

---

4. 通过 Style 覆盖样式

可以在 AXAML 中使用 Style 对 Upload 及其子组件进行全局或局部样式覆盖：

全局统一间距

<Window.Styles>
    <Style Selector="atom|Upload">
        <Setter Property="Margin" Value="0, 10" />
    </Style>
</Window.Styles>

按列表类型定制

<!-- 禁用 PictureCard 类型的内容对齐 -->
<Style Selector="atom|Upload[ListType=PictureCard]">
    <Setter Property="HorizontalContentAlignment" Value="Left" />
</Style>

自定义拖拽区域样式

<!-- 自定义拖拽区域的背景和边框 -->
<Style Selector="atom|UploadDefaultDropArea">
    <Setter Property="Background" Value="#f0f5ff" />
    <Setter Property="BorderBrush" Value="#1677ff" />
</Style>

<!-- 自定义悬浮状态 -->
<Style Selector="atom|UploadDefaultDropArea:pointerover">
    <Setter Property="BorderBrush" Value="#4096ff" />
</Style>

---

5. 通过 ControlTheme 完全替换主题

如果需要彻底替换 Upload 的模板和样式，可以定义自定义 ControlTheme：

<ControlTheme x:Key="MyCustomUpload" TargetType="atom:Upload">
    <Setter Property="Template">
        <ControlTemplate>
            <!-- 自定义模板结构 -->
        </ControlTemplate>
    </Setter>
</ControlTheme>

<atom:Upload Theme="{StaticResource MyCustomUpload}" />

⚠️ 注意：Upload 是一个复杂的复合控件，完全替换 ControlTheme 需要重新实现触发区、文件列表、图片预览等所有子组件的模板。建议优先使用 Style 覆盖和属性配置。

---

6. 控制动画行为

<!-- 禁用过渡动画 -->
<atom:Upload IsMotionEnabled="False">
    <atom:Button>Upload</atom:Button>
</atom:Upload>

---

样式选择器速查

说明：Avalonia 样式选择器中使用 atom|Upload 语法引用 atom XML 命名空间下的 Upload 类型，其中 | 是命名空间分隔符。

Upload 主控件选择器

选择器	说明
atom|Upload	匹配所有 Upload 实例
atom|Upload[ListType=Text]	匹配文本列表类型的 Upload
atom|Upload[ListType=Picture]	匹配图片列表类型的 Upload
atom|Upload[ListType=PictureCard]	匹配图片卡片墙类型的 Upload
atom|Upload[ListType=PictureCircle]	匹配圆形图片墙类型的 Upload
atom|Upload:disabled	匹配禁用状态的 Upload

UploadDefaultDropArea 选择器

选择器	说明
atom|UploadDefaultDropArea	匹配所有拖拽上传区域实例
atom|UploadDefaultDropArea:pointerover	拖拽区域鼠标悬浮状态（边框高亮为主色调）
atom|UploadDefaultDropArea:disabled	拖拽区域禁用状态（图标和文字变灰）
atom|UploadDefaultDropArea /template/ atom|DashedBorder#Frame	访问拖拽区域模板内的虚线边框
atom|UploadDefaultDropArea /template/ atom|IconPresenter#IconPresenter	访问拖拽区域模板内的图标
atom|UploadDefaultDropArea /template/ ContentPresenter#HeaderContentPresenter	访问主标题内容展示器
atom|UploadDefaultDropArea /template/ ContentPresenter#SubHeaderContentPresenter	访问副标题内容展示器

UploadTriggerContent 选择器（内部组件）

选择器	说明
atom|UploadTriggerContent[ListType=PictureCard]	PictureCard 类型的触发区（虚线边框卡片）
atom|UploadTriggerContent[ListType=PictureCircle]	PictureCircle 类型的触发区（虚线边框圆形）
atom|UploadTriggerContent[ListType=PictureCard]:pointerover	PictureCard 触发区悬浮状态
atom|UploadTriggerContent[ListType=PictureCircle]:pointerover	PictureCircle 触发区悬浮状态
atom|UploadTriggerContent:disabled	禁用状态的触发区

组合选择器示例

选择器	说明
atom|Upload[ListType=Text]:not(:disabled)	非禁用状态的文本列表 Upload
atom|Upload[ListType=PictureCard] /template/ atom|UploadPictureShapeList	访问 PictureCard 模板内的图片列表
atom|UploadDefaultDropArea /template/ atom|DashedBorder#Frame	自定义拖拽区域的虚线边框样式