Home » カスタムコントロール » TextBoxに透かし文字（Placeholder）を表示する

TextBoxに透かし文字（Placeholder）を表示する

2025年1月22日水曜日

C# WPF カスタムコントロール

記事のカテゴリー: C#、.NET9、WPF

Webサイトの検索欄や入力フォームなどで見かける透かし文字（Placeholder）をWPFのTextBoxで実現する方法を考えます。

1. Adornerを作る

最初にTextBoxの上に透かし文字を表示するためのAdornerを作ります。Adornerはコントロールの手前のレイヤーを使ってコントロールに関連付いた装飾を表示するための手法です（詳しくは装飾の概要を参照してください）。テキストの描画は難しいことをしないで、シンプルにTextBlockを配置します。

Adornerの表示位置はTextBoxの内部で実際にテキストの表示を担当するTextBoxViewの位置を取得して設定しています。

C#:

  1. // 透かし文字を TextBox の上に表示する Adorner
  2. public class PlaceholderAdorner : Adorner
  3. {
  4.     public PlaceholderAdorner(TextBox textBox) : this(textBox, string.Empty) {}
  5.     
  6.     public PlaceholderAdorner(TextBox textBox, string text) : base(textBox)
  7.     {
  8.         if ((textBox.Template.FindName("PART_ContentHost", textBox) is ScrollViewer contentHost)
  9.             && (contentHost.Content is UIElement textBoxView))
  10.         {
  11.             Offset = new(textBoxView.TranslatePoint(new(), textBox).X, 0.0);
  12.         }
  13.         else
  14.         {
  15.             Offset = new(textBox.BorderThickness.Left + textBox.Padding.Left, 0.0);
  16.         }
  17.  
  18.         TextBlock textBlock = new();
  19.         textBlock.Foreground = SystemColors.GrayTextBrush;
  20.         textBlock.Text = placeholder;
  21.         visualChildren.Add(textBlock);
  22.     }
  23.  
  24.     private List<Visual> visualChildren = [];
  25.     
  26.     protected override int VisualChildrenCount
  27.     {
  28.         get { return visualChildren.Count; }
  29.     }
  30.  
  31.     // 透かし文字のプロパティ
  32.     public string Placeholder
  33.     {
  34.         get { return ((TextBlock)visualChildren[0]).Text; }
  35.         set { ((TextBlock)visualChildren[0]).Text = value; }
  36.     }
  37.  
  38.     // 以下、文字の色やフォントを調整するプロパティ (カスタマイズ用)
  39.     public Brush Foreground
  40.     {
  41.         get { return ((TextBlock)visualChildren[0]).Foreground; }
  42.         set { ((TextBlock)visualChildren[0]).Foreground = value; }
  43.     }
  44.  
  45.     public FontFamily FontFamily
  46.     {
  47.         get { return ((TextBlock)visualChildren[0]).FontFamily; }
  48.         set { ((TextBlock)visualChildren[0]).FontFamily = value; }
  49.     }
  50.  
  51.     public double FontSize
  52.     {
  53.         get { return ((TextBlock)visualChildren[0]).FontSize; }
  54.         set { ((TextBlock)visualChildren[0]).FontSize = value; }
  55.     }
  56.  
  57.     public FontStretch FontStretch
  58.     {
  59.         get { return ((TextBlock)visualChildren[0]).FontStretch; }
  60.         set { ((TextBlock)visualChildren[0]).FontStretch = value; }
  61.     }
  62.  
  63.     public FontStyle FontStyle
  64.     {
  65.         get { return ((TextBlock)visualChildren[0]).FontStyle; }
  66.         set { ((TextBlock)visualChildren[0]).FontStyle = value; }
  67.     }
  68.  
  69.     public FontWeight FontWeight
  70.     {
  71.         get { return ((TextBlock)visualChildren[0]).FontWeight; }
  72.         set { ((TextBlock)visualChildren[0]).FontWeight = value; }
  73.     }
  74.  
  75.     public Vector Offset { get; set; }
  76.     
  77.     protected override Visual GetVisualChild(int index)
  78.     {
  79.         return visualChildren[index];
  80.     }
  81.     
  82.     protected override Size ArrangeOverride(Size finalSize)
  83.     {
  84.         TextBlock textBlock = (TextBlock)visualChildren[0];
  85.         double y = (textBlock.DesiredSize.Height < finalSize.Height)
  86.             ? (finalSize.Height - textBlock.DesiredSize.Height) / 2.0 : 0.0;
  87.         textBlock.Arrange(new Rect(Offset.X, y, textBlock.DesiredSize.Width, textBlock.DesiredSize.Height));
  88.         return finalSize;
  89.     }
  90. }

