browser.bookmarks

Описание

Используйте chrome.bookmarks API, чтобы создавать, упорядочивать и иным образом управлять закладками. Также ознакомьтесь с информацией о переопределении страниц, которое можно использовать для создания собственной страницы менеджера закладок.

Нажатие на звездочку добавляет закладку
Нажмите на звездочку, чтобы добавить закладку.

Разрешения

bookmarks

Чтобы использовать API закладок, необходимо объявить разрешение bookmarks в манифесте расширения. Пример:

{
  "name": "My extension",
  ...
  "permissions": [
    "bookmarks"
  ],
  ...
}

Основные понятия и использование

Объекты и свойства

Закладки организованы в виде дерева, где каждый узел является либо закладкой, либо папкой (иногда называемой группой). Каждый узел в дереве представлен объектом bookmarks.BookmarkTreeNode.

Свойства BookmarkTreeNode используются во всем API browser.bookmarks. Например, при вызове bookmarks.create вы передаете родительский элемент нового узла (parentId) и, при необходимости, свойства index, title и url узла. Информацию о свойствах узла можно найти в разделе bookmarks.BookmarkTreeNode.

Примеры

Следующий код создает папку с названием "Extension bookmarks". Первый аргумент create() задает свойства новой папки. Второй аргумент определяет функцию, которая будет выполнена после создания папки.

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

Следующий фрагмент кода создает закладку, указывающую на документацию для разработчиков расширений. Поскольку ничего плохого не произойдет, если создание закладки не удастся, этот код не утруждает себя определением функции обратного вызова.

browser.bookmarks.create({
  'parentId': extensionsFolderId,
  'title': 'Extensions doc',
  'url': 'https://developer.chrome.com/docs/extensions',
});

Чтобы попробовать этот API, установите пример Bookmarks API из репозитория chrome-extension-samples.

Типы

BookmarkTreeNode

Узел (закладка или папка) в дереве закладок. Дочерние узлы упорядочены в родительской папке.

Свойства

  • дети

    BookmarkTreeNode[] необязательный

    Упорядоченный список дочерних элементов этого узла.

  • dateAdded

    number (необязательно)

    Время создания узла в миллисекундах с начала отсчета (new Date(dateAdded)).

  • dateGroupModified

    number (необязательно)

    Время последнего изменения содержимого папки в миллисекундах с начала эпохи.

  • dateLastUsed

    number (необязательно)

    Chrome 114+ browser.* начиная с Chrome 148

    Время последнего открытия узла в миллисекундах с начала эпохи. Не задано для папок.

  • folderType

    FolderType необязательный

    Chrome 134+ browser.* начиная с Chrome 148

    Если она есть, то добавлена браузером и не может быть изменена пользователем или расширением. Дочерние узлы можно изменять, если для этого узла не задано свойство unmodifiable. Опускается, если узел может быть изменен пользователем и расширением (по умолчанию).

    Узлов каждого типа папки может быть несколько, один или ни одного. Папку можно добавить или удалить в браузере, но не через API расширений.

  • id

    string

    Уникальный идентификатор узла. Идентификаторы уникальны в пределах текущего профиля и остаются действительными даже после перезапуска браузера.

  • индекс

    number (необязательно)

    Позиция этого узла в родительской папке (начиная с нуля).

  • parentId

    Строка (необязательно)

    id родительской папки. Для корневого узла не указывается.

  • синхронизация

    Логическое значение

    Chrome 134+ browser.* начиная с Chrome 148

    Синхронизируется ли этот узел с удаленным хранилищем аккаунта пользователя в браузере. Это позволяет различать аккаунт и локальные версии одного и того же объекта FolderType. Значение этого свойства может меняться для существующего узла, например в результате действий пользователя.

    Примечание. Это значение отражает, сохранен ли узел во встроенном поставщике аккаунтов браузера. Узел может быть синхронизирован через сторонний сервис, даже если это значение равно false.

    Для управляемых узлов (узлов, где для свойства unmodifiable задано значение true) это свойство всегда будет иметь значение false.

  • название

    string

    Текст, который показывается для узла.

  • неизменяемый

    "managed"
     необязательно

    Указывает причину, по которой этот узел нельзя изменить. Значение managed указывает, что этот узел был настроен системным администратором или родителем контролируемого пользователя. Опускается, если узел может быть изменен пользователем и расширением (по умолчанию).

  • url

    Строка (необязательно)

    URL, на который переходит пользователь, когда нажимает на закладку. Для папок не указывается.

