syncfusion-winui-calendar

WinUI Calendar（SfCalendar）

Windows デスクトップアプリケーションで日付を選択するための Syncfusion WinUI Calendar（SfCalendar）コントロールの実装を包括的に解説します。Calendar コントロールは、単一日付、複数日付、日付範囲の選択に対応し、幅広いカスタマイズオプション、異なるビュー間の移動、日付の制限、ローカライズ機能を備えています。

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

次のような場合に、このスキルを使用してください。

• WinUI デスクトップアプリケーションで日付を選択するためのカレンダーコントロールを作成する
• 日付を選択する（単一、複数、範囲モード）
• ビュー間を移動する（月、年、10 年、100 年）
• 最小日付／最大日付や選択不可日を使用して日付を制限する
• テンプレート、特別な日付の強調表示、スタイル設定を使ってUI をカスタマイズする
• 異なるカルチャや言語に合わせてカレンダーをローカライズする
• さまざまな計算ルールで週番号を表示する
• 検証やビジネスロジックのために日付選択イベントを処理する
• キーボードナビゲーションに対応した、アクセシブルな日付ピッカーを実装する
• カレンダーの描画やデータバインディングの問題をトラブルシューティングする

コンポーネントの概要

SfCalendar は、WinUI デスクトップアプリケーション向けの主要な日付選択コントロールで、次の機能を提供します。

• 選択モード： 単一、複数、範囲、またはなし
• ビューの移動： 月、年、10 年、100 年ビュー
• 日付の制限： MinDate、MaxDate、BlackoutDates コレクション
• カスタマイズ： セルテンプレート、特別な日付の強調表示、テーマとの連携
• ローカライズ： 複数の暦の種類とカルチャに対応
• 週番号： ISO 8601 に対応した、設定可能な週番号
• キーボードサポート： 完全なキーボードナビゲーションとアクセシビリティ
• データバインディング： SelectedDate と SelectedDates のバインディングに対応し、MVVM に適しています

コントロールの構造：

• 日付セルを含む月ビュー（既定）
• 月セルを含む年ビュー
• 年セルを含む10年ビュー
• 10年単位のセルを含む100年ビュー
• ナビゲーションと現在のビューのタイトルを表示するヘッダー
• スクロール用のナビゲーションボタン

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

はじめに

📄 参照： references/getting-started.md

• WinUI 3 デスクトップアプリケーションの作成
• Syncfusion.Calendar.WinUI NuGet パッケージのインストール
• XAML で Calendar コントロールを追加する
• C# で Calendar コントロールを追加する
• 基本的な日付選択
• コントロール構造の概要

選択機能

📄 参照： references/selection.md

• 選択モード：なし、単一、複数、範囲
• SelectedDate プロパティ（単一選択）
• SelectedDates コレクション（複数／範囲選択）
• プログラムによる日付選択
• 選択変更イベント
• 選択した日付のデータバインディング

ナビゲーションと表示

📄 参照： references/navigation.md

• 表示モード：月、年、10年、100年
• ビュー間の移動
• 日付を表示範囲に含める SetDisplayDate メソッド
• Min／Max 表示モードの制限
• ビューの制限に基づく選択
• ナビゲーション方向（縦／横スクロール）

日付の制限

📄 参照： references/date-restrictions.md

• MinDate と MaxDate プロパティ
• 選択可能な日付範囲の制限
• BlackoutDates コレクション
• 特定の日付を選択対象から除外する
• 日付選択の検証
• 無効な日付のスタイル設定

ローカライズと書式設定

📄 参照： references/localization-formatting.md

• カルチャと言語のサポート
• 日付のカスタム書式設定に使用する FormatString
• 曜日名と月名の省略形
• RTL（右から左）サポート
• FlowDirection プロパティ
• 日付書式パターン

UI のカスタマイズ

📄 参照： references/customization.md

• セルテンプレート（DataTemplate）
• アイコンを使った特別な日付の強調表示
• カスタムセルスタイル
• ヘッダーのカスタマイズ
• 背景色と前景色
• 枠線と外観のカスタマイズ
• テーマとの連携

週番号

📄 参照： references/week-numbers.md

