AtomUI/docs/Desktop.Controls/NumericUpDown/NumericUpDownUsage.md

NumericUpDown 使用文档

本文档介绍 AtomUI NumericUpDown 控件的各种使用方式，示例代码摘自 Gallery 演示程序。

📖 Gallery 源码位置：controlgallery/AtomUIGallery/ShowCases/Views/DataEntry/NumberUpDownShowCase.axaml

---

前置准备

在 AXAML 中使用 NumericUpDown，需要引入以下命名空间：

xmlns:atom="https://atomui.net"
xmlns:antdicons="https://atomui.net/icons/antdesign"

在 C# 代码中引入：

using AtomUI.Desktop.Controls;   // NumericUpDown 控件
using AtomUI.Controls;            // SizeType 等共享类型

---

1. 基本用法

最简单的数字输入框，直接设置初始值：

<atom:NumericUpDown Value="3" HorizontalAlignment="Stretch" />

默认配置：

• 尺寸：Middle（32px 高度）
• 样式：Outline（标准边框）
• 步长：1
• 范围：decimal.MinValue ~ decimal.MaxValue

---

2. 高精度字符串模式（StringMode）

当需要处理超出 decimal 精度范围的数值时，启用 StringMode：

<StackPanel Orientation="Vertical" Spacing="10">
    <atom:NumericUpDown StringMode="True"
                        StringValue="{Binding StringModeValue, Mode=TwoWay}"
                        Increment="0.0001"
                        Minimum="0"
                        Maximum="100"
                        PlaceholderText="Input weight" />
    <TextBlock Text="{Binding StringModeValue, StringFormat=Raw: {0}}" />
</StackPanel>

// ViewModel
public class NumberUpDownViewModel : ReactiveObject
{
    private string? _stringModeValue = "0.123456789012345678901234";
    public string? StringModeValue
    {
        get => _stringModeValue;
        set => this.RaiseAndSetIfChanged(ref _stringModeValue, value);
    }
}

使用场景：科学计算、财务高精度场景，数值以原始字符串形式传输，避免精度丢失。

---

3. 键盘控制

通过 Keyboard 属性控制是否允许使用方向键步进：

<StackPanel Orientation="Vertical" Spacing="10">
    <atom:CheckBox Content="Keyboard enabled"
                   IsChecked="{Binding KeyboardEnabled}" />
    <atom:NumericUpDown Value="1.2"
                        Increment="0.1"
                        Keyboard="{Binding KeyboardEnabled}"
                        PlaceholderText="Keyboard disabled" />
</StackPanel>

private bool _keyboardEnabled = true;
public bool KeyboardEnabled
{
    get => _keyboardEnabled;
    set => this.RaiseAndSetIfChanged(ref _keyboardEnabled, value);
}

当 Keyboard="False" 时，Up/Down/PageUp/PageDown 键不会触发数值增减。

---

4. 鼠标滚轮控制

通过 MouseWheel 属性控制是否允许使用鼠标滚轮步进：

<StackPanel Orientation="Vertical" Spacing="10">
    <atom:CheckBox Content="Mouse wheel enabled"
                   IsChecked="{Binding MouseWheelEnabled}" />
    <atom:NumericUpDown Value="2.5"
                        Increment="0.5"
                        MouseWheel="{Binding MouseWheelEnabled}"
                        PlaceholderText="Mouse wheel disabled" />
</StackPanel>

private bool _mouseWheelEnabled = true;
public bool MouseWheelEnabled
{
    get => _mouseWheelEnabled;
    set => this.RaiseAndSetIfChanged(ref _mouseWheelEnabled, value);
}

---

5. 取值范围限制

通过 Minimum 和 Maximum 属性限制输入范围。步进按钮会自动感知边界并在到达极值时禁用：

<atom:NumericUpDown Minimum="0"
                    Maximum="10"
                    Value="3"
                    Increment="1" />

当 Value = 10 时，增加按钮自动禁用；当 Value = 0 时，减少按钮自动禁用。

---

6. 小数步长

通过 Increment 属性设置小数步长：

<atom:NumericUpDown Value="1.2"
                    Increment="0.25"
                    Minimum="0"
                    Maximum="2" />

每次点击步进按钮，数值增加或减少 0.25。

---

7. 三种尺寸

通过 SizeType 属性设置尺寸，支持 Large、Middle（默认）、Small 三种：

<StackPanel Orientation="Vertical" Spacing="10">
    <atom:NumericUpDown SizeType="Large" Value="3" />
    <atom:NumericUpDown SizeType="Middle" Value="3" />
    <atom:NumericUpDown SizeType="Small" Value="3" />
</StackPanel>

尺寸	高度	字体大小
Large	40px	InputFontSizeLG
Middle	32px	InputFontSize
Small	24px	InputFontSizeSM

---

8. 三种样式变体

通过 StyleVariant 属性设置样式变体：

<StackPanel Orientation="Vertical" Spacing="10">
    <atom:NumericUpDown Value="3" StyleVariant="Outline" />
    <atom:NumericUpDown Value="3" StyleVariant="Filled" />
    <atom:NumericUpDown Value="3" StyleVariant="Borderless" />
</StackPanel>

• Outline：标准边框样式（默认）
• Filled：灰色填充背景
• Borderless：无边框，适合嵌入其他控件内

---

9. 禁用状态

通过 IsEnabled="False" 禁用输入框，所有变体均支持：

<StackPanel Orientation="Vertical" Spacing="10">
    <atom:NumericUpDown Value="3" StyleVariant="Outline" IsEnabled="False" />
    <atom:NumericUpDown Value="3" StyleVariant="Filled" IsEnabled="False" />
    <atom:NumericUpDown Value="3" StyleVariant="Borderless" IsEnabled="False" />
