syncfusion-winui-color-palette

このスキルを使用するタイミング

ユーザーが次のことを求めた場合は、すぐにこのスキルを使用します。

• WinUI アプリケーションで、スウォッチベースのカラーパレット UI を実装したい
• バリエーションの色合いとともにテーマカラーを表示したい
• 色合いのバリエーションの有無を指定して標準色を表示したい
• テーマまたは標準のカラーパレットにカスタムカラーを追加したい
• 色を追加選択するための「その他の色」ダイアログを開きたい
• 「色なし」（透明色）の選択肢が必要
• 「その他の色」ダイアログで最近使用した色を追跡したい
• SelectedBrush を使用して、選択色をプログラムから設定または取得したい
• パレットのヘッダー、ヘッダーテンプレート、または色合い間の間隔をカスタマイズしたい
• レイアウトのフロー方向や前景のスタイルを変更したい
• ユーザーが簡単に戻せる自動／既定の色を設定したい

このスキルは、グラデーションベースまたはスペクトルベースのカラーピッカーではなく、Syncfusion WinUI Color Palette コントロール（SfColorPalette）を対象としています。

コンポーネントの概要

SfColorPalette は、スウォッチベースの色選択 UI を提供する WinUI コントロールです。次の機能をサポートしています。

• テーマカラー：バリエーションの色合いを含む組み込みのパレットテーマ（Office、Yellow、Green など）
• 標準色：色合いのバリエーションを任意で指定できる、固定セットの標準色
• カスタムカラー：テーマまたは標準のパレットに独自の色を追加
• 「その他の色」ダイアログ：不透明度を調整できる色スペクトルによる追加選択
• 最近使用した色：「その他の色」ダイアログで選択した色を追跡
• 自動色：設定可能な色を使った、既定／自動色ボタン
• 色なしオプション：透明色を選択するボタン
• ツールチップのサポート：ホバー時に色名を表示
• プログラムからのアクセス：SelectedBrush を使用して選択色を取得／設定
• イベント通知：リアルタイムで変更を検出する SelectedBrushChanged

主要な名前空間：

using Syncfusion.UI.Xaml.Editors;

NuGet パッケージ：

Syncfusion.Editors.WinUI

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

SfColorPalette を使ってみる

📄 参照： references/getting-started.md

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

• インストールと NuGet パッケージのセットアップ手順
• SfColorPalette コントロールの基本的な実装
• 名前空間とアセンブリの参照
• 選択色をプログラムから取得および設定する方法
• SelectedBrushChanged イベントの処理
• 「色なし」ボタンの表示／非表示
• 最小限の設定で動作する最初の XAML + C# の例

説明するトピック：

• WinUI 3 デスクトップアプリケーションの作成
• Syncfusion.Editors.WinUI NuGet パッケージの追加
• コントロールの名前空間のインポート
• XAML と C# による基本的な初期化
• SelectedBrush プロパティ（取得／設定）
• SelectedBrushChanged イベントの処理
• ShowNoColorButton プロパティ
• ShowMoreColorsButton プロパティ
• RecentColors コレクション
• コントロール構造の概要

---

テーマカラー

📄 参照： references/theme-colors.md

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

• 組み込みのテーマパレットから色を選択する
• 実行時にアクティブなテーマパレットを切り替える
• テーマパレットにカスタムカラーを追加する
• ベースとなるテーマカラーの表示／非表示
• テーマカラーの色合いのバリエーションの表示／非表示
• テーマパレットのヘッダーテキストまたはテンプレートのカスタマイズ
• テーマパレットのヘッダーを非表示にする
• ベースカラーとそのバリエーションの間隔を調整する

説明するトピック：

• ActivePalette プロパティと使用可能な ColorPaletteNames
• PaletteColors プロパティ（ColorPaletteModel）
• PaletteColors.ShowColors — ベースとなるテーマカラーの表示／非表示
• PaletteColors.ShowColorShades — 色合いのバリエーションの表示／非表示
• PaletteColors.Colors — カスタムの ColorModel エントリの追加
• PaletteColors.Header — カスタムのヘッダーテキスト
• PaletteColors.ShowHeader — ヘッダーの表示／非表示
• PaletteColors.HeaderTemplate — カスタムのヘッダー UI
• PaletteColors.ColorShadesSpacing — バリエーション間の間隔
• テーマパレット全体を非表示にする

---

標準色

📄 参照: references/standard-colors.md

次の操作を行う場合は、このリファレンスを参照してください。

• 組み込みの標準色パネルから色を選択する
• 標準カラーパレットにカスタム色を追加する
• 標準色のバリエーションの色合いを表示または非表示にする
• 標準色パネル全体を非表示にする
• 標準パレットのヘッダーテキストまたはテンプレートをカスタマイズする
• 標準パレットのヘッダーを非表示にする
• 標準色とそのバリエーションの間隔を調整する

