syncfusion-wpf-text-input-layout

WPF TextInputLayout の実装

WPF 用の TextInputLayout コントロールは、TextBox などの入力ビューにフローティングラベル、アイコン、補助ラベル、さまざまなコンテナーのスタイルを追加し、装飾とユーザーエクスペリエンスの向上を実現します。

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

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

• フローティングラベルを追加する：WPF の TextBox やその他の入力コントロールに追加します
• 入力検証 UI を実装する：エラーメッセージや視覚的なフィードバックを表示します
• 入力コンテナーをカスタマイズする：アウトライン、塗りつぶし、最小限のスタイルを設定します
• 補助テキストを追加する：入力フィールドにヘルパーテキストや文字数カウンターを追加します
• アイコンを含める：入力レイアウトに先頭または末尾のアイコンを追加します
• ヒントの配置を設定する：フロート動作を指定します
• 複数の入力タイプをサポートする：TextBox、PasswordBox、ComboBox などを扱います
• マテリアルデザイン風の入力フィールドを実装する：WPF に実装します
• 補助ラベルを追加する：アクセシビリティとユーザビリティを向上させます
• 色とスタイルをカスタマイズする：フォーカス時、フォーカスなし、エラー時の状態を設定します

コンポーネントの概要

SfTextInputLayout コントロールは、装飾要素で標準の WPF 入力コントロールをラップし、その機能を拡張します。

主な機能

• フローティングラベル：フォーカス時に入力欄の上に浮かび上がるアニメーション付きのヒントラベル
• コンテナーの種類：Outlined（デフォルト）、Filled、None のスタイル
• 補助ラベル：ヘルパーテキスト、エラーメッセージ、文字数カウンター
• カスタムアイコン：内側または外側に配置できる先頭および末尾のビュー
• 複数の入力ビュー：TextBox、PasswordBox、ComboBox、ComboBoxAdv、SfTextBoxExt、DatePicker、SfDatePicker、SfTimePicker、UpDown、SfMaskedEdit、IntegerTextBox、DoubleTextBox、PercentTextBox、CurrencyTextBox
• 状態に応じたスタイル設定：フォーカス時、フォーカスなし、エラー時の状態に応じた色
• RTL サポート：国際化に対応した右から左へのテキスト表示
• 幅広いカスタマイズ：境界線の太さ、角の丸み、パディングなど

一般的な使用例

• 検証機能付きのフォーム入力フィールド
• マテリアルデザイン風のインターフェイス
• ユーザー登録フォームやログインフォーム
• データ入力アプリケーション
• アイコン付きの検索ボックス
• 表示切り替え機能付きのパスワードフィールド
• 装飾付きコンテナーを備えたドロップダウン入力

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

はじめに

📄 参照： references/getting-started.md

• インストールとアセンブリの参照
• 名前空間のインポートと初期化
• TextInputLayout の基本設定
• ヒントラベルの追加
• HintVisibility の設定
• SfSkinManager によるテーマのサポート

コンテナーの種類とレイアウト

📄 参照： references/container-types.md

• ContainerType プロパティの概要
• Outlined コンテナー（角が丸い枠線がデフォルト）
• Filled コンテナー（背景とベースライン付き）
• None コンテナー（最小限のスタイル）
• ContainerBackground のカスタマイズ
• OutlineCornerRadius の設定

補助ラベルと検証

📄 参照： references/assistive-labels.md

• HelperText プロパティによるヘルパーテキスト
• HelperTextVisibility の設定
• ErrorText プロパティによるエラーメッセージ
• 検証状態を示す HasError プロパティ
• CharMaxLength による文字数カウンター
• CharCountVisibility の設定
• 検証パターンとベストプラクティス

カスタマイズとスタイル設定

📄 参照： references/customization.md

• フォーカス時の色を指定する FocusedForeground
• フォーカスなしの色を指定する Foreground
• エラー時の色を指定する ErrorForeground
• ActiveForeground プロパティ
• ContainerBackground のカスタマイズ
• 独立した境界線の色を指定する FocusedBorderBrush
• StrokeThickness と FocusedStrokeThickness
• InputViewPadding の設定
• 色のパターンとスタイル設定の方法

アイコンと入力ビュー

📄 参照： references/icons-and-views.md

