syncfusion-winforms-datetimepicker

Windows Forms DateTime エディター（SfDateTimeEdit）

Syncfusion Windows Forms の SfDateTimeEdit コントロールを使用すると、最小値と最大値の検証、ウォーターマーク、カスタムパターン、グローバル化に対応したテキスト形式またはマスク形式で、ユーザーが DateTime 値を編集できます。

このスキルを使用する場面

次のような場合に、このスキルを使用します。

• 日付と時刻の値を編集するとき（書式設定された入力と検証に対応）
• フォーム、予定、スケジュール管理アプリケーション向けに日付ピッカーを実装するとき
• 最小日付と最大日付の制約で日付範囲を制限するとき
• さまざまな形式で日付を表示するとき（長い日付、短い日付、時刻、カスタムパターン）
• フィールドごとの移動と上下ボタンに対応したマスクモード編集をサポートするとき
• ウォーターマークテキストを表示してnull 許容の日付を処理するとき
• カスタムエラーメッセージで日付入力を検証するとき
• 複数のカルチャとグローバル化の要件に対応するとき
• 国際的なアプリケーション向けに、日付編集でRTL（右から左）を実装するとき
• 予定管理ツールや日付ベースのフィルターインターフェイスを作成するとき

コンポーネントの概要

主な機能：

• 編集モード： デフォルト（テキスト）とマスク（書式設定されたフィールド間の移動）
• 日付範囲の検証： MinDateTime および MaxDateTime プロパティ
• 表示パターン： LongDate、ShortDate、LongTime、ShortTime、FullDateTime、MonthDay、YearMonth、Custom
• null 許容の日付： ウォーターマークテキストに対応した AllowNull
• 検証： エラーメッセージを含む組み込みの検証機能
• グローバル化： カルチャベースの書式設定とパターン
• 移動： フィールド間の移動に使用する Tab、矢印キー、上下ボタン
• 外観： テーマ、フォント、色、境界線、カレンダーのドロップダウン

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

はじめに

📄 参照： references/getting-started.md

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

• NuGet またはデザイナーから SfDateTimeEdit をインストールする
• Windows Forms プロジェクトにコントロールを追加する
• SfDateTimeEdit のインスタンスをプログラムで作成する
• 基本的な Value プロパティを設定する
• 初期の日付時刻ピッカーの設定を構成する
• アセンブリの要件を確認する

日付範囲と値

📄 参照： references/date-range-value.md

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

• Value プロパティを設定および取得する
• MinDateTime および MaxDateTime の制約を実装する
• AllowNull を使用して null 許容の日付を有効にする
• テキストベースの値に DateTimeText プロパティを使用する
• 値変更イベントを処理する
• 日付範囲の制限を検証する

表示パターン

📄 参照： references/display-patterns.md

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

• DateTimePattern（LongDate、ShortDate、LongTime など）を設定する
• Format プロパティを使用してカスタム表示形式を作成する
• 異なる形式で日付を表示する
• カルチャ固有の日付書式設定を行う
• 月と年のみを表示する
• 時刻のみを表示する

編集モード

📄 参照： references/editing-modes.md

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

• デフォルトモードとマスク編集モードを切り替える
• フィールドごとの移動を有効にする
• ShowUpDown ボタンを構成する
• キーボードショートカットを実装する
• Tab キーと矢印キーによる移動を処理する
• 日付フィールドの値を増減する

外観とスタイル設定

📄 参照： references/appearance-styling.md

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

• Style と ThemeName を使用してテーマを適用する
• フォント、色、境界線をカスタマイズする
• カレンダーのドロップダウンの外観を構成する
• ドロップダウンボタンを表示または非表示にする
• コントロールのサイズとレイアウトを設定する
• ツールチップを追加する

検証と機能

📄 参照： references/validation-features.md

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

• 検証モードを構成する
• ValidationCompleted イベントを処理する
• 検証エラーメッセージを表示する
• null 値に対してウォーターマークテキストを設定する
• グローバル化とカルチャのサポートを実装する
• RTL（右から左）モードを有効にする
• ReadOnly モードを設定する

