chrome.contextMenus

Descrizione

Utilizza l'API chrome.contextMenus per aggiungere elementi al menu contestuale di Google Chrome. Puoi scegliere a quali tipi di oggetti si applicano 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 in quelli con URL file:// o chrome://. Per controllare in quali documenti possono essere visualizzate le voci, specifica il campo documentUrlPatterns quando chiami il metodo create() o update().

Puoi creare tutti gli elementi del menu contestuale che ti servono, ma se più di uno della tua estensione è visibile contemporaneamente, Google Chrome li 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 16x16 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+

I diversi contesti in cui può essere visualizzato un menu. La specifica "tutti" equivale alla combinazione di tutti gli altri contesti, ad eccezione di "launcher". Il contesto "Avvio app" è supportato solo dalle app e viene utilizzato per aggiungere voci di menu al menu contestuale visualizzato quando si fa clic sull'icona dell'app nell'Avvio app/barra delle app/dock/ecc. Diverse piattaforme potrebbero imporre limitazioni a ciò che è effettivamente supportato in un menu contestuale dell'Avvio app.

Enum

"all"

"page"

"frame"

"selection"

"link"

"editable"

"image"

"video"

"audio"

"launcher"

"browser_action"

"page_action"

"action"

CreateProperties

Chrome 123+

Proprietà della nuova voce del menu contestuale.

Proprietà

  • selezionato

    booleano facoltativo

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

  • contesti

    [ContextType, ...ContextType[]] facoltativo

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

  • documentUrlPatterns

    string[] facoltativo

    Limita l'elemento in modo che venga applicato solo a documenti o frame il cui URL corrisponde a uno dei pattern specificati. Per informazioni dettagliate sui formati dei pattern, vedi Pattern di corrispondenza.

  • attivato

    booleano facoltativo

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

  • id

    stringa facoltativa

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

  • parentId

    stringa | numero facoltativo

    L'ID di una voce di menu principale; in questo modo, l'elemento diventa un elemento secondario di un elemento aggiunto in precedenza.

  • targetUrlPatterns

    string[] facoltativo

    Analogamente a documentUrlPatterns, i filtri basati sull'attributo src dei tag img, audio e video e sull'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

    booleano facoltativo

    Indica se l'elemento è visibile nel menu.

  • onclick

    void optional

    Una funzione richiamata quando viene fatto clic sulla voce di menu. Questa funzionalità non è disponibile all'interno di un service worker. Devi invece registrare un listener per contextMenus.onClicked.

    La funzione onclick ha questo aspetto: 

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

    • informazioni

      OnClickData

      Informazioni sull'elemento su cui è stato fatto clic e sul contesto in cui è avvenuto il clic.

    • tab

      Scheda

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

ItemType

Chrome 44+

Il tipo di voce di menu.

Enum

"normal"

"checkbox"

"radio"

"separator"

OnClickData

Informazioni inviate quando viene fatto clic su una voce di menu contestuale.

Proprietà

  • selezionato

    booleano facoltativo

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

  • modificabile

    booleano

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

  • frameId

    number (facoltativo)

    Chrome 51+

    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 punta.

  • mediaType

    stringa facoltativa

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

  • menuItemId

    stringa | numero

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

  • pageUrl

    stringa facoltativa

    L'URL della pagina in cui è stato fatto clic sulla voce di menu. Questa proprietà non è impostata se il clic si è verificato in un contesto in cui non è presente alcuna pagina corrente, ad esempio in un menu contestuale del launcher.

  • parentMenuItemId

    stringa | numero 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

    booleano facoltativo

    Un flag che indica lo stato di una casella di controllo o di un pulsante di opzione prima che venga 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 dell'azione di estensione. Qualsiasi elemento oltre questo limite verrà ignorato.

Valore

6

Metodi

create()

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

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

Parametri

  • createProperties

    CreateProperties

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • numero | stringa

    L'ID dell'articolo appena creato.

remove()

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

Rimuove una voce del menu contestuale.

Parametri

  • menuItemId

    stringa | numero

    L'ID della voce del menu contestuale da rimuovere.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 123+

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

removeAll()

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

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

Parametri

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 123+

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

update()

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

Aggiorna una voce di menu contestuale creata in precedenza.

Parametri

  • id

    stringa | numero

    L'ID dell'articolo da aggiornare.

  • updateProperties

    oggetto

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

    • selezionato

      booleano facoltativo

    • contesti

      [ContextType, ...ContextType[]] facoltativo

    • documentUrlPatterns

      string[] facoltativo

    • attivato

      booleano facoltativo

    • parentId

      stringa | numero facoltativo

      L'ID dell'elemento da impostare come elemento principale. 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

      booleano facoltativo

      Chrome 62+

      Indica se l'elemento è visibile nel menu.

    • onclick

      void optional

      La funzione onclick ha questo aspetto: 

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

      • informazioni

        OnClickData

        Chrome 44+
      • tab

        Scheda

        Chrome 44+

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

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 123+

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

Eventi

onClicked

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

Attivato quando viene fatto clic su una voce di menu contestuale.

Parametri