Descrizione
Utilizza l'API chrome.contextMenus
per aggiungere elementi al menu contestuale di Google Chrome. Puoi scegliere i tipi di oggetti a cui si applicano le aggiunte al menu contestuale, ad esempio immagini, link ipertestuali e pagine.
Autorizzazioni
contextMenus
Per usare l'API, devi dichiarare l'autorizzazione "contextMenus"
nel 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 nei documenti con URL file:// o chrome://. Per controllare in quali documenti possono essere visualizzati gli elementi, specifica il campo documentUrlPatterns
quando chiami i metodi create()
o update()
.
Puoi creare tutte le voci di menu contestuale che desideri, ma se più di una voce dell'estensione è visibile contemporaneamente, Google Chrome le comprime automaticamente in un unico menu principale.
Esempi
Per provare questa API, installa l'esempio di APIcontextMenus dal repository chrome-extension-samples.
Tipi
ContextType
I diversi contesti in cui può essere visualizzato un menu. Specificare "all" equivale alla combinazione di tutti gli altri contesti, ad eccezione di "Avvio app". Il contesto "Avvio app" è supportato soltanto dalle app e viene utilizzato per aggiungere voci di menu al menu contestuale che viene visualizzato quando fai clic sull'icona dell'app in Avvio app, nella barra delle applicazioni, nel dock e così via. Diverse piattaforme potrebbero porre dei limiti a ciò che è effettivamente supportato in un menu contestuale di Avvio app.
Enum
"frame"
"link"
"video"
"audio"
"browser_action"
CreateProperties
Proprietà della nuova voce di menu contestuale.
Proprietà
-
selezionato
booleano facoltativo
Lo stato iniziale di una casella di controllo o di un pulsante di opzione:
true
per l'opzione selezionata,false
per quella deselezionata. È 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 ai documenti o ai frame il cui URL corrisponde a uno dei pattern specificati. Per maggiori dettagli sui formati dei pattern, consulta la sezione Pattern di corrispondenza.
-
abilitata
booleano facoltativo
Indica se questa voce di 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 per questa estensione.
-
parentId
stringa | numero facoltativo
L'ID di una voce di menu principale. Questa opzione rende la voce secondaria di un elemento aggiunto in precedenza.
-
targetUrlPatterns
string[] facoltativo
Simili a
documentUrlPatterns
, filtri basati sull'attributosrc
dei tagimg
,audio
evideo
e sull'attributohref
dei taga
. -
title
stringa facoltativo
Il testo da visualizzare nell'elemento; questo è obbligatorio a meno che
type
non siaseparator
. Quando il contesto èselection
, utilizza%s
nella stringa per mostrare il testo selezionato. Ad esempio, se il valore di questo parametro è "Traduci '%s ' in latino Maiale" e l'utente seleziona la parola "freddo", la voce del menu contestuale per la selezione è "Traduci 'cool' in latino Maiale". -
Tipo
Facoltativo ItemType
Il tipo di voce del menu. Il valore predefinito è
normal
. -
visibile
booleano facoltativo
Se l'elemento è visibile nel menu.
-
onclick
void facoltativo
Funzione che viene richiamata quando si fa clic sulla voce di menu. Questa funzione 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
Informazioni sull'articolo su cui è stato fatto clic e sul contesto in cui è avvenuto.
-
Home
I dettagli della scheda in cui è avvenuto il clic. Questo parametro non è presente per le app della piattaforma.
-
ItemType
Il tipo di voce del menu.
Enum
"radio"
OnClickData
Informazioni inviate quando si fa 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 elemento di opzione dopo il clic.
-
modificabile
boolean
Un flag che indica se l'elemento è modificabile (input di testo, area di testo e così via).
-
frameId
numero facoltativo
Chrome 51 e versioni successiveL'ID del frame dell'elemento in cui è stato fatto clic sul menu contestuale, se si trovava in un frame.
-
frameUrl
stringa facoltativo
L'URL del frame dell'elemento in cui è stato fatto clic sul menu contestuale, se era in un frame.
-
linkUrl
stringa facoltativo
Se l'elemento è un link, l'URL a cui rimanda.
-
mediaType
stringa facoltativo
Il valore può essere "image", "video" o "audio" se il menu contestuale è stato attivato su uno di questi tipi di elementi.
-
stringa | 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 di 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 di Avvio app.
-
parentMenuItemId
stringa | numero facoltativo
L'ID principale, se presente, dell'articolo selezionato.
-
selectionText
stringa facoltativo
Il testo per la selezione del contesto, se presente.
-
srcUrl
stringa facoltativo
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 opzione prima del clic.
Proprietà
ACTION_MENU_TOP_LEVEL_LIMIT
Il numero massimo di elementi di un'estensione di primo livello che può essere aggiunto al menu contestuale di un'azione di estensione. Tutti gli elementi oltre questo limite verranno ignorati.
Valore
6
Metodi
create()
chrome.contextMenus.create(
createProperties: CreateProperties,
callback?: function,
)
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
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
numero | stringa
L'ID dell'elemento appena creato.
remove()
chrome.contextMenus.remove(
menuItemId: string | number,
callback?: function,
)
Rimuove una voce del menu contestuale.
Parametri
-
stringa | numero
L'ID della voce di menu contestuale da rimuovere.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 123 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
removeAll()
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
Ritorni
-
Promise<void>
Chrome 123 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
update()
chrome.contextMenus.update(
id: string | number,
updateProperties: object,
callback?: function,
)
Consente di aggiornare 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
-
abilitata
booleano facoltativo
-
parentId
stringa | numero facoltativo
L'ID dell'elemento da impostare come principale per questo elemento. Nota: non puoi impostare un elemento come elemento secondario del proprio discendente.
-
targetUrlPatterns
string[] facoltativo
-
title
stringa facoltativo
-
Tipo
Facoltativo ItemType
-
visibile
booleano facoltativo
Chrome 62 e versioni successiveSe l'elemento è visibile nel menu.
-
onclick
void facoltativo
La funzione
onclick
ha il seguente aspetto:(info: OnClickData, tab: Tab) => {...}
-
informazioniChrome 44 e versioni successive
-
HomeChrome 44 e versioni successive
I dettagli della scheda in cui è avvenuto il clic. Questo parametro non è presente per le app della piattaforma.
-
-
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 123 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
Eventi
onClicked
chrome.contextMenus.onClicked.addListener(
callback: function,
)
Attivato quando viene fatto clic su una voce di menu contestuale.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(info: OnClickData, tab?: tabs.Tab) => void
-
informazioni
-
Home
tabs.Tab facoltativo
-