# Django 3.2.11.dev 文档

# 通用日期视图

基于日期的通用视图，提供在 `django.views.generic.dates` 中，是用于显示基于日期数据的向下扩展页面的视图。

注解

本页的一些例子假定 `Article` 模型已在 `myapp/models.py` 中定义如下：

    from django.db import models
    from django.urls import reverse

    class Article(models.Model):
        title = models.CharField(max_length=200)
        pub_date = models.DateField()

        def get_absolute_url(self):
            return reverse('article-detail', kwargs={'pk': self.pk})

## `ArchiveIndexView`

class `ArchiveIndexView`

  一个按日期显示“最新”对象的顶层索引页。除非你将 `allow_future` 设置为 `True`，否则不包含日期在 未来 的对象。

  祖先（MRO）

  - `django.views.generic.list.MultipleObjectTemplateResponseMixin`
  - `django.views.generic.base.TemplateResponseMixin`
  - `django.views.generic.dates.BaseArchiveIndexView`
  - `django.views.generic.dates.BaseDateListView`
  - `django.views.generic.list.MultipleObjectMixin`
  - `django.views.generic.dates.DateMixin`
  - `django.views.generic.base.View`

  上下文

  除了 `django.views.generic.list.MultipleObjectMixin` （通过 `django.views.generic.dates.BaseDateListView`）提供的上下文外，模板的上下文将是：

  - `date_list`：一个 `QuerySet` 对象，包含根据 `queryset` 有对象可用的所有年份，以 `datetime.datetime` 对象表示，按降序排列。

  注意

  - 使用默认为 `latest` 的 `context_object_name`。
  - 使用默认为 `_archive` 的 `template_name_suffix`。
  - 默认情况下，按年提供 `date_list`，但可以使用 `date_list_period` 属性将其改为月或日。这也适用于所有子类视图。

  示例 myapp/urls.py：

      from django.urls import path
      from django.views.generic.dates import ArchiveIndexView

      from myapp.models import Article

      urlpatterns = [
          path('archive/',
               ArchiveIndexView.as_view(model=Article, date_field="pub_date"),
               name="article_archive"),
      ]

  示例 myapp/article_archive.html：

      <ul>
          {% for article in latest %}
              <li>{{ article.pub_date }}: {{ article.title }}</li>
          {% endfor %}
      </ul>

  这将输出所有文章。

## `YearArchiveView`

class `YearArchiveView`

  每年的存档页，显示某一年的所有可用月份。除非你把 `allow_future` 设置为 `True`，否则不显示日期在 未来 的对象。

  祖先（MRO）

  - `django.views.generic.list.MultipleObjectTemplateResponseMixin`
  - `django.views.generic.base.TemplateResponseMixin`
  - `django.views.generic.dates.BaseYearArchiveView`
  - `django.views.generic.dates.YearMixin`
  - `django.views.generic.dates.BaseDateListView`
  - `django.views.generic.list.MultipleObjectMixin`
  - `django.views.generic.dates.DateMixin`
  - `django.views.generic.base.View`
  `make_object_list`

    一个布尔值，用于指定是否检索今年的全部对象清单并将其传递给模板。如果 `True`，将向上下文提供对象清单。如果 `False`，将使用 `None` 查询集作为对象列表。默认情况下，这是 `False`。

  `get_make_object_list`()

    确定是否将对象列表作为上下文的一部分返回。默认返回 `make_object_list`。

  上下文

  除了 `django.views.generic.list.MultipleObjectMixin` （通过 `django.views.generic.dates.BaseDateListView`）提供的上下文外，模板的上下文将是：

  - `date_list`。一个 `QuerySet` 对象，包含根据 `queryset` 有对象可用的所有月份，以 `datetime.datetime` 对象表示，按升序排列。
  - `year`：一个 `date` 对象，代表特定年份。
  - `next_year`： 一个:class:~datetime.date 对象，根据 `allow_empty` 和 `allow_future`，表示下一年的第一天。
  - `previous_year`： 一个 `date` 对象，根据 `allow_empty` 和 `allow_future`，表示前一年的第一天。

  注意

  - 使用默认为 `_archive_year` 的 `template_name_suffix`。

  示例 myapp/views.py：

      from django.views.generic.dates import YearArchiveView

      from myapp.models import Article

      class ArticleYearArchiveView(YearArchiveView):
          queryset = Article.objects.all()
          date_field = "pub_date"
          make_object_list = True
          allow_future = True

  示例 myapp/urls.py：

      from django.urls import path

      from myapp.views import ArticleYearArchiveView

      urlpatterns = [
          path('<int:year>/',
               ArticleYearArchiveView.as_view(),
               name="article_year_archive"),
      ]

  示例 myapp/article_archive_year.html：

      <ul>
          {% for date in date_list %}
              <li>{{ date|date }}</li>
          {% endfor %}
      </ul>

      <div>
          <h1>All Articles for {{ year|date:"Y" }}</h1>
          {% for obj in object_list %}
              <p>
                  {{ obj.title }} - {{ obj.pub_date|date:"F j, Y" }}
              </p>
          {% endfor %}
      </div>