• ShowWeekNumbers プロパティ
• WeekNumberRule のオプション
• 週番号の書式設定
• FirstDay、FirstFourDayWeek、FirstFullWeek のルール
• カルチャ固有の週計算

クイックスタートの例

開始するための最小限の動作例を紹介します。

1. 名前空間を追加する

XAML：

<Window xmlns:calendar="using:Syncfusion.UI.Xaml.Calendar">

C#：

using Syncfusion.UI.Xaml.Calendar;

2. 基本的なカレンダーを作成する（XAML）

<Window
    x:Class="CalendarApp.MainWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:calendar="using:Syncfusion.UI.Xaml.Calendar">
    
    <Grid>
        <calendar:SfCalendar x:Name="sfCalendar" />
    </Grid>
</Window>

3. または、プログラムで作成する（C#）

using Syncfusion.UI.Xaml.Calendar;

namespace CalendarApp
{
    public sealed partial class MainWindow : Window
    {
        public MainWindow()
        {
            this.InitializeComponent();
            
            // Create calendar programmatically
            SfCalendar sfCalendar = new SfCalendar();
            this.Content = sfCalendar;
        }
    }
}

4. 日付を選択する（任意）

// Select today's date
sfCalendar.SelectedDate = DateTimeOffset.Now;

// Or select a specific date
sfCalendar.SelectedDate = new DateTimeOffset(new DateTime(2026, 3, 22));

一般的なパターン

パターン 1：単一の日付を選択する

<calendar:SfCalendar 
    x:Name="calendar"
    SelectionMode="Single"
    SelectedDate="{x:Bind ViewModel.SelectedDate, Mode=TwoWay}" />

// Access selected date
DateTimeOffset? selected = calendar.SelectedDate;

パターン 2：複数の日付を選択する

<calendar:SfCalendar 
    x:Name="calendar"
    SelectionMode="Multiple"
    SelectedDates="{x:Bind ViewModel.SelectedDates, Mode=TwoWay}" />

// Access multiple selected dates
DateTimeOffsetCollection selectedDates = calendar.SelectedDates;

パターン 3：日付範囲を選択する

<calendar:SfCalendar 
    x:Name="calendar"
    SelectionMode="Range" />

パターン 4：日付範囲を制限する

<calendar:SfCalendar 
    x:Name="calendar"
    MinDate="2026-01-01"
    MaxDate="2026-12-31" />

// Set date restrictions in code
calendar.MinDate = new DateTimeOffset(new DateTime(2026, 1, 1));
calendar.MaxDate = new DateTimeOffset(new DateTime(2026, 12, 31));

パターン 5：特定の日付を選択不可にする

// Create blackout dates collection
DateTimeOffsetCollection blackoutDates = new DateTimeOffsetCollection();
blackoutDates.Add(new DateTimeOffset(new DateTime(2026, 3, 25))); // Holiday
blackoutDates.Add(new DateTimeOffset(new DateTime(2026, 12, 25))); // Christmas

calendar.BlackoutDates = blackoutDates;

パターン 6：特定の月に移動する

// Navigate to a specific date's month
calendar.SetDisplayDate(new DateTimeOffset(new DateTime(2026, 6, 15)));

パターン 7：年表示での移動に制限する

<calendar:SfCalendar 
    x:Name="calendar"
    MinDisplayMode="Month"
    MaxDisplayMode="Year" />

パターン 8：ViewModel のデータバインディング

public class CalendarViewModel : INotifyPropertyChanged
{
    private DateTimeOffset? selectedDate;
    
    public DateTimeOffset? SelectedDate
    {
        get => selectedDate;
        set
        {
            selectedDate = value;
            OnPropertyChanged(nameof(SelectedDate));
        }
    }
    
    public event PropertyChangedEventHandler PropertyChanged;
    
