chrome.bookmarks

Description

Utilisez l'API chrome.bookmarks pour créer, organiser et manipuler les favoris. Consultez également Pages de remplacement, que vous pouvez utiliser pour créer une page de gestionnaire de favoris personnalisée.

Cliquer sur l'étoile permet d'ajouter un favori
Cliquer sur l'étoile ajoute un favori.

Autorisations

bookmarks

Pour utiliser l'API Bookmarks, vous devez déclarer l'autorisation "bookmarks" 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 un favori ou 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'ensemble de 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 qu'un nœud peut avoir, consultez bookmarks.BookmarkTreeNode.

Exemples

Le code suivant crée un dossier intitulé "Favoris de l'extension". 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 pointant vers la documentation destinée aux développeurs sur les extensions. Comme rien de grave ne se produit si la création du favori échoue, ce code ne se soucie pas 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 Bookmarks à partir du dépôt chrome-extension-samples.

Types

BookmarkTreeNode

Nœud (favori ou dossier) de l'arborescence des favoris. Les nœuds enfants sont triés dans leur dossier parent.

Propriétés

  • enfants

    BookmarkTreeNode[] facultatif

    Liste ordonnée des enfants de ce nœud.

  • dateAdded

    number facultatif

    Date de création de ce nœud, en millisecondes depuis l'epoch (new Date(dateAdded)).

  • dateGroupModified

    number facultatif

    Date et heure de la dernière modification du contenu de ce dossier, en millisecondes depuis l'epoch.

  • dateLastUsed

    number facultatif

    Chrome 114 ou version ultérieure

    Date et heure 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 ID sont uniques dans le profil actuel et restent valides même après le redémarrage du navigateur.

  • index

    number facultatif

    Position de ce nœud dans son dossier parent, basée sur 0.

  • parentId

    chaîne facultatif

    id du dossier parent. Omis pour le nœud racine.

  • titre

    chaîne

    Texte affiché pour le nœud.

  • non modifiable

    "managed"
     facultatif

    Indique la raison pour laquelle ce nœud ne peut pas être modifié. La valeur managed indique que ce nœud a été configuré par l'administrateur système ou par le responsable d'un utilisateur supervisé. Omis si le nœud peut être modifié par l'utilisateur et l'extension (par défaut).

  • url

    chaîne facultatif

    URL vers laquelle l'utilisateur est redirigé lorsqu'il clique sur le favori. omis pour les dossiers.

BookmarkTreeNodeUnmodifiable

Chrome 44 ou version ultérieure

Indique la raison pour laquelle ce nœud ne peut pas être modifié. 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

"managed"

CreateDetails

Objet transmis à la fonction create().

Propriétés

  • index

    number facultatif

  • parentId

    chaîne facultatif

    Par défaut, il s'agit du dossier "Autres favoris".

  • titre

    chaîne facultatif

  • url

    chaîne facultatif

Propriétés

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

Obsolète

Les opérations d'écriture des favoris ne sont plus limitées par Chrome.

Valeur

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

Obsolète

Les opérations d'écriture des favoris ne sont plus limitées par Chrome.

Valeur

1000000

Méthodes

create()

Promesse 
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

Renvoie

  • Chrome 90 et versions ultérieures

    Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout avec le même type que celui transmis au rappel.

get()

Promesse 
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[]]

    Un seul ID de chaîne ou un tableau d'ID de chaîne

  • rappel

    fonction facultatif

    Le paramètre callback se présente comme suit : 

    (results: BookmarkTreeNode[]) => void

Renvoie

  • Promise<BookmarkTreeNode[]>

    Chrome 90 et versions ultérieures

    Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout avec le même type que celui transmis au rappel.

getChildren()

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

    Le paramètre callback se présente comme suit : 

    (results: BookmarkTreeNode[]) => void

Renvoie

  • Promise<BookmarkTreeNode[]>

    Chrome 90 et versions ultérieures

    Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout avec le même type que celui transmis au rappel.

getRecent()

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

    Le paramètre callback se présente comme suit : 

    (results: BookmarkTreeNode[]) => void

Renvoie

  • Promise<BookmarkTreeNode[]>

    Chrome 90 et versions ultérieures

    Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout avec le même type que celui transmis au rappel.

getSubTree()

Promesse 
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 du sous-arbre à récupérer.

  • rappel

    fonction facultatif

    Le paramètre callback se présente comme suit : 

    (results: BookmarkTreeNode[]) => void

Renvoie

  • Promise<BookmarkTreeNode[]>

    Chrome 90 et versions ultérieures

    Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout avec le même type que celui transmis au rappel.

