Description
Utilisez l'API chrome.bookmarks
pour créer, organiser et manipuler des favoris. Consultez également l'article Remplacer les pages qui vous permet de créer une page personnalisée du gestionnaire de favoris.
Autorisations
bookmarks
Pour utiliser l'API Favoris, vous devez déclarer l'autorisation "Favoris" dans le fichier manifeste de l'extension. Exemple :
{
"name": "My extension",
...
"permissions": [
"bookmarks"
],
...
}
Concepts et utilisation
Objets et propriétés
Les favoris sont organisés dans une arborescence, où chaque nœud est soit un favori, soit un dossier (parfois appelé groupe). Chaque nœud de l'arborescence est représenté par un objet bookmarks.BookmarkTreeNode.
Les propriétés BookmarkTreeNode
sont utilisées dans l'API chrome.bookmarks
. Par exemple, lorsque vous appelez bookmarks.create, vous transmettez le parent du nouveau nœud (parentId
) et, éventuellement, les propriétés index
, title
et url
du nœud. Pour en savoir plus sur les propriétés d'un nœud, consultez la section bookmarks.BookmarkTreeNode.
Exemples
Le code suivant crée un dossier intitulé "Extension favoris". Le premier argument de create()
spécifie les propriétés du nouveau dossier. Le deuxième argument définit une fonction à
exécuter après la création du dossier.
chrome.bookmarks.create(
{'parentId': bookmarkBar.id, 'title': 'Extension bookmarks'},
function(newFolder) {
console.log("added folder: " + newFolder.title);
},
);
L'extrait de code suivant crée un favori qui renvoie vers la documentation destinée aux développeurs sur les extensions. Étant donné que rien n'est grave en cas d'échec de la création du favori, ce code ne prend pas la peine de définir une fonction de rappel.
chrome.bookmarks.create({
'parentId': extensionsFolderId,
'title': 'Extensions doc',
'url': 'https://developer.chrome.com/docs/extensions',
});
Pour essayer cette API, installez l'exemple d'API Favoris à partir du dépôt chrome-extension-samples.
Types
BookmarkTreeNode
Nœud (un favori ou un dossier) dans l'arborescence des favoris. Les nœuds enfants sont classés dans leur dossier parent.
Propriétés
-
enfants
BookmarkTreeNode[] facultatif
Liste numérotée des enfants de ce nœud.
-
dateAdded
numéro facultatif
Date de création de ce nœud, en millisecondes depuis l'epoch (
new Date(dateAdded)
). -
dateGroupModified
numéro facultatif
Date et heure de la dernière modification du contenu de ce dossier, en millisecondes depuis l'epoch.
-
dateLastUsed
numéro facultatif
Chrome 114 et versions ultérieuresDate de la dernière ouverture de ce nœud, en millisecondes depuis l'epoch. Non défini pour les dossiers.
-
id
chaîne
Identifiant unique du nœud. Les identifiants sont uniques au sein du profil actuel et restent valides même après le redémarrage du navigateur.
-
index
numéro facultatif
Position en base 0 de ce nœud dans son dossier parent.
-
parentId
string facultatif
Le fichier
id
du dossier parent. Omis pour le nœud racine. -
title
chaîne
Texte affiché pour le nœud.
-
non modifiable
facultatif
Indique la raison pour laquelle ce nœud n'est pas modifiable. La valeur
managed
indique que ce nœud a été configuré par l'administrateur système ou par le dépositaire d'un utilisateur supervisé. Omis si le nœud peut être modifié par l'utilisateur et l'extension (par défaut). -
url
string facultatif
URL vers laquelle accède un utilisateur lorsqu'il clique sur le favori. Omis pour les dossiers.
BookmarkTreeNodeUnmodifiable
Indique la raison pour laquelle ce nœud n'est pas modifiable. La valeur managed
indique que ce nœud a été configuré par l'administrateur système. Omis si le nœud peut être modifié par l'utilisateur et l'extension (par défaut).
Valeur
CreateDetails
Objet transmis à la fonction create().
Propriétés
-
index
numéro facultatif
-
parentId
string facultatif
Le dossier "Autres favoris" est sélectionné par défaut.
-
title
string facultatif
-
url
string facultatif
Propriétés
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
Les opérations d'écriture aux favoris ne sont plus limitées par Chrome.
Valeur
1000000
MAX_WRITE_OPERATIONS_PER_HOUR
Les opérations d'écriture aux favoris ne sont plus limitées par Chrome.
Valeur
1000000
Méthodes
create()
chrome.bookmarks.create(
bookmark: CreateDetails,
callback?: function,
)
Crée un favori ou un dossier sous le parentId spécifié. Si l'URL est NULL ou manquante, il s'agit d'un dossier.
Paramètres
-
ajouter aux favoris
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(result: BookmarkTreeNode) => void
-
résultat
-
Renvoie
-
Promise<BookmarkTreeNode>
Chrome 90 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
get()
chrome.bookmarks.get(
idOrIdList: string | [string, ...string[]],
callback?: function,
)
Récupère le ou les BookmarkTreeNode spécifiés.
Paramètres
-
idOrIdList
chaîne | [chaîne, ...chaîne[]]
ID à valeur de chaîne unique ou tableau d'ID à valeur de chaîne
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(results: BookmarkTreeNode[]) => void
-
résultats
-
Renvoie
-
Promise<BookmarkTreeNode[]>
Chrome 90 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
getChildren()
chrome.bookmarks.getChildren(
id: string,
callback?: function,
)
Récupère les enfants de l'ID BookmarkTreeNode spécifié.
Paramètres
-
id
chaîne
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(results: BookmarkTreeNode[]) => void
-
résultats
-
Renvoie
-
Promise<BookmarkTreeNode[]>
Chrome 90 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
getRecent()
chrome.bookmarks.getRecent(
numberOfItems: number,
callback?: function,
)
Récupère les favoris récemment ajoutés.
Paramètres
-
numberOfItems
Nombre
Le nombre maximum d'éléments à renvoyer.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(results: BookmarkTreeNode[]) => void
-
résultats
-
Renvoie
-
Promise<BookmarkTreeNode[]>
Chrome 90 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
getSubTree()
chrome.bookmarks.getSubTree(
id: string,
callback?: function,
)
Récupère une partie de la hiérarchie des favoris, à partir du nœud spécifié.
Paramètres
-
id
chaîne
ID de la racine de la sous-arborescence à récupérer.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(results: BookmarkTreeNode[]) => void
-
résultats
-
Renvoie
-
Promise<BookmarkTreeNode[]>
Chrome 90 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
getTree()
chrome.bookmarks.getTree(
callback?: function,
)
Récupère l'intégralité de la hiérarchie des favoris.
Paramètres
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(results: BookmarkTreeNode[]) => void
-
résultats
-
Renvoie
-
Promise<BookmarkTreeNode[]>
Chrome 90 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
move()
chrome.bookmarks.move(
id: string,
destination: object,
callback?: function,
)
Déplace le BookmarkTreeNode spécifié vers l'emplacement indiqué.
Paramètres
-
id
chaîne
-
destination
objet
-
index
numéro facultatif
-
parentId
string facultatif
-
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(result: BookmarkTreeNode) => void
-
résultat
-
Renvoie
-
Promise<BookmarkTreeNode>
Chrome 90 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
remove()
chrome.bookmarks.remove(
id: string,
callback?: function,
)
Supprime un favori ou un dossier de favoris vide.
Paramètres
-
id
chaîne
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Chrome 90 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
removeTree()
chrome.bookmarks.removeTree(
id: string,
callback?: function,
)
Supprime un dossier de favoris de manière récursive.
Paramètres
-
id
chaîne
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Chrome 90 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
search()
chrome.bookmarks.search(
query: string | object,
callback?: function,
)
Recherche les objets BookmarkTreeNode correspondant à la requête donnée. Les requêtes spécifiées avec un objet produisent des BookmarkTreeNodes correspondant à toutes les propriétés spécifiées.
Paramètres
-
requête
chaîne | objet
Il peut s'agir d'une chaîne de mots et d'expressions entre guillemets qui sont mises en correspondance avec les titres et les URL des favoris, ou d'un objet. S'il s'agit d'un objet, les propriétés
query
,url
ettitle
peuvent être spécifiées et les favoris correspondant à toutes les propriétés spécifiées seront générés.-
requête
string facultatif
Chaîne de mots et d'expressions entre guillemets qui sont mises en correspondance avec les titres et les URL des favoris.
-
title
string facultatif
Titre du favori ; correspond mot à mot.
-
url
string facultatif
URL du favori ; correspond exactement à Notez que les dossiers n'ont pas d'URL.
-
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(results: BookmarkTreeNode[]) => void
-
résultats
-
Renvoie
-
Promise<BookmarkTreeNode[]>
Chrome 90 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
update()
chrome.bookmarks.update(
id: string,
changes: object,
callback?: function,
)
Met à jour les propriétés d'un favori ou d'un dossier. Spécifiez uniquement les propriétés que vous souhaitez modifier. Les propriétés non spécifiées restent inchangées. Remarque:Actuellement, seuls les attributs "title" et "url" sont acceptés.
Paramètres
-
id
chaîne
-
modifications
objet
-
title
string facultatif
-
url
string facultatif
-
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(result: BookmarkTreeNode) => void
-
résultat
-
Renvoie
-
Promise<BookmarkTreeNode>
Chrome 90 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
Événements
onChanged
chrome.bookmarks.onChanged.addListener(
callback: function,
)
Déclenché lorsqu'un favori ou un dossier est modifié. Remarque:Actuellement, seuls les changements de titre et d'URL déclenchent ce comportement.
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(id: string, changeInfo: object) => void
-
id
chaîne
-
changeInfo
objet
-
title
chaîne
-
url
string facultatif
-
-
onChildrenReordered
chrome.bookmarks.onChildrenReordered.addListener(
callback: function,
)
Déclenché lorsque l'ordre des éléments enfants d'un dossier a été modifié en raison de l'ordre de tri dans l'interface utilisateur. Cette opération n'est pas appelée à la suite d'une commande move().
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(id: string, reorderInfo: object) => void
-
id
chaîne
-
reorderInfo
objet
-
childIds
chaîne[]
-
-
onCreated
chrome.bookmarks.onCreated.addListener(
callback: function,
)
Déclenché lors de la création d'un favori ou d'un dossier
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(id: string, bookmark: BookmarkTreeNode) => void
-
id
chaîne
-
ajouter aux favoris
-
onImportBegan
chrome.bookmarks.onImportBegan.addListener(
callback: function,
)
Déclenché lorsqu'une session d'importation de favoris commence. Les observateurs coûteux doivent ignorer les mises à jour onCreated jusqu'à ce qu'onImportEnded soit déclenché. Les observateurs doivent toujours traiter les autres notifications immédiatement.
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :() => void
onImportEnded
chrome.bookmarks.onImportEnded.addListener(
callback: function,
)
Déclenché à la fin d'une session d'importation de favoris
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :() => void
onMoved
chrome.bookmarks.onMoved.addListener(
callback: function,
)
Déclenché lorsqu'un favori ou un dossier est déplacé vers un autre dossier parent.
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(id: string, moveInfo: object) => void
-
id
chaîne
-
moveInfo
objet
-
index
Nombre
-
oldIndex
Nombre
-
oldParentId
chaîne
-
parentId
chaîne
-
-
onRemoved
chrome.bookmarks.onRemoved.addListener(
callback: function,
)
Déclenché lorsqu'un favori ou un dossier est supprimé. Lorsqu'un dossier est supprimé de manière récursive, une seule notification est déclenchée pour le dossier, mais aucune pour son contenu.
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(id: string, removeInfo: object) => void
-
id
chaîne
-
removeInfo
objet
-
index
Nombre
-
nœudChrome 48 ou version ultérieure
-
parentId
chaîne
-
-