Django模板中@register.filter等四类注册标签的差异解析

下面从定义、适用场景、实际代码示例三个维度，清晰区分这四个模板标签注册方式：

1. @register.filter #

• 核心特性：专门用于创建模板过滤器，对应的Python函数仅能接收1个（待处理变量）或2个（变量+可选参数）参数。
• 适用场景：对模板中的变量做格式化、转换或过滤，结果可直接用于模板的条件判断（比如{% if %}标签）。
• 示例：

  # app/templatetags/custom_tags.py
  from django import template
  register = template.Library()
  
  # 无参数过滤器：转大写
  @register.filter
  def to_upper(value):
      return value.upper()
  
  # 带参数过滤器：移除指定字符串
  @register.filter(name='cut')
  def cut_str(value, target):
      return value.replace(target, '')
  

  模板使用：

  {{ "hello"|to_upper }}  <!-- 输出：HELLO -->
  {{ "hello world"|cut:"world" }}  <!-- 输出：hello  -->
  {% if article.title|cut:"test" != "" %}
      <p>{{ article.title }}</p>
  {% endif %}
  

2. @register.simple_tag #

• 核心特性：创建通用的简单标签，对应的Python函数可接收任意数量的位置/关键字参数，返回内容直接渲染到模板中。
• 适用场景：执行独立的逻辑计算、数据查询，或生成固定格式的内容（比如当前时间、统计数据、自定义URL），结果一般不用于条件判断。
• 示例：

  @register.simple_tag
  def current_year():
      from datetime import datetime
      return datetime.now().year
  
  @register.simple_tag
  def build_breadcrumb(home, current):
      return f'<a href="/">{home}</a> > <span>{current}</span>'
  

  模板使用：

  版权所有 © {% current_year %}  <!-- 输出：版权所有 © 2024 -->
  {% build_breadcrumb "首页" "Python教程" %}  <!-- 输出面包屑HTML -->
  

3. @register.tag #

• 核心特性：最底层的标签注册方式，需要手动实现模板参数解析和渲染逻辑，灵活性拉满但开发成本最高。
• 适用场景：当filter和simple_tag无法满足复杂需求时使用，比如自定义带有特殊语法结构的标签（类似Django自带的{% for %}、{% if %}）。
• 示例：

  from django.template import Node, TemplateSyntaxError
  
  @register.tag(name='greet')
  def parse_greet(parser, token):
      # 解析模板中的参数格式，比如 {% greet "Alice" %}
      parts = token.split_contents()
      if len(parts) != 2:
          raise TemplateSyntaxError("{% greet %} 仅需一个参数")
      name = parts[1].strip('"')
      return GreetNode(name)
  
  # 自定义节点类处理渲染
  class GreetNode(Node):
      def __init__(self, name):
          self.name = name
      def render(self, context):
          return f"你好，{self.name}！"
  

  模板使用：

  {% greet "张三" %}  <!-- 输出：你好，张三！ -->
  

4. @register.inclusion_tag #

• 核心特性：通过渲染指定的子模板生成HTML片段，Python函数负责提供子模板所需的上下文数据，最终将渲染结果插入当前模板。
• 适用场景：复用结构固定但数据动态变化的HTML组件，比如用户卡片、导航栏、表单按钮（类似Django admin底部的操作按钮）。
• 示例：
  先创建子模板templates/templatetags/user_card.html：

  <div class="user-card">
      <h4>{{ user.username }}</h4>
      <p>邮箱：{{ user.email }}</p>
  </div>
  

  然后定义标签：

  @register.inclusion_tag('templatetags/user_card.html')
  def render_user_card(user):
      # 返回的字典作为子模板的上下文
      return {'user': user}
  

  模板使用：

  {% render_user_card request.user %}  <!-- 渲染出用户卡片的完整HTML -->
  

快速对比表 #

内容的提问来源于stack exchange，提问作者Super Kai - Kazuya Ito