Django 常用过滤器案例演示

Django 模板过滤器（Template Filters）是对模板中变量进行处理的核心工具，语法为 {{ '{{' }} 变量|过滤器:参数 }}，支持链式调用（如 {{ '{{' }} var|lower|truncatechars:10 }}）。本文针对 18 个高频过滤器，提供「语法说明+实际案例+应用场景」，结合真实开发场景帮助理解记忆。

一、基础数据处理过滤器

1. cut - 移除指定字符

语法

{{ '{{' }} 字符串变量|cut:"要移除的字符" }}

说明

移除字符串中所有指定的单个字符（注意：不能移除多字符字符串，仅支持单个字符匹配）。

案例

<p>原始字符串：{{ '{{' }} "Hello, Django! 2025" }}</p>
<p>移除逗号：{{ '{{' }} "Hello, Django! 2025"|cut:"," }}</p>
<p>移除空格：{{ '{{' }} "Hello, Django! 2025"|cut:" " }}</p>

输出结果

原始字符串：Hello, Django! 2025
移除逗号：Hello Django! 2025
移除空格：Hello,Django!2025

应用场景

清理字符串中的特殊分隔符（如逗号、空格）、格式化用户输入的无意义字符。

2. default - 变量为空时显示默认值

语法

{{ '{{' }} 变量|default:"默认值" }}

说明

当变量为「空值」（None、空字符串 ""、空列表 []、空字典 {}、0、False）时，显示默认值；变量非空则显示原变量。

案例

<p>用户名：{{ '{{' }} username|default:"匿名用户" }}</p>
<p>年龄：{{ '{{' }} age|default:"未填写" }}</p>
<p>是否VIP：{{ '{{' }} is_vip|default:"普通用户" }}</p>
<p>地址：{{ '{{' }} address|default:"未设置" }}</p>

输出结果

用户名：匿名用户
年龄：0  
是否VIP：普通用户  
地址：未设置

应用场景

处理用户未填写的表单字段、默认显示占位内容（如匿名用户、未设置）。

3. default-if-none - 仅变量为 None 时显示默认值

语法

{{ '{{' }} 变量|default_if_none:"默认值" }}

说明

仅当变量严格为 None 时显示默认值；空字符串、0、False、空列表等「非 None 空值」不会触发，会显示原变量。

案例

<p>用户名：{{ '{{' }} username|default_if_none:"匿名用户" }}</p>
<p>年龄：{{ '{{' }} age|default_if_none:"未填写" }}</p>
<p>地址：{{ '{{' }} address|default_if_none:"未设置" }}</p>

输出结果

用户名：  
年龄：0  
地址：未设置  

应用场景

区分「用户主动填写为空」和「变量未定义（None）」的场景（如表单中用户主动留空 vs 未提交该字段）。

4. length - 获取变量长度

语法

{{ '{{' }} 变量|length }}

说明

返回变量的长度：字符串返回字符数、列表/元组/集合返回元素个数、字典返回键值对个数；None 返回 0。

案例

<p>字符串长度：{{ '{{' }} name|length }}</p>
<p>列表元素个数：{{ '{{' }} books|length }}</p>
<p>字典键值对个数：{{ '{{' }} user|length }}</p>
<p>空字符串长度：{{ '{{' }} empty_str|length }}</p>
<p>None 长度：{{ '{{' }} none_var|length }}</p>

输出结果

字符串长度：6
列表元素个数：3
字典键值对个数：2
空字符串长度：0
None 长度：0

应用场景

显示列表数据总数（如“共 3 本书”）、限制字符串长度前的判断、表单字段长度校验提示。

二、序列（列表/元组）处理过滤器

1. first - 获取序列第一个元素

语法

{{ '{{' }} 序列变量|first }}

说明

返回列表、元组、字符串的第一个元素；空序列或 None 返回空。

案例