## `MonthArchiveView`

class `MonthArchiveView`

  每月的存档页，显示特定月份的所有对象。除非你把 `allow_future` 设置为 `True`，否则不显示日期在 未来 的对象。

  祖先（MRO）

  - `django.views.generic.list.MultipleObjectTemplateResponseMixin`
  - `django.views.generic.base.TemplateResponseMixin`
  - `django.views.generic.dates.BaseMonthArchiveView`
  - `django.views.generic.dates.YearMixin`
  - `django.views.generic.dates.MonthMixin`
  - `django.views.generic.dates.BaseDateListView`
  - `django.views.generic.list.MultipleObjectMixin`
  - `django.views.generic.dates.DateMixin`
  - `django.views.generic.base.View`

  上下文

  除了 `MultipleObjectMixin` （通过 `BaseDateListView`）提供的上下文外，模板的上下文将是：

  - `date_list`：一个 `QuerySet` 对象，根据 `queryset`，以 `datetime.datetime` 对象的形式表示，按升序排列，包含给定月份内有对象可用的所有日子。
  - `month`：一个 `date` 对象，代表指定月份。
  - `next_month`： 一个 `date` 对象，根据 `allow_empty` 和 `allow_future`，表示下个月的第一天。
  - `previous_month`： 一个 `date` 对象，根据 `allow_empty` 和 `allow_future`，表示前一个月的第一天。

  注意

  - 使用默认为 `_archive_month` 的 `template_name_suffix`。

  示例 myapp/views.py：

      from django.views.generic.dates import MonthArchiveView

      from myapp.models import Article

      class ArticleMonthArchiveView(MonthArchiveView):
          queryset = Article.objects.all()
          date_field = "pub_date"
          allow_future = True

  示例 myapp/urls.py：

      from django.urls import path

      from myapp.views import ArticleMonthArchiveView

      urlpatterns = [
          # Example: /2012/08/
          path('<int:year>/<int:month>/',
               ArticleMonthArchiveView.as_view(month_format='%m'),
               name="archive_month_numeric"),
          # Example: /2012/aug/
          path('<int:year>/<str:month>/',
               ArticleMonthArchiveView.as_view(),
               name="archive_month"),
      ]

  示例 myapp/article_archive_month.html：

      <ul>
          {% for article in object_list %}
              <li>{{ article.pub_date|date:"F j, Y" }}: {{ article.title }}</li>
          {% endfor %}
      </ul>

      <p>
          {% if previous_month %}
              Previous Month: {{ previous_month|date:"F Y" }}
          {% endif %}
          {% if next_month %}
              Next Month: {{ next_month|date:"F Y" }}
          {% endif %}
      </p>

## `WeekArchiveView`

