如何为Wagtail StreamField的Document块定义自定义渲染模板

单项目快速实现 #

你可以通过以下3个步骤完成自定义渲染：

1. 给DocumentChooserBlock指定自定义渲染模板
   修改你的CustomPage模型中StreamField的定义，给文档块传入template参数：

class CustomPage(Page):
    body = StreamField(
        [("document", DocumentChooserBlock(template="blocks/document_pdf.html")),]
    )
    # 其余原有逻辑保持不变

2. 创建自定义渲染模板
   在你项目的templates目录下新建blocks/document_pdf.html文件，写入以下内容：

{% load wagtaildocs_tags %}
{% with document=value %}
{% if document.file_extension == 'pdf' %}
<!-- PDF内嵌容器，属性供JS组件读取 -->
<div class="pdf-embed-container" 
     data-pdf-url="{% doc_url document %}" 
     data-pdf-name="{{ document.title }}">
</div>
{% else %}
<!-- 非PDF文档保持默认链接渲染 -->
<a href="{% doc_url document %}" target="_blank">{{ document.title }}</a>
{% endif %}
{% endwith %}

3. 添加PDF渲染逻辑
   在你的页面模板中引入你选用的JS PDF组件，编写初始化代码，遍历所有pdf-embed-container容器，读取对应的PDF地址完成内嵌渲染即可。

如果你需要全局覆盖所有DocumentChooserBlock的渲染，不需要逐个修改Block定义，直接在项目templates目录下新建wagtaildocs/blocks/document_chooser.html文件，写入上述模板内容即可自动生效。

封装为通用Wagtail扩展 #

如果要发布为公共扩展，可以封装自定义Block类降低用户使用成本：

1. 定义继承自DocumentChooserBlock的自定义类

from wagtail.documents.blocks import DocumentChooserBlock

class PDFEmbeddableDocumentBlock(DocumentChooserBlock):
    def __init__(
        self,
        embed_pdf: bool = True,
        container_class: str = "pdf-embed-container",
        use_bundled_js: bool = True,
        **kwargs
    ):
        self.embed_pdf = embed_pdf
        self.container_class = container_class
        self.use_bundled_js = use_bundled_js
        super().__init__(**kwargs)

    def get_context(self, value, parent_context=None):
        context = super().get_context(value, parent_context)
        context.update({
            "embed_pdf": self.embed_pdf,
            "container_class": self.container_class,
            "use_bundled_js": self.use_bundled_js
        })
        return context

    class Meta:
        template = "wagtail_pdf_embed/blocks/document.html"
        icon = "doc-full"
        label = "文档（支持PDF内嵌）"

2. 封装配套资源
   将自定义模板、你选用的PDF JS组件、默认样式都打包到扩展包中，同时给用户预留自定义模板、禁用内置JS的配置项，适配不同项目的定制需求。用户安装扩展后只需将原有DocumentChooserBlock替换为你提供的PDFEmbeddableDocumentBlock即可直接使用。

内容的提问来源于stack exchange，提问作者Brylie Christopher Oxley