<p>水果列表第一个元素：{{ '{{' }} fruits|first }}</p>
<p>空列表第一个元素：{{ '{{' }} empty_list|first }}</p>
<p>字符串第一个字符：{{ '{{' }} text|first }}</p>

输出结果

水果列表第一个元素：苹果
空列表第一个元素：
字符串第一个字符：H

应用场景

快速获取列表首项（如“最新文章：{{ articles|first }}”）、字符串首字符大写（配合 upper）。

2. last - 获取序列最后一个元素

语法

{{ '{{' }} 序列变量|last }}

说明

返回列表、元组、字符串的最后一个元素；空序列或 None 返回空。

案例

<p>水果列表最后一个元素：{{ '{{' }} fruits|last }}</p>
<p>字符串最后一个字符：{{ '{{' }} text|last }}</p>

输出结果

水果列表最后一个元素：橙子
字符串最后一个字符：o

应用场景

快速获取列表尾项（如“最后更新：{{ logs|last }}”）。

3. random - 从序列中随机取一个元素

语法

{{ '{{' }} 序列变量|random }}

说明

从非空列表、元组、字符串中随机返回一个元素；空序列返回空。

案例

<p>随机推荐水果：{{ '{{' }} fruits|random }}</p>
<p>随机取字符串字符：{{ '{{' }} text|random }}</p>

输出结果（每次刷新可能不同）

随机推荐水果：香蕉
随机取字符串字符：e

应用场景

随机推荐内容（如“今日推荐商品”“随机名言”）、测试环境随机生成测试数据。

4. slice - 序列切片（截取部分元素）

语法

{{ '{{' }} 序列变量|slice:"开始索引:结束索引:步长" }}

说明

• 语法与 Python 切片一致：[start:end:step]，左闭右开（包含 start，不包含 end）；
• 支持负数索引（如 -1 表示最后一个元素）；
• 字符串、列表、元组均可使用。

案例

<p>截取前3个元素：{{ '{{' }} nums|slice:":3" }}</p>
<p>截取索引2-4（含2不含4）：{{ '{{' }} nums|slice:"2:4" }}</p>
<p>倒序取元素：{{ '{{' }} nums|slice:"::-1" }}</p>
<p>字符串截取前5个字符：{{ '{{' }} text|slice:":5" }}</p>

输出结果

截取前3个元素：[1, 2, 3]
截取索引2-4（含2不含4）：[3, 4]
倒序取元素：[6, 5, 4, 3, 2, 1]
字符串截取前5个字符：Djang

应用场景

分页显示列表前 N 项（如“热门文章前 5 篇”）、截取长字符串预览、获取序列部分数据。

5. join - 用指定字符连接序列元素

语法

{{ '{{' }} 序列变量|join:"连接符" }}

说明

将列表、元组中的元素（必须是字符串或可转为字符串的类型）用指定连接符拼接成一个字符串；字典会连接键名。

案例

<p>标签拼接（逗号分隔）：{{ '{{' }} tags|join:"," }}</p>
<p>ID 拼接（横线分隔）：{{ '{{' }} ids|join:"-" }}</p>
<p>字典键名拼接：{{ '{{' }} user|join:"|" }}</p>

输出结果

标签拼接（逗号分隔）：Python,Django,Web
ID 拼接（横线分隔）：1-2-3
字典键名拼接：name|age

应用场景

显示多标签（如文章标签、商品分类）、拼接 ID 字符串（如“选中 ID：1-2-3”）。

三、字符串处理过滤器

1. upper - 字符串转为大写

语法

{{ '{{' }} 字符串变量|upper }}

说明

将字符串中所有小写字母转为大写；非字母字符不变。

案例

<p>原始字符串：{{ '{{' }} "Hello Django!" }}</p>
<p>转为大写：{{ '{{' }} "Hello Django!"|upper }}</p>

输出结果

原始字符串：Hello Django!
转为大写：HELLO DJANGO!

应用场景