class `WeekArchiveView`

  每周的档案页，显示某一周的所有对象。除非你将 `allow_future` 设置为 `True`，否则不显示日期在 未来 的对象。

  祖先（MRO）

  - `django.views.generic.list.MultipleObjectTemplateResponseMixin`
  - `django.views.generic.base.TemplateResponseMixin`
  - `django.views.generic.dates.BaseWeekArchiveView`
  - `django.views.generic.dates.YearMixin`
  - `django.views.generic.dates.WeekMixin`
  - `django.views.generic.dates.BaseDateListView`
  - `django.views.generic.list.MultipleObjectMixin`
  - `django.views.generic.dates.DateMixin`
  - `django.views.generic.base.View`

  上下文

  除了 `MultipleObjectMixin` （通过 `BaseDateListView`）提供的上下文外，模板的上下文将是：

  - `week`：一个 `date` 对象，表示指定星期的第一天。
  - `next_week`：一个 `date` 对象，根据 `allow_empty` 和 `allow_future`，表示下周的第一天。
  - `previous_week`：一个 `date` 对象，根据 `allow_empty` 和 `allow_future`，表示前一周的第一天。

  注意

  - 使用默认为 `_archive_week` 的 `template_name_suffix`。

  - `week_format` 属性是一个 `strptime()` 格式字符串，用于解析星期数。支持的值如下：

    - `'%U'`：根据美国的周制，一周从周日开始。这是默认值。

    - `'%W'`：与 `'%U'` 类似，但它假定一周从星期一开始。这与 ISO 8601 周号不同。

    - `'%V'` ： ISO 8601 周号，即一周开始于星期一。

      New in Django 3.2:

      增加了对 `'%V'` 周格式的支持。

  示例 myapp/views.py：

      from django.views.generic.dates import WeekArchiveView

      from myapp.models import Article

      class ArticleWeekArchiveView(WeekArchiveView):
          queryset = Article.objects.all()
          date_field = "pub_date"
          week_format = "%W"
          allow_future = True

  示例 myapp/urls.py：

      from django.urls import path

      from myapp.views import ArticleWeekArchiveView

      urlpatterns = [
          # Example: /2012/week/23/
          path('<int:year>/week/<int:week>/',
               ArticleWeekArchiveView.as_view(),
               name="archive_week"),
      ]

  示例 myapp/article_archive_week.html：

      <h1>Week {{ week|date:'W' }}</h1>

      <ul>
          {% for article in object_list %}
              <li>{{ article.pub_date|date:"F j, Y" }}: {{ article.title }}</li>
          {% endfor %}
      </ul>

      <p>
          {% if previous_week %}
              Previous Week: {{ previous_week|date:"W" }} of year {{ previous_week|date:"Y" }}
          {% endif %}
          {% if previous_week and next_week %}--{% endif %}
          {% if next_week %}
              Next week: {{ next_week|date:"W" }} of year {{ next_week|date:"Y" }}
          {% endif %}
      </p>

  在这个例子中，你输出的是周数。请记住，由 `date` 模板过滤器用 '`W'` 格式字符计算的星期数与 `strftime()` 和 `strptime()` 用 `'%W'` 格式字符串计算的星期数并不总是相同的。例如，对于 2015 年， `date` 输出的周数比 `strftime()` 输出的周数高 1。`date` 中的 `'%U'` `strftime()` 格式字符串没有等价物。因此，你应该避免使用 `date` 为 `WeekArchiveView` 生成 URL。

## `DayArchiveView`

class `DayArchiveView`

  一个显示某一天所有对象的日存档页面。未来的日子会抛出 404 错误，不管未来的日子是否有任何对象存在，除非你把 `allow_future` 设置为 `True`。

  祖先（MRO）

  - `django.views.generic.list.MultipleObjectTemplateResponseMixin`
  - `django.views.generic.base.TemplateResponseMixin`
  - `django.views.generic.dates.BaseDayArchiveView`
  - `django.views.generic.dates.YearMixin`
  - `django.views.generic.dates.MonthMixin`
  - `django.views.generic.dates.DayMixin`
  - `django.views.generic.dates.BaseDateListView`
  - `django.views.generic.list.MultipleObjectMixin`
  - `django.views.generic.dates.DateMixin`
  - `django.views.generic.base.View`

  上下文

  除了 `MultipleObjectMixin` （通过 `BaseDateListView`）提供的上下文外，模板的上下文将是：

  - `day`：一个 `date` 对象，代表指定的一天。
  - `next_day`：一个 `date` 对象，根据 `allow_empty` 和 `allow_future` 表示第二天。
  - `previous_day`：一个 `date` 对象，根据 `allow_empty` 和 `allow_future` 表示前一天。
  - `next_month`： 一个 `date` 对象，根据 `allow_empty` 和 `allow_future`，表示下个月的第一天。
  - `previous_month`： 一个 `date` 对象，根据 `allow_empty` 和 `allow_future`，表示前一个月的第一天。

  注意

  - 使用默认为 `_archive_day` 的 `template_name_suffix`。

  示例 myapp/views.py：

      from django.views.generic.dates import DayArchiveView

      from myapp.models import Article

      class ArticleDayArchiveView(DayArchiveView):
          queryset = Article.objects.all()
          date_field = "pub_date"
          allow_future = True

  示例 myapp/urls.py：

      from django.urls import path

      from myapp.views import ArticleDayArchiveView

      urlpatterns = [
          # Example: /2012/nov/10/
          path('<int:year>/<str:month>/<int:day>/',
               ArticleDayArchiveView.as_view(),
               name="archive_day"),
      ]

  示例 myapp/article_archive_day.html：

      <h1>{{ day }}</h1>

      <ul>
          {% for article in object_list %}
              <li>{{ article.pub_date|date:"F j, Y" }}: {{ article.title }}</li>
          {% endfor %}
      </ul>

      <p>
          {% if previous_day %}
              Previous Day: {{ previous_day }}
          {% endif %}
          {% if previous_day and next_day %}--{% endif %}
          {% if next_day %}
              Next Day: {{ next_day }}
          {% endif %}
      </p>

## `TodayArchiveView`

class `TodayArchiveView`

  一个显示 今天 所有对象的日存档页面。这和 `django.views.generic.dates.DayArchiveView` 完全一样，只是用今天的日期代替 `year`／`month`／`day` 参数。

  祖先（MRO）

  - `django.views.generic.list.MultipleObjectTemplateResponseMixin`
  - `django.views.generic.base.TemplateResponseMixin`
  - `django.views.generic.dates.BaseTodayArchiveView`
  - `django.views.generic.dates.BaseDayArchiveView`
  - `django.views.generic.dates.YearMixin`
  - `django.views.generic.dates.MonthMixin`
  - `django.views.generic.dates.DayMixin`
  - `django.views.generic.dates.BaseDateListView`
  - `django.views.generic.list.MultipleObjectMixin`
  - `django.views.generic.dates.DateMixin`
  - `django.views.generic.base.View`

  注意

  - 使用默认为 `_archive_today` 的 `template_name_suffix`。

  示例 myapp/views.py：

      from django.views.generic.dates import TodayArchiveView

      from myapp.models import Article

      class ArticleTodayArchiveView(TodayArchiveView):
          queryset = Article.objects.all()
          date_field = "pub_date"
          allow_future = True

  示例 myapp/urls.py：

      from django.urls import path

      from myapp.views import ArticleTodayArchiveView

      urlpatterns = [
          path('today/',
               ArticleTodayArchiveView.as_view(),
               name="archive_today"),
      ]

  `TodayArchiveView` 的示例模板在哪里？

  该视图默认使用与前面例子中的 `DayArchiveView` 相同的模板。如果你需要一个不同的模板，请将 `template_name` 属性设置为新模板的名称。

## `DateDetailView`

class `DateDetailView`

  一个页面代表一个单独的对象。如果对象有一个未来的日期值，除非你把 `allow_future` 设置为 `True`，否则视图会默认抛出 404 错误。

  祖先（MRO）

  - `django.views.generic.detail.SingleObjectTemplateResponseMixin`
  - `django.views.generic.base.TemplateResponseMixin`
  - `django.views.generic.dates.BaseDateDetailView`
  - `django.views.generic.dates.YearMixin`
  - `django.views.generic.dates.MonthMixin`
  - `django.views.generic.dates.DayMixin`
  - `django.views.generic.dates.DateMixin`
  - `django.views.generic.detail.BaseDetailView`
  - `django.views.generic.detail.SingleObjectMixin`
  - `django.views.generic.base.View`

  上下文

  - 包括与 `DateDetailView` 中指定的 `model` 相关的单个对象。

  注意

  - 使用默认为 `_detail` 的 `template_name_suffix`。

  示例 myapp/urls.py：

      from django.urls import path
      from django.views.generic.dates import DateDetailView

      urlpatterns = [
          path('<int:year>/<str:month>/<int:day>/<int:pk>/',
               DateDetailView.as_view(model=Article, date_field="pub_date"),
               name="archive_date_detail"),
      ]

  示例 myapp/article_detail.html：

      <h1>{{ object.title }}</h1>

注解

上面列出的所有通用视图都有匹配的 `Base` 视图，唯一不同的是它们不包括 `MultipleObjectTemplateResponseMixin`）用于存档视图）或 `SingleObjectTemplateResponseMixin` （用于 `DateDetailView`）。

class `BaseArchiveIndexView`

class `BaseYearArchiveView`

class `BaseMonthArchiveView`

class `BaseWeekArchiveView`

class `BaseDayArchiveView`

class `BaseTodayArchiveView`

class `BaseDateDetailView`