• LeadingView と LeadingViewPosition の設定
• TrailingView と TrailingViewPosition の設定
• フォントアイコンを使ったアイコンの実装
• 対応する入力ビュー：TextBox、PasswordBox、ComboBox、ComboBoxAdv、SfTextBoxExt、DatePicker、SfDatePicker、SfTimePicker、UpDown、SfMaskedEdit、IntegerTextBox、DoubleTextBox、PercentTextBox、CurrencyTextBox
• ComboBoxAdv の統合
• SfTextBoxExt（オートコンプリート）のサポート
• DropDownBorder のカスタマイズ
• InputView プロパティの使用

ヒントの設定

📄 参照： references/hint-configuration.md

• HintFloatMode プロパティのオプション
• Float モード（デフォルトの動作）
• AlwaysFloat モード（常に上部に表示）
• None モード（フォーカス時に非表示）
• ヒントのアニメーションと配置
• ヒントラベルのベストプラクティス

高度な機能

📄 参照： references/advanced-features.md

• FlowDirection プロパティによる RTL サポート
• 右から左へのテキストフローの設定
• ドロップダウンの枠線のカスタマイズ
• API リファレンスの全体的な概要
• パフォーマンスに関する考慮事項
• ベストプラクティスとパターン
• よくある問題のトラブルシューティング

クイックスタートの例

ヒント付きの基本的な TextInputLayout

XAML：

<Window xmlns:inputLayout="clr-namespace:Syncfusion.UI.Xaml.TextInputLayout;assembly=Syncfusion.SfTextInputLayout.WPF">
    
    <inputLayout:SfTextInputLayout 
        Hint="Name" 
        HelperText="Enter your full name">
        <TextBox />
    </inputLayout:SfTextInputLayout>
    
</Window>

C#：

using Syncfusion.UI.Xaml.TextInputLayout;

var inputLayout = new SfTextInputLayout();
inputLayout.Hint = "Name";
inputLayout.HelperText = "Enter your full name";
inputLayout.InputView = new TextBox();

検証とエラー状態を設定する場合

XAML：

<inputLayout:SfTextInputLayout 
    Hint="Email" 
    HelperText="Enter a valid email address"
    ErrorText="Invalid email format"
    HasError="True"
    ErrorForeground="Red">
    <TextBox Text="invalid@"/>
</inputLayout:SfTextInputLayout>

アイコン付きのアウトラインコンテナー

XAML：

<inputLayout:SfTextInputLayout 
    Hint="Search" 
    ContainerType="Outlined"
    FocusedForeground="Blue">
    <TextBox />
    <inputLayout:SfTextInputLayout.LeadingView>
        <Label Content="🔍" FontSize="16"/>
    </inputLayout:SfTextInputLayout.LeadingView>
</inputLayout:SfTextInputLayout>

よくあるパターン

検証付きフォームフィールドのパターン

検証付きフォーム入力には、次のパターンを使用します。

<StackPanel>
    
    <inputLayout:SfTextInputLayout 
        Hint="Username" 
        HelperText="At least 5 characters"
        CharMaxLength="20"
        CharCountVisibility="Visible">
        <TextBox TextChanged="ValidateUsername"/>
    </inputLayout:SfTextInputLayout>
    
    
    <inputLayout:SfTextInputLayout 
        Hint="Password" 
        HelperText="Must contain letters and numbers">
        <PasswordBox PasswordChanged="ValidatePassword"/>
    </inputLayout:SfTextInputLayout>
</StackPanel>

private void ValidateUsername(object sender, TextChangedEventArgs e)
{
    var textBox = sender as TextBox;
    var layout = FindParent<SfTextInputLayout>(textBox);
    
    if (textBox.Text.Length < 5)
    {
        layout.HasError = true;
        layout.ErrorText = "Username too short";
    }
    else
    {
        layout.HasError = false;
    }
}

Material Design スタイルのパターン

Material Design スタイルの入力欄を作成します。

<inputLayout:SfTextInputLayout 
    Hint="Email Address" 
    ContainerType="Filled"
    FocusedForeground="#6200EE"
    ContainerBackground="#F5F5F5"
    HelperText="We'll never share your email">
    <TextBox />
</inputLayout:SfTextInputLayout>

アイコン付き検索ボックスのパターン

先頭／末尾のアイコン付き検索入力欄を実装します。

