chrome.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 del menu contestuale, ad esempio immagini, link ipertestuali e pagine.

Autorizzazioni

contextMenus

Per usare l'API, devi dichiarare l'autorizzazione "contextMenus" nel file manifest dell'estensione. Inoltre, devi specificare un'icona di 16 x 16 pixel per la visualizzazione 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 contenenti file:// o chrome://. Per stabilire in quali documenti possono essere visualizzati i tuoi elementi, specifica campo documentUrlPatterns quando chiami i metodi create() o update().

Puoi creare tutte le voci di menu contestuale che ti servono, ma se ne hai più di una visibili contemporaneamente, Google Chrome le comprime automaticamente in un unico menu principale.

Esempi

Per provare questa API, installa l'esempio dell'APIcontextMenus da chrome-extension-samples repository Git.

Tipi

ContextType

Chrome 44 e versioni successive .

I diversi contesti in cui può apparire un menu. Specificare "tutti" e alla combinazione di tutti gli altri contesti, ad eccezione di "Avvio app". L'app Avvio app il contesto è 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, nella barra delle applicazioni, nel dock e così via. Piattaforme diverse potrebbero porre limitazioni a ciò che è effettivamente supportato in un menu contestuale di Avvio app.

Enum

"tutti"

"pagina"

"frame"

"selezione"

"link"

"modificabile"

"image"

"video"

"audio"

"Avvio app"

"browser_action"

"page_action"

"azione"

CreateProperties

Chrome 123 e versioni successive .

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 la casella selezionata, false per quella non selezionata. È 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'applicazione dell'elemento solo a documenti o frame il cui URL corrisponde a uno dei pattern specificati. Per maggiori dettagli sui formati dei pattern, consulta Pattern di corrispondenza.

  • abilitata

    booleano facoltativo

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

  • id

    stringa facoltativo

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

  • parentId

    string | numero facoltativo

    L'ID di una voce di menu principale. l'elemento diventa quindi secondario rispetto a un altro elemento aggiunto in precedenza.

  • targetUrlPatterns

    string[] facoltativo

    Simili a documentUrlPatterns, filtri basati sull'attributo src dei tag img, audio e video e sull'attributo href dei tag a.

  • titolo

    stringa facoltativo

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

  • tipo

    ItemType facoltativo

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

  • visibile

    booleano facoltativo

    Se l'elemento è visibile nel menu.

  • onclick

    void facoltativo

    Una funzione che viene richiamata quando l'utente 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 questo aspetto: 

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

    • informazioni

      OnClickData

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

    • tab

      Scheda

      I dettagli della scheda in cui è stato eseguito il clic. Questo parametro non è presente per le app delle piattaforme.

ItemType

Chrome 44 e versioni successive .

Il tipo di voce di menu.

Enum

"normale"

"casella di controllo"

"radio"

"separatore"

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 opzione dopo il clic.

  • modificabile

    booleano

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

  • frameId

    numero facoltativo

    Chrome 51 e versioni successive .

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

  • frameUrl

    stringa facoltativo

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

  • linkUrl

    stringa facoltativo

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

  • mediaType

    stringa facoltativo

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

  • menuItemId

    string | numero

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

  • pageUrl

    stringa facoltativo

    L'URL della pagina in cui è stato fatto clic sulla voce del menu. Questa proprietà non è 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 | numero facoltativo

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

  • selectionText

    stringa facoltativo

    Il testo per la selezione del contesto, se presente.

  • srcUrl

    stringa facoltativo

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

  • wasChecked

    booleano facoltativo

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

Proprietà

ACTION_MENU_TOP_LEVEL_LIMIT

Il numero massimo di elementi dell'estensione di primo livello che possono essere aggiunti al menu contestuale di un'azione dell'estensione. Tutti gli elementi che superano questo limite verranno ignorati.

Valore

6

Metodi

create()

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

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 disponibili in runtime.lastError.

Parametri

  • createProperties

    CreateProperties

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • numero | stringa

    L'ID dell'elemento appena creato.

remove()

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

Rimuove una voce del menu contestuale.

Parametri

  • menuItemId

    string | numero

    L'ID della voce del menu contestuale da rimuovere.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 123 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

removeAll()

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

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

Parametri

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 123 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

update()

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

Consente di aggiornare una voce del menu contestuale creata in precedenza.

Parametri

  • id

    string | 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

    • abilitata

      booleano facoltativo

    • parentId

      string | numero facoltativo

      L'ID dell'elemento da impostare come principale. Nota: non puoi impostare un elemento in modo che diventi figlio del suo discendente.

    • targetUrlPatterns

      string[] facoltativo

    • titolo

      stringa facoltativo

    • tipo

      ItemType facoltativo

    • visibile

      booleano facoltativo

      Chrome 62 e versioni successive .

      Se l'elemento è visibile nel menu.

    • onclick

      void facoltativo

      La funzione onclick ha questo aspetto: 

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

      • informazioni

        OnClickData

        Chrome 44 e versioni successive .
      • tab

        Scheda

        Chrome 44 e versioni successive .

        I dettagli della scheda in cui è stato eseguito il clic. Questo parametro non è presente per le app delle piattaforme.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 123 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

Eventi

onClicked

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

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

Parametri