browser.contextMenus

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

Per utilizzare l'API, devi dichiarare l'autorizzazione "contextMenus" nel file 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"
  },
  ...
}

Concetti e 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 i metodi 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.

La maggior parte di questa pagina contiene informazioni di riferimento per i membri di questa API. Per istruzioni sull'utilizzo dell'API, consulta Crea un menu contestuale.

Esempi

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

Tipi

ContextType

Browser Chrome 44 e versioni successive * da Chrome 148

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 browser.* da Chrome 148

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

Browser Chrome 44 e versioni successive * da Chrome 148

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+ browser.* da Chrome 148

    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()

browser.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()

browser.contextMenus.remove(
  menuItemId: string | number,
): Promise<void>

Rimuove una voce del menu contestuale.

Parametri

  • menuItemId

    string | number

    L'ID della voce del menu contestuale da rimuovere.

Resi

  • Promise<void>

    Chrome 123 e versioni successive browser.* da Chrome 148

    Si risolve quando il menu contestuale è stato rimosso.

removeAll()

browser.contextMenus.removeAll(): Promise<void>

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

Resi

  • Promise<void>

    Chrome 123 e versioni successive browser.* da Chrome 148

    Viene risolta al termine della rimozione.

update()

browser.contextMenus.update(
  id: string | number,
  updateProperties: object,
): 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 browser.* da Chrome 148

      Indica se l'elemento è visibile nel menu.

    • onclick

      void optional

      La funzione onclick ha il seguente aspetto: 

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

      • informazioni

        OnClickData

        Browser Chrome 44 e versioni successive * da Chrome 148
      • tab

        Tab

        Browser Chrome 44 e versioni successive * da Chrome 148

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

Resi

  • Promise<void>

    Chrome 123 e versioni successive browser.* da Chrome 148

    Viene risolto quando il menu contestuale è stato aggiornato.

Eventi

onClicked

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

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

Parametri