<inputLayout:SfTextInputLayout 
    Hint="Search..." 
    ContainerType="Outlined"
    OutlineCornerRadius="20">
    <TextBox TextChanged="OnSearchTextChanged"/>
    
    <inputLayout:SfTextInputLayout.LeadingView>
        <Label Content="🔍" FontSize="18"/>
    </inputLayout:SfTextInputLayout.LeadingView>
    
    <inputLayout:SfTextInputLayout.TrailingView>
        <Button Content="✕" Click="ClearSearch" 
                Background="Transparent" BorderThickness="0"/>
    </inputLayout:SfTextInputLayout.TrailingView>
</inputLayout:SfTextInputLayout>

アウトラインコンテナー付きドロップダウンのパターン

TextInputLayout を使用して ComboBox を拡張します。

<inputLayout:SfTextInputLayout 
    Hint="Country" 
    ContainerType="Outlined"
    FocusedBorderBrush="Blue">
    <ComboBox ItemsSource="{Binding Countries}" 
              SelectedItem="{Binding SelectedCountry}"/>
</inputLayout:SfTextInputLayout>

主なプロパティ

コア設定

• InputView：入力コントロール（TextBox、PasswordBox など）
• Hint：フローティングラベルのテキスト
• HintVisibility：ヒントラベルの表示を制御します
• HintFloatMode：Float、AlwaysFloat、または None
• ContainerType：Outlined、Filled、または None

補助ラベル

• HelperText：追加のガイダンステキスト
• ErrorText：エラーメッセージのテキスト
• HasError：エラー状態を表示するブール値
• CharMaxLength：最大文字数
• CharCountVisibility：文字数カウンターの表示／非表示

スタイル設定プロパティ

• FocusedForeground：フォーカス時の色
• Foreground：フォーカスがないときの色
• ErrorForeground：エラー状態の色
• ContainerBackground：背景色
• FocusedBorderBrush：フォーカス時の枠線の色

枠線とストローク

• StrokeThickness：フォーカスがないときの枠線の太さ（デフォルト：1）
• FocusedStrokeThickness：フォーカス時の枠線の太さ（デフォルト：2）
• OutlineCornerRadius：アウトライン枠線の角の半径

アイコンとビュー

• LeadingView：左側のアイコン／ビュー
• LeadingViewPosition：Inside または Outside
• TrailingView：右側のアイコン／ビュー
• TrailingViewPosition：Inside または Outside

よくある使用例

ユーザー登録フォーム

複数の TextInputLayout コントロールを検証と組み合わせ、ユーザー名、メールアドレス、パスワードなどのフィールドにリアルタイムの検証フィードバックを表示します。

ログイン画面

フローティングラベルとエラー状態を備えた、メールアドレス／ユーザー名およびパスワード入力欄を使って、すっきりとした Material Design スタイルのログインフォームを作成します。

検索インターフェース

先頭／末尾のビューを使って、アイコン、プレースホルダーのヒント、クリアボタンを備えた検索ボックスを実装します。

データ入力フォーム

補助テキスト、文字数制限、検証メッセージを備えた包括的なフォームを構築し、ユーザーエクスペリエンスを向上させます。

設定パネル

さまざまな入力タイプ（TextBox、ComboBox、PasswordBox）で TextInputLayout を使用し、設定インターフェース全体で一貫したスタイルを適用します。

プロフィールの編集

検証、自己紹介フィールドの文字数カウンター、適切なエラー処理を備えたプロフィール編集フォームを作成します。

関連コンポーネント

• TextBox：テキスト用の主要な入力ビュー
• PasswordBox：パスワード入力用
• ComboBox/ComboBoxAdv：ドロップダウン選択用
• SfTextBoxExt：オートコンプリート機能用
• DatePicker/SfDatePicker：日付選択用
• SfTimePicker：時刻選択用
• UpDown：数値のステッパー入力用
• SfMaskedEdit：マスク付きテキスト入力用
• IntegerTextBox/DoubleTextBox/PercentTextBox/CurrencyTextBox：数値入力用

注意事項

• ヒントラベルはフォーカス状態に応じて自動的にアニメーションします
• エラー検証ロジックはアプリケーション側で実装する必要があります
• 文字数カウンターは、上限を超えるとエラー色で表示されます
• FocusedBorderBrush は、境界線に対して FocusedForeground を上書きします
• DropDownBorder は ComboBox/ComboBoxAdv にのみ適用されます
• OutlineCornerRadius は Outlined コンテナータイプにのみ適用されます

---

次のステップ： 実装のニーズに応じて、上記のリファレンスドキュメントを参照してください。初期設定については getting-started.md から始め、その後必要に応じて各機能を確認してください。