chrome.bookmarks

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.

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

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érieures

    Date 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

Chrome 44 ou version ultérieure

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

Obsolète

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

Valeur

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

Obsolète

Les opérations d'écriture aux 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 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()

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

    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

Renvoie

  • Promise<BookmarkTreeNode[]>

    Chrome 90 et versions ultérieures

    Les 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()

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

Récupère les enfants de l'ID BookmarkTreeNode spécifié.

Paramètres

Renvoie

  • Promise<BookmarkTreeNode[]>

    Chrome 90 et versions ultérieures

    Les 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()

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

Récupère les favoris récemment ajoutés.

Paramètres

  • numberOfItems

    number

    Le nombre maximum d'éléments à renvoyer.

  • rappel

    fonction facultative

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

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 de la sous-arborescence à récupérer.

  • rappel

    fonction facultative

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

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

Promesse 
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

Renvoie

  • Chrome 90 et versions ultérieures

    Les 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()

Promesse 
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érieures

    Les 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()

Promesse 
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érieures

    Les 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.

Promesse 
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 et title 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

Renvoie

  • Promise<BookmarkTreeNode[]>

    Chrome 90 et versions ultérieures

    Les 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()

Promesse 
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

Renvoie

  • Chrome 90 et versions ultérieures

    Les 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

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

        number

      • oldIndex

        number

      • 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

        number

      • Chrome 48 ou version ultérieure
      • parentId

        chaîne