説明するトピック:

• StandardColors プロパティ（StandardPaletteModel）
• StandardColors.ShowColors — 標準色の表示／非表示
• StandardColors.ShowColorShades — バリエーションの色合いの表示／非表示
• StandardColors.Colors — カスタム ColorModel エントリの追加
• StandardColors.Header — カスタムヘッダーテキスト
• StandardColors.ShowHeader — ヘッダーの表示／非表示
• StandardColors.HeaderTemplate — カスタムヘッダー UI
• StandardColors.ColorShadesSpacing — バリエーションの間隔
• 標準色パネル全体を非表示にする

---

その他の色ダイアログ

📄 参照: references/more-color-dialog.md

次の操作を行う場合は、このリファレンスを参照してください。

• その他の色ボタンを有効または無効にする
• その他の色ダイアログの仕組みを理解する
• 色の選択肢を制限するため、その他の色オプションを非表示にする

説明するトピック:

• ShowMoreColorsButton プロパティ
• カラースペクトルダイアログからカスタム色を選択する
• その他の色ボタンを非表示にする

---

UI のカスタマイズ

📄 参照: references/ui-customization.md

次の操作を行う場合は、このリファレンスを参照してください。

• 選択した色をプログラムから設定または取得する
• null／透明色の値を設定する
• 自動（既定）色ボタンを設定する
• 既定の色ボタンを非表示にする
• パレットヘッダーの前景色をカスタマイズする
• フロー方向を変更する（右から左への表示に対応）
• 色項目のツールチップの動作を理解する
• 最近使用した色のパネルを操作する

説明するトピック:

• SelectedBrush プロパティ（プログラムからのアクセス）
• null／透明色の設定（Colors.Transparent）
• AutomaticBrush プロパティ — 既定の色の設定
• ShowDefaultColorButton プロパティ — 既定の色ボタンの表示／非表示
• Foreground プロパティ — ヘッダーテキストの色
• FlowDirection プロパティ — RTL 対応
• 色項目のツールチップの動作
• RecentColors コレクション — 最近使用した色

---

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

📄 参照: references/best-practices.md

次の操作を行う場合は、このリファレンスを参照してください。

• SfColorPalette と SfColorPicker の使い分けに関するガイダンスを確認する
• 一般的な実装パターンと使用例を確認する
• 色の選択や表示に関する問題をトラブルシューティングする
• エッジケースと制限事項を理解する
• アクセシビリティに関する考慮事項を確認する
• フライアウト、ダイアログ、プロパティパネルとの統合を確認する

説明するトピック:

• パレットとピッカーの使い分け
• 一般的な使用例（テーマセレクター、ドキュメントエディター、描画ツール）
• トラブルシューティングガイド
• 回避すべきエッジケース
• アクセシビリティのベストプラクティス
• 統合パターン（フライアウト、ダイアログ、プロパティパネル）

---

クイックスタートの例

SfColorPalette を使い始めるための最小限の例を紹介します。

XAML の実装

<Page
    x:Class="ColorPaletteApp.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 Padding="20">
        
        <editors:SfColorPalette 
            x:Name="colorPalette"
            ShowMoreColorsButton="True"
            ShowNoColorButton="True"
            SelectedBrushChanged="ColorPalette_SelectedBrushChanged" />
    </Grid>
</Page>

C# のコードビハインド

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

namespace ColorPaletteApp
{
    public sealed partial class MainPage : Page
    {
        public MainPage()
        {
            this.InitializeComponent();
        }

        private void ColorPalette_SelectedBrushChanged(object sender, SelectedBrushChangedEventArgs e)
        {
            var oldBrush = e.OldBrush;
            var newBrush = e.NewBrush;

            // Apply selected color to a target element
            if (newBrush is SolidColorBrush solidBrush)
            {
                targetRectangle.Fill = solidBrush;
            }
        }
    }
}

---

一般的なパターン

パターン 1：テーマと標準色を使用する基本パレット

<editors:SfColorPalette Name="colorPalette">
    <editors:SfColorPalette.PaletteColors>
        <editors:ColorPaletteModel ShowColorShades="True"/>
    </editors:SfColorPalette.PaletteColors>
    <editors:SfColorPalette.StandardColors>
        <editors:StandardPaletteModel ShowColorShades="True"/>
    </editors:SfColorPalette.StandardColors>
</editors:SfColorPalette>

パターン 2：アクティブなパレット（テーマの切り替え）

<editors:SfColorPalette ActivePalette="Yellow" Name="colorPalette" />