BookmarkTreeNodeUnmodifiable

Chrome 44+ browser.* начиная с Chrome 148

Указывает причину, по которой этот узел нельзя изменить. Значение managed указывает, что этот узел был настроен системным администратором. Опускается, если узел может быть изменен пользователем и расширением (по умолчанию).

Значение

"managed"

CreateDetails

Объект, переданный функции create().

Свойства

  • индекс

    number (необязательно)

  • parentId

    Строка (необязательно)

    По умолчанию это папка "Другие закладки".

  • название

    Строка (необязательно)

  • url

    Строка (необязательно)

FolderType

Chrome 134+ browser.* начиная с Chrome 148

Указывает тип папки.

Перечисление

"bookmarks-bar"
Папка, содержимое которой показывается в верхней части окна браузера.

"other"
Закладки, которые показываются в полном списке закладок на всех платформах.

"mobile"
закладки, доступные на мобильных устройствах пользователя, но которые можно изменить с помощью расширения или в диспетчере закладок.

"managed"
Папка верхнего уровня, которая может присутствовать, если системный администратор или законный представитель контролируемого профиля настроил закладки.

Свойства

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

Поддержка прекращена

Операции записи закладок больше не ограничены Chrome.

Значение

1 000 000

MAX_WRITE_OPERATIONS_PER_HOUR

Поддержка прекращена

Операции записи закладок больше не ограничены Chrome.

Значение

1 000 000

ROOT_NODE_ID

Chrome 145 и более поздние версии browser.* начиная с Chrome 148

id, связанный с узлом корневого уровня.

Значение

"0"

Методы

create()

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

Создает закладку или папку с указанным идентификатором parentId. Если URL имеет значение NULL или отсутствует, будет создана папка.

Параметры

Возвраты

  • Chrome 90 и более поздних версий browser.* начиная с Chrome 148

get()

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

Получает указанные объекты BookmarkTreeNode.

Параметры

  • idOrIdList

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

    Один идентификатор в виде строки или массив идентификаторов в виде строк.

Возвраты

  • Promise<BookmarkTreeNode[]>

    Chrome 90 и более поздних версий browser.* начиная с Chrome 148

getChildren()

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

Возвращает дочерние элементы указанного BookmarkTreeNode id.

Параметры

  • id

    string

Возвраты

  • Promise<BookmarkTreeNode[]>

    Chrome 90 и более поздних версий browser.* начиная с Chrome 148

getRecent()

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

Получает недавно добавленные закладки.

Параметры

  • numberOfItems

    число

    Максимальное количество возвращаемых объектов.

Возвраты

  • Promise<BookmarkTreeNode[]>

    Chrome 90 и более поздних версий browser.* начиная с Chrome 148

getSubTree()

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

Извлекает часть иерархии закладок, начиная с указанного узла.

Параметры

  • id

    string

    Идентификатор корня поддерева, которое нужно получить.

Возвраты

  • Promise<BookmarkTreeNode[]>

    Chrome 90 и более поздних версий browser.* начиная с Chrome 148

getTree()

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

Извлекает всю иерархию закладок.

Возвраты

  • Promise<BookmarkTreeNode[]>

    Chrome 90 и более поздних версий browser.* начиная с Chrome 148

move()

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

