Questa pagina è stata tradotta dall'API Cloud Translation.

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

Chrome 44 e versioni successive

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

Chrome 123 e versioni successive

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'attributo src dei tag img, audio e video e sull'attributo href dei tag a.
title

stringa facoltativo

Il testo da visualizzare nell'elemento; questo è obbligatorio a meno che type non sia separator. 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
  
  OnClickData
  
  Informazioni sull'articolo su cui è stato fatto clic e sul contesto in cui è avvenuto.
- Home
  
  Tabulazione
  
  I dettagli della scheda in cui è avvenuto il clic. Questo parametro non è presente per le app della piattaforma.

ItemType

Chrome 44 e versioni successive

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 successive

L'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.
menuItemId

string|number

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

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

CreateProperties
callback

funzione facoltativa

Il parametro callback ha il seguente aspetto:
```
()=>void
```

Ritorni

number|string

L'ID dell'elemento appena creato.

remove()

Promessa

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

Rimuove una voce del menu contestuale.

Parametri

menuItemId

string|number

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 successive

Le 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()

Promessa

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 successive

Le 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()

Promessa

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

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

Parametri

id

string|number

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 successive
  
  Se l'elemento è visibile nel menu.
- onclick
  
  void facoltativo
  
  La funzione onclick ha il seguente aspetto:
```
(info: OnClickData,tab: Tab)=> {...}
```
  - informazioni
    
    OnClickData
    
    Chrome 44 e versioni successive
  - Home
    
    Tabulazione
    
    Chrome 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 successive

Le 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
  
  OnClickData
- Home
  
  tabs.Tab facoltativo