Contributed by
Mathieu Piot
in #26332.

在 web 程序中为表单字段添加帮助信息是常见的需求。但是，Symfony Form 组件不提供这个功能，你需要创建一个 Form extension 表单扩展，像下面这样:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

namespace App\Form\Extension;
 
use Symfony\Component\Form\AbstractTypeExtension;
use Symfony\Component\Form\Extension\Core\Type\FormType;
use Symfony\Component\Form\FormInterface;
use Symfony\Component\Form\FormView;
use Symfony\Component\OptionsResolver\OptionsResolver;
 
class HelpMessageExtension extends AbstractTypeExtension
{
    public function getExtendedType()
    {
        return FormType::class;
    }
 
    public function buildView(FormView $view, FormInterface $form, array $options)
    {
        $view->vars['help'] = $options['help'] ?? '';
    }
 
    public function configureOptions(OptionsResolver $resolver)
    {
        $resolver->setDefaults(['help' => null]);
    }
}

然后创建 form theme（表单主题） 来显示帮助信息:

1
2
3
4
5
6
7
8
9

{% use "bootstrap_4_layout.html.twig" %}
 
{% block form_row %}
    {# ... #}
 
    {% if form.vars.help ?? false %}
        <div class="form--help">{{ form.vars.help }}</div>
    {% endif %}
{% endblock form_row %}

在 Symfony 4.1 中，所有这些都不再需要。因为你可以通过 help 选项在任何字段定义帮助信息:

1
2
3
4

// ...
$builder->add('email', null, [
    'help' => 'Make sure to add a valid email',
]);

下图是帮助信息在我们的 Bootstrap 4 表单主题 中的样子:

得益于 diversity initiative 多样化倡议，我们在诸多方面优先了web可访问性，因此表单主题也被更新，在那些拥有帮助信息的表单字段中，包括了必要的 aria-describedby 属性。

最后，如果你使用 Twig 函数来 自定义Symfony表单，比如 form_row(), form_label(), 等等。你可以使用一个名为 form_help() 的新函数来获取到帮助信息。