平面应用程序

Django 带有一个可选的“flatpages”应用程序。它允许您将“平面”HTML 内容存储在数据库中，并通过 Django 的管理界面和 Python API 为您处理管理。

平面页面是具有 URL、标题和内容的对象。将它用于一次性的特殊情况页面，例如“关于”或“隐私政策”页面，您希望将这些页面存储在数据库中，但又不想为其开发自定义 Django 应用程序。

平面页面可以使用自定义模板或默认的、系统范围的平面页面模板。它可以与一个或多个站点相关联。

如果您更愿意将内容放在自定义模板中，则可以选择将内容字段留空。

安装

要安装 flatpages 应用程序，请按照下列步骤操作：

通过将 'django.contrib.sites' 添加到您的 :setting:`INSTALLED_APPS` 设置来安装站点框架，如果它不在那里的话。

还要确保您已将 :setting:`SITE_ID` 正确设置为设置文件所代表的站点的 ID。这通常是 1（即 SITE_ID = 1，但是如果您使用站点框架来管理多个站点，则它可能是不同站点的 ID。
将 'django.contrib.flatpages' 添加到您的 :setting:`INSTALLED_APPS` 设置。

然后：

在您的 URLconf 中添加一个条目。例如：

urlpatterns = [
    path('pages/', include('django.contrib.flatpages.urls')),
]

或：

将 'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware' 添加到您的 :setting:`MIDDLEWARE` 设置。
运行命令 :djadmin:`manage.py 迁移 ` .

工作原理

manage.py migrate 在您的数据库中创建两个表：django_flatpage 和 django_flatpage_sites。 django_flatpage 是一个查找表，将 URL 映射到标题和一堆文本内容。 django_flatpage_sites 将平面页面与站点相关联。

使用 URLconf

有几种方法可以在 URLconf 中包含平面页面。您可以将特定路径专用于平面页面：

urlpatterns = [
    path('pages/', include('django.contrib.flatpages.urls')),
]

您也可以将其设置为“catchall”模式。在这种情况下，将模式放在其他 urlpatterns 的末尾很重要：

from django.contrib.flatpages import views

# Your other patterns here
urlpatterns += [
    re_path(r'^(?P<url>.*/)$', views.flatpage),
]

警告

如果您将 :setting:`APPEND_SLASH` 设置为 False，您必须删除笼统模式中的斜线，否则没有尾部斜线的平面将无法匹配。

另一种常见的设置是对有限的一组已知页面使用平面页面并对 url 进行硬编码，因此您可以使用 :ttag:`url` 模板标签来引用它们：

from django.contrib.flatpages import views

urlpatterns += [
    path('about-us/', views.flatpage, {'url': '/about-us/'}, name='about'),
    path('license/', views.flatpage, {'url': '/license/'}, name='license'),
]

使用中间件

FlatpageFallbackMiddleware 可以完成所有工作。

class FlatpageFallbackMiddleware

每次任何 Django 应用程序引发 404 错误时，该中间件都会检查 flatpages 数据库以查找所请求的 URL 作为最后的手段。具体来说，它会检查具有与 :setting:`SITE_ID` 设置对应的站点 ID 的给定 URL 的平面页面。

如果找到匹配项，则遵循以下算法：

如果平面页面有自定义模板，它会加载该模板。否则，它会加载模板 flatpages/default.html。
它向该模板传递一个单一的上下文变量 flatpage，它是 flatpage 对象。它使用 RequestContext 来渲染模板。

如果结果 URL 指向有效的平面页面，中间件只会添加尾部斜杠和重定向（通过查看 :setting:`APPEND_SLASH` 设置）。重定向是永久性的（301 状态代码）。

如果未找到匹配项，则继续照常处理请求。

中间件仅在 404 秒内被激活——而不是 500 秒或任何其他状态代码的响应。

Flatpages 不会应用视图中间件

因为 FlatpageFallbackMiddleware 仅在 URL 解析失败并产生 404 后才应用，所以它返回的响应不会应用任何视图中间件方法。只有通过正常 URL 解析成功路由到视图的请求才会应用视图中间件。

注意 :setting:`MIDDLEWARE` 的顺序很重要。通常，您可以将 FlatpageFallbackMiddleware 放在列表的末尾。这意味着它将在处理响应时首先运行，并确保任何其他响应处理中间件看到真正的平面响应而不是 404。

有关中间件的更多信息，请阅读中间件文档。

确保您的 404 模板有效

请注意，FlatpageFallbackMiddleware 仅在另一个视图成功生成 404 响应后才会介入。如果另一个视图或中间件类尝试生成 404 但最终引发异常，则响应将变为 HTTP 500（“内部服务器错误”）并且 FlatpageFallbackMiddleware 将不会尝试提供平面页面.

如何添加、更改和删除平面页面

通过管理界面

