chrome.bookmarks

Cette autorisation déclenche un avertissement.

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.

Autorisations

bookmarks

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

Fichier manifeste

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"
  ],
  ...
}

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. Étant donné qu'aucun problème 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.

  • folderType

    FolderType facultatif

    En attente

    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. Omis 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 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, basée sur 0.

  • parentId

    chaîne facultatif

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

  • Synchronisation…

    booléen

    En attente

    Indique si ce nœud est synchronisé avec le stockage de compte à distance de l'utilisateur par le navigateur. Vous pouvez l'utiliser pour distinguer les versions du compte et les versions locales uniquement du même FolderType. La valeur de cette propriété peut changer pour un nœud existant, par exemple en raison d'une action de l'utilisateur.

    Remarque: indique si le nœud est enregistré dans le fournisseur de comptes intégré du navigateur. Il est possible qu'un nœud soit synchronisé via un tiers, même si cette valeur est fausse.

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

  • 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

FolderType

En attente

Indique le type de dossier.

  • 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
  • géré: dossier de niveau supérieur qui peut être présent si l'administrateur système ou le responsable d'un utilisateur supervisé a configuré des favoris.

Énumération

"bookmarks-bar"

"other"

"mobile"

"managed"

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 ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

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 ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

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 ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getRecent()

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

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

Paramètres

  • numberOfItems

    Total

    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 ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

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 ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

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 ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

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 ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

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 ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

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 ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

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. S'il s'agit d'un objet, les propriétés query, url et title peuvent être spécifiées, et des 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 ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

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 ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

É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

        Total

      • oldIndex

        Total

      • 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

        Total

      • Chrome 48 ou version ultérieure
      • parentId

        chaîne