// Switch theme programmatically
colorPalette.ActivePalette = ColorPaletteNames.Office;

パターン 3：カスタムテーマと標準色

<editors:SfColorPalette Name="colorPalette">
    <editors:SfColorPalette.PaletteColors>
        <editors:ColorPaletteModel ShowColors="True" ShowColorShades="True" Header="Brand Colors">
            <editors:ColorPaletteModel.Colors>
                <editors:ColorCollection>
                    <editors:ColorModel Color="#FF1464A0" Tooltip="Brand Blue" />
                    <editors:ColorModel Color="#FF00A651" Tooltip="Brand Green" />
                    <editors:ColorModel Color="#FFFF6600" Tooltip="Brand Orange" />
                </editors:ColorCollection>
            </editors:ColorPaletteModel.Colors>
        </editors:ColorPaletteModel>
    </editors:SfColorPalette.PaletteColors>
</editors:SfColorPalette>

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

// Set selected color
colorPalette.SelectedBrush = new SolidColorBrush(Colors.Yellow);

// Set transparent/no color
colorPalette.SelectedBrush = new SolidColorBrush(Colors.Transparent);

// Read selected color
if (colorPalette.SelectedBrush is SolidColorBrush brush)
{
    var color = brush.Color;
}

パターン 5：すべてのオプションを有効にする

<editors:SfColorPalette 
    ShowMoreColorsButton="True"
    ShowNoColorButton="True"
    AutomaticBrush="Black"
    ShowDefaultColorButton="True"
    Name="colorPalette" />

---

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

プロパティ	型	既定値	目的
SelectedBrush	Brush	Transparent	現在選択されている色を取得または設定します
ActivePalette	ColorPaletteNames	Office	アクティブな組み込みテーマパレットを設定します
PaletteColors	ColorPaletteModel	—	テーマカラーパネルを構成します
StandardColors	StandardPaletteModel	—	標準カラーパネルを構成します
ShowMoreColorsButton	bool	true	「その他の色」ボタンの表示／非表示を切り替えます
ShowNoColorButton	bool	false	「色なし」（透明）ボタンの表示／非表示を切り替えます
AutomaticBrush	Brush	Black	既定／自動の色を設定します
ShowDefaultColorButton	bool	true	既定の色ボタンの表示／非表示を切り替えます
RecentColors	Collection	—	最近使用した色の一覧を取得します
Foreground	Brush	Black	ヘッダーテキストの前景色を設定します
FlowDirection	FlowDirection	LeftToRight	RTL／LTR のレイアウト方向を設定します

ColorPaletteModel / StandardPaletteModel のプロパティ：

プロパティ	型	既定値	目的
ShowColors	bool	true	基本色の表示／非表示を切り替えます
ShowColorShades	bool	true/false	色のバリエーションの表示／非表示を切り替えます
Colors	ColorCollection	—	カスタムカラーの項目
Header	string	"Theme Colors" / "Standard Colors"	パネルのヘッダーテキスト
ShowHeader	bool	true	ヘッダーの表示／非表示を切り替えます
HeaderTemplate	DataTemplate	—	カスタムヘッダー UI
ColorShadesSpacing	double	10	基本色と色のバリエーションの間隔

---

主なイベント

イベント	引数	目的
SelectedBrushChanged	SelectedBrushChangedEventArgs	選択色が変更されたときに発生します

イベント引数のプロパティ：

• OldBrush — 以前に選択されていたブラシ
• NewBrush — 新たに選択されたブラシ

---

一般的な使用例

1. ドキュメントエディター — フォント色や蛍光ペンの色の選択（MS Word のカラーパレットのような機能）
2. テーマカスタマイザー — ユーザーがブランドカラーやテーマカラーから選べるようにします
3. 描画／注釈ツール — ペン、蛍光ペン、図形の塗りつぶし用のカラーピッカー
4. フォームデザインツール — フォーム要素の背景色やテキスト色の選択
5. ダッシュボードビルダー — 定義済みのパレットからウィジェットに色を割り当てます

---

次のステップ

1. シンプルに始める： 基本設定については、getting-started.md をご覧ください
2. テーマカラー： theme-colors.md を使ってパレットテーマをカスタマイズします
3. 標準色： standard-colors.md を使って標準カラーパネルを構成します
4. その他の色： more-color-dialog.md を使って拡張カラー ダイアログを追加します
5. UI のカスタマイズ： ui-customization.md の視覚的なカスタマイズを適用します
6. 最適化： 本番環境に適した実装については、best-practices.md をご確認ください

---

注： このスキルでは、Syncfusion WinUI Color Palette コントロール（SfColorPalette）を扱います。グラデーション／スペクトルベースの色選択については、syncfusion-winui-colorpicker スキルをご覧ください。