chrome.bookmarks

Description

Utilisez l'API chrome.bookmarks pour créer, organiser et manipuler des favoris. Consultez également l'article Remplacer les pages, qui permet de créer une page personnalisée dans le Gestionnaire de favoris.

<ph type="x-smartling-placeholder">
</ph> Cliquer sur l&#39;étoile permet d&#39;ajouter un favori
Le fait de cliquer sur l'étoile ajoute un favori.

Autorisations

bookmarks

Vous devez déclarer les "favoris" autorisation dans le fichier manifeste de l'extension d'utiliser l'API des favoris. 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 correspond à un favori ou à un dossier. (parfois appelé groupe). Chaque nœud de l'arborescence est représenté 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, le les propriétés index, title et url du nœud. Pour en savoir plus, consultez bookmarks.BookmarkTreeNode. sur les propriétés qu'un nœud peut avoir.

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écuté 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 redirige vers la documentation pour les développeurs sur les extensions. Depuis rien de grave ne se passera si la création du favori échoue, ce code ne permet pas de définir un 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 de chrome-extension-samples. un dépôt de clés.

Types

BookmarkTreeNode

Un 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 de dernière modification du contenu de ce dossier, en millisecondes depuis l'epoch.

  • dateLastUsed

    numéro facultatif

    Chrome 114 ou version ultérieure

    Date de la dernière ouverture de ce nœud, en millisecondes depuis l'époque. Non défini pour les dossiers.

  • id

    chaîne

    Identifiant unique du nœud. Les identifiants sont uniques dans le 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

    chaîne facultatif

    Le 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 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

    chaîne facultatif

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

BookmarkTreeNodeUnmodifiable

Chrome (version 44 ou 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

"géré"

CreateDetails

Objet transmis à la fonction create().

Propriétés

  • index

    numéro facultatif

  • parentId

    chaîne facultatif

    Le dossier "Autres favoris" est sélectionné par défaut.

  • titre

    chaîne facultatif

  • url

    chaîne facultatif

Propriétés

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

<ph type="x-smartling-placeholder"></ph> Obsolète

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

Valeur

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

<ph type="x-smartling-placeholder"></ph> Obsolète

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

Valeur

1000000

Méthodes

create()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.bookmarks.create(
  bookmark: CreateDetails,
  callback?: function,
)

Crée un favori ou un dossier sous l'élément parentId spécifié. Si l'URL est NULL ou manquante, il s'agira d'un dossier.

Paramètres

Renvoie

  • Promise&lt;BookmarkTreeNode&gt;

    Chrome 90 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

get()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.bookmarks.get(
  idOrIdList: string | [string, ...string[]],
  callback?: function,
)

Récupère le ou les BookmarkTreeNode(s) spécifiés.

Paramètres

  • idOrIdList

    string | [chaîne, ...chaîne[]]

    ID de valeur de chaîne unique ou tableau d'ID de valeur de chaîne

  • rappel

    function facultatif

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

    (results: BookmarkTreeNode[]) => void

Renvoie

  • Promise&lt;BookmarkTreeNode[]&gt;

    Chrome 90 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

getChildren()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.bookmarks.getChildren(
  id: string,
  callback?: function,
)

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

Paramètres

Renvoie

  • Promise&lt;BookmarkTreeNode[]&gt;

    Chrome 90 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

getRecent()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.bookmarks.getRecent(
  numberOfItems: number,
  callback?: function,
)

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

Paramètres

  • numberOfItems

    Nombre

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

  • rappel

    function facultatif

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

    (results: BookmarkTreeNode[]) => void

Renvoie

  • Promise&lt;BookmarkTreeNode[]&gt;

    Chrome 90 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

getSubTree()

<ph type="x-smartling-placeholder"></ph> 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

    function facultatif

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

    (results: BookmarkTreeNode[]) => void

Renvoie

  • Promise&lt;BookmarkTreeNode[]&gt;

    Chrome 90 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

getTree()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.bookmarks.getTree(
  callback?: function,
)

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

Paramètres

Renvoie

  • Promise&lt;BookmarkTreeNode[]&gt;

    Chrome 90 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

move()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.bookmarks.move(
  id: string,
  destination: object,
  callback?: function,
)

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

Paramètres

  • id

    chaîne

  • destination

    objet

    • index

      numéro facultatif

    • parentId

      chaîne facultatif

  • rappel

    function facultatif

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

    (result: BookmarkTreeNode) => void

Renvoie

  • Promise&lt;BookmarkTreeNode&gt;

    Chrome 90 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

remove()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.bookmarks.remove(
  id: string,
  callback?: function,
)

Supprime un favori ou un dossier de favoris vide.

Paramètres

  • id

    chaîne

  • rappel

    function facultatif

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

    () => void

Renvoie

  • Promesse<void>

    Chrome 90 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

removeTree()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.bookmarks.removeTree(
  id: string,
  callback?: function,
)

Supprime un dossier de favoris de manière récursive.

Paramètres

  • id

    chaîne

  • rappel

    function facultatif

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

    () => void

Renvoie

  • Promesse<void>

    Chrome 90 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.bookmarks.search(
  query: string | object,
  callback?: function,
)

Recherche les BookmarkTreeNodes 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

    string | objet

    Il s'agit soit d'une chaîne de mots et d'expressions entre guillemets, d'une correspondance avec les URL et les titres des favoris, soit un objet. Dans le cas d'un objet, les propriétés query, url et title peuvent être spécifiées, et des favoris correspondant à toutes les propriétés spécifiées sont générés.

    • requête

      chaîne facultatif

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

    • titre

      chaîne facultatif

      Titre du favori correspond mot pour mot.

    • url

      chaîne facultatif

      URL du favori correspond mot pour mot. Notez que les dossiers n'ont pas d'URL.

  • rappel

    function facultatif

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

    (results: BookmarkTreeNode[]) => void

Renvoie

  • Promise&lt;BookmarkTreeNode[]&gt;

    Chrome 90 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

update()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.bookmarks.update(
  id: string,
  changes: object,
  callback?: function,
)

Met à jour les propriétés d'un favori ou d'un dossier. spécifier uniquement les propriétés que vous souhaitez modifier ; les propriétés non spécifiées restent inchangées. Remarque:Actuellement, seul l'attribut 'titre' [title] et 'url' sont pris en charge.

Paramètres

  • id

    chaîne

  • modifications

    objet

    • titre

      chaîne facultatif

    • url

      chaîne facultatif

  • rappel

    function facultatif

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

    (result: BookmarkTreeNode) => void

Renvoie

  • Promise&lt;BookmarkTreeNode&gt;

    Chrome 90 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La 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é lors de modifications apportées à un favori ou à un dossier Remarque:Actuellement, seules les modifications 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 les éléments enfants d'un dossier ont changé d'ordre en raison du tri dans l'interface utilisateur. Cette fonction n'est pas appelée à la suite d'une commande 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é lors de la création d'un favori ou d'un dossier

Paramètres

onImportBegan

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

Déclenché au début d'une session d'importation de favoris. Les observateurs coûteux doivent ignorer les mises à jour onCreated jusqu'au déclenchement de onImportEnded. Les observateurs doivent traiter les autres notifications immédiatement.

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é lors de la suppression d'un favori ou d'un dossier Lorsqu'un dossier est supprimé de façon récursive, une seule notification est déclenchée pour ce dossier, mais 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 (version 48 ou ultérieure)
      • parentId

        chaîne