Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

Selection.getRangeAt — recuperare un intervallo di selezione

Selection.getRangeAt(0) restituisce l’oggetto Range associato alla selezione del documento, non una copia.

Versione: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintassi

selection.getRangeAt(index)

selection.getRangeAt(index) espone l’intervallo della selezione. È un’API Web del browser, non una funzionalità ECMAScript; Node 24 non ne dimostra il supporto.

Prima di chiamare il metodo con l’indice 0, verifica che selection !== null e selection.rangeCount > 0. La specifica richiede che venga sollevata un’eccezione IndexSizeError se l’indice è diverso da 0, se la selezione è vuota o se uno dei suoi estremi si trova fuori dall’albero del documento. I browser non seguono sempre questa regola: Firefox può esporre più intervalli di selezione, quindi anche un indice diverso da 0 può funzionare. Se un estremo si trova in un albero dello Shadow DOM, non dare per scontato che il browser sollevi questa eccezione. Anche una selezione ridotta a un cursore può avere un intervallo.

Il risultato è un riferimento: modificare l’intervallo influisce sulla selezione finché restano associati. Chiamate ripetute con lo stesso indice restituiscono lo stesso oggetto, a meno che l’intervallo non venga sostituito o rimosso. La specifica è un Working Draft, non una tabella di compatibilità dei browser.

Esempi

(() => {
  const selection = window.getSelection();
  if (!selection || !document.body) {
    throw new Error("An active browser document is required.");
  }

  const element = document.createElement("p");
  element.textContent = "Hello world";
  document.body.append(element);

  try {
    selection.removeAllRanges();
    const range = document.createRange();
    range.setStart(element.firstChild, 0);
    range.setEnd(element.firstChild, 5);
    selection.addRange(range);

    if (selection.rangeCount === 0) {
      throw new Error("No selection range is available.");
    }
    const selectedRange = selection.getRangeAt(0);
    console.log(selectedRange.toString());
    console.log(selectedRange === selection.getRangeAt(0));
  } finally {
    selection.removeAllRanges();
    element.remove();
  }
})();

Risultato

Hello
true

Il codice e il risultato sono stati verificati in un ambiente Chromium isolato. L’esempio recupera l’unico intervallo con l’indice `0` e verifica che una seconda chiamata restituisca lo stesso oggetto. Non verifica indici diversi da `0` né estremi in un albero dello Shadow DOM.

Fonti