Django フォームでフィールドに補足情報を表示！forms.BoundField.help_textの使い方をマスターしよう

forms.BoundField.help_text は、以下の情報を格納します。

• 入力エラーに関するヒント
• フィールドの使用方法に関するガイダンス

この情報は、フォームフィールドの下に小さなテキストとして表示されます。

forms.BoundField.help_text の設定方法

forms.BoundField.help_text は、以下の2つの方法で設定できます。

方法1：フォームフィールドの定義時に設定

from django.forms import CharField

class MyForm(forms.Form):
    name = CharField(label='名前', help_text='氏名を全角で入力してください。')

方法2：テンプレート内で設定

{% for field in form %}
    <div class="field">
        <label for="{{ field.html_name }}">{{ field.label }}</label>
        {{ field.as_widget }}
        <p class="help-text">{{ field.help_text }}</p>
    </div>
{% endfor %}

forms.BoundField.help_text は、以下の用途に活用できます。

• フィールドに関連する追加情報を提供する
• 入力エラーの原因を説明する
• フィールドの使用方法に関する明確な指示を提供する

forms.BoundField.help_text を効果的に活用することで、ユーザーにとってより使いやすいフォームを作成することができます。

• forms.BoundField.help_text は、条件に応じて動的に設定することができます。
• forms.BoundField.help_text は、HTML 形式で記述することができます。

---

フォームフィールドの定義時に help_text を設定

from django.forms import CharField, ModelForm

class MyModel(models.Model):
    name = models.CharField(max_length=255)

class MyForm(ModelForm):
    class Meta:
        model = MyModel
        fields = ['name']

    name = CharField(label='名前', help_text='氏名を全角で入力してください。')

<form method="post">
    {% csrf_token %}
    <div class="field">
        <label for="id_name">名前</label>
        <input type="text" name="name" id="id_name" required>
        <p class="help-text">氏名を全角で入力してください。</p>
    </div>
    <button type="submit">送信</button>
</form>

テンプレート内で help_text を設定

{% for field in form %}
    <div class="field">
        <label for="{{ field.html_name }}">{{ field.label }}</label>
        {{ field.as_widget }}
        <p class="help-text">{{ field.help_text }}</p>
    </div>
{% endfor %}

このテンプレートは、以下のHTMLを生成します。

<form method="post">
    {% csrf_token %}
    <div class="field">
        <label for="id_name">名前</label>
        <input type="text" name="name" id="id_name" required>
        <p class="help-text">氏名を全角で入力してください。</p>
    </div>
    <div class="field">
        <label for="id_email">メールアドレス</label>
        <input type="email" name="email" id="id_email" required>
        <p class="help-text">有効なメールアドレスを入力してください。</p>
    </div>
    <button type="submit">送信</button>
</form>

条件に応じて help_text を設定

from django.forms import CharField, ModelForm

class MyModel(models.Model):
    name = models.CharField(max_length=255)

class MyForm(ModelForm):
    class Meta:
        model = MyModel
        fields = ['name']

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        if self.instance and self.instance.pk:
            self.fields['name'].help_text = '名前を変更することはできません。'

MyForm(instance=MyModel.objects.get(pk=1))

このコードは、MyModel インスタンスが存在する場合は、name フィールドの help_text を "名前を変更することはできません。" に設定します。

from django.forms import CharField, ModelForm

class MyModel(models.Model):
    name = models.CharField(max_length=255)

class MyForm(ModelForm):
    class Meta:
        model = MyModel
        fields = ['name']

    name = CharField(label='名前', help_text='<p>氏名を全角で入力してください。<br>必須項目です。</p>')

このコードは、name フィールドの help_text を HTML 形式で設定します。

from django.forms import CharField, ModelForm
from django.utils.translation import gettext_lazy

class MyModel(models.Model):
    name = models.CharField(max_length=255)

class MyForm(ModelForm):
    class Meta:
        model = MyModel
        fields = ['name']

    name = CharField(label=gettext_lazy('名前'), help_text=gettext_lazy('氏名を全角で入力してください。'))

---

以下に、forms.BoundField.help_text の代替方法をいくつか紹介します。

プレースホルダー属性

from django.forms import CharField

class MyForm(forms.Form):
    name = CharField(label='名前', placeholder='氏名を全角で入力してください。')

ツールチップ

JavaScript ライブラリを使用して、フィールドにマウスオーバーしたときにツールチップを表示することができます。これは、より詳細な情報を表示したい場合に有効です。

<label for="id_name">名前</label>
<input type="text" name="name" id="id_name" required data-toggle="tooltip" data-placement="top" title="氏名を全角で入力してください。">

$(document).ready(function() {
    $('[data-toggle="tooltip"]').tooltip();
});

カスタムウィジェット

from django.forms import CharField, Widget

class HelpTextWidget(Widget):
    def render(self, name, value, attrs=None):
        html = '<label for="%s">%s</label>' % (attrs['id'], attrs['label'])
        html += '<input type="text" name="%s" id="%s" value="%s">' % (name, attrs['id'], value)
        html += '<p class="help-text">%s</p>' % self.help_text
        return html

class MyForm(forms.Form):
    name = CharField(label='名前', widget=HelpTextWidget(help_text='氏名を全角で入力してください。'))

カスタムバリデーションエラーメッセージ

from django.forms import CharField, ValidationError

def validate_name(value):
    if not value.isupper():
        raise ValidationError('氏名を全角で入力してください。')

class MyForm(forms.Form):
    name = CharField(label='名前', validators=[validate_name])

from django import template

register = template.Library()

@register.simple_tag
def render_help_text(field):
    if field.help_text:
        return '<p class="help-text">%s</p>' % field.help_text
    return ''

class MyForm(forms.Form):
    name = CharField(label='名前')

{% for field in form %}
    <div class="field">
        <label for="{{ field.html_name }}">{{ field.label }}</label>
        {{ field.as_widget }}
        {{ render_help_text(field) }}
    </div>
{% endfor %}

これらの代替方法は、それぞれ異なる利点と欠点があります。状況に応じて適切な方法を選択してください。

• forms.BoundField.help_text は、条件に応じて動的に設定することができます。
• forms.BoundField.help_text は、HTML 形式で記述することができます。