chrome.contextMenus

refresh date: 2026-09-25 robots: noindex

Descrizione

Utilizza l'API chrome.contextMenus per aggiungere elementi al menu contestuale di Google Chrome. Puoi scegliere i tipi di oggetti a cui applicare le aggiunte al menu contestuale, ad esempio immagini, link ipertestuali e pagine.

Autorizzazioni

contextMenus

Utilizzo

Le voci del menu contestuale possono essere visualizzate in qualsiasi documento (o frame all'interno di un documento), anche quelli con URL file:// o chrome://. Per controllare in quali documenti possono essere visualizzati i tuoi elementi, specifica il campo documentUrlPatterns quando chiami il metodo create() o update().

Puoi creare tutte le voci del menu contestuale di cui hai bisogno, ma se ne sono visibili più di una della tua estensione contemporaneamente, Google Chrome le comprime automaticamente in un unico menu principale.

Manifest

Per utilizzare l'API, devi dichiarare l'autorizzazione "contextMenus" nel manifest dell'estensione. Inoltre, devi specificare un'icona di 16 x 16 pixel da visualizzare accanto alla voce di menu. Ad esempio:

{
  "name": "My extension",
  ...
  "permissions": [
    "contextMenus"
  ],
  "icons": {
    "16": "icon-bitty.png",
    "48": "icon-small.png",
    "128": "icon-large.png"
  },
  ...
}

Esempi

Per provare questa API, installa l'esempio di API contextMenus dal repository chrome-extension-samples.

Tipi

ContextType

Chrome 44 e versioni successive

I diversi contesti in cui può essere visualizzato un menu. Specificare "all" equivale alla combinazione di tutti gli altri contesti, ad eccezione di "launcher" e "tab". Il contesto "Avvio app" è supportato solo dalle app e viene utilizzato per aggiungere voci di menu al menu contestuale che viene visualizzato quando si fa clic sull'icona dell'app in Avvio app/barra delle app/dock e così via. Piattaforme diverse potrebbero imporre limitazioni su ciò che è effettivamente supportato in un menu contestuale di Avvio app.

Enum

"all"

"page"

"frame"

"selection"

"link"

"editable"

"image"

"video"

"audio"

"launcher"

"action"
Si applica al menu contestuale dell'azione dell'estensione (l'icona della barra degli strumenti).

"tab"
Si applica al menu contestuale di una scheda nella tabstrip.

CreateProperties

Chrome 123 e versioni successive

Proprietà della nuova voce del menu contestuale.

Proprietà

• selezionato

  boolean facoltativo

  Lo stato iniziale di una casella di controllo o di un pulsante di opzione: true per selezionato, false per non selezionato. In un determinato gruppo è possibile selezionare un solo pulsante di opzione alla volta.

• contesti

  [ContextType, …ContextType[]] facoltativo

  Elenco dei contesti in cui verrà visualizzata questa voce di menu. Il valore predefinito è ['page'].

• documentUrlPatterns

  string[] facoltativo

  Limita l'applicazione dell'elemento solo ai documenti o ai frame il cui URL corrisponde a uno dei pattern specificati. Per i dettagli sui formati dei pattern, consulta Pattern di corrispondenza.

• attivato

  boolean facoltativo

  Indica se questa voce del menu contestuale è attiva o disattivata. Il valore predefinito è true.

• id

  stringa facoltativa

  L'ID univoco da assegnare a questo elemento. Obbligatoria per le pagine degli eventi. Non può essere uguale a un altro ID per questa estensione.

• parentId

  string | number facoltativo

  L'ID di una voce di menu principale, che rende la voce secondaria rispetto a una voce aggiunta in precedenza.

• targetUrlPatterns

  string[] facoltativo

  Analogamente a documentUrlPatterns, filtra in base all'attributo src dei tag img, audio e video e all'attributo href dei tag a.

• titolo

  stringa facoltativa

  Il testo da visualizzare nell'elemento; questo campo è obbligatorio, a meno che type non sia separator. Quando il contesto è selection, utilizza %s all'interno della stringa per mostrare il testo selezionato. Ad esempio, se il valore di questo parametro è "Traduci '%s ' in Pig Latin" e l'utente seleziona la parola "cool", la voce del menu contestuale per la selezione è "Traduci 'cool' in Pig Latin".

• tipo

  ItemType facoltativo

  Il tipo di voce di menu. Il valore predefinito è normal.

• visibile

  boolean facoltativo

  Indica se l'elemento è visibile nel menu.

• onclick

  void optional

  Una funzione che viene richiamata quando si fa clic sulla voce di menu. Questa opzione non è disponibile all'interno di un service worker; devi invece registrare un listener per contextMenus.onClicked.

  La funzione onclick ha il seguente aspetto:

  (info: OnClickData, tab: Tab) => {...}

  • informazioni

    OnClickData

    Informazioni sull'elemento selezionato e sul contesto in cui è avvenuto il clic.

  • tab

    Tab

    I dettagli della scheda in cui è stato effettuato il clic. Questo parametro non è presente per le app della piattaforma.

ItemType

Chrome 44 e versioni successive

Il tipo di voce di menu.

Enum

"normal"

"checkbox"

"radio"

"separator"

OnClickData

Informazioni inviate quando si fa clic su una voce del menu contestuale.

Proprietà

• selezionato

  boolean facoltativo

  Un flag che indica lo stato di una casella di controllo o di un pulsante di opzione dopo che è stato fatto clic.

• modificabile

  booleano

  Un flag che indica se l'elemento è modificabile (input di testo, area di testo e così via).

• frameId

  number optional

  Chrome 51 e versioni successive

  L'ID del frame dell'elemento in cui è stato fatto clic sul menu contestuale, se si trovava in un frame.

• frameUrl

  stringa facoltativa

  L'URL del frame dell'elemento in cui è stato fatto clic sul menu contestuale, se si trovava in un frame.

• linkUrl

  stringa facoltativa

  Se l'elemento è un link, l'URL a cui rimanda.

• mediaType

  stringa facoltativa

  Uno tra "image", "video" o "audio" se il menu contestuale è stato attivato su uno di questi tipi di elementi.

• menuItemId

  string | number

  L'ID della voce di menu su cui è stato fatto clic.

• pageUrl

  stringa facoltativa

  L'URL della pagina in cui è stata selezionata la voce di menu. Questa proprietà non viene impostata se il clic si è verificato in un contesto in cui non esiste una pagina corrente, ad esempio in un menu contestuale di Avvio app.

• parentMenuItemId

  string | number facoltativo

  L'ID principale, se presente, dell'elemento su cui è stato fatto clic.

• selectionText

  stringa facoltativa

  Il testo per la selezione del contesto, se presente.

• srcUrl

  stringa facoltativa

  Sarà presente per gli elementi con un URL "src".

• wasChecked

  boolean facoltativo

  Un flag che indica lo stato di una casella di controllo o di un pulsante di opzione prima che venisse selezionato.

Proprietà

ACTION_MENU_TOP_LEVEL_LIMIT

Il numero massimo di elementi di estensione di primo livello che possono essere aggiunti a un menu contestuale di azioni di estensione. Qualsiasi elemento oltre questo limite viene ignorato.

Valore

6

Metodi

create()

chrome.contextMenus.create(
  createProperties: CreateProperties,
  callback?: function,
): number | string

Crea una nuova voce del menu contestuale. Se si verifica un errore durante la creazione, potrebbe non essere rilevato fino all'attivazione del callback di creazione; i dettagli saranno in runtime.lastError.

Parametri

• createProperties

  CreateProperties

• callback

  funzione elemento facoltativo

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• number | string

  L'ID dell'elemento appena creato.

remove()

Promise

chrome.contextMenus.remove(
  menuItemId: string | number,
  callback?: function,
): Promise<void>

Rimuove una voce del menu contestuale.

Parametri

• menuItemId

  string | number

  L'ID della voce del menu contestuale da rimuovere.

• callback

  funzione elemento facoltativo

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promise<void>

  Chrome 123 e versioni successive

  Si risolve quando il menu contestuale è stato rimosso.

  Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

removeAll()

Promise

chrome.contextMenus.removeAll(
  callback?: function,
): Promise<void>

Rimuove tutte le voci del menu contestuale aggiunte da questa estensione.

Parametri

• callback

  funzione elemento facoltativo

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promise<void>

  Chrome 123 e versioni successive

  Viene risolta al termine della rimozione.

  Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

update()

Promise

chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
  callback?: function,
): Promise<void>

Aggiorna una voce del menu contestuale creata in precedenza.

Parametri

• id

  string | number

  L'ID dell'elemento da aggiornare.

• updateProperties

  oggetto

  Le proprietà da aggiornare. Accetta gli stessi valori della funzione contextMenus.create.

  • selezionato

    boolean facoltativo

  • contesti

    [ContextType, …ContextType[]] facoltativo

  • documentUrlPatterns

    string[] facoltativo

  • attivato

    boolean facoltativo

  • parentId

    string | number facoltativo

    L'ID dell'elemento da impostare come elemento principale di questo elemento. Nota: non puoi impostare un elemento in modo che diventi un elemento secondario del proprio discendente.

  • targetUrlPatterns

    string[] facoltativo

  • titolo

    stringa facoltativa

  • tipo

    ItemType facoltativo

  • visibile

    boolean facoltativo

    Chrome 62 e versioni successive

    Indica se l'elemento è visibile nel menu.

  • onclick

    void optional

    La funzione onclick ha il seguente aspetto:

    (info: OnClickData, tab: Tab) => {...}

    • informazioni

      OnClickData

      Chrome 44 e versioni successive
    • tab

      Tab

      Chrome 44 e versioni successive

      I dettagli della scheda in cui è stato effettuato il clic. Questo parametro non è presente per le app della piattaforma.

• callback

  funzione elemento facoltativo

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promise<void>

  Chrome 123 e versioni successive

  Viene risolto quando il menu contestuale è stato aggiornato.

  Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

Eventi

onClicked

chrome.contextMenus.onClicked.addListener(
  callback: function,
)

Attivato quando si fa clic su una voce del menu contestuale.

Parametri

• callback

  funzione

  Il parametro callback ha il seguente aspetto:

  (info: OnClickData, tab?: tabs.Tab) => void

  • informazioni

    OnClickData

  • tab

    tabs.Tab facoltativo