编辑“︁Django自定义过滤器”︁（章节）

= Django自定义过滤器 =

'''Django自定义过滤器'''是Django模板系统中的一个高级功能，允许开发者扩展模板引擎的默认功能，创建可重用的数据处理逻辑。本文将从基础概念到实际应用逐步讲解如何创建和使用自定义过滤器。

== 概念介绍 ==
Django模板系统默认提供了一系列内置过滤器（如<code>lower</code>、<code>date</code>等），但开发者可能需要实现特定业务逻辑的过滤操作。自定义过滤器本质是一个Python函数，通过注册到模板库中，可以在模板中使用<code>\|</code>语法调用。

=== 核心特点 ===
* '''输入输出处理'''：接收一个值（和可选参数），返回处理后的结果
* '''模板语法集成'''：通过<code>\{\{ value\|filter_name:arg \}\}</code>格式调用
* '''可复用性'''：一次定义，全项目可用

== 创建步骤 ==
以下是创建自定义过滤器的完整流程：

=== 1. 创建模板标签目录 ===
在Django应用目录下创建<code>templatetags</code>目录，并添加<code>__init__.py</code>文件：
<syntaxhighlight lang="bash">
myapp/
├── templatetags/
│   ├── __init__.py
│   └── custom_filters.py
</syntaxhighlight>

=== 2. 编写过滤器函数 ===
在<code>custom_filters.py</code>中定义过滤器：
<syntaxhighlight lang="python">
from django import template

register = template.Library()

@register.filter(name='multiply')
def multiply(value, arg):
    """将输入值乘以参数"""
    try:
        return float(value) * float(arg)
    except (ValueError, TypeError):
        return ''
</syntaxhighlight>

=== 3. 模板中加载使用 ===
在模板文件中加载并使用：
<syntaxhighlight lang="django">
{% load custom_filters %}

\{\{ 5|multiply:3 \}\}  {# 输出：15 #}
</syntaxhighlight>

== 进阶用法 ==

=== 过滤器参数 ===
自定义过滤器最多接受2个参数：
* 管道符左侧的值（必需）
* 冒号后的参数（可选）

<syntaxhighlight lang="python">
@register.filter
def replace(value, old_new):
    """替换字符串中的字符"""
    old, new = old_new.split(',')
    return value.replace(old, new)
</syntaxhighlight>
使用方式：
<syntaxhighlight lang="django">
\{\{ "hello"|replace:"e,o" \}\}  {# 输出："hollo" #}
</syntaxhighlight>

=== 字符串过滤器 ===
处理字符串的常见案例：
<syntaxhighlight lang="python">
@register.filter(is_safe=True)
def truncate_middle(value, max_length=10):
    """将长字符串中间截断显示"""
    if len(value) <= max_length:
        return value
    part = (max_length - 3) // 2
    return f"{value[:part]}...{value[-part:]}"
</syntaxhighlight>

=== 日期处理 ===
扩展Django的日期格式化：
<syntaxhighlight lang="python">
from datetime import datetime

@register.filter
def days_since(value):
    """计算距今多少天"""
    if not value:
        return ""
    delta = datetime.now().date() - value
    return f"{delta.days}天前"
</syntaxhighlight>

== 安全考虑 ==
使用<code>is_safe=True</code>标记过滤器为安全HTML：
<syntaxhighlight lang="python">
@register.filter(is_safe=True)
def bold_first(value):
    """加粗第一个单词"""
    words = value.split(' ', 1)
    if len(words) > 1:
        return f"<strong>{words[0]}</strong> {words[1]}"
    return f"<strong>{value}</strong>"
</syntaxhighlight>

== 实际案例 ==

=== 电商价格处理 ===
<syntaxhighlight lang="python">
@register.filter
def format_price(value, currency="¥"):
    """格式化价格显示"""
    try:
        price = float(value)
        if price.is_integer():
            return f"{currency}{int(price)}"
        return f"{currency}{price:.2f}"
    except (ValueError, TypeError):
        return "价格无效"
</syntaxhighlight>
模板中使用：
<syntaxhighlight lang="django">
\{\{ product.price|format_price \}\}  {# 输出：¥199 #}
\{\{ product.price|format_price:"$" \}\}  {# 输出：$199.00 #}
</syntaxhighlight>

=== 权限检查过滤器 ===
<syntaxhighlight lang="python">
@register.filter
def has_permission(user, perm):
    """检查用户权限"""
    return user.has_perm(perm)
</syntaxhighlight>
模板中使用：
<syntaxhighlight lang="django">
{% if user|has_permission:"auth.delete_user" %}
    <button>删除用户</button>
{% endif %}
</syntaxhighlight>

== 调试技巧 ==
当过滤器不生效时，检查：
1. 是否创建了<code>templatetags</code>目录和<code>__init__.py</code>
2. 模板中是否使用<code>{% load %}</code>标签
3. 过滤器函数是否使用<code>@register.filter</code>装饰器
4. 服务器是否重启（开发模式下）

== 性能优化 ==
频繁使用的复杂过滤器可以考虑使用<code>@register.filter</code>的<code>expects_localtime</code>或<code>needs_autoescape</code>参数进行优化。

== 总结 ==
Django自定义过滤器是扩展模板功能的有力工具，通过本文的学习，您应该能够：
* 理解过滤器的基本工作原理
* 创建各种类型的自定义过滤器
* 在实际项目中应用过滤器解决特定问题
* 处理过滤器的安全性和性能问题

通过合理使用自定义过滤器，可以保持模板代码的简洁性和可维护性，同时实现复杂的显示逻辑。

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