`` 元素中 (这里 ``my_block_name`` 是 StreamField 中定义的块名)。
如果需要使用自定义的 HTML 标记，可能遍历字段中各个值，然后对每个块使用 ``{% include_block %}`` 进行处理:
.. code-block:: html+django
{% load wagtailcore_tags %}
...
{% for block in page.body %}
{% include_block block %}
{% endfor %}
如需进一步控制特定块的渲染方法，每个块都提供了 ``block_type`` 和 ``value`` 属性，可以判断这些属性然后分别进行处理:
.. code-block:: html+django
{% load wagtailcore_tags %}
...
{% for block in page.body %}
{% if block.block_type == 'heading' %}
{{ block.value }}
{% else %}
{% include_block block %}
{% endif %}
{% endfor %}
默认情况下，每个块使用最简单的 HTML 标签修饰，或者根本不用。例如 CharBlock 值直接渲染成普通广西，ListBlock 输出子块时使用 `
` 修饰。
在定制这个 HTML 渲染过程，可以通过 ``template`` 参数将渲染模板文件名传递给块。这对基于 StructBlock 的块特别有用:
.. code-block:: python
('person', blocks.StructBlock(
[
('first_name', blocks.CharBlock()),
('surname', blocks.CharBlock()),
('photo', ImageChooserBlock(required=False)),
('biography', blocks.RichTextBlock()),
],
template='myapp/blocks/person.html',
icon='user'
))
或者在定义 StructBlock 子类时:
.. code-block:: python
class PersonBlock(blocks.StructBlock):
first_name = blocks.CharBlock()
surname = blocks.CharBlock()
photo = ImageChooserBlock(required=False)
biography = blocks.RichTextBlock()
class Meta:
template = 'myapp/blocks/person.html'
icon = 'user'
在模板中，块值通过变量 ``value`` 取出:
.. code-block:: html+django
{% load wagtailimages_tags %}
{% image value.photo width-400 %}
{{ value.first_name }} {{ value.surname }}
{{ value.biography }}
由于 ``first_name``, ``surname``, ``photo`` 和 ``biography`` 以各自方式定义，也可以写成:
.. code-block:: html+django
{% load wagtailcore_tags wagtailimages_tags %}
{% image value.photo width-400 %}
{% include_block value.first_name %} {% include_block value.surname %}
{% include_block value.biography %}
使用 ``{{ my_block }}`` 与 ``{% include_block my_block %}`` 语句是同样的意思，但限制更多，模板中的 ``request`` 或 ``page`` 没有绑定; 因此建议只对不生成 HTML 的简单值进行处理，例如 PersonBlock 使用的模板:
.. code-block:: html+django
{% load wagtailimages_tags %}
{% image value.photo width-400 %}
{{ value.first_name }} {{ value.surname }}
{% if request.user.is_authenticated %}
Contact this person
{% endif %}
{{ value.biography }}
{{ block }}
{% endif %}
{% endfor %}
{# Correct: #}
{% for block in page.body %}
{% if block.block_type == 'person' %}
{% include_block block %}
{% endif %}
{% endfor %}
和 Django 的 ``{% include %}`` 标签一样, ``{% include_block %}`` 允许使用类似于 ``{% include_block my_block with foo="bar" %}`` 的语法传递额外的变量给模板:
.. code-block:: html+django
{# In page template: #}
{% for block in page.body %}
{% if block.block_type == 'person' %}
{% include_block block with classname="important" %}
{% endif %}
{% endfor %}
{# In PersonBlock template: #}
...
``{% include_block my_block with foo="bar" only %}`` 的语法格式也是支持的，这里设置父模板中的变量只有 ``foo`` 传递给子模板。
.. _streamfield_get_context:
除了使用父模板传来变量，子类中也可以重写 ``get_context`` 方法来增加模板上下文的变量:
.. code-block:: python
import datetime
class EventBlock(blocks.StructBlock):
title = blocks.CharBlock()
date = blocks.DateBlock()
def get_context(self, value, parent_context=None):
context = super().get_context(value, parent_context=parent_context)
context['is_happening_today'] = (value['date'] == datetime.date.today())
return context
class Meta:
template = 'myapp/blocks/event.html'
在这个例子中，在模板中 ``is_happening_today`` 变更也是可以使用的。 当块通过 ``{% include_block %}`` 标签渲染模板时，关键字参数 ``parent_context`` 是可用的，其中存放者父模板中的上下文变量字典。
BoundBlock 与 value
----------------------
全部块类型，不只是 StructBlock，都接受 ``template`` 参数来决定在页面上显示时如何渲染。但是负责处理 Python 基础数据类型的块，例如 ``CharBlock`` 和 ``IntegerBlock`` 在模板中应用时有一些限制，
这是因为这些 Python 内置类型(如 ``str``, ``int`` 等等) 并不能 '告知' 是否用在模板渲染中。可能通过一个例子来了解下这种情况：
.. code-block:: python
class HeadingBlock(blocks.CharBlock):
class Meta:
template = 'blocks/heading.html'
这里 ``blocks/heading.html`` 内容如下:
.. code-block:: html+django
{{ value }}
这样就定义了一个类似文本字段的块，但输出时使用 ```` 标签进行渲染:
.. code-block:: python
class BlogPage(Page):
body = StreamField([
# ...
('heading', HeadingBlock()),
# ...
])
.. code-block:: html+django
{% load wagtailcore_tags %}
{% for block in page.body %}
{% if block.block_type == 'heading' %}
{% include_block block %} {# This block will output its own ...
tags. #}
{% endif %}
{% endfor %}
这种设计设想是值是一个普通的字符串，但在模板 include_block 引用时输出了带 标签的字符串。这在 Python 中使用非常容易造成困扰，但在这个地方可以完成预想的工作，
原因是 block 是通过遍历 StreamField 获得的条目，并不是块的本身的值。遍历时获得的值是 ``BoundBlock`` 类的实例，包括了值和块的定义内容。跟踪一下块定义，``BoundBlock``
是知道使用哪个模板渲染输出结果的。要获取本身编辑时输入的值，应使用 ``block.value`` 变量。所在在模板页面中使用 ``{% include_block block.value %}`` 就得到正常输入字符串，没有 ```` 标签。
(严格说来，遍历 StreamField 字段获得的条目是 ``StreamChild`` 实例，包括 ``block_type`` 属性和 ``value`` 属性。)
有 Django 开发经验的开发者可以参考 Django Form 框架中的 ``BoundField`` 类来理解 ``BoundBlock``，``BoundField`` 也是包含了表单字段以及在表单上如何将值渲染到 HTML 表单的定义。
正常情况下，开发时不需要担心这些内部细节，Wagtail 使用模板时会处理这些问题。但在复杂的设计中，例如访问 ``ListBlock`` 或 ``StructBlock`` 中的块时，这种情况下没有 ``BoundBlock`` 这层处理，
所以其中的条目不知道是在做模板渲染。下面例子，``HeadingBlock`` 是一个 StructBlock 的子项：
.. code-block:: python
class EventBlock(blocks.StructBlock):
heading = HeadingBlock()
description = blocks.TextBlock()
# ...
class Meta:
template = 'blocks/event.html'
``blocks/event.html`` 文件内容:
.. code-block:: html+django
{% load wagtailcore_tags %}
{% include_block value.heading %}
- {% include_block value.description %}
这种情况下，``value.heading`` 返回的是一个原始输入的字符串内容，而不是 ``BoundBlock``，这是必须的，否则像 ``{% if value.heading == 'Party!' %}`` 之类比较不可能为真。
这意味着 ``{% include_block value.heading %}`` 将渲染输出为普通字符串，没有 ```` 标签。要生成带 ```` 标签的模板，要使用 ``value.bound_blocks.heading`` 的形式
来明确指明使用 ``BoundBlock`` 实例的模板格式输出。
.. code-block:: html+django
{% load wagtailcore_tags %}
{% include_block value.bound_blocks.heading %}
- {% include_block value.description %}
实际上对这种复合块结构的输出，为了更具可读性，最好是相关的 HTML 标签编写在顶层复合块模板中。例如，要输出 ```` 标签，可以在 EventBlock 的模板中定义:
.. code-block:: html+django
{% load wagtailcore_tags %}
{{ value.heading }}
- {% include_block value.description %}
这种限制不会影响 StructBlock 及 StreamBlock 做为 StructBlock 子结点的值, 因为 Wagtail 在实现这些复合块时知道它们渲染的模板，与放不放在 ``BoundBlock`` 中无关。
例如一个结构块嵌入另一个结构块中：
.. code-block:: python
class EventBlock(blocks.StructBlock):
heading = HeadingBlock()
description = blocks.TextBlock()
guest_speaker = blocks.StructBlock([
('first_name', blocks.CharBlock()),
('surname', blocks.CharBlock()),
('photo', ImageChooserBlock()),
], template='blocks/speaker.html')
这样 EventBlock 模板中使用 ``{% include_block value.guest_speaker %}`` 会知道使用 ``blocks/speaker.html`` 渲染输出。
总结下来，使用 BoundBlocks 与普通值应参考如下准则：
1. 在遍历 StreamField 或 StreamBlock (例如 ``{% for block in page.body %}``)时，将得到一系列 BoundBlocks 条目。
2. 对于 BoundBlock 对象实例, 使用 ``block.value`` 获取原始值。
3. 访问 StructBlock (例如 ``value.heading``) 子项返回原始值, 而要使用相关的 BoundBlock 时, 使用 ``value.bound_blocks.heading`` 格式。
4. ListBlock 是一个普通的 Python 列表; 遍历时返回原始值，而不是 BoundBlocks 条目。
5. StructBlock 和 StreamBlock 值是一至知道自已渲染模板的, 即使不在遍历的 BoundBlock 条目中。
.. _custom_editing_interfaces_for_structblock:
定制 ``StructBlock`` 编辑界面
---------------------------------------------
要改变 ``StructBlock`` 在页面编辑器上显示的方式，可以使用 ``form_classname`` 指定 CSS 风格
(通过 ``StructBlock`` 构造函数的关键字参数，或 ``Meta`` 子类的属性)， 设置后会用指定值覆盖缺省的 ``struct-block``:
.. code-block:: python
class PersonBlock(blocks.StructBlock):
first_name = blocks.CharBlock()
surname = blocks.CharBlock()
photo = ImageChooserBlock(required=False)
biography = blocks.RichTextBlock()
class Meta:
icon = 'user'
form_classname = 'person-block struct-block'
这个就可以为这个块设置特定的 CSS 样式 ``person-block``，参考 :ref:`insert_editor_css` 勾子说明。
.. Note::
Wagtail 编辑器已经内置了 ``struct-block`` 类以及其它相关元素的 CSS 样式定义。使用 ``form_classname`` 设定 ``StructBlock`` 时记得加上 ``struct-block`` 以简化定义内容。
如果要更进一步改变 HTML 标签，可以重写 ``Meta`` 子类的 ``form_template`` 属性，设定新的模板文件。模板中可以使用如下变量：
``children``
组成 ``StructBlock`` 所有子块的 ``OrderedDict``，字典内容是包含子块的``BoundBlock``。通常在模板中使用 ``render_form`` 来渲染他们。
``help_text``
块帮助文本。
``classname``
CCS 的样式类名，保存 ``form_classname`` 的值(缺省是 ``struct-block``)。
``block_definition``
这个块的 ``StructBlock`` 类实例。
``prefix``
块实例中表单的前缀，以保证各个表单中的标识是唯一的。
要增加其它的变量，可以重写块的 ``get_form_context`` 方法:
.. code-block:: python
class PersonBlock(blocks.StructBlock):
first_name = blocks.CharBlock()
surname = blocks.CharBlock()
photo = ImageChooserBlock(required=False)
biography = blocks.RichTextBlock()
def get_form_context(self, value, prefix='', errors=None):
context = super().get_form_context(value, prefix=prefix, errors=errors)
context['suggested_first_names'] = ['John', 'Paul', 'George', 'Ringo']
return context
class Meta:
icon = 'user'
form_template = 'myapp/block_forms/person.html'
.. _custom_value_class_for_structblock:
定制 ``StructBlock`` 的 value_class
--------------------------------------
要改变获取 ``StructBlock`` 值的方法，可以设置 ``value_class`` 属性 (通过 ``StructBlock`` 构造函数的关键字参数，或 ``Meta`` 子类的属性)
来重新定义获值的过程。
``value_class`` 必须是 ``StructValue`` 子类，任何附加的方法要取得子块原始值通过方法的 ``self`` 参数 (例如 ``self.get('my_block')``)。
例:
.. code-block:: python
from wagtail.core.models import Page
from wagtail.core.blocks import (
CharBlock, PageChooserBlock, StructValue, StructBlock, TextBlock, URLBlock)
class LinkStructValue(StructValue):
def url(self):
external_url = self.get('external_url')
page = self.get('page')
if external_url:
return external_url
elif page:
return page.url
class QuickLinkBlock(StructBlock):
text = CharBlock(label="link text", required=True)
page = PageChooserBlock(label="page", required=False)
external_url = URLBlock(label="external URL", required=False)
class Meta:
icon = 'site'
value_class = LinkStructValue
class MyPage(Page):
quick_links = StreamField([('links', QuickLinkBlock())], blank=True)
quotations = StreamField([('quote', StructBlock([
('quote', TextBlock(required=True)),
('page', PageChooserBlock(required=False)),
('external_url', URLBlock(required=False)),
], icon='openquote', value_class=LinkStructValue))], blank=True)
content_panels = Page.content_panels + [
StreamFieldPanel('quick_links'),
StreamFieldPanel('quotations'),
]
在模板中使用改变获取值的方法:
.. code-block:: html+django
{% load wagtailcore_tags %}
{% for quotation in page.quotations %}
{{ quotation.value.quote }}
{% endfor %}