chrome.bookmarks

Descrizione

Usa l'API chrome.bookmarks per creare, organizzare e manipolare in altro modo i preferiti. Consulta anche l'articolo Eseguire l'override delle pagine, che puoi utilizzare per creare una pagina Gestione Preferiti personalizzata.

Se fai clic sulla stella viene aggiunto un preferito
Se fai clic sulla stella aggiungi un preferito.

Autorizzazioni

bookmarks

Per utilizzare l'API bookmarks, devi dichiarare l'autorizzazione "bookmarks" nel manifest dell'estensione. Ad esempio:

{
  "name": "My extension",
  ...
  "permissions": [
    "bookmarks"
  ],
  ...
}

Concetti e utilizzo

Oggetti e proprietà

I preferiti sono organizzati in una struttura ad albero, in cui ogni nodo è un preferito o una cartella (a volte chiamato gruppo). Ogni nodo nella struttura ad albero è rappresentato da un oggetto bookmarks.BookmarkTreeNode.

Le proprietà BookmarkTreeNode vengono utilizzate nell'API chrome.bookmarks. Ad esempio, quando chiami bookmarks.create, passi la proprietà principale del nuovo nodo (parentId) e, facoltativamente, le proprietà index, title e url del nodo. Consulta bookmarks.BookmarkTreeNode per informazioni sulle proprietà che un nodo può avere.

Esempi

Il seguente codice crea una cartella con il titolo "Preferiti delle estensioni". Il primo argomento per create() specifica le proprietà della nuova cartella. Il secondo argomento definisce una funzione da eseguire dopo la creazione della cartella.

chrome.bookmarks.create(
  {'parentId': bookmarkBar.id, 'title': 'Extension bookmarks'},
  function(newFolder) {
    console.log("added folder: " + newFolder.title);
  },
);

Lo snippet successivo crea un segnalibro che rimanda alla documentazione per sviluppatori per le estensioni. Poiché non succederà nulla di male se la creazione del preferito non va a buon fine, questo codice non si preoccupa di definire una funzione di callback.

chrome.bookmarks.create({
  'parentId': extensionsFolderId,
  'title': 'Extensions doc',
  'url': 'https://developer.chrome.com/docs/extensions',
});

Per provare questa API, installa l'esempio dell'API Segnalibri dal repository chrome-extension-samples.

Tipi

BookmarkTreeNode

Un nodo (un preferito o una cartella) nell'albero dei preferiti. I nodi secondari sono ordinati all'interno della rispettiva cartella padre.

Proprietà

  • bambini

    BookmarkTreeNode[] facoltativo

    Un elenco ordinato di elementi secondari di questo nodo.

  • dateAdded

    numero facoltativo

    Data di creazione di questo nodo, in millisecondi dall'epoca (new Date(dateAdded)).

  • dateGroupModified

    numero facoltativo

    L'ultima modifica dei contenuti di questa cartella, in millisecondi dall'epoca.

  • dateLastUsed

    numero facoltativo

    Chrome 114 e versioni successive

    L'ultima apertura del nodo, in millisecondi dall'epoca. Non impostato per le cartelle.

  • id

    stringa

    L'identificatore univoco del nodo. Gli ID sono univoci all'interno del profilo corrente e rimangono validi anche dopo il riavvio del browser.

  • indice

    numero facoltativo

    La posizione in base 0 di questo nodo all'interno della relativa cartella padre.

  • parentId

    stringa facoltativo

    Il id della cartella principale. Omesso per il nodo radice.

  • title

    stringa

    Il testo visualizzato per il nodo.

  • non modificabile

     facoltativo

    Indica il motivo per cui questo nodo non è modificabile. Il valore managed indica che il nodo è stato configurato dall'amministratore di sistema o dal custode di un utente supervisionato. Omesso se il nodo può essere modificato dall'utente e dall'estensione (impostazione predefinita).

  • url

    stringa facoltativo

    L'URL a cui viene indirizzato quando un utente fa clic sul preferito. Omesso per le cartelle.

