chrome.bookmarks

Cette autorisation déclenche un avertissement.

Description

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

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 sous forme d'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 toute 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é "Extension bookmarks" (Favoris d'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 une fois le dossier créé.

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

L'extrait suivant crée un signet pointant vers la documentation pour les développeurs concernant les extensions. Étant donné qu'il ne se passera rien de grave si la création du signet échoue, 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 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 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 de la dernière modification du contenu de ce dossier, en millisecondes depuis l'époque.

  • dateLastUsed

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

  • folderType

    FolderType facultatif

    Chrome 134 et versions ultérieures

    Le cas échéant, il s'agit d'un dossier ajouté par le navigateur et que l'utilisateur ou l'extension ne peuvent pas modifier. Les nœuds enfants peuvent être modifiés si ce nœud n'a pas la propriété unmodifiable définie. Omettez cette valeur si le nœud peut être modifié par l'utilisateur et l'extension (valeur 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 (basée sur 0) dans son dossier parent.

  • parentId

    chaîne facultative

    id du dossier parent. Omettez-le pour le nœud racine.

  • Synchronisation…

    booléen

    Chrome 134 et versions ultérieures

    Indique si ce nœud est synchronisé avec le stockage du compte distant de l'utilisateur par le navigateur. Cela permet de faire la distinction entre les versions au niveau du compte et celles locales uniquement 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 pour lesquels 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 ne peut pas être modifié. La valeur managed indique que ce nœud a été configuré par l'administrateur système ou par le représentant légal d'un utilisateur supervisé. Omettez cette valeur si le nœud peut être modifié par l'utilisateur et l'extension (valeur par défaut).

  • url

    chaîne facultative

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

BookmarkTreeNodeUnmodifiable

Chrome 44 et versions ultérieures

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. Omettez cette valeur si le nœud peut être modifié par l'utilisateur et l'extension (valeur par défaut).

Valeur

"managed"

CreateDetails

Objet transmis à la fonction create().

Propriétés

  • index

    number facultatif

  • parentId

    chaîne facultative

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

  • titre

    chaîne facultative

  • url

    chaîne facultative

FolderType

Chrome 134 et versions ultérieures

Indique le type de dossier.

Énumération

"bookmarks-bar"
Dossier dont le contenu est affiché en haut de la fenêtre du navigateur.

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

"mobile"
Les favoris sont généralement disponibles sur les appareils mobiles de l'utilisateur, mais peuvent être modifiés par une extension ou dans le gestionnaire de favoris.

"géré"
Dossier de premier niveau qui peut être présent si l'administrateur système ou le représentant légal 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

Méthodes

create()

Promise 
chrome.bookmarks.create(
  bookmark: CreateDetails,
  callback?: function,
): Promise<BookmarkTreeNode>

Crée un favori ou un dossier sous le parentId spécifié. Si l'URL est définie sur NULL ou est 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 les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

get()

Promise 
chrome.bookmarks.get(
  idOrIdList: string | [string, ...string[]],
  callback?: function,
): Promise<BookmarkTreeNode[]>

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

Paramètres

  • idOrIdList

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

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

  • callback

    function 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 les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getChildren()

Promise 
chrome.bookmarks.getChildren(
  id: string,
  callback?: function,
): Promise<BookmarkTreeNode[]>

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

Paramètres

  • id

    chaîne

  • callback

    function 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 les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getRecent()

Promise 
chrome.bookmarks.getRecent(
  numberOfItems: number,
  callback?: function,
): Promise<BookmarkTreeNode[]>

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

Paramètres

  • numberOfItems

    Total

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

  • callback

    function 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 les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getSubTree()

Promise 
chrome.bookmarks.getSubTree(
  id: string,
  callback?: function,
): Promise<BookmarkTreeNode[]>

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

Paramètres

  • id

    chaîne

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

  • callback

    function 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 les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getTree()

Promise 
chrome.bookmarks.getTree(
  callback?: function,
): Promise<BookmarkTreeNode[]>

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 les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

move()

Promise 
chrome.bookmarks.move(
  id: string,
  destination: object,
  callback?: function,
): 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 facultative

  • callback

    function 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 les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

remove()

Promise 
chrome.bookmarks.remove(
  id: string,
  callback?: function,
): Promise<void>

Supprime un favori ou un dossier de favoris vide.

Paramètres

  • id

    chaîne

  • callback

    function 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 les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

removeTree()

Promise 
chrome.bookmarks.removeTree(
  id: string,
  callback?: function,
): Promise<void>

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

Paramètres

  • id

    chaîne

  • callback

    function 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 les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

Promise 
chrome.bookmarks.search(
  query: string | object,
  callback?: function,
): Promise<BookmarkTreeNode[]>

Recherche les 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 qui sont mises en correspondance avec les URL et les titres des favoris, ou objet. Si la valeur est 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 facultative

      Chaîne de mots et de phrases entre guillemets qui sont mises en correspondance avec les URL et les titres des favoris.

    • titre

      chaîne facultative

      Titre du favori (correspondance exacte).

    • url

      chaîne facultative

      URL du favori (correspondance exacte). Notez que les dossiers n'ont pas d'URL.

  • callback

    function 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 les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

update()

Promise 
chrome.bookmarks.update(
  id: string,
  changes: object,
  callback?: function,
): Promise<BookmarkTreeNode>

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 resteront inchangées. Remarque : Actuellement, seuls les attributs "title" et "url" sont acceptés.

Paramètres

  • id

    chaîne

  • modifications

    objet

    • titre

      chaîne facultative

    • url

      chaîne facultative

  • callback

    function 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 les 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 est modifié. Remarque : Actuellement, seuls les changements 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 facultative

onChildrenReordered

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

Événement déclenché lorsque l'ordre des enfants d'un dossier a été modifié en raison du 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

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

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

Paramètres

  • callback

    fonction

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

    () => void

onImportEnded

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

Déclenché lorsqu'une session d'importation de favoris est terminée.

Paramètres

  • callback

    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

  • callback

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

Événement 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

        Total

      • Chrome 48 et versions ultérieures
      • parentId

        chaîne