chrome.bookmarks

Описание

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

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

Разрешения

bookmarks

Чтобы использовать API закладок, вы должны объявить разрешение «закладки» в манифесте расширения . Например:

{
  "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) ).

  • датаГруппаИзменено

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

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

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

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

    Хром 114+

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

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

    нить

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

  • индекс

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

    Позиция этого узла, отсчитываемая от 0, в его родительской папке.

  • родительский идентификатор

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

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

  • заголовок

    нить

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

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

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

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

  • URL

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

    URL-адрес, по которому осуществляется переход, когда пользователь щелкает закладку. Опущено для папок.

BookmarkTreeNodeUnmodifiable

Хром 44+

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

Ценить

"удалось"

CreateDetails

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

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

  • индекс

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

  • родительский идентификатор

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

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

  • заголовок

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

  • URL

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

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

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

Устарело

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

Ценить

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

Устарело

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

Ценить

1000000

Методы

create()

Обещать
chrome.bookmarks.create(
  bookmark: CreateDetails,
  callback?: function,
)

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

Параметры

Возврат

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

    Хром 90+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

get()

Обещать
chrome.bookmarks.get(
  idOrIdList: string | [string, ...string[]],
  callback?: function,
)

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

Параметры

  • idOrIdList

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

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

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

    функция необязательна

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

    (results: BookmarkTreeNode[]) => void

Возврат

  • Обещание< BookmarkTreeNode []>

    Хром 90+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

getChildren()

Обещать
chrome.bookmarks.getChildren(
  id: string,
  callback?: function,
)

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

Параметры

Возврат

  • Обещание< BookmarkTreeNode []>

    Хром 90+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

getRecent()

Обещать
chrome.bookmarks.getRecent(
  numberOfItems: number,
  callback?: function,
)

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

Параметры

  • количество предметов

    число

    Максимальное количество товаров для возврата.

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

    функция необязательна

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

    (results: BookmarkTreeNode[]) => void

Возврат

  • Обещание< BookmarkTreeNode []>

    Хром 90+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

getSubTree()

Обещать
chrome.bookmarks.getSubTree(
  id: string,
  callback?: function,
)

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

Параметры

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

    нить

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

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

    функция необязательна

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

    (results: BookmarkTreeNode[]) => void

Возврат

  • Обещание< BookmarkTreeNode []>

    Хром 90+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

getTree()

Обещать
chrome.bookmarks.getTree(
  callback?: function,
)

Получает всю иерархию закладок.

Параметры

Возврат

  • Обещание< BookmarkTreeNode []>

    Хром 90+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

move()

Обещать
chrome.bookmarks.move(
  id: string,
  destination: object,
  callback?: function,
)

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

Параметры

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

    нить

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

    объект

    • индекс

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

    • родительский идентификатор

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

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

    функция необязательна

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

    (result: BookmarkTreeNode) => void

Возврат

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

    Хром 90+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

remove()

Обещать
chrome.bookmarks.remove(
  id: string,
  callback?: function,
)

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

Параметры

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

    нить

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

    функция необязательна

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

    () => void

Возврат

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

    Хром 90+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

removeTree()

Обещать
chrome.bookmarks.removeTree(
  id: string,
  callback?: function,
)

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

Параметры

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

    нить

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

    функция необязательна

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

    () => void

Возврат

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

    Хром 90+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

Обещать
chrome.bookmarks.search(
  query: string | object,
  callback?: function,
)

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

Параметры

  • запрос

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

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

    • запрос

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

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

    • заголовок

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

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

    • URL

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

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

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

    функция необязательна

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

    (results: BookmarkTreeNode[]) => void

Возврат

  • Обещание< BookmarkTreeNode []>

    Хром 90+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

update()

Обещать
chrome.bookmarks.update(
  id: string,
  changes: object,
  callback?: function,
)

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

Параметры

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

    нить

  • изменения

    объект

    • заголовок

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

    • URL

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

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

    функция необязательна

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

    (result: BookmarkTreeNode) => void

Возврат

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

    Хром 90+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

События

onChanged

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

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

Параметры

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

    функция

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

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

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

      нить

    • изменениеИнформация

      объект

      • заголовок

        нить

      • URL

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

onChildrenReordered

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

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

Параметры

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

    функция

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

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

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

      нить

    • переупорядочитьинформацию

      объект

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

        нить[]

onCreated

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

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

Параметры

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

      объект

      • индекс

        число

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

        число

      • старыйродительид

        нить

      • родительский идентификатор

        нить

onRemoved

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

Вызывается при удалении закладки или папки. Когда папка удаляется рекурсивно, для папки выдается одно уведомление, а для ее содержимого — ни одно.

Параметры

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

    функция

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

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

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

      нить

    • удалитьинформацию

      объект