browser.bookmarks

Description

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

Cliquer sur l'étoile ajoute un favori
Cliquez sur l'étoile pour ajouter un favori.

Autorisations

bookmarks

Vous devez déclarer l'autorisation "bookmarks" dans le fichier manifeste de l'extension pour utiliser l'API Bookmarks. 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 browser.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é "Extension bookmarks". Le premier argument de create() spécifie les propriétés du nouveau dossier. Le deuxième argument définit une fonction à exécuter une fois le dossier créé.

browser.bookmarks.create(
  {'parentId': bookmarkBar.id, 'title': 'Extension bookmarks'},
  function(newFolder) {
    console.log("added folder: " + newFolder.title);
  },
);

L'extrait suivant crée un favori pointant vers la documentation pour les développeurs d'extensions. Comme rien de grave ne se produira si la création du favori échoue, ce code ne prend pas la peine de définir une fonction de rappel.

browser.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) 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

    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+ browser.* depuis Chrome 148

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

  • folderType

    FolderType facultatif

    Chrome 134+ browser.* depuis Chrome 148

    S'il est présent, il s'agit d'un dossier ajouté par le navigateur et qui ne peut pas être modifié par l'utilisateur ni par l'extension. Les nœuds enfants peuvent être modifiés si la propriété unmodifiable n'est pas définie pour ce nœud. Cette valeur est omise si le nœud peut être modifié par l'utilisateur et l'extension (par défaut).

    Il peut y avoir zéro, un ou plusieurs nœuds de chaque type de dossier. Un dossier peut être ajouté ou supprimé par le navigateur, mais pas via l'API d'extensions.

  • 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 (base 0).

  • parentId

    chaîne facultatif

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

  • Synchronisation…

    booléen

    Chrome 134+ browser.* depuis Chrome 148

    Indique si ce nœud est synchronisé avec l'espace de stockage du compte distant de l'utilisateur par le navigateur. Cela peut être utilisé pour distinguer les versions de compte et les versions locales d'un même FolderType. La valeur de cette propriété peut changer pour un nœud existant, par exemple à la suite d'une action de l'utilisateur.

    Remarque : Cela indique si le nœud est enregistré dans le fournisseur de compte intégré du navigateur. Il est possible qu'un nœud soit synchronisé via un tiers, même si cette valeur est définie sur "false".

    Pour les nœuds gérés (nœuds où unmodifiable est défini sur true), cette propriété sera toujours false.

  • 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 responsable d'un utilisateur supervisé. Cette valeur est omise 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+ browser.* depuis Chrome 148

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. Cette valeur est omise 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

FolderType

Chrome 134+ browser.* depuis Chrome 148

Indique le type de dossier.

Énumération

"bookmarks-bar"
Dossier dont le contenu s'affiche en haut de la fenêtre du navigateur.

"other"
Favoris affichés dans la liste complète des favoris sur toutes les plates-formes.

"mobile"
Favoris généralement disponibles sur les appareils mobiles de l'utilisateur, mais modifiables par extension ou dans le gestionnaire de favoris.

"managed"
Dossier de premier niveau qui peut être présent si l'administrateur système ou le responsable d'un utilisateur supervisé a configuré des favoris.

Propriétés

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

Obsolète

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

Valeur

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

Obsolète

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

Valeur

1000000

ROOT_NODE_ID

Chrome 145+ browser.* depuis Chrome 148

id associé au nœud de niveau racine.

Valeur

"0"

Méthodes

create()

browser.bookmarks.create(
  bookmark: CreateDetails,
): Promise<BookmarkTreeNode>

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

get()

browser.bookmarks.get(
  idOrIdList: string | [string, ...string[]],
): Promise<BookmarkTreeNode[]>

Récupère les BookmarkTreeNode spécifiés.

Paramètres

  • idOrIdList

    string | [string, ...string[]]

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

Renvoie

getChildren()

browser.bookmarks.getChildren(
  id: string,
): Promise<BookmarkTreeNode[]>

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

Paramètres

  • id

    chaîne

Renvoie

getRecent()

browser.bookmarks.getRecent(
  numberOfItems: number,
): Promise<BookmarkTreeNode[]>

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

Paramètres

  • numberOfItems

    nombre

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

Renvoie

getSubTree()

browser.bookmarks.getSubTree(
  id: string,
): Promise<BookmarkTreeNode[]>

Récupère une partie de la hiérarchie des favoris, en commençant par le nœud spécifié.

Paramètres

  • id

    chaîne

    ID de la racine de la sous-arborescence à récupérer.

Renvoie

getTree()

browser.bookmarks.getTree(): Promise<BookmarkTreeNode[]>

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

Renvoie

move()

browser.bookmarks.move(
  id: string,
  destination: object,
): Promise<BookmarkTreeNode>

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

Paramètres

  • id

    chaîne

  • destination

    objet

    • index

      number facultatif

    • parentId

      chaîne facultatif

Renvoie

remove()

browser.bookmarks.remove(
  id: string,
): Promise<void>

Supprime un favori ou un dossier de favoris vide.

Paramètres

  • id

    chaîne

Renvoie

  • Promise<void>

    Chrome 90+ browser.* depuis Chrome 148

removeTree()

browser.bookmarks.removeTree(
  id: string,
): Promise<void>

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

Paramètres

  • id

    chaîne

Renvoie

  • Promise<void>

    Chrome 90+ browser.* depuis Chrome 148 
browser.bookmarks.search(
  query: string | object,
): Promise<BookmarkTreeNode[]>

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

    Soit une chaîne de mots et d'expressions entre guillemets qui sont mis en correspondance avec les URL et les titres des favoris, soit 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

      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.

Renvoie

update()

browser.bookmarks.update(
  id: string,
  changes: object,
): Promise<BookmarkTreeNode>

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 ne seront pas modifiées. Remarque : Actuellement, seuls "title" et "url" sont acceptés.

Paramètres

  • id

    chaîne

  • modifications

    objet

    • titre

      chaîne facultatif

    • url

      chaîne facultatif

Renvoie

Événements

onChanged

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

Se déclenche lorsqu'un favori ou un dossier est modifié. Remarque : Actuellement, seules les modifications de titre et d'URL déclenchent cette action.

Paramètres

  • callback

    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

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

Se déclenche lorsque l'ordre des enfants d'un dossier a été modifié en raison d'un tri dans l'UI. Cette méthode n'est pas appelée à la suite d'un move().

Paramètres

  • callback

    fonction

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

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

    • id

      chaîne

    • reorderInfo

      objet

      • childIds

        chaîne[]

onCreated

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

Déclenché lorsqu'un favori ou un dossier est créé.

Paramètres

  • callback

    fonction

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

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

onImportBegan

browser.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 onImportEnded soit déclenché. Les observateurs doivent toujours traiter les autres notifications immédiatement.

Paramètres

  • callback

    fonction

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

    () => void

onImportEnded

browser.bookmarks.onImportEnded.addListener(
  callback: function,
)

Déclenché lorsqu'une session d'importation de favoris se termine.

Paramètres

  • callback

    fonction

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

    () => void

onMoved

browser.bookmarks.onMoved.addListener(
  callback: function,
)

Se déclenche lorsqu'un favori ou un dossier est déplacé vers un autre dossier parent.

Paramètres

  • callback

    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

browser.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, et aucune pour son contenu.

Paramètres

  • callback

    fonction

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

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

    • id

      chaîne

    • removeInfo

      objet

      • index

        nombre

      • Chrome 48+ browser.* depuis Chrome 148
      • parentId

        chaîne