统一字符串格式（如用户名大写显示、标题大写强调）。

2. lower - 字符串转为小写

语法

{{ '{{' }} 字符串变量|lower }}

说明

将字符串中所有大写字母转为小写；非字母字符不变。

案例

<p>原始字符串：{{ '{{' }} "HELLO DJANGO!" }}</p>
<p>转为小写：{{ '{{' }} "HELLO DJANGO!"|lower }}</p>

输出结果

原始字符串：HELLO DJANGO!
转为小写：hello django!

应用场景

统一用户输入格式（如邮箱地址小写存储前的显示、关键词搜索时的格式统一）。

3. stringtags - 移除字符串中的 HTML 标签

语法

{{ '{{' }} 字符串变量|striptags }}

说明

移除字符串中所有 HTML 标签（如 <p>、<a>、<script> 等），保留标签内的文本内容。

案例

<p>原始 HTML 文本：{{ '{{' }} html_text }}</p>
<p>移除标签后：{{ '{{' }} html_text|striptags }}</p>

输出结果

原始 HTML 文本：<h1>标题</h1><p>这是一段<span style='color:red'>带标签</span>的文本</p>
移除标签后：标题这是一段带标签的文本

应用场景

显示用户输入的富文本内容（避免 XSS 攻击）、提取 HTML 文本中的纯文字预览。

4. truncatechars - 按字符数截断字符串

语法

{{ '{{' }} 字符串变量|truncatechars:"最大字符数" }}

说明

• 截断字符串到指定字符数，末尾添加 ...（... 占 3 个字符，因此实际显示字符数 = 最大字符数 - 3）；
• 中文、英文、数字均按 1 个字符计算。

案例

<p>截断为 10 个字符：{{ '{{' }} long_text|truncatechars:10 }}</p>
<p>截断为 20 个字符：{{ '{{' }} long_text|truncatechars:20 }}</p>

输出结果

截断为 10 个字符：Django 是一个高...  
截断为 20 个字符：Django 是一个高效的 Python Web 开发...  

应用场景

列表页显示长文本预览（如文章摘要、商品描述）、限制表格中字符串长度避免布局错乱。

5. truncatechars_html - 按字符数截断带 HTML 标签的字符串

语法

{{ '{{' }} 带HTML的字符串变量|truncatechars_html:"最大字符数" }}

说明

• 与 truncatechars 类似，但会保留 HTML 标签结构（避免标签被截断导致页面错乱）；
• 仅计算标签内的文本字符数，HTML 标签本身不计算。

案例

<p>截断为 15 个字符：{{ '{{' }} html_long_text|truncatechars_html:15 }}</p>

输出结果

<p>Django 是一个<span style='color:blue'>高效的...</span></p>

应用场景

截断富文本内容（如带格式的文章摘要），避免 HTML 标签被截断导致页面样式错乱。

6. safe - 标记字符串为安全 HTML 内容

语法

{{ '{{' }} 字符串变量|safe }}

说明

• Django 模板默认会转义 HTML 特殊字符（如 < 转为 <、> 转为 >），防止 XSS 攻击；
• safe 过滤器会告诉 Django 该字符串是安全的，无需转义，直接作为 HTML 渲染。

案例

<p>未加 safe（默认转义）：{{ '{{' }} safe_html }}</p>
<p>加 safe（渲染为 HTML）：{{ '{{' }} safe_html|safe }}</p>
<p>危险脚本（即使加 safe，生产环境会被拦截）：{{ '{{' }} unsafe_html|safe }}</p>

输出结果

未加 safe（默认转义）：<a href='https://www.djangoproject.com'>Django 官网</a>
加 safe（渲染为 HTML）：Django 官网  
危险脚本（即使加 safe，生产环境会被拦截）：

应用场景

渲染可信的 HTML 内容（如管理员后台编辑的富文本、系统内置的 HTML 模板）；注意：不可用于用户输入的内容，避免 XSS 攻击。