Перемещает указанный узел BookmarkTreeNode в заданное местоположение.

Параметры

  • id

    string

  • целевой аккаунт

    Объект

    • индекс

      number (необязательно)

    • parentId

      Строка (необязательно)

Возвраты

  • Chrome 90 и более поздних версий browser.* начиная с Chrome 148

remove()

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

Удаляет закладку или пустую папку закладок.

Параметры

  • id

    string

Возвраты

  • Promise<void>

    Chrome 90 и более поздних версий browser.* начиная с Chrome 148

removeTree()

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

Рекурсивно удаляет папку закладок.

Параметры

  • id

    string

Возвраты

  • Promise<void>

    Chrome 90 и более поздних версий browser.* начиная с Chrome 148 
browser.bookmarks.search(
  query: string | object,
): Promise<BookmarkTreeNode[]>

Поиск объектов BookmarkTreeNode, соответствующих заданному запросу. Запросы, указанные с объектом, создают BookmarkTreeNodes, соответствующие всем указанным свойствам.

Параметры

  • запрос

    string | object

    Строка со словами и фразами в кавычках, которые сопоставляются с URL и названиями закладок, или объект. Если это объект, можно указать свойства query, url и title, и будут созданы закладки, соответствующие всем указанным свойствам.

    • запрос

      Строка (необязательно)

      Строка со словами и фразами в кавычках, которые сопоставляются с URL и названиями закладок.

    • название

      Строка (необязательно)

      Название закладки. Поиск выполняется по точному совпадению.

    • url

      Строка (необязательно)

      URL закладки. Совпадение должно быть точным. Обратите внимание, что у папок нет URL.

Возвраты

  • Promise<BookmarkTreeNode[]>

    Chrome 90 и более поздних версий browser.* начиная с Chrome 148

update()

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

Обновляет свойства закладки или папки. Укажите только те свойства, которые вы хотите изменить. Неуказанные свойства останутся без изменений. Примечание. В настоящее время поддерживаются только title и url.

Параметры

  • id

    string

  • Изменения

    Объект

    • название

      Строка (необязательно)

    • url

      Строка (необязательно)

Возвраты

  • Chrome 90 и более поздних версий browser.* начиная с Chrome 148

События

onChanged

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

Срабатывает при изменении закладки или папки. Примечание. В настоящее время это происходит только при изменении заголовка и URL.

Параметры

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

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

    • id

      string

    • changeInfo

      Объект

      • название

        string

      • url

        Строка (необязательно)

onChildrenReordered

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

Срабатывает, когда дочерние элементы папки меняют свой порядок из-за сортировки в пользовательском интерфейсе. Этот метод не вызывается в результате move().

Параметры

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

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

    • id

      string

    • reorderInfo

      Объект

      • childIds

        string[]

onCreated

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

Срабатывает при создании закладки или папки.

Параметры

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

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

onImportBegan

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

Срабатывает, когда начинается сеанс импорта закладок. Ресурсоемкие наблюдатели должны игнорировать обновления onCreated, пока не будет запущено onImportEnded. Наблюдатели должны немедленно реагировать на другие уведомления.

Параметры

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

    () => void

onImportEnded

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

Срабатывает, когда сеанс импорта закладок завершен.

Параметры

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

    () => void

onMoved

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

Срабатывает, когда закладка или папка перемещается в другую родительскую папку.

Параметры

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

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

    • id

      string

    • moveInfo

      Объект

      • индекс

        число

      • oldIndex

        число

      • oldParentId

        string

      • parentId

        string

onRemoved

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

Срабатывает, когда закладка или папка удаляется. При рекурсивном удалении папки уведомление отправляется только для нее, а не для ее содержимого.

Параметры

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

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

    • id

      string

    • removeInfo

      Объект

      • индекс

        число

      • узел

        BookmarkTreeNode

        Chrome 48+ browser.* начиная с Chrome 148
      • parentId

        string