# 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).