Django provides a few classes that help you manage paginated data -- that is, data that's split across several pages, with "Previous/Next" links. These classes live in django/core/paginator.py.
Paginator
classPaginator
(object_list, per_page, orphans=0, allow_empty_first_page=True)A paginator acts like a sequence of Page
when using len()
or
iterating it directly.
Support for iterating over Paginator
was added.
Paginator.
object_list
Required. A list, tuple, QuerySet
, or other sliceable object with a
count()
or __len__()
method. For consistent pagination,
QuerySet
s should be ordered, e.g. with an
order_by()
clause or with a default
ordering
on the model.
Performance issues paginating large QuerySet
s
If you're using a QuerySet
with a very large number of items,
requesting high page numbers might be slow on some databases, because
the resulting LIMIT
/OFFSET
query needs to count the number of
OFFSET
records which takes longer as the page number gets higher.
Paginator.
per_page
orphans
optional argument below).Paginator.
orphans
orphans
, then those items will be added to the previous page (which becomes the last page) instead of leaving the items on a page by themselves. For example, with 23 items, per_page=10
, and orphans=3
, there will be two pages; the first page with 10 items and the second (and last) page with 13 items. orphans
defaults to zero, which means pages are never combined and the last page may have one item.Paginator.
allow_empty_first_page
False
and object_list
is empty, then an EmptyPage
error will be raised.Paginator.
get_page
(number)Returns a Page
object with the given 1-based index, while also
handling out of range and invalid page numbers.
If the page isn't a number, it returns the first page. If the page number is negative or greater than the number of pages, it returns the last page.
Raises an EmptyPage
exception only if you specify
Paginator(..., allow_empty_first_page=False)
and the object_list
is
empty.
Paginator.
page
(number)Page
object with the given 1-based index. Raises InvalidPage
if the given page number doesn't exist.
Paginator.
count
The total number of objects, across all pages.
注解
When determining the number of objects contained in object_list
,
Paginator
will first try calling object_list.count()
. If
object_list
has no count()
method, then Paginator
will
fall back to using len(object_list)
. This allows objects, such as
QuerySet
, to use a more efficient count()
method when
available.
Paginator.
num_pages
Paginator.
page_range
[1, 2, 3, 4]
.
Page
classYou usually won't construct Page
objects by hand -- you'll get them by
iterating Paginator
, or by using Paginator.page()
.
Page
(object_list, number, paginator)Page.object_list
when using len()
or iterating it directly.Page.
has_next
()True
if there's a next page.Page.
has_previous
()True
if there's a previous page.Page.
has_other_pages
()True
if there's a next or previous page.Page.
next_page_number
()InvalidPage
if next page doesn't exist.Page.
previous_page_number
()InvalidPage
if previous page doesn't exist.Page.
start_index
()start_index()
would return 3
.Page.
end_index
()end_index()
would return 4
.
InvalidPage
The Paginator.page()
method raises an exception if the requested page is
invalid (i.e. not an integer) or contains no objects. Generally, it's enough
to catch the InvalidPage
exception, but if you'd like more granularity,
you can catch either of the following exceptions:
PageNotAnInteger
page()
is given a value that isn't an integer.EmptyPage
page()
is given a valid value but no objects exist on that page.Both of the exceptions are subclasses of InvalidPage
, so you can handle
them both with except InvalidPage
.