chrome.bookmarks

Descrizione

Utilizza l'API chrome.bookmarks per creare, organizzare e manipolare i preferiti. Consulta anche Override Pages, che puoi utilizzare per creare una pagina Gestione preferiti personalizzata.

Se fai clic sulla stella, viene aggiunto un preferito
Fai clic sulla stella per aggiungere un preferito.

Autorizzazioni

bookmarks

Per utilizzare l'API dei preferiti, devi dichiarare l'autorizzazione "preferiti" 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 chiamata gruppo). Ogni nodo dell'albero è rappresentato da un oggetto bookmarks.BookmarkTreeNode.

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

Esempi

Il codice seguente crea una cartella con il titolo "Preferiti delle estensioni". Il primo argomento di 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 preferito che rimanda alla documentazione per gli sviluppatori relativa alle 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 di API Bookmarks 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 cartella principale.

Proprietà

  • bambini

    BookmarkTreeNode[] facoltativo

    Un elenco ordinato di nodi secondari di questo nodo.

  • dateAdded

    number facoltativo

    Quando è stato creato questo nodo, in millisecondi dall'epoca (new Date(dateAdded)).

  • dateGroupModified

    number facoltativo

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

  • dateLastUsed

    number facoltativo

    Chrome 114 e versioni successive

    Data dell'ultima apertura di questo 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

    number facoltativo

    La posizione basata su 0 di questo nodo all'interno della cartella principale.

  • parentId

    stringa facoltativa

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

  • titolo

    stringa

    Il testo visualizzato per il nodo.

  • non modificabile

    "managed"
     facoltativo

    Indica il motivo per cui questo nodo non è modificabile. Il valore managed indica che questo 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 (valore predefinito).

  • url

    stringa facoltativa

    L'URL a cui si accede 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 (valore predefinito).

Valore

"managed"

CreateDetails

Oggetto passato alla funzione create().

Proprietà

  • indice

    number facoltativo

  • parentId

    stringa facoltativa

    Il valore predefinito è la cartella Altri preferiti.

  • titolo

    stringa facoltativa

  • url

    stringa facoltativa

Proprietà

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

Obsoleto

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

Valore

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

Obsoleto

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 con l'ID genitore specificato. Se l'URL è NULL o mancante, si tratta di una cartella.

Parametri

Resi

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

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

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (results: BookmarkTreeNode[]) => void

Resi

  • Promise<BookmarkTreeNode[]>

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

getChildren()

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

Recupera i figli dell'ID BookmarkTreeNode specificato.

Parametri

Resi

  • Promise<BookmarkTreeNode[]>

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

getRecent()

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

Recupera i preferiti aggiunti di recente.

Parametri

  • numberOfItems

    numero

    Il numero massimo di elementi da restituire.

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (results: BookmarkTreeNode[]) => void

Resi

  • Promise<BookmarkTreeNode[]>

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

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

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (results: BookmarkTreeNode[]) => void

Resi

  • Promise<BookmarkTreeNode[]>

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

getTree()

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

Recupera l'intera gerarchia dei preferiti.

Parametri

Resi

  • Promise<BookmarkTreeNode[]>

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

move()

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

Sposta il BookmarkTreeNode specificato nella posizione indicata.

Parametri

  • id

    stringa

  • destinazione

    oggetto

    • indice

      number facoltativo

    • parentId

      stringa facoltativa

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (result: BookmarkTreeNode) => void

Resi

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

remove()

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

Rimuove un preferito o una cartella di preferiti vuota.

Parametri

  • id

    stringa

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

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

removeTree()

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

Rimuove in modo ricorsivo una cartella dei preferiti.

Parametri

  • id

    stringa

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

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

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

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

Parametri

  • query

    stringa | oggetto

    Una stringa di parole e frasi tra virgolette che vengono associate 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 prodotti i preferiti corrispondenti a tutte le proprietà specificate.

    • query

      stringa facoltativa

      Una stringa di parole e frasi tra virgolette che vengono confrontate con gli URL e i titoli dei preferiti.

    • titolo

      stringa facoltativa

      Il titolo del preferito; corrisponde alla versione letterale.

    • url

      stringa facoltativa

      L'URL del preferito; le corrispondenze sono letterali. Tieni presente che le cartelle non hanno URL.

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (results: BookmarkTreeNode[]) => void

Resi

  • Promise<BookmarkTreeNode[]>

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

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à che vuoi modificare; le proprietà non specificate rimarranno invariate. Nota:al momento sono supportati solo "title" e "url".

Parametri

  • id

    stringa

  • modifiche

    oggetto

    • titolo

      stringa facoltativa

    • url

      stringa facoltativa

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (result: BookmarkTreeNode) => void

Resi

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

onChanged

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

Viene attivato quando un preferito o una cartella cambia. Nota:al momento, questa operazione viene attivata solo dalle modifiche al titolo e all'URL.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

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

    • id

      stringa

    • changeInfo

      oggetto

      • titolo

        stringa

      • url

        stringa facoltativa

onChildrenReordered

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

Viene attivato quando l'ordine delle cartelle secondarie di una cartella è cambiato a causa dell'ordinamento nell'interfaccia utente. Non viene chiamato a seguito di un movimento().

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

Viene attivato quando viene creato un preferito o una cartella.

Parametri

onImportBegan

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

Viene attivato quando viene avviata una sessione di importazione dei preferiti. Gli osservatori costosi devono ignorare gli aggiornamenti onCreated finché non viene attivato onImportEnded. Gli osservatori devono comunque gestire immediatamente le altre notifiche.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    () => void

onImportEnded

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

Viene 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 viene spostato 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,
)

Viene attivato quando viene rimosso un preferito o una cartella. Quando una cartella viene rimossa in modo ricorsivo, viene inviata una singola notifica per la cartella e nessuna per i relativi contenuti.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

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

    • id

      stringa

    • removeInfo

      oggetto

      • indice

        numero

      • Chrome 48 o versioni successive
      • parentId

        stringa