chrome.bookmarks

Questa autorizzazione attiva un avviso.

Descrizione

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

Autorizzazioni

bookmarks

Se fai clic sulla stella, viene aggiunto un segnalibro

Manifest

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

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

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 in tutta l'API chrome.bookmarks. Ad esempio, quando chiami bookmarks.create, trasmetti il nodo padre 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 dell'estensione". 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);
  },
);

Il seguente snippet crea un segnalibro che rimanda alla documentazione per gli sviluppatori relativa alle estensioni. Poiché non succederà nulla di grave se la creazione del segnalibro 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 dei nodi secondari di questo nodo.

  • dateAdded

    number (facoltativo)

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

  • dateGroupModified

    number (facoltativo)

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

  • dateLastUsed

    number (facoltativo)

    Chrome 114+

    Data dell'ultima apertura di questo nodo, in millisecondi dall'epoca. Non impostato per le cartelle.

  • folderType

    FolderType facoltativo

    Chrome 134+

    Se presente, si tratta di una cartella aggiunta dal browser e che non può essere modificata dall'utente o dall'estensione. I nodi secondari possono essere modificati se questo nodo non ha impostato la proprietà unmodifiable. Omesso se il nodo può essere modificato dall'utente e dall'estensione (impostazione predefinita).

    Possono esserci zero, uno o più nodi di ogni tipo di cartella. Una cartella può essere aggiunta o rimossa dal browser, ma non tramite l'API Extensions.

  • 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 di questo nodo all'interno della cartella principale, a partire da 0.

  • parentId

    stringa facoltativa

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

  • sincronizzazione in corso…

    booleano

    Chrome 134+

    Indica se questo nodo viene sincronizzato con lo spazio di archiviazione dell'account remoto dell'utente dal browser. Può essere utilizzato per distinguere tra le versioni dell'account e solo locali dello stesso FolderType. Il valore di questa proprietà può cambiare per un nodo esistente, ad esempio a seguito dell'azione dell'utente.

    Nota: questo valore indica se il nodo viene salvato nel provider di account integrato del browser. È possibile che un nodo venga sincronizzato tramite una terza parte, anche se questo valore è false.

    Per i nodi gestiti (nodi in cui unmodifiable è impostato su true), questa proprietà sarà sempre false.

  • 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 tutore di un utente supervisionato. Omesso se il nodo può essere modificato dall'utente e dall'estensione (impostazione predefinita).

  • url

    stringa facoltativa

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

BookmarkTreeNodeUnmodifiable

Chrome 44+

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

"managed"

CreateDetails

Oggetto passato alla funzione create().

Proprietà

  • indice

    number (facoltativo)

  • parentId

    stringa facoltativa

    Per impostazione predefinita, viene selezionata la cartella Altri preferiti.

  • titolo

    stringa facoltativa

  • url

    stringa facoltativa

FolderType

Chrome 134+

Indica il tipo di cartella.

Enum

"bookmarks-bar"
La cartella il cui contenuto viene visualizzato nella parte superiore della finestra del browser.

"altro"
Preferiti visualizzati nell'elenco completo dei preferiti su tutte le piattaforme.

"mobile"
I preferiti sono generalmente disponibili sui dispositivi mobili dell'utente, ma possono essere modificati tramite l'estensione o nel Gestore dei preferiti.

"gestito"
Una cartella di primo livello che potrebbe essere presente se l'amministratore di sistema o il tutore di un utente supervisionato ha configurato i preferiti.

Proprietà

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

Obsoleto

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

Valore

1.000.000

MAX_WRITE_OPERATIONS_PER_HOUR

Obsoleto

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

Valore

1.000.000

Metodi

create()

Promessa 
chrome.bookmarks.create(
  bookmark: CreateDetails,
  callback?: function,
): Promise<BookmarkTreeNode>

Crea un segnalibro o una cartella in base al parentId specificato. Se l'URL è NULL o mancante, si tratta di una cartella.

Parametri

Resi

  • Chrome 90+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

get()

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

Recupera i nodi BookmarkTreeNode specificati.

Parametri

  • idOrIdList

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

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

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (results: BookmarkTreeNode[]) => void

