颜色选取器Color picker

颜色选取器用于浏览和选择颜色。A color picker is used to browse through and select colors. 默认情况下,它使用户可以在色谱上浏览颜色,或在红-绿-蓝 (RGB)、色调饱和度值 (HSV) 或十六进制文本框中指定颜色。By default, it lets a user navigate through colors on a color spectrum, or specify a color in either Red-Green-Blue (RGB), Hue-Saturation-Value (HSV), or Hexadecimal textboxes.


获取 Windows UI 库Get the Windows UI Library

WinUI 徽标

ColorPicker 控件作为 Windows UI 库的一部分提供,该库是一个 Nuget 包,其中包含用于 Windows 应用的新控件和 UI 功能。The ColorPicker control is included as part of the Windows UI Library, a NuGet package that contains new controls and UI features for Windows apps. 有关详细信息(包括安装说明),请参阅 Windows UI 库For more info, including installation instructions, see Windows UI Library.

Windows UI 库 API: ColorPicker 类Color 属性ColorChanged 事件Windows UI Library APIs: ColorPicker class, Color property, ColorChanged event

平台 API: ColorPicker 类Color 属性ColorChanged 事件Platform APIs: ColorPicker class, Color property, ColorChanged event

这是正确的控件吗?Is this the right control?

使用颜色选取器可使用户可以应用中选择颜色。Use the color picker to let a user select colors in your app. 例如,使用它可更改颜色设置,如字体颜色、背景或应用主题颜色。For example, use it to change color settings, such as font colors, background, or app theme colors.

如果应用是用于绘图或使用触笔的类似任务,请考虑使用墨迹书写控件以及颜色选取器。If your app is for drawing or similar tasks using pen, consider using Inking controls along with the color picker.


XAML 控件库XAML Controls Gallery
XAML controls gallery

如果已安装 XAML 控件库应用,请单击此处打开此应用,了解 ColorPicker 的实际应用If you have the XAML Controls Gallery app installed, click here to open the app and see the ColorPicker in action.

创建颜色选取器Create a color picker

此示例演示如何在 XAML 中创建默认颜色选取器。This example shows how to create a default color picker in XAML.

<ColorPicker x:Name="myColorPicker"/>

默认情况下,颜色选取器在色谱旁的矩形栏中显示所选颜色的预览。By default, the color picker shows a preview of the chosen color on the rectangular bar beside the color spectrum. 可以使用 ColorChanged 事件或 Color 属性访问所选颜色并在应用中使用它。You can use either the ColorChanged event or the Color property to access the selected color and use it in your app. 有关详细代码,请参阅下面的示例。See the following examples for detailed code.

绑定到所选颜色Bind to the chosen color

当颜色选择应立即生效时,可以使用数据绑定绑定到 Color 属性,或处理 ColorChanged 事件以在代码中访问所选颜色。When the color selection should take effect immediately, you can either use databinding to bind to the Color property, or handle the ColorChanged event to access the selected color in your code.

在此示例中,会将用作 Rectangle 的 Fill 的 SolidColorBrush 的 Color 属性直接绑定到颜色选取器的所选颜色。In this example, you bind the Color property of a SolidColorBrush that's used as the Fill for a Rectangle directly to the color picker's selected color. 对颜色选取器进行的任何更改都会导致绑定属性发生实时更改。Any change to the color picker results in a live change to the bound property.

<ColorPicker x:Name="myColorPicker"

<Rectangle Height="50" Width="50">
        <SolidColorBrush Color="{x:Bind myColorPicker.Color, Mode=OneWay}"/>

此示例使用只带有圆形和滑块的简化颜色选取器,这是常用的“非正式”颜色选取体验。This example uses a simplified color picker with just the circle and the slider, which is a common "casual" color picking experience. 当颜色更改可以进行显示并在受影响对象上实时发生时,无需显示颜色预览栏。When the color change can be seen and happens in real-time on the affected object, you don't need to show the color preview bar. 有关详细信息,请参阅自定义颜色选取器部分。See the Customize the color picker section for more info.

保存所选颜色Save the chosen color

在某些情况下,你不想立即应用颜色更改。In some cases, you don't want to apply the color change immediately. 例如,在浮出控件中承载颜色选取器时,建议仅在用户确认选择或关闭浮出控件之后,才应用所选颜色。For example, when you host a color picker in a flyout, we recomend that you apply the selected color only after the user confirms the selection or closes the flyout. 还可以保存所选颜色值以供将来使用。You can also save the selected color value to use later.

在此示例中,在具有“确认”和“取消”按钮的浮出控件中承载颜色选取器。In this example, you host a color picker in a Flyout with Confirm and Cancel buttons. 当用户确认其颜色选择时,保存所选颜色以便将来在应用中使用。When the user confirms their color choice, you save the selected color to use later in your app.

    <Flyout x:Key="myColorPickerFlyout">
            <ColorPicker x:Name="myColorPicker"

            <Grid RelativePanel.Below="myColorPicker"
                <Button Content="OK" Click="confirmColor_Click"
                        Margin="0,12,2,0" HorizontalAlignment="Stretch"/>
                <Button Content="Cancel" Click="cancelColor_Click"
                        Margin="2,12,0,0" HorizontalAlignment="Stretch"

<Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
    <Button x:Name="colorPickerButton"
            Content="Pick a color"
            Flyout="{StaticResource myColorPickerFlyout}"/>
private Color mycolor;