2. 添付ビヘイビアを作る

次に添付ビヘイビアを作ります。Adornerを作成してTextBoxの上に表示するPlaceholder添付プロパティを定義します。TextBoxのTextChangedイベントを購読して、テキストが空のときにのみAdornerを表示します。

C#:

  1. public static class PlaceholderBehavior
  2. {
  3.     // 透かし文字を TextBox の上に表示する添付プロパティ
  4.     public static readonly DependencyProperty PlaceholderProperty = DependencyProperty.RegisterAttached(
  5.         "Placeholder", typeof(string), typeof(PlaceholderBehavior), new FrameworkPropertyMetadata(null, OnPlaceholderChanged));
  6.  
  7.     public static string? GetPlaceholder(DependencyObject obj) { return (string)obj.GetValue(PlaceholderProperty); }
  8.     public static void SetPlaceholder(DependencyObject obj, string? value) { obj.SetValue(PlaceholderProperty, value); }
  9.  
  10.     // イベント購読に使う内部用の添付プロパティ
  11.     private static readonly DependencyProperty IsAttachedProperty = DependencyProperty.RegisterAttached(
  12.         "IsAttached", typeof(bool), typeof(PlaceholderBehavior), new FrameworkPropertyMetadata(false, OnIsAttachedChanged));
  13.  
  14.     private static bool GetIsAttached(DependencyObject obj) { return (bool)obj.GetValue(IsAttachedProperty); }
  15.     private static void SetIsAttached(DependencyObject obj, bool value) { obj.SetValue(IsAttachedProperty, value); }
  16.  
  17.     // Adorner を保存する内部用の添付プロパティ
  18.     private static readonly DependencyProperty AdornerProperty = DependencyProperty.RegisterAttached(
  19.         "Adorner", typeof(PlaceholderAdorner), typeof(PlaceholderBehavior), new FrameworkPropertyMetadata(null));
  20.  
  21.     private static PlaceholderAdorner? GetAdorner(DependencyObject obj) { return (PlaceholderAdorner)obj.GetValue(AdornerProperty); }
  22.     private static void SetAdorner(DependencyObject obj, PlaceholderAdorner? value) { obj.SetValue(AdornerProperty, value); }
  23.     
  24.     private static void OnPlaceholderChanged(DependencyObject obj, DependencyPropertyChangedEventArgs e)
  25.     {
  26.         if (obj is not TextBox textBox)
  27.         {
  28.             return;
  29.         }
  30.         
  31.         if (e.NewValue is string { Length: > 0 })
  32.         {
  33.             UpdateAdorner(textBox);
  34.             SetIsAttached(textBox, true);  // イベントを購読する
  35.         }
  36.         else
  37.         {
  38.             SetIsAttached(textBox, false);  // イベントを購読解除する
  39.         }
  40.     }
  41.  
  42.     private static void OnIsAttachedChanged(DependencyObject obj, DependencyPropertyChangedEventArgs e)
  43.     {
  44.         if (obj is not TextBox textBox)
  45.         {
  46.             return;
  47.         }
  48.  
  49.         if (e.NewValue is true)
  50.         {
  51.             WeakEventManager<TextBox, RoutedEventArgs>.AddHandler(textBox, nameof(textBox.Loaded), TextBox_Loaded);
  52.             WeakEventManager<TextBox, RoutedEventArgs>.AddHandler(textBox, nameof(textBox.Unloaded), TextBox_Unloaded);
  53.             WeakEventManager<TextBox, TextChangedEventArgs>.AddHandler(textBox, nameof(textBox.TextChanged), TextBox_TextChanged);
  54.         }
  55.         else
  56.         {
  57.             WeakEventManager<TextBox, RoutedEventArgs>.RemoveHandler(textBox, nameof(textBox.Loaded), TextBox_Loaded);
  58.             WeakEventManager<TextBox, RoutedEventArgs>.RemoveHandler(textBox, nameof(textBox.Unloaded), TextBox_Unloaded);
  59.             WeakEventManager<TextBox, TextChangedEventArgs>.RemoveHandler(textBox, nameof(textBox.TextChanged), TextBox_TextChanged);
  60.             DeleteAdorner(textBox, true);
  61.         }
  62.     }
  63.     
  64.     // Adorner を削除する
  65.     private static void DeleteAdorner(TextBox textBox, bool completely)
  66.     {
  67.         if ((GetAdorner(textBox) is PlaceholderAdorner adorner)
  68.             && (adorner.Parent is AdornerLayer adornerLayer))
  69.         {
  70.             adornerLayer.Remove(adorner);
  71.         }
  72.  
  73.         if (completely)
  74.         {
  75.             SetAdorner(textBox, null);
  76.         }
  77.     }
  78.     
  79.     // Adorner の表示を更新する
  80.     private static void UpdateAdorner(TextBox textBox)
  81.     {
  82.         if (!textBox.IsLoaded)
  83.         {
  84.             return;
  85.         }
  86.  
  87.         string placeholder = (string)GetPlaceholder(textBox)!;  // null のときは到達しない
  88.  
  89.         // Adorner が未作成なら作成する
  90.         if (GetAdorner(textBox) is PlaceholderAdorner adorner)
  91.         {
  92.             adorner.Placeholder = placeholder;
  93.         }
  94.         else
  95.         {
  96.             adorner = new(textBox, placeholder) { FontSize = textBox.FontSize, IsClipEnabled = true };
  97.             SetAdorner(textBox, adorner);
  98.         }
  99.  
  100.         // Adorner が AdornerLayer に追加されていないなら追加する
  101.         if (!adorner.IsLoaded)
  102.         {
  103.             if (AdornerLayer.GetAdornerLayer(textBox) is not AdornerLayer adornerLayer)
  104.             {
  105.                 return;
  106.             }
  107.  
  108.             adornerLayer.Add(adorner);
  109.         }
  110.  
  111.         // TextBox の入力状態に応じて Adorner を表示、または非表示にする
  112.         adorner.Visibility = (textBox.Text.Length == 0) ? Visibility.Visible : Visibility.Hidden;
  113.     }
  114.  
  115.     private static void TextBox_Loaded(object? sender, RoutedEventArgs e)
  116.     {
  117.         if (sender is TextBox textBox)
  118.         {
  119.             UpdateAdorner(textBox);
  120.         }
  121.     }
  122.  
  123.     private static void TextBox_Unloaded(object? sender, RoutedEventArgs e)
  124.     {
  125.         if (sender is TextBox textBox)
  126.         {
  127.             DeleteAdorner(textBox, false);
  128.         }
  129.     }
  130.  
  131.     private static void TextBox_TextChanged(object? sender, TextChangedEventArgs e)
  132.     {
  133.         if (sender is TextBox textBox)
  134.         {
  135.             UpdateAdorner(textBox);
  136.         }
  137.     }
  138. }

3. TextBoxに添付プロパティを設定する

TextBoxにPlaceholder添付プロパティを設定します。

XAML:

  1. <Window
  2.     ...
  3.     xmlns:local="clr-namespace:WpfApp1"
  4.     ...>
  5.

XAML:

  1. <TextBox local:PlaceholderBehavior.Placeholder="設定を検索" />

更新履歴

  • : 初稿
  • : イベント購読を多重登録してしまう問題に対応しました。PlaceholderBehaviorクラスにIsAttached添付プロパティを追加して再構成しています。
  • : TextBoxを破棄してもAdornerが表示されたままになってしまう問題に対応しました。PlaceholderBehaviorクラスでTextBoxのUnloadedイベントの購読を追加しています。
-
カテゴリ , ,