chrome.contextMenus

Descrizione

Utilizza l'API chrome.contextMenus per aggiungere elementi al menu contestuale di Google Chrome. Puoi scegliere a quali tipi di oggetti 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 all'elemento del menu. Ad esempio:

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

Concetti e utilizzo

Gli elementi del menu contestuale possono essere visualizzati 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 visualizzati i tuoi elementi, 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 dell'API contextMenus dal repository chrome-extension-samples.

Tipi

ContextType

Chrome 44 e versioni successive

I diversi contesti in cui può essere visualizzato un menu. La specifica di "all" è equivalente alla combinazione di tutti gli altri contesti, ad eccezione di "launcher". Il contesto "launcher" è supportato solo dalle app e viene utilizzato per aggiungere voci di menu al menu contestuale visualizzato quando si fa clic sull'icona dell'app in Avvio app/barra delle app/dock e così via. Piattaforme diverse potrebbero imporre limitazioni a ciò che è effettivamente supportato in un menu contestuale di 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 deselezionato. 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

    stringa[] facoltativo

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

  • abilitata

    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 un elemento di menu principale, che rende l'elemento un elemento secondario di un elemento aggiunto in precedenza.

  • targetUrlPatterns

    stringa[] facoltativo

    Analogamente a documentUrlPatterns, i filtri si basano 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 dialetto rumeno" e l'utente seleziona la parola "cool", l'elemento del menu contestuale per la selezione è "Traduci "cool" in dialetto rumeno".

  • 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 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 ascoltatore per contextMenus.onClicked.

    La funzione onclick ha il seguente aspetto: 

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

    • informazioni

      OnClickData

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

    • tab

      Tab

      I dettagli della scheda in cui si è verificato il clic. Questo parametro non è presente per le app di piattaforma.

ItemType

Chrome 44 e versioni successive

Il tipo di voce di menu.

Enum

"normale"

"checkbox"

"radio"

"separator"

OnClickData

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

Proprietà

  • selezionato

    booleano facoltativo

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

  • modificabile

    booleano

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

  • frameId

    number facoltativo

    Chrome 51 e versioni successive

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

  • frameUrl

    stringa facoltativa

    L'URL del frame dell'elemento su 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 dei valori "image", "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 sull'elemento del menu. Questa proprietà non è impostata se il clic si è verificato in un contesto in cui non è presente una pagina corrente, ad esempio in un menu contestuale del programma di avvio.

  • 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 elemento di tipo pulsante di opzione prima che venga fatto clic.

Proprietà

ACTION_MENU_TOP_LEVEL_LIMIT

Il numero massimo di elementi di primo livello dell'estensione che possono essere aggiunti a un menu contestuale dell'azione dell'estensione. Eventuali elementi oltre questo limite verranno ignorati.

Valore

6

Metodi

create()

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

Crea un nuovo elemento del menu contestuale. Se si verifica un errore durante la creazione, potrebbe non essere rilevato fino all'attivazione del callback di creazione. I dettagli sono disponibili in runtime.lastError.

Parametri

  • createProperties

    CreateProperties

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • numero | stringa

    L'ID dell'elemento appena creato.

remove()

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

Rimuove un elemento del menu contestuale.

Parametri

  • menuItemId

    stringa | numero

    L'ID dell'elemento del menu contestuale da rimuovere.

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 123 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

removeAll()

Promessa 
chrome.contextMenus.removeAll(
  callback?: function,
)

Rimuove tutti gli elementi del menu contestuale aggiunti da questa estensione.

Parametri

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 123+

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

update()

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

Aggiorna un elemento del menu contestuale creato in precedenza.

Parametri

  • id

    stringa | numero

    L'ID dell'elemento da aggiornare.

  • updateProperties

    oggetto

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

    • selezionato

      booleano facoltativo

    • contesti

      [ContextType, ...ContextType[]] facoltativo

    • documentUrlPatterns

      stringa[] facoltativo

    • abilitata

      booleano facoltativo

    • parentId

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

      stringa[] facoltativo

    • titolo

      stringa facoltativa

    • tipo

      ItemType facoltativo

    • visibile

      booleano 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 si è verificato il clic. Questo parametro non è presente per le app di piattaforma.

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 123 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

Eventi

onClicked

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

Viene attivato quando viene fatto clic su un elemento del menu contestuale.

Parametri