# Sélectionner des pages Comment désigner les pages sur lesquelles une action doit agir : les champs pages, page_order et groups, et la syntaxe de plages qu’ils partagent. Beaucoup d’actions n’agissent que sur une partie des pages d’un document. Vous décrivez cette partie avec une syntaxe de plages compacte : des numéros de page et des plages comptés à partir de 1 et séparés par des virgules, comme `1..3,5`. Les mêmes numéros et les mêmes plages se retrouvent dans toutes les actions, mais ils se lisent avec l’un de deux sens, comme un **ensemble** ou comme une **liste ordonnée**. Cette page est la référence unique pour les deux ; chaque action dotée d’un champ de pages renvoie ici. ## Deux sortes de sélection - Un champ **ensemble** (`pages`) répond à la question *quelles* pages. L’ordre et les doublons sont ignorés, et les pages sélectionnées sont toujours traitées dans l’ordre du document. - Un champ **ordonné** (`page_order`, ainsi que chaque groupe de `groups`) répond à la question *dans quelle séquence*. L’ordre et les répétitions comptent, et les pages ressortent exactement comme elles sont écrites. La syntaxe d’expression d’une plage est identique dans les deux cas. La différence tient uniquement à la manière dont le résultat est interprété. ## Sélection par ensemble : le champ `pages` Un champ `pages` est une liste, séparée par des virgules, de numéros de page et de plages comptés à partir de 1 : - Une seule page, par exemple `5`. - Une plage, par exemple `2..6` (les pages 2 à 6). - Une plage ouverte : `8..` va de la page 8 à la dernière page, et `..5` va de la première page à la page 5. - Un indice négatif compte depuis la fin : `-1` est la dernière page, `-2` l’avant-dernière. Les plages les acceptent aussi, si bien que `-3..-1` désigne les trois dernières pages. Un champ `pages` est traité comme un **ensemble** : l’ordre et les doublons sont ignorés, et les pages sont toujours traitées dans l’ordre du document. Le laisser vide sélectionne toutes les pages. | Motif | Sélectionne | | --------- | ------------------------------------------- | | *(omis)* | Toutes les pages | | `1` | La première page uniquement | | `2..6` | Les pages 2 à 6 | | `1..3,5` | Les pages 1, 2, 3 et 5 | | `8..` | De la page 8 à la dernière page | | `..5` | De la première page à la page 5 | | `..-2` | De la première page à l’avant-dernière | | `-1` | La dernière page | | `-3..-1` | Les trois dernières pages | Comme un ensemble ignore l’ordre, `5,1,2..3` et `1,2,3,5` sélectionnent exactement les mêmes pages, et les deux s’appliquent dans l’ordre du document. Certaines actions ajoutent une règle qui leur est propre : [Supprimer des pages](/docs/api/remove-pages-from-pdf), par exemple, doit laisser au moins une page, si bien qu’une sélection qui supprimerait toutes les pages est rejetée. ## Sélection ordonnée : `page_order` et `groups` Certaines entrées sont une liste **ordonnée** plutôt qu’un ensemble. Elles emploient les mêmes numéros et les mêmes plages que ci-dessus, mais l’ordre et les doublons y comptent : les pages ressortent exactement comme elles sont listées, une page nommée deux fois est émise deux fois, et toute page omise est écartée. Une plage peut aussi être décroissante, si bien que `10..5` descend de la page 10 à la page 5. - [`page_order`](/docs/api/reorder-pages-of-pdf) (utilisé par la réorganisation) est une seule liste ordonnée. `3,1,2` place la page 3 en premier, puis la 1, puis la 2. Comme les pages omises sont écartées et les répétitions conservées, la réorganisation fait aussi office d’extraction, de duplication et de réorganisation combinées. - [`groups`](/docs/api/split-pdf-into-page-groups) (utilisé par la division en groupes de pages) regroupe plusieurs listes ordonnées séparées par des `;`. Chaque groupe devient un PDF de sortie, et à l’intérieur d’un groupe les règles ordonnées s’appliquent. `2..8,29;1` produit deux documents : le premier avec les pages 2 à 8 puis 29, le second avec la page 1. ## Quel champ utilise chaque action | Champ | Sémantique | Actions | | --- | --- | --- | | `pages` | Ensemble | [Ajouter un filigrane texte](/docs/api/add-text-watermark-to-pdf), [Ajouter un filigrane image](/docs/api/add-image-watermark-to-pdf), [Extraire des pages](/docs/api/extract-pages-from-pdf), [Supprimer des pages](/docs/api/remove-pages-from-pdf), [Faire pivoter des pages](/docs/api/rotate-pages-in-pdf) | | `page_order` | Ordonné | [Réorganiser les pages](/docs/api/reorder-pages-of-pdf) | | `groups` | Ordonné, par groupe | [Diviser en groupes de pages](/docs/api/split-pdf-into-page-groups) | Prenez un champ ensemble quand le résultat est le même quelle que soit la séquence que vous écrivez, par exemple pour apposer un filigrane sur les pages 2, 4 et 6. Prenez un champ ordonné quand la séquence *est* le résultat, par exemple pour réorganiser ou répéter des pages. ## Les règles valables partout - Les numéros de page **commencent à 1**. Il n’existe pas de page `0`. - Les indices négatifs et les plages ouvertes fonctionnent aussi bien dans les champs ensemble que dans les champs ordonnés. - Une sélection qui référence une page au-delà du document, par exemple `12` dans un fichier de dix pages, est rejetée avec un `400`. Voir [Erreurs](/docs/api/errors).