クイックスタート

基本的な DateTime ピッカー

using Syncfusion.WinForms.Input;

// Create datetime editor
SfDateTimeEdit dateTimeEdit = new SfDateTimeEdit();
dateTimeEdit.Location = new Point(20, 20);
dateTimeEdit.Size = new Size(200, 30);
dateTimeEdit.Value = DateTime.Now;

// Add to form
this.Controls.Add(dateTimeEdit);

VB.NET：

Imports Syncfusion.WinForms.Input

' Create datetime editor
Dim dateTimeEdit As New SfDateTimeEdit()
dateTimeEdit.Location = New Point(20, 20)
dateTimeEdit.Size = New Size(200, 30)
dateTimeEdit.Value = DateTime.Now

' Add to form
Me.Controls.Add(dateTimeEdit)

よく使われるパターン

パターン 1：範囲制限付きの日付ピッカー

// Appointment date picker (next 30 days only)
SfDateTimeEdit appointmentDate = new SfDateTimeEdit();
appointmentDate.Value = DateTime.Now;
appointmentDate.MinDateTime = DateTime.Now;
appointmentDate.MaxDateTime = DateTime.Now.AddDays(30);
appointmentDate.DateTimePattern = DateTimePattern.LongDate;

this.Controls.Add(appointmentDate);

パターン 2：時刻のみのピッカー

// Time selection control
SfDateTimeEdit timePicker = new SfDateTimeEdit();
timePicker.Value = DateTime.Now;
timePicker.DateTimePattern = DateTimePattern.LongTime;
timePicker.DateTimeEditingMode = DateTimeEditingMode.Mask;
timePicker.ShowUpDown = true;

this.Controls.Add(timePicker);

パターン 3：カスタム書式の日付エディター

// Custom format: "DD-MMM-YYYY" (e.g., "25-Dec-2024")
SfDateTimeEdit customDate = new SfDateTimeEdit();
customDate.Value = DateTime.Now;
customDate.DateTimePattern = DateTimePattern.Custom;
customDate.Format = "dd-MMM-yyyy";

this.Controls.Add(customDate);

パターン 4：ウォーターマーク付きの null 許容日付

// Optional date field with watermark
SfDateTimeEdit optionalDate = new SfDateTimeEdit();
optionalDate.DateTimeEditingMode = DateTimeEditingMode.Mask;
optionalDate.AllowNull = true;
optionalDate.Value = null;
optionalDate.Watermark = "Select a date...";

this.Controls.Add(optionalDate);

パターン 5：上下ボタン付きのマスクモード

// Field-by-field editing with increment/decrement
SfDateTimeEdit maskEditor = new SfDateTimeEdit();
maskEditor.Value = DateTime.Now;
maskEditor.DateTimeEditingMode = DateTimeEditingMode.Mask;
maskEditor.ShowUpDown = true;
maskEditor.DateTimePattern = DateTimePattern.ShortDate;

this.Controls.Add(maskEditor);

パターン 6：日付範囲フィルター

// Date range for filtering (From/To dates)
SfDateTimeEdit fromDate = new SfDateTimeEdit();
fromDate.Value = DateTime.Now.AddDays(-30);
fromDate.DateTimePattern = DateTimePattern.ShortDate;

SfDateTimeEdit toDate = new SfDateTimeEdit();
toDate.Value = DateTime.Now;
toDate.DateTimePattern = DateTimePattern.ShortDate;
toDate.MinDateTime = fromDate.Value.Value;

// Update toDate minimum when fromDate changes
fromDate.ValueChanged += (s, e) => {
    if (fromDate.Value.HasValue)
        toDate.MinDateTime = fromDate.Value.Value;
};

this.Controls.Add(fromDate);
this.Controls.Add(toDate);

パターン 7：検証付きの日付入力

// Date entry with validation
SfDateTimeEdit validatedDate = new SfDateTimeEdit();
validatedDate.Value = DateTime.Now;
validatedDate.MinDateTime = new DateTime(2020, 1, 1);
validatedDate.MaxDateTime = new DateTime(2030, 12, 31);

