chrome.bookmarks

Описание

Используйте API chrome.bookmarks для создания, упорядочивания и других операций с закладками. См. также раздел «Переопределение страниц» , который можно использовать для создания пользовательской страницы менеджера закладок.

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

Разрешения

bookmarks

Для использования API закладок необходимо указать разрешение «bookmarks» в манифесте расширения . Например:

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

Концепции и использование

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

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

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

Примеры

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

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

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

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

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

Типы

BookmarkTreeNode

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

Характеристики

  • дети

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

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

  • дата добавления

    номер необязательно

    Когда этот узел был создан, в миллисекундах с начала эпохи ( new Date(dateAdded) ).

  • dateGroupModified

    номер необязательно

    Когда содержимое этой папки последний раз изменилось, в миллисекундах с начала эпохи.

  • датапоследнегоиспользования

    номер необязательно

    Хром 114+

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

  • Тип_папки

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

    Хром 134+

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

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

  • идентификатор

    нить

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

  • индекс

    номер необязательно

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

  • parentId

    строка необязательная

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

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

    булев

    Хром 134+

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

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

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

  • заголовок

    нить

    Текст, отображаемый для узла.

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

    "удалось"
    необязательный

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

  • URL-адрес

    строка необязательная

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

BookmarkTreeNodeUnmodifiable

Хром 44+

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

Ценить

"удалось"

CreateDetails

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

Характеристики

  • индекс

    номер необязательно

  • parentId

    строка необязательная

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

  • заголовок

    строка необязательная

  • URL-адрес

    строка необязательная

FolderType

Хром 134+

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

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

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

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

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

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

Характеристики

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

Устаревший

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

Ценить

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

Устаревший

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

Ценить

1000000

Методы

create()

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

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

Параметры

Возврат

get()

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

Извлекает указанные BookmarkTreeNode.

Параметры

  • idOrIdList

    строка | [строка, ...строка[]]

    Один строковый идентификатор или массив строковых идентификаторов

Возврат

getChildren()

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

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

Параметры

  • идентификатор

    нить

Возврат

getRecent()

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

Извлекает недавно добавленные закладки.

Параметры

  • количество элементов

    число

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

Возврат

getSubTree()

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

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

Параметры

  • идентификатор

    нить

    Идентификатор корня поддерева, который требуется извлечь.

Возврат

getTree()

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

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

Возврат

move()

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

Перемещает указанный BookmarkTreeNode в указанное место.

Параметры

  • идентификатор

    нить

  • место назначения

    объект

    • индекс

      номер необязательно

    • parentId

      строка необязательная

Возврат

remove()

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

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

Параметры

  • идентификатор

    нить

Возврат

  • Обещание<void>

    Хром 90+

removeTree()

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

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

Параметры

  • идентификатор

    нить

Возврат

  • Обещание<void>

    Хром 90+
chrome.bookmarks.search(
  query: string | object,
): Promise<BookmarkTreeNode[]>

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

Параметры

  • запрос

    строка | объект

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

    • запрос

      строка необязательная

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

    • заголовок

      строка необязательная

      Название закладки; совпадает дословно.

    • URL-адрес

      строка необязательная

      URL-адрес закладки совпадает дословно. Обратите внимание, что у папок URL-адреса нет.

Возврат

update()

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

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

Параметры

  • идентификатор

    нить

  • изменения

    объект

    • заголовок

      строка необязательная

    • URL-адрес

      строка необязательная

Возврат

События

onChanged

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

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

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

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

    • идентификатор

      нить

    • changeInfo

      объект

      • заголовок

        нить

      • URL-адрес

        строка необязательная

onChildrenReordered

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

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

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

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

    • идентификатор

      нить

    • reorderInfo

      объект

      • childIds

        нить[]

onCreated

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

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

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

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

onImportBegan

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

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

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

    () => void

onImportEnded

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

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

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

    () => void

onMoved

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

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

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

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

    • идентификатор

      нить

    • moveInfo

      объект

      • индекс

        число

      • старыйИндекс

        число

      • oldParentId

        нить

      • parentId

        нить

onRemoved

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

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

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

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

    • идентификатор

      нить

    • removeInfo

      объект

      • индекс

        число

      • Хром 48+
      • parentId

        нить