Resi

  • Promise<BookmarkTreeNode[]>

    Chrome 90+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

getChildren()

Promessa 
chrome.bookmarks.getChildren(
  id: string,
  callback?: function,
): Promise<BookmarkTreeNode[]>

Recupera i nodi secondari dell'ID BookmarkTreeNode specificato.

Parametri

Resi

  • Promise<BookmarkTreeNode[]>

    Chrome 90+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

getRecent()

Promessa 
chrome.bookmarks.getRecent(
  numberOfItems: number,
  callback?: function,
): Promise<BookmarkTreeNode[]>

Recupera i preferiti aggiunti di recente.

Parametri

  • numberOfItems

    numero

    Il numero massimo di elementi da restituire.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (results: BookmarkTreeNode[]) => void

Resi

  • Promise<BookmarkTreeNode[]>

    Chrome 90+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

getSubTree()

Promessa 
chrome.bookmarks.getSubTree(
  id: string,
  callback?: function,
): Promise<BookmarkTreeNode[]>

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

Resi

  • Promise<BookmarkTreeNode[]>

    Chrome 90+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

getTree()

Promessa 
chrome.bookmarks.getTree(
  callback?: function,
): Promise<BookmarkTreeNode[]>

Recupera l'intera gerarchia dei preferiti.

Parametri

Resi

  • Promise<BookmarkTreeNode[]>

    Chrome 90+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

move()

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

Sposta il nodo dell'albero dei preferiti specificato nella posizione fornita.

Parametri

  • id

    stringa

  • destinazione

    oggetto

    • indice

      number (facoltativo)

    • parentId

      stringa facoltativa

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (result: BookmarkTreeNode) => void

Resi

  • Chrome 90+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

remove()

Promessa 
chrome.bookmarks.remove(
  id: string,
  callback?: function,
): Promise<void>

Rimuove un preferito o una cartella di preferiti vuota.

Parametri

  • id

    stringa

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 90+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

removeTree()

Promessa 
chrome.bookmarks.removeTree(
  id: string,
  callback?: function,
): Promise<void>

Rimuove in modo ricorsivo una cartella di preferiti.

Parametri

  • id

    stringa

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 90+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

Promessa 
chrome.bookmarks.search(
  query: string | object,
  callback?: function,
): Promise<BookmarkTreeNode[]>

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

Parametri

  • query

    stringa | oggetto

    Una stringa di parole e frasi tra virgolette che vengono confrontate con i titoli e gli URL dei preferiti oppure un oggetto. Se un oggetto, le proprietà query, url e title possono essere specificate e verranno prodotti segnalibri corrispondenti a tutte le proprietà specificate.

    • query

      stringa facoltativa

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

    • titolo

      stringa facoltativa

      Il titolo del segnalibro, che corrisponde esattamente.

    • url

      stringa facoltativa

      L'URL del preferito, che deve corrispondere esattamente. Tieni presente che le cartelle non hanno un URL.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (results: BookmarkTreeNode[]) => void

Resi

  • Promise<BookmarkTreeNode[]>

    Chrome 90+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

update()

Promessa 
chrome.bookmarks.update(
  id: string,
  changes: object,
  callback?: function,
): Promise<BookmarkTreeNode>

Aggiorna le proprietà di un segnalibro 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

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (result: BookmarkTreeNode) => void

Resi

  • Chrome 90+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

Eventi

onChanged

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

Attivato quando un preferito o una cartella cambia. Nota:al momento, solo le modifiche al titolo e all'URL attivano questa operazione.

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

Attivato quando l'ordine dei figli di una cartella è cambiato perché l'ordine è stato ordinato nella UI. Questa chiamata non viene eseguita a seguito di una chiamata a move().

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

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

    • id

      stringa

    • reorderInfo

      oggetto

      • childIds

        string[]

onCreated

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

Attivato quando viene creato un segnalibro o una cartella.

Parametri

onImportBegan

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

Attivato all'inizio di 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,
)

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

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

Attivato quando viene rimosso un segnalibro o una cartella. Quando una cartella viene rimossa in modo ricorsivo, viene attivata una sola 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