validatedDate.ValidationCompleted += (s, e) => {
    if (!e.IsValid)
    {
        MessageBox.Show($"Invalid date: {e.ErrorMessage}");
    }
};

this.Controls.Add(validatedDate);

主なプロパティ

プロパティ	型	説明
Value	DateTime?	現在の日付と時刻の値（null 許容）
MinDateTime	DateTime	許可される最小の日付と時刻
MaxDateTime	DateTime	許可される最大の日付と時刻
DateTimePattern	DateTimePattern	表示形式（LongDate、ShortDate、LongTime など）
Format	string	カスタムの日付と時刻の書式文字列
DateTimeEditingMode	DateTimeEditingMode	編集モード（Default または Mask）
AllowNull	bool	null 値のサポートを有効にします
Watermark	string	値が null のときに表示するテキスト
ShowUpDown	bool	マスクモードで上下ボタンを表示します
DateTimeText	string	テキスト文字列としての日付と時刻
ValidationErrorMessage	string	カスタムの検証エラーメッセージ
Style	SfDateTimeEditStyle	外観スタイル／テーマ
ReadOnly	bool	読み取り専用モードを有効にします
ToolTipText	string	コントロールのツールチップテキスト

主なイベント

イベント	説明
ValueChanged	Value プロパティが変更されたときに発生します
ValidationCompleted	検証が完了した後に発生します
DateTimeTextChanged	DateTimeText が変更されたときに発生します

一般的なユースケース

ユースケース 1：予約のスケジュール設定

営業時間の制約に従って、予約の日付と時刻を選択します。

ユースケース 2：日付範囲のフィルタリング

レポートやデータクエリに「開始日」から「終了日」までのフィルターを実装します。

ユースケース 3：生年月日の入力

過去の日付に制限を設け、カスタム書式で生年月日を入力します。

ユースケース 4：時刻の入力

シフトのスケジュール設定や時間の記録に、時刻のみを入力します。

ユースケース 5：任意の日付フィールド

空のときにウォーターマークを表示する、null 許容の日付フィールドを持つフォームです。

ユースケース 6：国際的な日付入力

アラビア語やヘブライ語などの RTL サポートを含む、カルチャ固有の日付書式を使用します。

ベストプラクティス

1. 適切な日付範囲を設定する：MinDateTime と MaxDateTime を使用して、無効な日付選択を防ぎます
2. 適切なパターンを選ぶ：スペースに制約のある UI では ShortDate、わかりやすさを重視する場合は LongDate を使用します
3. 正確な入力にはマスクモードを有効にする：フィールドごとに編集するには DateTimeEditingMode.Mask を使用します
4. 任意の日付にはウォーターマークを表示する：AllowNull=true を設定し、わかりやすいウォーターマークテキストを指定します
5. ValueChanged で検証する：ValueChanged イベントハンドラーに検証ロジックを実装します
6. カスタム書式は控えめに使用する：ユーザーが慣れ親しんだ形式にするため、標準パターンを使用します
7. カルチャ設定を考慮する：国際的なユーザーをサポートする場合は、異なるカルチャでテストします
8. null 値を処理する：Value.Value を使用する前に、必ず Value.HasValue を確認します
9. ツールチップを提供する：ToolTipText を使用して、日付形式や制約についてユーザーに案内します
10. キーボード操作をテストする：マスクモードで Tab キーと矢印キーがスムーズに動作することを確認します

DateTimePickerAdv との比較

次の要件がある場合は SfDateTimeEdit を使用します：

• テーマに対応したモダンな UI
• フィールド間を移動できるマスクモード
• ウォーターマークのサポート
• 優れた検証機能
• カルチャ固有のパターン

次の要件がある場合は DateTimePickerAdv を使用します：

• 上下ボタン／ドロップダウンボタンの外観をカスタマイズする
• レガシーアプリケーションとの互換性
• SfDateTimeEdit にはない特定の高度なカスタマイズ