syncfusion-winui-color-picker

Syncfusion WinUI Color Picker（SfColorPicker）の実装

このスキルを使うタイミング

ユーザーが次のような要望を示したら、直ちにこのスキルを使ってください。

• WinUI アプリケーションにカラーピッカー UI を実装したい
• 複数のカラーモデル（RGB、HSV、HSL、CMYK）を使って単色を選択したい
• グラデーションブラシ（線形または放射状）を作成したい
• カラースペクトルの形状（ボックスまたはリング）をカスタマイズしたい
• アルファ値／不透明度を制御して色を編集したい
• 単色モードとグラデーションブラシモードを切り替えたい
• 16 進数形式のカラー入力／出力が必要
• 色の選択変更イベントを処理したい
• カラーチャンネルの入力オプション（スライダー、テキスト入力）をカスタマイズしたい
• プログラムからカラーブラシを選択したい

このスキルは、一般的なカラーピッカーソリューションではなく、Syncfusion WinUI Color Picker（SfColorPicker）コントロール専用です。

コンポーネントの概要

SfColorPicker は、色の値を選択、調整するための WinUI コントロールです。次の機能をサポートします。

• 単色：16 進数エディターを備えた RGB、HSV、HSL、CMYK カラーモデル
• グラデーションブラシ：複数の停止点を持つ線形および放射状のグラデーションカラーブラシ
• カラースペクトル：ボックスまたはリング形状でインタラクティブに色を選択
• 不透明度の制御：スライダーとテキスト入力によるアルファチャンネルの調整
• モードの切り替え：単色モードとグラデーションモードを動的に切り替え
• イベント通知：リアルタイムの色選択変更イベント

主要な名前空間：

using Syncfusion.UI.Xaml.Editors;

NuGet パッケージ：

Syncfusion.Editors.WinUI

---

ドキュメントとナビゲーションガイド

SfColorPicker を使い始める

📄 参照： references/getting-started.md

次の情報が必要な場合は、このリファレンスを参照してください。

• インストールおよび NuGet パッケージのセットアップ手順
• SfColorPicker コントロールの基本的な実装
• 名前空間とアセンブリの参照
• イベント処理を含む、最初に動作する XAML + C# の例
• コントロールの構造の理解と、セットアップ問題のトラブルシューティング

対象トピック：

• WinUI 3 デスクトップアプリケーションの作成
• Syncfusion.Editors.WinUI NuGet パッケージの追加
• コントロールの名前空間のインポート
• 基本的な XAML と C# の初期化
• コントロール構造の概要
• 一般的な初期設定

---

単色の選択

📄 参照： references/solid-color-selection.md

次の情報が必要な場合は、このリファレンスを参照してください。

• プログラムまたはインタラクティブな操作による単色ブラシの選択
• さまざまなカラーモデル（RGB、HSV、HSL、CMYK）の使用
• 実行時のカラーチャンネルの切り替え
• 16 進数形式のカラー入力／出力の実装
• 不透明度／アルファ値の制御
• カラーチャンネルの入力オプション（スライダーまたはテキスト）をカスタマイズ
• 単色の選択変更イベントの処理

対象トピック：

• プログラムおよびインタラクティブな選択に使う SelectedBrush プロパティ
• 使用例を含む ColorChannelOptions（RGB、HSV、HSL、CMYK）
• 単色モードのみに制限する BrushTypeOptions
• 不透明度を制御する AlphaInputOptions（All、TextInput、SliderInput）
• 16 進数エディターの表示を制御する IsHexInputVisible
• ColorChannelInputOptions（TextInput、SliderInput、All）
• ColorEditorsVisibilityMode（Inline、Expandable、Collapsed）
• SelectedBrushChanged イベントの処理

---

グラデーションの色選択

📄 参照： references/gradient-color-selection.md

次の内容が必要な場合は、このリファレンスを参照してください：

• 複数のカラーストップを使用した線形グラデーションブラシの作成
• グラデーションの原点と中心を指定した放射状グラデーションブラシの作成
• プログラムによるグラデーションブラシの構成
• 実行時のインタラクティブなグラデーション編集
• グラデーションの角度と方向の調整
• グラデーションのオフセット（開始点／終了点、半径）の変更
• グラデーションの不透明度の制御
• グラデーションの色変更イベントの処理

扱うトピック：

• GradientStop、StartPoint、EndPoint を使用した LinearGradientBrush
• GradientOrigin、Center、RadiusX、RadiusY を使用した RadialGradientBrush
• BrushTypeOptions によるインタラクティブなグラデーションの作成
• AxisInputOption — シンプル（角度／方向）と詳細（精密なエディター）
• グラデーションストップの追加、削除、並べ替え
• グラデーションの不透明度の制御
• グラデーションブラシの SelectedBrushChanged イベント

---

UI のカスタマイズとモード

📄 参照： references/ui-customization.md

次の内容が必要な場合は、このリファレンスを参照してください：

• 単色、線形、放射状のブラシモードの切り替え
• 特定のブラシタイプの有効化または制限
• 色スペクトルの形状（ボックスまたはリング）の変更
• 色スペクトルの構成要素（色相、彩度、明度）のカスタマイズ
• BrushTypeOptions の組み合わせの理解
• 実行時にブラシモードを切り替えたときの動作

扱うトピック：