    protected void OnPropertyChanged(string propertyName)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

<calendar:SfCalendar 
    SelectedDate="{x:Bind ViewModel.SelectedDate, Mode=TwoWay}" />

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

選択プロパティ

プロパティ	型	説明
SelectedDate	DateTimeOffset?	選択した日付を取得または設定します（単一選択モード）。
SelectedDates	DateTimeOffsetCollection	選択した日付のコレクションを取得または設定します（複数選択／範囲選択モード）。
SelectedRange	DateTimeOffsetRange	SelectionMode が Range の場合に、選択した日付範囲を取得します。
SelectionMode	CalendarSelectionMode	日付の選択モード：None、Single、Multiple、Range
SelectionHighlightMode	SelectionHighlightMode	選択した日付の強調表示スタイル：Outline、Filled
SelectionShape	SelectionShape	選択インジケーターの形状：Circle、Rectangle

日付の制限プロパティ

プロパティ	型	説明
MinDate	DateTimeOffset	選択可能な最小日付（既定値：1/1/1920）
MaxDate	DateTimeOffset	選択可能な最大日付（既定値：12/31/2120）
BlackoutDates	DateTimeOffsetCollection	選択できない（ブロックされた）日付のコレクション

表示と移動のプロパティ

プロパティ	型	説明
DisplayMode	CalendarDisplayMode	現在の表示：Month、Year、Decade、Century
MinDisplayMode	CalendarDisplayMode	ユーザーが移動できる最小の表示レベル
MaxDisplayMode	CalendarDisplayMode	ユーザーが移動できる最大の表示レベル
NavigationDirection	CalendarNavigationDirection	表示内でのスクロール方向：Vertical、Horizontal
OutOfScopeVisibility	OutOfScopeVisibility	隣接する月の日付の表示／非表示：Enabled、Hidden
HeaderInfo	object	カレンダーのカスタムヘッダーコンテンツ

ローカライズと書式設定のプロパティ

プロパティ	型	説明
CalendarIdentifier	string	カレンダーシステムの種類：GregorianCalendar、HijriCalendar、HebrewCalendar など
FirstDayOfWeek	FirstDayOfWeek	週の初日：Sunday、Monday、Tuesday など
DayFormat	string	日付の数字の書式パターン（例：「{day.integer(2)}」）
MonthFormat	string	月名の書式パターン（例：「{month.full}」）
DayOfWeekFormat	string	曜日ヘッダーの書式パターン（例：「{dayofweek.abbreviated(3)}」）
MonthHeaderFormat	string	月／年ヘッダーの書式パターン（例：「{month.full} {year.full}」）
NumberOfWeeksInView	int	月表示で表示する週の行数（既定値：6）

週番号のプロパティ

プロパティ	型	説明
ShowWeekNumbers	bool	週番号の列を表示します（既定値：false）
WeekNumberRule	CalendarWeekRule	週の計算ルール：FirstDay、FirstFourDayWeek、FirstFullWeek
WeekNumberFormat	string	週番号の書式（プレースホルダーとして # を使用します。例：「W #」）

一般的な使用例

イベントスケジュールアプリケーション

ユーザーが予約、会議、リマインダー用の日付を1日単位で選択できるインターフェースを作成します。選択可能な日付を未来の日付に制限したり、営業日のみを表示したりできます。

休暇申請システム

複数の日付選択、会社の休日を選択不可にする設定、連続した休暇日を選択する範囲選択に対応した休暇管理システムを構築します。

予約カレンダー

日付の空き状況を動的に表示し、予約できない日付を選択不可に設定したうえで、ItemPrepared イベントを通じて空き状況をリアルタイムで確認できる予約システムを実装します。

国際対応の日付ピッカー

ヒジュラ暦、ヘブライ暦、ペルシャ暦など、異なる暦に対応したローカライズ済みカレンダー、右から左に記述する言語、文化ごとの書式設定をサポートする多言語アプリケーションを開発します。

日付範囲によるフィルタリング

レポート、分析ダッシュボード、取引の検索で使う日付範囲をユーザーが選択できるデータフィルタリングインターフェースを作成し、最小日付と最大日付を設定します。

クレジットカードの有効期限セレクター

年表示と10年単位の表示のみに移動を制限し、クレジットカードの有効期限を月と年だけで選択できるようにします。

---

次のステップ： 実装する内容に応じて、上記のリファレンスドキュメントをお読みください。まずは初期設定のために getting-started.md を読み、その後、必要に応じて各機能の詳細をご確認ください。