syncfusion-winforms-banner-text-provider

Syncfusion WinForms BannerTextProvider の実装

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

次の場合にこのスキルを使用します：

• ユーザーが透かし／プレースホルダーテキストを必要としている - 空のエディターコントロールにヒントテキストを表示する場合
• BannerTextProvider を実装する - TextBoxExt、ComboBoxAdv、CurrencyTextBox などのエディターコントロールにバナーテキストを追加する場合
• バナーの外観をカスタマイズする - テキストの色、フォント、表示モードを設定する場合
• テキストの表示モードを設定する - FocusMode（フォーカス時に非表示）または EditMode（入力時に非表示）を選択する場合
• 複数のエディターコントロールに対応する - さまざまな Syncfusion または Microsoft のコントロールにバナーテキストを適用する場合
• ユーザーが次のような語句に言及している： 透かし、プレースホルダーテキスト、ヒントテキスト、バナーテキスト、BannerTextProvider、BannerTextInfo

コンポーネントの概要

BannerTextProvider は、エディターコントロールに透かしテキストを表示するエクステンダーコントロールです。コントロールが空のときに視覚的なヒントを表示し、ユーザーがコントロールを操作するとテキストを自動的に非表示にします。

主な機能：

• テキストモード： バナーテキストが非表示になるタイミングを制御する FocusMode と EditMode
• カスタマイズ： テキストの色、フォント、表示の制御
• 複数コントロールのサポート： 14 種類以上のエディターコントロール（TextBoxExt、ComboBoxAdv、CurrencyTextBox など）に対応
• デザイナーとコードのサポート： フォームデザイナーまたはプログラムから追加可能

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

はじめに

📄 参照： references/getting-started.md

• アセンブリのデプロイと NuGet のインストール
• フォームデザイナーから BannerTextProvider を追加する
• コードから BannerTextProvider を追加する
• コントロールにバナーテキストを割り当てる
• BannerTextInfo の基本的な設定

バナーテキストの設定

📄 参照： references/banner-text-configuration.md

• Text プロパティと表示の制御
• テキストの色の設定（BannerTextInfo.Color）
• フォントのカスタマイズ（BannerTextInfo.Font）
• Mode プロパティ：FocusMode と EditMode の比較
• 設定の完全な例

対応コントロール

📄 参照： references/supported-controls.md

• 対応する 14 種類以上のコントロールの完全な一覧
• コントロールのカテゴリ（エディター、メニュー、リボン、ツールバー）
• 互換性マトリックス
• コントロールの種類ごとのベストプラクティス
• 制限事項と回避策

実用例

📄 参照： references/practical-examples.md

• エンドツーエンドのコード例
• デザイナーベースの実装手順
• コードベースの実装パターン
• 異なる設定を使用する複数のコントロール
• 実行時にバナーテキストを動的に変更する

カスタマイズとヒント

📄 参照： references/customization-and-tips.md

• 高度なスタイル設定の手法
• パフォーマンスの最適化
• よくある問題とトラブルシューティング
• 特殊なケースとベストプラクティス
• アクセシビリティに関する考慮事項

クイックスタートの例

// 1. Create BannerTextProvider (usually in Form designer or Form_Load)
BannerTextProvider bannerTextProvider = new BannerTextProvider(this.components);

// 2. Create TextBoxExt control
TextBoxExt textBox = new TextBoxExt()
{
    Size = new System.Drawing.Size(200, 30),
    Location = new System.Drawing.Point(20, 20)
};
this.Controls.Add(textBox);

// 3. Set banner text
BannerTextInfo bannerInfo = new BannerTextInfo()
{
    Text = "Enter your name...",
    Visible = true,
    Font = new System.Drawing.Font("Verdana", 9, System.Drawing.FontStyle.Italic),
    Color = System.Drawing.Color.Gray,
    Mode = BannerTextMode.EditMode  // Disappears when user types
};

bannerTextProvider.SetBannerText(textBox, bannerInfo);

よくあるパターン

パターン 1：シンプルなプレースホルダーテキスト

ユーザーの入力時に非表示になる基本的なヒントテキストが必要な場合：

bannerTextProvider.SetBannerText(textBox, 
    new BannerTextInfo("Type here...", true));

パターン 2：スタイル付きの透かし（EditMode）

コンテンツが追加されたときにのみ非表示になる、より目立つ透かしを表示する場合：

var bannerInfo = new BannerTextInfo(
    Text = "Email address",
    Visible = true,
    Font = new Font("Verdana", 8.25f, FontStyle.Italic),
    Color = Color.RoyalBlue,
    Mode = BannerTextMode.EditMode
);
bannerTextProvider.SetBannerText(emailTextBox, bannerInfo);

パターン 3：フォーカスベースのバナー（FocusMode）

コントロールがフォーカスを受け取ると非表示になる、一時的なヒントを表示する場合：

var bannerInfo = new BannerTextInfo(
    Text = "Click to edit",
    Visible = true,
    Color = Color.LightGray,
    Mode = BannerTextMode.FocusMode  // Disappears on focus
);
bannerTextProvider.SetBannerText(textBox, bannerInfo);

パターン 4：複数コントロールの設定

複数のエディターコントロールに効率よくバナーテキストを適用します：

var controls = new[] { nameTextBox, emailTextBox, phoneTextBox };
var placeholders = new[] { "Full Name", "Email Address", "Phone Number" };

for (int i = 0; i < controls.Length; i++)
{
    bannerTextProvider.SetBannerText(controls[i],
        new BannerTextInfo(placeholders[i], true));
}

主なモードの説明

モード	動作	最適な用途
FocusMode	コントロールがフォーカスを受け取るとバナーテキストが非表示になります	すばやいヒントテキスト、一時的なガイダンス
EditMode	コントロールにテキストが含まれる場合にのみバナーテキストが非表示になります	持続的な透かし、明確な区別

注： 最適な結果を得るには、バナーテキストを設定する前に、コントロールの既定の Text プロパティをクリアしてください。

重要な考慮事項

⚠️ デフォルトのテキストをクリアする： バナーテキストを設定する前に、必ずコントロールの Text プロパティをクリアしてください。 ⚠️ サポート対象のコントロールのみ： BannerTextProvider は、特定の 14 個以上のコントロールで動作します（supported-controls.md を参照）。 ⚠️ アセンブリ参照： Syncfusion.Shared.Base アセンブリが必要です。 ⚠️ EditMode のベストプラクティス： ユーザーがテキストを入力するまでバナーを表示し続ける必要がある場合は、EditMode を使用してください。

---

次の手順： まず はじめに を参照してコンポーネントをセットアップし、その後、具体的なニーズに応じて他のガイドを参照してください。