• BrushTypeOptions の構成（SolidColorBrush、LinearGradientBrush、RadialGradientBrush、All）
• インタラクティブなブラシモードのドロップダウンの動作
• ColorSpectrumShape（ボックスとリング）と用途の指針
• ColorSpectrumComponents（SaturationValue、HueSaturation、HueValue など）
• アプリの種類に応じた一般的なカスタマイズパターン

---

ベストプラクティスとトラブルシューティング

📄 参照： references/best-practices.md

次の内容が必要な場合は、このリファレンスを参照してください：

• 単色とグラデーションカラーの使い分けに関する指針
• グラデーションのパフォーマンス最適化のヒント
• 一般的なユースケースの実装パターン
• 色の選択やレンダリングに関する問題のトラブルシューティング
• アクセシビリティに関する考慮事項
• 統合パターン（フライアウト、ダイアログ、プロパティパネル）

扱うトピック：

• 単色とグラデーションの選択マトリックス
• パフォーマンスのヒント：グラデーションストップ数の制限、ブラシのキャッシュ、イベントのデバウンス
• 一般的なユースケース：テーマピッカー、描画ツール、テキストハイライト、背景エディター
• フライアウト、ダイアログ、プロパティパネルの統合パターン
• よくある間違い（ブラシタイプの不一致、null チェックの不足）
• アクセシビリティ：キーボードナビゲーション、ARIA 属性、スクリーンリーダーのサポート

---

クイックスタートの例

XAML

<Page
    x:Class="ColorPickerApp.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:editors="using:Syncfusion.UI.Xaml.Editors">

    <Grid>
        <editors:SfColorPicker
            x:Name="colorPicker"
            SelectedBrush="Blue"
            BrushTypeOptions="All"
            SelectedBrushChanged="ColorPicker_SelectedBrushChanged" />
    </Grid>
</Page>

C# コードビハインド

using Syncfusion.UI.Xaml.Editors;
using Microsoft.UI.Xaml.Media;

private void ColorPicker_SelectedBrushChanged(object sender, SelectedBrushChangedEventArgs args)
{
    if (args?.NewBrush is SolidColorBrush solidBrush)
    {
        var color = solidBrush.Color; // Access R, G, B, A
    }
    else if (args?.NewBrush is LinearGradientBrush linearBrush)
    {
        var stops = linearBrush.GradientStops;
    }
    else if (args?.NewBrush is RadialGradientBrush radialBrush)
    {
        var stops = radialBrush.GradientStops;
    }
}

---

一般的なパターン

パターン 1：単色のカラーピッカーのみ

<editors:SfColorPicker
    BrushTypeOptions="SolidColorBrush"
    ColorChannelOptions="RGB"
    IsHexInputVisible="True" />

パターン 2：グラデーションエディターのみ

<editors:SfColorPicker
    BrushTypeOptions="LinearGradientBrush,RadialGradientBrush"
    AxisInputOption="Simple" />

パターン 3：プログラムによる色選択

// Solid color
colorPicker.SelectedBrush = new SolidColorBrush(Colors.Red);

// Linear gradient
var linearGradient = new LinearGradientBrush();
linearGradient.StartPoint = new Point(0, 0);
linearGradient.EndPoint = new Point(1, 1);
linearGradient.GradientStops.Add(new GradientStop() { Color = Colors.Yellow, Offset = 0.0 });
linearGradient.GradientStops.Add(new GradientStop() { Color = Colors.Red, Offset = 1.0 });
colorPicker.SelectedBrush = linearGradient;

パターン 4：カスタムスペクトル形状

<editors:SfColorPicker
    ColorSpectrumShape="Ring"
    ColorSpectrumComponents="HueSaturation" />

---

主なプロパティのリファレンス

プロパティ	型	デフォルト	用途
SelectedBrush	Brush	Blue	選択された色ブラシを取得／設定します
BrushTypeOptions	BrushTypeOptions	All	特定のブラシモード（Solid、Linear、Radial）を有効にします
ColorChannelOptions	ColorChannelOptions	RGB	カラーモデル（RGB、HSV、HSL、CMYK）を設定します
ColorSpectrumShape	ColorSpectrumShape	Box	スペクトルの形状（Box または Ring）を設定します
ColorSpectrumComponents	ColorSpectrumComponents	SaturationValue	スペクトルの軸を定義します
AlphaInputOptions	ColorInputOptions	All	アルファ／不透明度入力の表示を制御します
IsHexInputVisible	bool	true	16 進数エディターの表示／非表示を切り替えます
ColorChannelInputOptions	ColorInputOptions	All	チャネル入力の種類（Slider／Text／All）を制御します
ColorEditorsVisibilityMode	ColorEditorsVisibilityMode	Inline	エディターの表示方法（Inline／Expandable／Collapsed）を設定します
AxisInputOption	AxisInputOption	Simple	グラデーション軸入力の複雑さを制御します

主なイベント

イベント	引数	用途
SelectedBrushChanged	SelectedBrushChangedEventArgs	選択されたブラシが変更されたときに発生します

イベント引数： OldBrush（変更前の選択） · NewBrush（新しい選択）

---

よくある使用例

1. テーマカラーセレクター — アプリのテーマカラーをユーザーがカスタマイズできるようにします
2. 描画ツール — グラフィック／描画アプリケーションで色を選択します
3. スタイルエディター — デザインツールで UI 要素の色をカスタマイズします
4. グラデーション背景エディター — グラデーション背景や視覚効果を作成します
5. カラーパレットマネージャー — クリエイティブアプリケーションでカラーパレットを管理します