编辑“︁Django自定义模板标签”︁（章节）

= Django自定义模板标签 =

== 介绍 ==
'''Django自定义模板标签'''是Django模板系统的一项强大功能，允许开发者扩展模板语言的功能，创建可重用的模板组件。通过自定义标签，开发者可以封装复杂的逻辑，简化模板代码，提高可维护性。

在Django中，模板标签分为两类：
* '''简单标签（Simple Tags）'''：处理输入参数并返回字符串
* '''包含标签（Inclusion Tags）'''：渲染另一个模板片段

== 创建自定义标签的步骤 ==

=== 1. 创建templatetags目录 ===
首先在您的Django应用中创建<code>templatetags</code>目录，并添加<code>__init__.py</code>文件使其成为Python包：

<syntaxhighlight lang="bash">
myapp/
    __init__.py
    models.py
    templatetags/
        __init__.py
        custom_tags.py  # 自定义标签模块
    views.py
</syntaxhighlight>

=== 2. 注册标签 ===
在<code>custom_tags.py</code>中，您需要先导入必要的模块并注册标签库：

<syntaxhighlight lang="python">
from django import template

register = template.Library()
</syntaxhighlight>

== 简单标签示例 ==

=== 基本语法 ===
创建简单标签使用<code>@register.simple_tag</code>装饰器：

<syntaxhighlight lang="python">
@register.simple_tag
def current_time(format_string):
    from datetime import datetime
    return datetime.now().strftime(format_string)
</syntaxhighlight>

=== 模板中使用 ===
在模板中加载并使用自定义标签：

<syntaxhighlight lang="django">
{% load custom_tags %}

<p>当前时间: {% current_time "%Y-%m-%d %H:%M:%S" %}</p>
</syntaxhighlight>

'''输出示例'''：
<pre>
当前时间: 2023-11-15 14:30:45
</pre>

== 包含标签示例 ==

包含标签允许您渲染另一个模板片段，非常适合重复使用的UI组件。

=== 创建包含标签 ===
<syntaxhighlight lang="python">
@register.inclusion_tag('template_name.html')
def show_recent_posts(count=5):
    from myapp.models import Post
    posts = Post.objects.order_by('-created_at')[:count]
    return {'posts': posts}
</syntaxhighlight>

=== 创建模板片段 ===
创建<code>recent_posts.html</code>：

<syntaxhighlight lang="django">
<ul>
{% for post in posts %}
    <li><a href="{{ post.get_absolute_url }}">{{ post.title }}</a></li>
{% endfor %}
</ul>
</syntaxhighlight>

=== 使用包含标签 ===
<syntaxhighlight lang="django">
{% load custom_tags %}

<div class="sidebar">
    {% show_recent_posts 3 %}
</div>
</syntaxhighlight>

== 高级用法 ==

=== 处理上下文 ===
您可以通过<code>takes_context=True</code>访问模板上下文：

<syntaxhighlight lang="python">
@register.simple_tag(takes_context=True)
def url_replace(context, field, value):
    dict_ = context['request'].GET.copy()
    dict_[field] = value
    return dict_.urlencode()
</syntaxhighlight>

=== 使用示例 ===
<syntaxhighlight lang="django">
<a href="?{% url_replace 'page' page_obj.next_page_number %}">下一页</a>
</syntaxhighlight>

== 实际应用案例 ==

=== 案例1：动态导航菜单 ===
创建根据用户权限显示不同菜单项的自定义标签：

<syntaxhighlight lang="python">
@register.inclusion_tag('menu.html', takes_context=True)
def render_menu(context):
    request = context['request']
    items = [
        {'name': '首页', 'url': '/', 'visible': True},
        {'name': '管理', 'url': '/admin/', 'visible': request.user.is_staff}
    ]
    return {'menu_items': [item for item in items if item['visible']]}
</syntaxhighlight>

=== 案例2：Markdown渲染 ===
创建将Markdown转换为HTML的标签：

<syntaxhighlight lang="python">
import markdown

@register.filter
def markdown_to_html(text):
    return markdown.markdown(text)
</syntaxhighlight>

== 性能考虑 ==

* 自定义标签会被缓存，通常不需要担心性能问题
* 对于数据库查询，考虑使用<code>@register.simple_tag</code>的<code>cached</code>参数
* 复杂逻辑最好放在视图中，而不是模板标签中

== 最佳实践 ==

1. 保持标签功能单一
2. 为标签编写详细的文档字符串
3. 对输入参数进行验证
4. 为常用功能创建单元测试
5. 遵循Django的命名约定

== 常见问题 ==

'''Q: 为什么我的自定义标签不生效？'''
A: 确保：
* <code>templatetags</code>目录结构正确
* 已重启开发服务器
* 模板中正确使用了<code>{% load %}</code>标签

'''Q: 如何传递多个参数？'''
A: 简单标签可以接受多个参数，例如：
<syntaxhighlight lang="python">
@register.simple_tag
def my_tag(a, b, c):
    return f"{a}-{b}-{c}"
</syntaxhighlight>

== 总结 ==
Django自定义模板标签是扩展模板功能的强大工具。通过创建简单标签和包含标签，您可以：
* 减少模板中的重复代码
* 封装复杂逻辑
* 创建可重用的组件
* 保持模板简洁易读

掌握自定义标签将显著提高您的Django开发效率和代码质量。

[[Category:后端框架]]
[[Category:Django]]
[[Category:Django模板系统]]