• 3.0
  • 3.1
  • dev
  • Version de la documentation : 3.2

Pagination

Django propose quelques classes pour aider à gérer des données paginées, c’est-à-dire des données divisées en plusieurs pages avec des liens « Précédent/Suivant ». Ces classes se trouvent dans django/core/paginator.py.

For examples, see the Pagination topic guide.

Classe Paginator

class Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True)

Un paginateur se comporte comme une liste d’objets Page lorsqu’on lui applique len() ou qu’on itère directement sur lui.

Changed in Django 3.1:

La prise en charge de l’itération sur Paginator a été ajoutée.

Paginator.object_list

Obligatoire. Une liste, un tuple, un QuerySet ou tout autre objet segmentable et doté d’une méthode count() ou __len__(). Pour une pagination cohérente, les QuerySet doivent être triés, par ex. avec une clause order_by() ou avec un tri par défaut ordering sur le modèle.

Problèmes de performances avec la pagination de QuerySet volumineux

Si vous utilisez un QuerySet avec un très grand nombre d’éléments, la récupération de numéros de page élevés peut être lent avec certaines bases de données, car la requête LIMIT/OFFSET résultante a besoin de compter le nombre d’enregistrements OFFSET, ce qui prend plus de temps avec des numéros de page élevés.

Paginator.per_page

Obligatoire. Le nombre maximum d’éléments à inclure dans une page, sans tenir compte des orphelins (voir le paramètre facultatif orphans ci-dessous).

Paginator.orphans

Facultatif. Utilisez ce paramètre lorsque vous ne souhaitez pas de dernière page avec très peu d’éléments. Lorsque la dernière page ne contient que le nombre orphans d’éléments ou moins, ces éléments sont alors ajoutés à la page précédente (qui devient la dernière page) au lieu de les laisser seuls sur une page. Par exemple, avec 23 éléments, per_page=10 et orphans=3, il y aura deux pages ; la première avec 10 éléments et la seconde (et dernière) avec 13 éléments. orphans vaut zéro par défaut, ce qui signifie que les pages ne sont jamais jointes et que la dernière page peut ne posséder qu’un seul élément.

Paginator.allow_empty_first_page

Facultatif. Indique si la première page peut être vide. Avec la valeur False et une liste object_list vide, une erreur EmptyPage sera produite.

Méthodes

Paginator.get_page(number)

Renvoie un objet Page correspondant à l’index number (commençant à 1), en gérant également les numéros de page non valides ou hors limites.

Si la page n’est pas un nombre, la première page est renvoyée. Si le numéro de page est négatif ou plus grand que le nombre de pages, c’est la dernière page qui est renvoyée.

Ne produit une exception EmptyPage que si vous indiquez Paginator(..., allow_empty_first_page=False) et que object_list est vide.

Paginator.page(number)

Returns a Page object with the given 1-based index. Raises PageNotAnInteger if the number cannot be converted to an integer by calling int(). Raises InvalidPage if the given page number doesn’t exist.

Paginator.get_elided_page_range(number, *, on_each_side=3, on_ends=2)
New in Django 3.2.

Returns a 1-based list of page numbers similar to Paginator.page_range, but may add an ellipsis to either or both sides of the current page number when Paginator.num_pages is large.

The number of pages to include on each side of the current page number is determined by the on_each_side argument which defaults to 3.

The number of pages to include at the beginning and end of page range is determined by the on_ends argument which defaults to 2.

For example, with the default values for on_each_side and on_ends, if the current page is 10 and there are 50 pages, the page range will be [1, 2, '…', 7, 8, 9, 10, 11, 12, 13, '…', 49, 50]. This will result in pages 7, 8, and 9 to the left of and 11, 12, and 13 to the right of the current page as well as pages 1 and 2 at the start and 49 and 50 at the end.

Raises InvalidPage if the given page number doesn’t exist.

Attributs

Paginator.ELLIPSIS
New in Django 3.2.

A translatable string used as a substitute for elided page numbers in the page range returned by get_elided_page_range(). Default is '…'.

Paginator.count

Le nombre total d’objets sur toutes les pages.

Note

Lors de la détermination du nombre d’objets contenus dans object_list, Paginator essaie d’abord d’appeler object_list.count(). Si object_list n’a pas de méthode count(), Paginator se rabat sur len(object_list). Cela permet à des objets comme les QuerySet d’utiliser une méthode count() plus efficace le cas échéant.

Paginator.num_pages

Le nombre total de pages.

Paginator.page_range

Une itération d’intervalle de numéros de pages commençant à 1, par ex. produisant [1, 2, 3, 4].

Classe Page

Les objets Page ne sont normalement pas construits manuellement, mais plutôt obtenus en itérant sur Paginator ou en appelant Paginator.page().

class Page(object_list, number, paginator)

Une page se comporte comme un liste de Page.object_list lorsqu’on lui applique len() ou qu’on effectue une itération sur elle.

Méthodes

Page.has_next()

Renvoie True s’il existe une page suivante.

Page.has_previous()

Renvoie True s’il existe une page précédente.

Page.has_other_pages()

Renvoie True s’il existe une page suivante ou une page précédente.

Page.next_page_number()

Renvoie le prochain numéro de page. Génère InvalidPage s’il n’y a pas de page suivante.

Page.previous_page_number()

Renvoie le numéro de page précédent. Génère InvalidPage s’il n’y a pas de page précédente.

Page.start_index()

Renvoie l’index (commençant par 1) du premier objet de la page, relatif à tous les autres objets de la liste du paginateur. Par exemple, lors de la pagination d’une liste de 5 objets par groupes de 2, la méthode start_index() de la deuxième page renverrait 3.

Page.end_index()

Renvoie l’index (commençant par 1) du dernier objet de la page, relatif à tous les autres objets de la liste du paginateur. Par exemple, lors de la pagination d’une liste de 5 objets par groupes de 2, la méthode end_index() de la deuxième page renverrait 4.

Attributs

Page.object_list

La liste des objets de cette page.

Page.number

Le numéro de page (commençant par 1) de cette page.

Page.paginator

L’objet Paginator associé.

Exceptions

exception InvalidPage

Une classe de base pour les exceptions levées lorsqu’un paginateur reçoit un numéro de page non valable.

La méthode Paginator.page() lève une exception quand la page demandée n’est pas valable (par ex. pas un nombre entier) ou quand elle ne contient aucun objet. Il est généralement suffisant d’intercepter l’exception InvalidPage, mais si vous souhaitez plus de finesse, vous pouvez intercepter l’une des exceptions suivantes :

exception PageNotAnInteger

Générée lorsque page() reçoit une valeur qui n’est pas un nombre entier.

exception EmptyPage

Générée lorsque page() reçoit une valeur valable, mais que la page en question ne contient pas d’objet.

Ces deux exceptions sont des sous-classes de InvalidPage, il est donc possible de les intercepter toutes deux par une ligne except InvalidPage.

Back to Top