如果您已激活自动 Django 管理界面，您应该会在管理索引页面上看到“Flatpages”部分。在编辑系统中的任何其他对象时编辑平面。

FlatPage 模型具有 contrib.flatpages 不使用的 enable_comments 字段，但这可能对您的项目或第三方应用程序有用。它不会出现在管理界面中，但是您可以通过为 FlatPage 注册一个自定义的 ModelAdmin 来添加它：

from django.contrib import admin
from django.contrib.flatpages.admin import FlatPageAdmin
from django.contrib.flatpages.models import FlatPage
from django.utils.translation import gettext_lazy as _

# Define a new FlatPageAdmin
class FlatPageAdmin(FlatPageAdmin):
    fieldsets = (
        (None, {'fields': ('url', 'title', 'content', 'sites')}),
        (_('Advanced options'), {
            'classes': ('collapse',),
            'fields': (
                'enable_comments',
                'registration_required',
                'template_name',
            ),
        }),
    )

# Re-register FlatPageAdmin
admin.site.unregister(FlatPage)
admin.site.register(FlatPage, FlatPageAdmin)

通过 Python API

class FlatPage: Flatpages 由标准的 Django 模型表示，该模型位于 :source:`django/contrib/flatpages/models.py`。您可以通过 Django 数据库 API 访问平面对象。

检查重复的平面页面 URL。

如果您通过自己的代码添加或修改平面页面，您可能需要检查同一站点中是否存在重复的平面页面 URL。 admin 中使用的 flatpage 表单执行此验证检查，可以从 django.contrib.flatpages.forms.FlatpageForm 导入并在您自己的视图中使用。

平面模板

默认情况下，平面页面通过模板 flatpages/default.html 呈现，但您可以为特定的平面页面覆盖它：在管理员中，标题为“高级选项”的折叠字段集（单击将展开它）包含一个字段，用于指定模板名称。如果您通过 Python API 创建平面页面，您可以将模板名称设置为 FlatPage 对象上的字段 template_name。

创建 flatpages/default.html 模板是您的责任；在您的模板目录中，创建一个包含文件 default.html 的 flatpages 目录。

Flatpage 模板被传递一个单一的上下文变量，flatpage，它是 flatpage 对象。

这是一个示例 flatpages/default.html 模板：

<!DOCTYPE html>
<html>
<head>
<title>{{ flatpage.title }}</title>
</head>
<body>
{{ flatpage.content }}
</body>
</html>

由于您已经将原始 HTML 输入到管理页面的平面页面中，因此 flatpage.title 和 flatpage.content 都被标记为 而不是 ，需要自动 HTML 转义在模板中。

获取模板中的 FlatPage 对象列表

flatpages 应用程序提供了一个模板标签，允许您遍历当前站点上所有可用的平面页面。

与所有自定义模板标签一样，您需要加载其自定义标签库才能使用它。加载库后，您可以通过 :ttag:`get_flatpages` 标签检索所有当前平面页面：

{% load flatpages %}
{% get_flatpages as flatpages %}
<ul>
    {% for page in flatpages %}
        <li><a href="{{ page.url }}">{{ page.title }}</a></li>
    {% endfor %}
</ul>

显示 registration_required 平面

默认情况下，:ttag:`get_flatpages` 模板标签将只显示标记为 registration_required = False 的平面页面。如果要显示受注册保护的平面页面，则需要使用 for 子句指定经过身份验证的用户。

例如：

{% get_flatpages for someuser as about_pages %}

如果您提供匿名用户，:ttag:`get_flatpages` 的行为与您未提供用户的行为相同——即，它只会向您显示公共平面页面。

通过基本 URL 限制平面页面

可选参数 starts_with 可用于将返回的页面限制为以特定基本 URL 开头的页面。此参数可以作为字符串传递，也可以作为要从上下文解析的变量传递。

例如：

{% get_flatpages '/about/' as about_pages %}
{% get_flatpages about_prefix as about_pages %}
{% get_flatpages '/about/' for someuser as about_pages %}

与 django.contrib.sitemaps 集成

class FlatPageSitemap: sitemaps.FlatPageSitemap 类查看为当前 :setting:`SITE_ID` 定义的所有公开可见的 flatpages（参见 sites 文档 ) 并在站点地图中创建一个条目。这些条目仅包括 location 属性 - 不包括 lastmod、changefreq 或 priority。

示例

这是使用 FlatPageSitemap 的 URLconf 示例：

from django.contrib.flatpages.sitemaps import FlatPageSitemap
from django.contrib.sitemaps.views import sitemap
from django.urls import path

urlpatterns = [
    # ...

    # the sitemap
    path('sitemap.xml', sitemap,
        {'sitemaps': {'flatpages': FlatPageSitemap}},
        name='django.contrib.sitemaps.views.sitemap'),
]

flatpages 应用程序 — Django 文档