private void confirmColor_Click(object sender, RoutedEventArgs e)
    // Assign the selected color to a variable to use outside the popup.
    myColor = myColorPicker.Color;

    // Close the Flyout.

private void cancelColor_Click(object sender, RoutedEventArgs e)
    // Close the Flyout.

配置颜色选取器Configure the color picker

使用户可以选取颜色并不一定需要所有字段,因此颜色选取器十分灵活。Not all fields are necessary to let a user pick a color, so the color picker is flexible. 它提供了各种选项,使你可以配置控件以符合需求。It provides a variety of options that let you configure the control to fit your needs.

例如,当用户无需精确控制时(如在笔记应用中选取荧光笔颜色),则可以使用简化 UI。For example, when the user doesn't need precise control, like picking a highlighter color in a note taking app, you can use a simplified UI. 可以隐藏文本输入字段,并将色谱更改为圆形。You can hide the text entry fields and change the color spectrum to a circle.

当用户需要精确控制时(如在图形设计应用中),可以为颜色的每个方面都显示滑块和文本输入字段。When the user does need precise control, like in a graphic design app, you can show both sliders and text entry fields for each aspect of the color.

显示圆形色谱Show the circle spectrum

此示例演示如何使用 ColorSpectrumShape 属性将颜色选取器配置为使用圆形色谱而不是默认的正方形。This example shows how to use the ColorSpectrumShape property to configure the color picker to use a circular spectrum instead of the default square.

<ColorPicker x:Name="myColorPicker"


必须在正方形与圆形色谱之间进行选择时,一个主要考虑因素是准确性。When you must choose between the square and circle color spectrum, a primary consideration is accuracy. 用户在使用正方形选择特定颜色时会拥有更多控制权,因为会显示更多色域。A user has more control when they select a specific color using a square because more of the color gamut is shown. 应将圆形色谱视为更多“非正式”颜色选择体验。You should consider the circle spectrum as more of the "casual" color choosing experience.

显示 alpha 通道Show the alpha channel

在此示例中,会在颜色选取器上启用不透明度滑块和文本框。In this example, you enable an opacity slider and textbox on the color picker.

<ColorPicker x:Name="myColorPicker"

IsAlphaEnabled 设置为 true 的颜色选取器

显示简单选取器Show a simple picker

此示例演示如何配置具有简单 UI 的颜色选取器以进行“非正式”使用。This example shows how to configure the color picker with a simple UI for "casual" use. 会显示圆形色谱并隐藏默认文本输入框。You show the circular spectrum and hide the default text input boxes. 当颜色更改可以进行显示并在受影响对象上实时发生时,无需显示颜色预览栏。When the color change can be seen and happens in real-time on the affected object, you don't need to show the color preview bar. 否则,应让颜色预览保持可见。Otherwise, you should leave the color preview visible.

<ColorPicker x:Name="myColorPicker"


显示或隐藏其他功能Show or hide additional features

下表显示可以用于配置 ColorPicker 控件的所有选项。This table shows all the options you can use to configure the ColorPicker control.

功能Feature “属性”Properties
色谱Color spectrum IsColorSpectrumVisible、ColorSpectrumShape、ColorSpectrumComponentsIsColorSpectrumVisible, ColorSpectrumShape, ColorSpectrumComponents
颜色预览Color preview IsColorPreviewVisibleIsColorPreviewVisible
颜色值Color values IsColorSliderVisible、IsColorChannelTextInputVisibleIsColorSliderVisible, IsColorChannelTextInputVisible
不透明度值Opacity values IsAlphaEnabled、IsAlphaSliderVisible、IsAlphaTextInputVisibleIsAlphaEnabled, IsAlphaSliderVisible, IsAlphaTextInputVisible
十六进制值Hex values IsHexInputVisibleIsHexInputVisible


IsAlphaEnabled 必须为 true,才能显示不透明度文本框和滑块。IsAlphaEnabled must be true in order to show the opacity textbox and slider. 随后可以使用 IsAlphaTextInputVisible 和 IsAlphaSliderVisible 属性修改输入控件的可见性。The visibility of the input controls can then be modified using IsAlphaTextInputVisible and IsAlphaSliderVisible properties. 有关详细信息,请参阅 API 文档。See the API documentation for details.

应做事项和禁止事项Do's and Don'ts

  • 考虑适合于应用的颜色选取体验的类型。Do think about what kind of color picking experience is appropriate for your app. 某些方案可能无需精细的颜色选取,可受益于简化选取器Some scenarios may not require granular color picking and would benefit from a simplified picker
  • 若要获得最准确的颜色选取体验,请使用正方形色谱并确保它至少是 256x256 像素,或是包含文本输入字段以便让用户可以优化其所选颜色。For the most accurate color picking experience, use the square spectrum and ensure it is at least 256x256px, or include the text input fields to let users refine their selected color.
  • 在浮出控件中使用时,在色谱中点击或单独调整滑块不应提交颜色选择。When used in a flyout, tapping in the spectrum or adjusting the slider alone should not commit the color selection. 若要提交选择,请执行以下操作:To commit the selection:
    • 提供提交和取消按钮以应用或取消选择。Provide commit and cancel buttons to apply or cancel the selection. 点击后退按钮或在浮出控件外部点击会清除它,而不保存用户选择。Hitting the back button or tapping outside of the flyout will dismiss it, and not save the user's selection.
    • 或者,通过在浮出控件外部点击或点击后退按钮,在清除浮出控件时提交选择。Or, commit the selection upon dismissing the flyout, by either tapping outside of the flyout or hitting the back button.

获取示例代码Get the sample code