--- title: "Pagination" version: 2.0 locale: fr source: https://docs.djangoproject.com/fr/2.0/topics/pagination/ canonical: https://djangodocs.dev/fr/2.0/topics/pagination/ --- # Pagination Django fournit quelques classes qui aident à effectuer de la pagination de données, c’est-à-dire des données qui sont partagées en plusieurs pages, avec des liens « Précédent/Suivant ». Ces classes se trouvent dans `django/core/paginator.py`. ## Exemple En donnant à [`Paginator`](#django.core.paginator.Paginator) une liste d’objets ainsi que le nombre d’éléments souhaités sur chaque page, cette classe vous offre des méthodes pour accéder aux éléments des différentes pages : ``` >>> from django.core.paginator import Paginator >>> objects = ['john', 'paul', 'george', 'ringo'] >>> p = Paginator(objects, 2) >>> p.count 4 >>> p.num_pages 2 >>> type(p.page_range) >>> p.page_range range(1, 3) >>> page1 = p.page(1) >>> page1 >>> page1.object_list ['john', 'paul'] >>> page2 = p.page(2) >>> page2.object_list ['george', 'ringo'] >>> page2.has_next() False >>> page2.has_previous() True >>> page2.has_other_pages() True >>> page2.next_page_number() Traceback (most recent call last): ... EmptyPage: That page contains no results >>> page2.previous_page_number() 1 >>> page2.start_index() # The 1-based index of the first item on this page 3 >>> page2.end_index() # The 1-based index of the last item on this page 4 >>> p.page(0) Traceback (most recent call last): ... EmptyPage: That page number is less than 1 >>> p.page(3) Traceback (most recent call last): ... EmptyPage: That page contains no results ``` > **Note** > > Remarquez que vous pouvez donner à `Paginator` une liste/tuple, un `QuerySet` Django ou tout autre objet possédant une méthode count()\` ou `__len__()`. Pour déterminer le nombre d’objets contenus dans l’objet transmis, `Paginator` essaie d’abord d’appeler `count()` et se rabat sur `len()` si l’objet en question n’a pas de méthode `count()`. Cela permet à des objets comme les `QuerySet` de Django d’utiliser une méthode `count()` plus efficace le cas échéant. ## Utilisation de `Paginator` dans une vue Voici un exemple un peu plus complexe qui utilise [`Paginator`](#django.core.paginator.Paginator) dans une vue pour paginer un résultat de requête. Nous présentons à la fois la vue et le gabarit correspondant pour vous montrer comment afficher les résultats. Cet exemple part du principe qu’il existe un modèle `Contacts` qui a déjà été importé. La fonction de vue ressemble à ceci : ``` from django.core.paginator import EmptyPage, PageNotAnInteger, Paginator from django.shortcuts import render def listing(request): contact_list = Contacts.objects.all() paginator = Paginator(contact_list, 25) # Show 25 contacts per page page = request.GET.get('page') contacts = paginator.get_page(page) return render(request, 'list.html', {'contacts': contacts}) ``` Dans le gabarit `list.html`, il est nécessaire d’inclure des éléments de navigation pour passer d’une page à l’autre, ainsi que des informations utiles sur les objets eux-mêmes : ```html+django {% for contact in contacts %} {# Each "contact" is a Contact model object. #} {{ contact.full_name|upper }}
... {% endfor %} ``` ## Objets `Paginator` Voici le constructeur de la classe [`Paginator`](#django.core.paginator.Paginator) : #### `class Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True)` ### Paramètres obligatoires **`object_list`** 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()`](/fr/2.0/ref/models/querysets/#django.db.models.query.QuerySet.order_by) ou avec un tri par défaut [`ordering`](/fr/2.0/ref/models/options/#django.db.models.Options.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. **`per_page`** Le nombre maximum d’éléments à inclure dans une page, sans tenir compte des orphelins (voir le paramètre facultatif `orphans` ci-dessous). ### Paramètres facultatifs **`orphans`** 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. **`allow_empty_first_page`** 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)` > **New in Django 2.0** Renvoie un objet [`Page`](#django.core.paginator.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. Elle ne produit une exception ([`EmptyPage`](#django.core.paginator.EmptyPage)) seulement si vous indiquez `Paginator(..., allow_empty_first_page=False)` et que `object_list` est vide. #### `Paginator.page(number)` Renvoie un objet [`Page`](#django.core.paginator.Page) correspondant à l’index `number` (commençant à 1). Si le numéro de page indiqué n’existe pas, une exception [`InvalidPage`](#django.core.paginator.InvalidPage) est levée. ### Attributs #### `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` de Django 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]`. ## Exceptions `InvalidPage` #### `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()`](#django.core.paginator.Paginator.page) lève une exception quand la page demandée n’est pas valable (par ex. ce n’est 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` Levée lorsque `page()` reçoit une valeur qui n’est pas un nombre entier. #### `exception EmptyPage` Levé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`](#django.core.paginator.InvalidPage), il est donc possible de les intercepter par une simple ligne `except InvalidPage`. ## Objets `Page` Les objets `Page` ne sont normalement pas construits manuellement, mais plutôt obtenus en appelant [`Paginator.page()`](#django.core.paginator.Paginator.page). #### `class Page(object_list, number, paginator)` Une page se comporte comme un liste de [`Page.object_list`](#django.core.paginator.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`](#django.core.paginator.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`](#django.core.paginator.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()`](#django.core.paginator.Page.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()`](#django.core.paginator.Page.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`](#django.core.paginator.Paginator) associé.