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

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"
  },
  ...
}

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

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+

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+

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+

Eventi

onClicked

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

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

Parametri