</StackPanel>

禁用状态下：输入框不可编辑、步进按钮不可点击、整体使用灰色调。

---

10. 前后置标签（AddOn）

通过 LeftAddOn 和 RightAddOn 属性在输入框外部添加附加内容：

<StackPanel Orientation="Vertical" Spacing="10">
    <!-- 文字标签 -->
    <atom:NumericUpDown LeftAddOn="http://" RightAddOn=".com"
                        Width="400" Value="3" />

    <!-- 图标标签 -->
    <atom:NumericUpDown
        RightAddOn="{antdicons:AntDesignIconProvider Kind=SettingOutlined}"
        Width="400" Value="3" />

    <!-- 混合：左侧文字 + 右侧内部内容 -->
    <atom:NumericUpDown LeftAddOn="http://" InnerRightContent=".com"
                        Width="400" Value="3" />
</StackPanel>

AddOn 是输入框外部的独立区域，有独立的背景色和边框，适合显示协议前缀、域名后缀等。

---

11. 清除按钮

通过 IsAllowClear="True" 启用清除按钮：

<atom:NumericUpDown PlaceholderText="input with clear icon"
                    Width="400"
                    IsAllowClear="True" />

• 输入框非空且非只读时，右侧显示清除图标（默认 CloseCircleFilled）
• 点击清除图标将 Value 设为 null
• 可通过 ClearIcon 属性自定义图标

---

12. 内部前后置内容（Prefix / Suffix）

通过 InnerLeftContent 和 InnerRightContent 属性在输入框内部添加图标或文本：

<StackPanel Orientation="Vertical" Spacing="10">
    <!-- 图标前后缀 -->
    <atom:NumericUpDown PlaceholderText="Enter your value"
        InnerLeftContent="{antdicons:AntDesignIconProvider Kind=UserOutlined, FillBrush=#D7D7D7}"
        InnerRightContent="{antdicons:AntDesignIconProvider Kind=InfoCircleOutlined, FillBrush=#8C8C8C}" />

    <!-- 文本前后缀 -->
    <atom:NumericUpDown InnerLeftContent="￥" InnerRightContent="RMB" />

    <!-- 禁用状态下的前后缀 -->
    <atom:NumericUpDown InnerLeftContent="￥" InnerRightContent="RMB" IsEnabled="False" />
</StackPanel>

与 AddOn 的区别：InnerLeftContent / InnerRightContent 嵌入在输入框内部，没有独立背景，适合显示货币符号、单位等。

---

13. 验证状态

通过 Status 属性设置错误或警告状态，可与所有变体组合：

<StackPanel Orientation="Vertical" Spacing="10">
    <!-- Outline 变体 -->
    <atom:NumericUpDown PlaceholderText="Error" Status="Error" />
    <atom:NumericUpDown PlaceholderText="Warning" Status="Warning" />

    <!-- 带前缀图标的状态 -->
    <atom:NumericUpDown PlaceholderText="Error with prefix"
        InnerLeftContent="{antdicons:AntDesignIconProvider Kind=ClockCircleOutlined}"
        Status="Error" />
    <atom:NumericUpDown PlaceholderText="Warning with prefix"
        InnerLeftContent="{antdicons:AntDesignIconProvider Kind=ClockCircleOutlined}"
        Status="Warning" />

    <!-- Filled 变体 -->
    <atom:NumericUpDown PlaceholderText="Error" Status="Error"
        InnerLeftContent="{antdicons:AntDesignIconProvider Kind=ClockCircleOutlined}"
        StyleVariant="Filled" />
    <atom:NumericUpDown PlaceholderText="Warning" Status="Warning"
        InnerLeftContent="{antdicons:AntDesignIconProvider Kind=ClockCircleOutlined}"
        StyleVariant="Filled" />

    <!-- Borderless 变体 -->
    <atom:NumericUpDown PlaceholderText="Error" Status="Error"
        InnerLeftContent="{antdicons:AntDesignIconProvider Kind=ClockCircleOutlined}"
        StyleVariant="Borderless" />
    <atom:NumericUpDown PlaceholderText="Warning" Status="Warning"
        InnerLeftContent="{antdicons:AntDesignIconProvider Kind=ClockCircleOutlined}"
        StyleVariant="Borderless" />
</StackPanel>

验证状态通过颜色变化提供视觉反馈：

• Error：边框/底部线变为红色系（ColorError）
• Warning：边框/底部线变为黄色系（ColorWarning）

---

常见组合模式

表单中的数值输入

<atom:FormItem Label="Age" IsRequired="True">
    <atom:NumericUpDown Minimum="0" Maximum="150" Increment="1"
                        PlaceholderText="Enter age" />
</atom:FormItem>

带单位的金额输入

<atom:NumericUpDown InnerLeftContent="￥"
                    InnerRightContent="元"
                    Minimum="0"
                    Increment="0.01"
                    FormatString="N2"
                    PlaceholderText="请输入金额" />

紧凑空间中的数值输入

<atom:Space Compact="True">
    <atom:NumericUpDown Value="100" />
    <atom:NumericUpDown Value="200" />
    <atom:NumericUpDown Value="300" />
</atom:Space>

MVVM 值绑定

<atom:NumericUpDown Value="{Binding Quantity}"
                    Minimum="{Binding MinQuantity}"
                    Maximum="{Binding MaxQuantity}"
                    Increment="1" />

// ViewModel
[Reactive]
public decimal? Quantity { get; set; } = 1;
public decimal MinQuantity => 0;
public decimal MaxQuantity => 999;