BookmarkTreeNodeUnmodifiable

Chrome 44 e versioni successive

Indica il motivo per cui questo nodo non è modificabile. Il valore managed indica che questo nodo è stato configurato dall'amministratore di sistema. Omesso se il nodo può essere modificato dall'utente e dall'estensione (impostazione predefinita).

Valore

CreateDetails

Oggetto passato alla funzione create().

Proprietà

  • indice

    numero facoltativo

  • parentId

    stringa facoltativo

    Il valore predefinito è la cartella Altri preferiti.

  • title

    stringa facoltativo

  • url

    stringa facoltativo

Proprietà

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

Deprecato

Le operazioni di scrittura dei preferiti non sono più limitate da Chrome.

Valore

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

Deprecato

Le operazioni di scrittura dei preferiti non sono più limitate da Chrome.

Valore

1000000

Metodi

create()

Promessa 
chrome.bookmarks.create(
  bookmark: CreateDetails,
  callback?: function,
)

Crea un preferito o una cartella sotto il parentId specificato. Se l'URL è NULL o mancante, sarà una cartella.

Parametri

Ritorni

  • Chrome 90 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.

get()

Promessa 
chrome.bookmarks.get(
  idOrIdList: string|[string,...string[]],
  callback?: function,
)

Recupera i BookmarkTreeNode specificati.

Parametri

  • idOrIdList

    stringa|[stringa,...stringa[]]

    Un singolo ID con valore stringa o un array di ID con valori stringa

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (results: BookmarkTreeNode[])=>void

Ritorni

  • Promise<BookmarkTreeNode[]>

    Chrome 90 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.

getChildren()

Promessa 
chrome.bookmarks.getChildren(
  id: string,
  callback?: function,
)

Recupera gli elementi secondari dell'ID BookmarkTreeNode specificato.

Parametri

Ritorni

  • Promise<BookmarkTreeNode[]>

    Chrome 90 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.

getRecent()

Promessa 
chrome.bookmarks.getRecent(
  numberOfItems: number,
  callback?: function,
)

Recupera i preferiti aggiunti di recente.

Parametri

  • numberOfItems

    numero

    Il numero massimo di articoli da restituire.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (results: BookmarkTreeNode[])=>void

Ritorni

  • Promise<BookmarkTreeNode[]>

    Chrome 90 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.

getSubTree()

Promessa 
chrome.bookmarks.getSubTree(
  id: string,
  callback?: function,
)

Recupera parte della gerarchia dei preferiti, a partire dal nodo specificato.

Parametri

  • id

    stringa

    L'ID della radice del sottoalbero da recuperare.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (results: BookmarkTreeNode[])=>void

Ritorni

  • Promise<BookmarkTreeNode[]>

    Chrome 90 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.

getTree()

Promessa 
chrome.bookmarks.getTree(
  callback?: function,
)

Recupera l'intera gerarchia dei preferiti.

Parametri

Ritorni

  • Promise<BookmarkTreeNode[]>

    Chrome 90 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.

move()

Promessa 
chrome.bookmarks.move(
  id: string,
  destination: object,
  callback?: function,
)

Sposta il BookmarkTreeNode specificato nella posizione fornita.

Parametri

  • id

    stringa

  • destinazione

    oggetto

    • indice

      numero facoltativo

    • parentId

      stringa facoltativo

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (result: BookmarkTreeNode)=>void

Ritorni

  • Chrome 90 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.

remove()

Promessa 
chrome.bookmarks.remove(
  id: string,
  callback?: function,
)

Rimuove un preferito o una cartella di Preferiti vuota.

Parametri

  • id

    stringa

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 90 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.

removeTree()

Promessa 
chrome.bookmarks.removeTree(
  id: string,
  callback?: function,
)

Rimuove in modo ricorsivo una cartella di preferiti.

Parametri

  • id

    stringa

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 90 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.

Promessa 
chrome.bookmarks.search(
  query: string|object,
  callback?: function,
)

