# Selecionar páginas Como indicar as páginas em que uma ação deve atuar: os campos pages, page_order e groups e a sintaxe de intervalos que eles compartilham. Muitas ações atuam sobre um subconjunto das páginas de um documento. Você descreve esse subconjunto com uma sintaxe compacta de intervalos: números de página com base 1 e intervalos separados por vírgulas, como `1..3,5`. Os mesmos números e intervalos aparecem em todas as ações, mas são lidos com um de dois sentidos: como um **conjunto** ou como uma **lista ordenada**. Esta página é a referência única para os dois; toda ação com um campo de páginas aponta para cá. ## Dois tipos de seleção - Um campo de **conjunto** (`pages`) responde *quais* páginas. A ordem e as duplicatas são ignoradas, e as páginas selecionadas são sempre processadas na ordem do documento. - Um campo **ordenado** (`page_order` e cada grupo em `groups`) responde *em que sequência*. A ordem e as repetições têm significado: as páginas saem exatamente como foram escritas. A sintaxe para expressar um intervalo é idêntica nos dois casos. A diferença está apenas em como o resultado é interpretado. ## Seleção por conjunto: o campo `pages` Um campo `pages` é uma lista separada por vírgulas de números de página com base 1 e de intervalos: - Uma única página, como `5`. - Um intervalo, como `2..6` (as páginas 2 a 6). - Um intervalo aberto: `8..` vai da página 8 até a última página, e `..5` vai da primeira página até a página 5. - Um índice negativo conta a partir do fim: `-1` é a última página, `-2` a penúltima. Os intervalos também os aceitam, então `-3..-1` são as três últimas páginas. Um campo `pages` é tratado como um **conjunto**: a ordem e as duplicatas são ignoradas, e as páginas são sempre processadas na ordem do documento. Deixá-lo vazio seleciona todas as páginas. | Padrão | Seleciona | | ----------- | -------------------------------------- | | *(omitir)* | Todas as páginas | | `1` | Apenas a primeira página | | `2..6` | As páginas 2 a 6 | | `1..3,5` | As páginas 1, 2, 3 e 5 | | `8..` | Da página 8 até a última página | | `..5` | Da primeira página até a página 5 | | `..-2` | Da primeira página até a penúltima | | `-1` | A última página | | `-3..-1` | As três últimas páginas | Como um conjunto ignora a ordem, `5,1,2..3` e `1,2,3,5` selecionam exatamente as mesmas páginas, e os dois são aplicados na ordem do documento. Algumas ações acrescentam uma regra própria: [Remover páginas](/docs/api/remove-pages-from-pdf), por exemplo, precisa deixar pelo menos uma página, então uma seleção que removeria todas as páginas é rejeitada. ## Seleção ordenada: `page_order` e `groups` Algumas entradas são uma lista **ordenada** em vez de um conjunto. Elas usam os mesmos números e intervalos de cima, mas aqui a ordem e as duplicatas importam: as páginas saem exatamente como foram listadas, uma página citada duas vezes é emitida duas vezes, e qualquer página deixada de fora é descartada. Um intervalo também pode ser decrescente, então `10..5` percorre da página 10 até a página 5. - [`page_order`](/docs/api/reorder-pages-of-pdf) (usado pela reordenação) é uma única lista ordenada. `3,1,2` coloca a página 3 primeiro, depois a 1 e depois a 2. Como as páginas omitidas são descartadas e as repetições são mantidas, a reordenação serve também como extração, duplicação e reordenação combinadas. - [`groups`](/docs/api/split-pdf-into-page-groups) (usado pela divisão em grupos de páginas) são várias listas ordenadas separadas por `;`. Cada grupo vira um PDF de saída e, dentro de um grupo, valem as regras de ordem. `2..8,29;1` produz dois documentos: o primeiro com as páginas 2 a 8 e depois a 29, o segundo com a página 1. ## Qual campo cada ação usa | Campo | Semântica | Ações | | --- | --- | --- | | `pages` | Conjunto | [Adicionar marca-d’água de texto](/docs/api/add-text-watermark-to-pdf), [Adicionar marca-d’água de imagem](/docs/api/add-image-watermark-to-pdf), [Extrair páginas](/docs/api/extract-pages-from-pdf), [Remover páginas](/docs/api/remove-pages-from-pdf), [Girar páginas](/docs/api/rotate-pages-in-pdf) | | `page_order` | Ordenado | [Reordenar páginas](/docs/api/reorder-pages-of-pdf) | | `groups` | Ordenado, por grupo | [Dividir em grupos de páginas](/docs/api/split-pdf-into-page-groups) | <Tip> Recorra a um campo de conjunto quando o resultado é o mesmo qualquer que seja a sequência que você escreve: carimbar uma marca-d’água nas páginas 2, 4 e 6. Recorra a um campo ordenado quando a sequência *é* o resultado: rearranjar ou repetir páginas. </Tip> ## Regras que valem em todo lugar - Os números de página têm **base 1**. Não existe página `0`. - Índices negativos e intervalos abertos funcionam tanto em campos de conjunto quanto em campos ordenados. - Uma seleção que faz referência a uma página além do documento, como `12` em um arquivo de dez páginas, é rejeitada com um `400`. Consulte [Erros](/docs/api/errors).