# Selezionare le pagine Come indicare le pagine su cui un’azione deve agire: i campi pages, page_order e groups e la sintassi di intervallo che condividono. Molte azioni agiscono su un sottoinsieme delle pagine di un documento. Quel sottoinsieme si descrive con una sintassi di intervallo compatta: numeri di pagina in base 1 e intervalli, separati da virgole, come `1..3,5`. Gli stessi numeri e gli stessi intervalli compaiono in tutte le azioni, ma si leggono con uno di due significati: come **insieme** oppure come **elenco ordinato**. Questa pagina è il riferimento unico per entrambi; ogni azione dotata di un campo di pagine rimanda qui. ## Due tipi di selezione - Un campo **insieme** (`pages`) risponde alla domanda *quali* pagine. L’ordine e i duplicati vengono ignorati e le pagine selezionate vengono sempre elaborate seguendo l’ordine del documento. - Un campo **ordinato** (`page_order`, e ogni gruppo di `groups`) risponde alla domanda *in quale sequenza*. L’ordine e le ripetizioni contano: le pagine escono esattamente come sono scritte. La sintassi con cui si esprime un intervallo è identica in entrambi i casi. La differenza sta soltanto nel modo in cui il risultato viene interpretato. ## Selezione per insieme: il campo `pages` Un campo `pages` è un elenco di numeri di pagina in base 1 e di intervalli, separati da virgole: - Una singola pagina, ad esempio `5`. - Un intervallo, ad esempio `2..6` (dalla pagina 2 alla pagina 6). - Un intervallo aperto: `8..` va dalla pagina 8 all’ultima pagina e `..5` va dalla prima pagina alla pagina 5. - Un indice negativo conta a partire dalla fine: `-1` è l’ultima pagina, `-2` la penultima. Anche gli intervalli li accettano, quindi `-3..-1` indica le ultime tre pagine. Un campo `pages` è trattato come un **insieme**: l’ordine e i duplicati vengono ignorati e le pagine vengono sempre elaborate seguendo l’ordine del documento. Lasciandolo vuoto si selezionano tutte le pagine. | Schema | Seleziona | | ---------- | ------------------------------------------ | | *(omesso)* | Tutte le pagine | | `1` | Solo la prima pagina | | `2..6` | Dalla pagina 2 alla pagina 6 | | `1..3,5` | Le pagine 1, 2, 3 e 5 | | `8..` | Dalla pagina 8 all’ultima pagina | | `..5` | Dalla prima pagina alla pagina 5 | | `..-2` | Dalla prima pagina alla penultima | | `-1` | L’ultima pagina | | `-3..-1` | Le ultime tre pagine | Poiché un insieme è privo di ordine, `5,1,2..3` e `1,2,3,5` selezionano esattamente le stesse pagine ed entrambi vengono applicati seguendo l’ordine del documento. Alcune azioni aggiungono una regola propria: [Rimuovere pagine](/docs/api/remove-pages-from-pdf), per esempio, deve lasciare almeno una pagina, quindi una selezione che rimuoverebbe tutte le pagine viene rifiutata. ## Selezione ordinata: `page_order` e `groups` Alcuni input sono un elenco **ordinato** anziché un insieme. Usano gli stessi numeri e gli stessi intervalli visti sopra, ma qui l’ordine e i duplicati contano: le pagine escono esattamente come sono elencate, una pagina indicata due volte viene emessa due volte e ogni pagina omessa viene scartata. Un intervallo può anche essere decrescente, quindi `10..5` scende dalla pagina 10 alla pagina 5. - [`page_order`](/docs/api/reorder-pages-of-pdf) (usato dal riordino) è un unico elenco ordinato. `3,1,2` mette per prima la pagina 3, poi la 1, poi la 2. Poiché le pagine omesse vengono scartate e le ripetizioni vengono conservate, il riordino funge anche da estrazione, duplicazione e riordino in una sola operazione. - [`groups`](/docs/api/split-pdf-into-page-groups) (usato dalla divisione in gruppi di pagine) è formato da più elenchi ordinati separati da `;`. Ogni gruppo diventa un PDF di output e, all’interno di un gruppo, valgono le regole ordinate. `2..8,29;1` produce due documenti: il primo con le pagine da 2 a 8 e poi la 29, il secondo con la pagina 1. ## Quale campo usa ogni azione | Campo | Semantica | Azioni | | --- | --- | --- | | `pages` | Insieme | [Aggiungere una filigrana di testo](/docs/api/add-text-watermark-to-pdf), [Aggiungere una filigrana immagine](/docs/api/add-image-watermark-to-pdf), [Estrarre pagine](/docs/api/extract-pages-from-pdf), [Rimuovere pagine](/docs/api/remove-pages-from-pdf), [Ruotare le pagine](/docs/api/rotate-pages-in-pdf) | | `page_order` | Ordinato | [Riordinare le pagine](/docs/api/reorder-pages-of-pdf) | | `groups` | Ordinato, per gruppo | [Dividere in gruppi di pagine](/docs/api/split-pdf-into-page-groups) | Conviene un campo insieme quando il risultato è lo stesso a prescindere dalla sequenza che si scrive: apporre una filigrana sulle pagine 2, 4 e 6. Conviene un campo ordinato quando la sequenza *è* il risultato: riorganizzare o ripetere le pagine. ## Regole valide ovunque - I numeri di pagina sono **in base 1**. Non esiste una pagina `0`. - Gli indici negativi e gli intervalli aperti funzionano sia nei campi insieme sia nei campi ordinati. - Una selezione che fa riferimento a una pagina oltre la fine del documento, ad esempio `12` in un file di dieci pagine, viene rifiutata con un `400`. Vedere [Errori](/docs/api/errors).