Cerca BookmarkTreeNodes corrispondenti alla query specificata. Le query specificate con un oggetto producono BookmarkTreeNodes che corrisponde a tutte le proprietà specificate.

Parametri

  • query

    stringa|oggetto

    Una stringa di parole e frasi tra virgolette corrispondenti a URL e titoli dei preferiti oppure un oggetto. Se si tratta di un oggetto, è possibile specificare le proprietà query, url e title e verranno generati preferiti che corrispondono a tutte le proprietà specificate.

    • query

      stringa facoltativo

      Una stringa di parole e frasi tra virgolette corrispondenti a URL e titoli dei preferiti.

    • title

      stringa facoltativo

      Il titolo del preferito; corrisponde esattamente al titolo.

    • url

      stringa facoltativo

      L'URL del preferito; corrisponde esattamente al testo. Tieni presente che le cartelle non hanno un URL.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (results: BookmarkTreeNode[])=>void

Ritorni

  • Promise<BookmarkTreeNode[]>

    Chrome 90 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.bookmarks.update(
  id: string,
  changes: object,
  callback?: function,
)

Aggiorna le proprietà di un preferito o di una cartella. Specifica solo le proprietà da modificare; le proprietà non specificate rimarranno invariate. Nota: al momento sono supportati solo "title" e "url".

Parametri

  • id

    stringa

  • modifiche

    oggetto

    • title

      stringa facoltativo

    • url

      stringa facoltativo

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (result: BookmarkTreeNode)=>void

Ritorni

  • Chrome 90 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

onChanged

chrome.bookmarks.onChanged.addListener(
  callback: function,
)

Attivato quando un preferito o una cartella vengono modificati. Nota: al momento, questa impostazione viene attivata solo dalle modifiche ai titoli e agli URL.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (id: string,changeInfo: object)=>void

    • id

      stringa

    • changeInfo

      oggetto

      • title

        stringa

      • url

        stringa facoltativo

onChildrenReordered

chrome.bookmarks.onChildrenReordered.addListener(
  callback: function,
)

Attivato quando gli elementi secondari di una cartella hanno modificato l'ordine in base all'ordinamento nell'interfaccia utente. Questo metodo non viene chiamato in seguito a move().

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (id: string,reorderInfo: object)=>void

    • id

      stringa

    • reorderInfo

      oggetto

      • childIds

        stringa[]

onCreated

chrome.bookmarks.onCreated.addListener(
  callback: function,
)

Attivato quando vengono creati un preferito o una cartella.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (id: string,bookmark: BookmarkTreeNode)=>void

onImportBegan

chrome.bookmarks.onImportBegan.addListener(
  callback: function,
)

Attivato quando inizia una sessione di importazione dei preferiti. Gli osservatori costosi dovrebbero ignorare gli aggiornamenti onCreated fino a quando onImportEnded non viene attivato. Gli osservatori dovrebbero comunque gestire immediatamente le altre notifiche.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    ()=>void

onImportEnded

chrome.bookmarks.onImportEnded.addListener(
  callback: function,
)

Attivato al termine di una sessione di importazione dei preferiti.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    ()=>void

onMoved

chrome.bookmarks.onMoved.addListener(
  callback: function,
)

Viene attivato quando un preferito o una cartella vengono spostati in un'altra cartella principale.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (id: string,moveInfo: object)=>void

    • id

      stringa

    • moveInfo

      oggetto

      • indice

        numero

      • oldIndex

        numero

      • oldParentId

        stringa

      • parentId

        stringa

onRemoved

chrome.bookmarks.onRemoved.addListener(
  callback: function,
)

Attivato quando un preferito o una cartella vengono rimossi. Quando una cartella viene rimossa in modo ricorsivo, viene attivata una singola notifica per la cartella e nessuna per i suoi contenuti.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (id: string,removeInfo: object)=>void

    • id

      stringa

    • removeInfo

      oggetto

      • indice

        numero

      • Chrome 48 e versioni successive
      • parentId

        stringa