四、日期与数字处理过滤器

1. date - 日期时间格式化

语法

{{ '{{' }} 日期变量|date:"格式化字符串" }}

说明

• 将 datetime 或 date 类型变量格式化为指定字符串；None 或无效日期返回空；
• 常用格式化字符：
  • Y：4 位年份（如 2025）、y：2 位年份（如 25）；
  • m：2 位月份（如 03）、n：1 位月份（如 3）；
  • d：2 位日期（如 05）、j：1 位日期（如 5）；
  • H：24 小时制（如 14）、h：12 小时制（如 02）；
  • i：2 位分钟（如 30）、s：2 位秒（如 59）；
  • D：星期缩写（如 Mon）、l：星期全称（如 Monday）。

案例

<p>默认格式：{{ '{{' }} create_time|date }}</p>
<p>年月日：{{ '{{' }} create_time|date:"Y-m-d" }}</p>
<p>年月日 时分秒：{{ '{{' }} create_time|date:"Y年m月d日 H:i:s" }}</p>
<p>带星期：{{ '{{' }} create_time|date:"Y-m-d l H:i" }}</p>

输出结果

默认格式：Mar 15, 2025
年月日：2025-03-15
年月日 时分秒：2025年03月15日 14:30:20
带星期：2025-03-15 Saturday 14:30

应用场景

显示文章发布时间、订单创建时间、活动开始时间等，统一日期格式。

2. floatformat - 浮点数格式化

语法

{{ '{{' }} 浮点数变量|floatformat:"小数位数" }}

说明

• 格式化浮点数，保留指定小数位数，自动四舍五入；
• 若小数位数为 0，仅显示整数部分（去除小数点后末尾的 0）；
• 若不指定小数位数（floatformat），默认保留 1 位小数。

案例

<p>默认保留1位小数：{{ '{{' }} price|floatformat }}</p>
<p>保留2位小数：{{ '{{' }} score|floatformat:2 }}</p>
<p>保留0位小数（整数）：{{ '{{' }} num|floatformat:0 }}</p>
<p>保留3位小数：{{ '{{' }} rate|floatformat:3 }}</p>

输出结果

默认保留1位小数：99.9
保留2位小数：85.46  
保留0位小数（整数）：100
保留3位小数：0.789

应用场景

显示价格、评分、比例等数字（如商品价格 99.90 元、用户评分 8.5 分）。

五、核心总结与使用技巧

1. 过滤器核心特性

• 链式调用：多个过滤器可叠加使用（如 {{ '{{' }} text|lower|truncatechars:10 }}）；
• 参数传递：带参数的过滤器用冒号 : 连接（如 date:"Y-m-d"），参数含空格需用引号包裹；
• 空值兼容：大部分过滤器对 None、空序列有兼容处理，不会报错。

2. 开发实战建议

• 优先使用过滤器处理模板数据，避免在视图中过度格式化（分离视图逻辑与显示逻辑）；
• 敏感场景（如用户输入的 HTML）慎用 safe 过滤器，必须使用时需先做 XSS 过滤；
• 日期格式化优先使用 date 过滤器，而非在视图中手动格式化（适配多语言、多时区）；
• 长文本截断优先使用 truncatechars_html（若含 HTML 标签），避免页面样式错乱。

3. 常见误区

• 混淆 default 和 default-if-none：记住“default 匹配所有空值，default-if-none 仅匹配 None”；
• cut 过滤器仅支持单个字符：如需移除多字符字符串，需自定义过滤器；
• safe 过滤器的滥用：用户输入的内容绝对不能直接用 safe 渲染，需通过富文本编辑器过滤危险标签。

通过以上案例，可覆盖 Django 开发中 90% 以上的过滤器使用场景。实际开发中，可根据需求组合使用过滤器，提高模板代码的简洁性和可维护性。如需更复杂的逻辑处理，可基于这些基础过滤器自定义扩展。