getTree()

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

Récupère l'intégralité de la hiérarchie des favoris.

Paramètres

Renvoie

  • Promise<BookmarkTreeNode[]>

    Chrome 90 et versions ultérieures

    Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout avec le même type que celui transmis au rappel.

move()

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

Déplace le BookmarkTreeNode spécifié à l'emplacement fourni.

Paramètres

  • id

    chaîne

  • destination

    objet

    • index

      number facultatif

    • parentId

      chaîne facultatif

  • rappel

    fonction facultatif

    Le paramètre callback se présente comme suit : 

    (result: BookmarkTreeNode) => void

Renvoie

  • Chrome 90 et versions ultérieures

    Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout avec le même type que celui transmis au rappel.

remove()

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

Supprime un favori ou un dossier de favoris vide.

Paramètres

  • id

    chaîne

  • rappel

    fonction facultatif

    Le paramètre callback se présente comme suit : 

    () => void

Renvoie

  • Promise<void>

    Chrome 90 et versions ultérieures

    Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout avec le même type que celui transmis au rappel.

removeTree()

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

Supprime récursivement un dossier de favoris.

Paramètres

  • id

    chaîne

  • rappel

    fonction facultatif

    Le paramètre callback se présente comme suit : 

    () => void

Renvoie

  • Promise<void>

    Chrome 90 et versions ultérieures

    Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout avec le même type que celui transmis au rappel.

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

Recherche des BookmarkTreeNodes correspondant à la requête donnée. Les requêtes spécifiées avec un objet génèrent des BookmarkTreeNodes correspondant à toutes les propriétés spécifiées.

Paramètres

  • requête

    chaîne | objet

    Chaîne de mots et d'expressions entre guillemets mis en correspondance avec les URL et les titres des favoris, ou objet. Si vous spécifiez un objet, les propriétés query, url et title peuvent être spécifiées, et les signets correspondant à toutes les propriétés spécifiées seront générés.

    • requête

      chaîne facultatif

      Chaîne de mots et d'expressions entre guillemets qui sont mis en correspondance avec les URL et les titres des favoris.

    • titre

      chaîne facultatif

      Titre du favori : correspond exactement.

    • url

      chaîne facultatif

      URL du favori : correspond exactement. Notez que les dossiers n'ont pas d'URL.

  • rappel

    fonction facultatif

    Le paramètre callback se présente comme suit : 

    (results: BookmarkTreeNode[]) => void

Renvoie

  • Promise<BookmarkTreeNode[]>

    Chrome 90 et versions ultérieures

    Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout avec le même type que celui transmis au rappel.

update()

Promesse 
chrome.bookmarks.update(
  id: string,
  changes: object,
  callback?: function,
)

Met à jour les propriétés d'un favori ou d'un dossier. Ne spécifiez que les propriétés que vous souhaitez modifier. Les propriétés non spécifiées ne seront pas modifiées. Remarque:Pour le moment, seuls les attributs "title" et "url" sont acceptés.

Paramètres

  • id

    chaîne

  • modifications

    objet

    • titre

      chaîne facultatif

    • url

      chaîne facultatif

  • rappel

    fonction facultatif

    Le paramètre callback se présente comme suit : 

    (result: BookmarkTreeNode) => void

Renvoie

  • Chrome 90 et versions ultérieures

    Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout 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 change. Remarque:Actuellement, seuls les changements de titre et d'URL déclenchent cette action.

Paramètres

  • rappel

    fonction

    Le paramètre callback se présente comme suit : 

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

    • id

      chaîne

    • changeInfo

      objet

      • titre

        chaîne

      • url

        chaîne facultatif

onChildrenReordered

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

Déclenché lorsque l'ordre des enfants d'un dossier a changé en raison de l'ordre de tri dans l'interface utilisateur. Cette méthode n'est pas appelée à la suite d'un move().

Paramètres

  • rappel

    fonction

    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é lorsqu'un favori ou un dossier est créé.

Paramètres

  • rappel

    fonction

    Le paramètre callback se présente comme suit : 

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

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 que l'événement onImportEnded soit déclenché. Les observateurs doivent toujours gérer immédiatement les autres notifications.

Paramètres

  • rappel

    fonction

    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

    fonction

    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

    fonction

    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 envoyée pour le dossier, et aucune pour son contenu.

Paramètres

  • rappel

    fonction

    Le paramètre callback se présente comme suit : 

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

    • id

      chaîne

    • removeInfo

      objet

      • index

        Nombre

      • Chrome 48 et versions ultérieures
      • parentId

        chaîne