{"title":"自定义模板的后端","version":"3.1","locale":"zh-hans","docname":"howto/custom-template-backend","url":"/zh-hans/3.1/howto/custom-template-backend/","canonical":"https://djangodocs.dev/zh-hans/3.1/howto/custom-template-backend/","summary":"自定义后端 Link to this heading # 以下是如何实现一个在另一个模板系统中使用的自定义后端。一个模板后端是继承自后端基本类 django.template.backends.base.BaseEngine 。它必须实现 get_template() 和可选实现 from_string() 。以下是一个模拟…","html":"

自定义模板的后端Link to this heading#

\n
\n

自定义后端Link to this heading#

\n

以下是如何实现一个在另一个模板系统中使用的自定义后端。一个模板后端是继承自后端基本类 django.template.backends.base.BaseEngine 。它必须实现 get_template() 和可选实现 from_string() 。以下是一个模拟 foobar 模板库的例子。

\n
Code
from django.template import TemplateDoesNotExist, TemplateSyntaxError\nfrom django.template.backends.base import BaseEngine\nfrom django.template.backends.utils import csrf_input_lazy, csrf_token_lazy\n\nimport foobar\n\n\nclass FooBar(BaseEngine):\n\n    # Name of the subdirectory containing the templates for this engine\n    # inside an installed application.\n    app_dirname = 'foobar'\n\n    def __init__(self, params):\n        params = params.copy()\n        options = params.pop('OPTIONS').copy()\n        super().__init__(params)\n\n        self.engine = foobar.Engine(**options)\n\n    def from_string(self, template_code):\n        try:\n            return Template(self.engine.from_string(template_code))\n        except foobar.TemplateCompilationFailed as exc:\n            raise TemplateSyntaxError(exc.args)\n\n    def get_template(self, template_name):\n        try:\n            return Template(self.engine.get_template(template_name))\n        except foobar.TemplateNotFound as exc:\n            raise TemplateDoesNotExist(exc.args, backend=self)\n        except foobar.TemplateCompilationFailed as exc:\n            raise TemplateSyntaxError(exc.args)\n\n\nclass Template:\n\n    def __init__(self, template):\n        self.template = template\n\n    def render(self, context=None, request=None):\n        if context is None:\n            context = {}\n        if request is not None:\n            context['request'] = request\n            context['csrf_input'] = csrf_input_lazy(request)\n            context['csrf_token'] = csrf_token_lazy(request)\n        return self.template.render(context)\n
\n

请参阅 DEP 182 以获取更多信息。

\n
\n
\n

为自定义引擎集成调试功能Link to this heading#

\n

当模板有错误时Django调试页面会提供相应的钩子信息。自定义后端引擎能使用这些钩子来细化显示给用户的回溯信息。以下是可用的钩子：

\n
\n

模板剖析Link to this heading#

\n

当错误 TemplateDoesNotExist 发生时显示剖析。它会列举出尝试查找指定模板时使用的模板引擎和加载器。举个例子，如果配置了两个Django引擎，剖析显示如下：

\n\"/zh-hans/3.1/_images/postmortem.png\"\n

当 TemplateDoesNotExist 错误触发时自定义引擎会填写 后端 和 尝试 参数。使用剖析 :ref:` 的后端必须要指定模板对象上的一个来源 1` 。

\n
\n
\n

上下文信息Link to this heading#

\n

当模板解析或渲染时发生错误，Django会显示错误所在的行。举个例子：

\n\"/zh-hans/3.1/_images/template-lines.png\"\n

在解析或渲染异常中配置了 template_debug 属性的自定义引擎会显示这条信息。这个属性是一个有以下值的类 dict：

\n\n

根据上述模板错误， template_debug 会像这样：

\n
Code
{\n    'name': '/path/to/template.html',\n    'message': "Invalid block tag: 'syntax'",\n    'source_lines': [\n        (1, 'some\\n'),\n        (2, 'lines\\n'),\n        (3, 'before\\n'),\n        (4, 'Hello {% syntax error %} {{ world }}\\n'),\n        (5, 'some\\n'),\n        (6, 'lines\\n'),\n        (7, 'after\\n'),\n        (8, ''),\n    ],\n    'line': 4,\n    'before': 'Hello ',\n    'during': '{% syntax error %}',\n    'after': ' {{ world }}\\n',\n    'total': 9,\n    'bottom': 9,\n    'top': 1,\n}\n
\n
\n
\n

原始API和第3方集成Link to this heading#

\n

Django有一个可用 template.origin 属性的 Origin 基本对象类。这可以让调试信息显示在 :ref:`template 模板剖析上，同时支持第3方库，例如 `Django Debug Toolbar`_。

\n

自定义引擎可以通过创建有以下特定属性的对象来提供自身的 template.origin 信息。

\n\n
\n
","rootId":"custom-template-backend","toc":[{"title":"自定义后端","anchor":"custom-backends","children":[]},{"title":"为自定义引擎集成调试功能","anchor":"debug-integration-for-custom-engines","children":[{"title":"模板剖析","anchor":"template-postmortem","children":[]},{"title":"上下文信息","anchor":"contextual-line-information","children":[]},{"title":"原始API和第3方集成","anchor":"origin-api-and-3rd-party-integration","children":[]}]}],"breadcrumbs":[{"docname":"howto/index","title":"操作指南","url":"/zh-hans/3.1/howto/"}],"prev":{"docname":"howto/custom-lookups","title":"自定义查询器","url":"/zh-hans/3.1/howto/custom-lookups/"},"next":{"docname":"howto/custom-template-tags","title":"自定义模板标签和过滤器","url":"/zh-hans/3.1/howto/custom-template-tags/"},"formats":{"html":"/zh-hans/3.1/howto/custom-template-backend/","markdown":"/zh-hans/3.1/howto/custom-template-backend.md","json":"/zh-hans/3.1/howto/custom-template-backend.json"},"source":"https://github.com/django/django/blob/stable/3.1.x/docs/howto/custom-template-backend.txt","official":"https://docs.djangoproject.com/zh-hans/3.1/howto/custom-template-backend/","inVersions":["6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1"],"inLocales":["en","zh-hans","fr","ja","id","pt-br","ko","es","el","pl"]}