chrome.bookmarks

Opis

Użyj interfejsu API chrome.bookmarks do tworzenia, porządkowania i modyfikowania zakładek. Zapoznaj się też z artykułem Zastępowanie stron, w którym znajdziesz informacje o tworzeniu niestandardowej strony Menedżera zakładek.

Kliknięcie gwiazdki powoduje dodanie zakładki.
Kliknięcie gwiazdki powoduje dodanie zakładki.

Uprawnienia

bookmarks

Aby korzystać z interfejsu bookmark API, musisz zadeklarować uprawnienie „bookmarks” w manifeście rozszerzenia. Na przykład:

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

Pojęcia i zastosowanie

Obiekty i właściwości

Zakładki są uporządkowane w drzewie, w którym każdy węzeł jest zakładką lub folderem (czasami nazywanym grupą). Każdy węzeł w drzewie jest reprezentowany przez obiekt bookmarks.BookmarkTreeNode.

Właściwości BookmarkTreeNode są używane w całym interfejsie API chrome.bookmarks. Na przykład podczas wywołania funkcji bookmarks.create przekazujesz element nadrzędny nowego węzła (parentId) oraz opcjonalnie właściwości węzła index, title i url. Informacje o właściwościach, które może mieć węzeł, znajdziesz w pliku bookmarks.BookmarkTreeNode.

Przykłady

Podany niżej kod tworzy folder o nazwie „Zakładki rozszerzenia”. Pierwszy argument funkcji create() określa właściwości nowego folderu. Drugi argument definiuje funkcję, która ma zostać wykonana po utworzeniu folderu.

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

Następny fragment kodu tworzy zakładkę wskazującą dokumentację dla deweloperów dotyczącą rozszerzeń. Ponieważ nic złego nie stanie się, jeśli tworzenie zakładki się nie powiedzie, ten kod nie definiuje funkcji wywołania zwrotnego.

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

Aby wypróbować ten interfejs API, zainstaluj przykład interfejsu Bookmark API z repozytorium chrome-extension-samples.

Typy

BookmarkTreeNode

węzeł (zakładka lub folder) na drzewie zakładek. W folderze nadrzędnym węzły podrzędne są uporządkowane.

Właściwości

  • dzieci

    BookmarkTreeNode[] opcjonalnie

    Uporządkowana lista węzłów podrzędnych tego węzła.

  • dateAdded

    numer opcjonalny

    Czas utworzenia tego węzła w milisekundach od początku epoki (new Date(dateAdded)).

  • dateGroupModified

    numer opcjonalny

    Czas ostatniej zmiany zawartości tego folderu w milisekundach od początku epoki.

  • dateLastUsed

    numer opcjonalny

    Chrome 114 lub nowszy

    Czas ostatniego otwarcia tego węzła w milisekundach od początku epoki. Nie ustawiono dla folderów.

  • folderType

    FolderType opcjonalny

    Oczekuje

    Jeśli jest obecny, to folder dodany przez przeglądarkę, którego nie można modyfikować przez użytkownika ani rozszerzenie. Węzły podrzędne można modyfikować, jeśli nie mają ustawionej właściwości unmodifiable. Pomiń, jeśli węzeł może być modyfikowany przez użytkownika i rozszerzenie (domyślnie).

    W przypadku każdego typu folderu może być 0, 1 lub wiele węzłów. Folder może zostać dodany lub usunięty przez przeglądarkę, ale nie za pomocą interfejsu API rozszerzeń.

  • id

    ciąg znaków

    Unikalny identyfikator węzła. Identyfikatory są unikalne w ramach bieżącego profilu i pozostają ważne nawet po ponownym uruchomieniu przeglądarki.

  • indeks

    numer opcjonalny

    Pozycja tego węzła w folderze nadrzędnym (liczona od 0).

  • parentId

    string opcjonalny

    id folderu nadrzędnego. W przypadku węzła głównego jest pomijany.

  • synchronizuję

    wartość logiczna

    Oczekuje

    Określa, czy ten węzeł jest synchronizowany przez przeglądarkę z miejscem na zdalnym koncie użytkownika. Można go użyć do rozróżnienia wersji konta i wersji tylko na potrzeby lokalizacji tego samego FolderType. Wartość tej właściwości może się zmienić w przypadku istniejącego węzła, np. w wyniku działania użytkownika.

    Uwaga: to ustawienie określa, czy węzeł jest zapisywany w budowanym przez przeglądarkę wbudowanym dostawcy kont. Możliwe jest, że węzeł może być synchronizowany przez zewnętrzne źródło danych, nawet jeśli ta wartość jest ustawiona na „fałsz”.

    W przypadku węzłów zarządzanych (węzły, w których parametr unmodifiable ma wartość true) ta właściwość będzie zawsze miała wartość false.

  • tytuł

    ciąg znaków

    Tekst wyświetlany dla węzła.

  • niemodyfikowalne

    "managed"
     opcjonalnie

    Wskazuje powód, dla którego ten węzeł jest niedostępny do modyfikacji. Wartość managed wskazuje, że ten węzeł został skonfigurowany przez administratora systemu lub opiekuna użytkownika nadzorowanego. Pomiń, jeśli węzeł może być modyfikowany przez użytkownika i rozszerzenie (domyślnie).

  • URL

    string opcjonalny

    Adres URL, do którego następuje przejście po kliknięciu zakładki. W przypadku folderów jest pomijany.

BookmarkTreeNodeUnmodifiable

Chrome 44 lub nowszy

Wskazuje powód, dla którego ten węzeł jest niedostępny do modyfikacji. Wartość managed wskazuje, że ten węzeł został skonfigurowany przez administratora systemu. Pomiń, jeśli węzeł może być modyfikowany przez użytkownika i rozszerzenie (domyślnie).

Wartość

„zarządzane”

CreateDetails

Obiekt przekazany do funkcji create().

Właściwości

  • indeks

    numer opcjonalny

  • parentId

    string opcjonalny

    Domyślnie jest to folder Inne zakładki.

  • tytuł

    string opcjonalny

  • URL

    string opcjonalny

FolderType

Oczekuje

Wskazuje typ folderu.

Typ wyliczeniowy

"bookmarks-bar"
Folder, którego zawartość jest wyświetlana u góry okna przeglądarki.

„inne”
zakładki wyświetlane na pełnej liście zakładek na wszystkich platformach.

„mobile”
Zakładki są zwykle dostępne na urządzeniach mobilnych użytkownika, ale można je modyfikować w rozszerzeniu lub w menedżerze zakładek.

„zarządzany”
Folder najwyższego poziomu, który może być obecny, jeśli administrator systemu lub opiekun użytkownika nadzorowanego skonfigurował zakładki.

Właściwości

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

Wycofane

Operacje zapisu zakładek nie są już ograniczone przez Chrome.

Wartość

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

Wycofane

Operacje zapisu zakładek nie są już ograniczone przez Chrome.

Wartość

1000000

Metody

create()

Obietnice 
chrome.bookmarks.create(
  bookmark: CreateDetails,
  callback?: function,
)

Tworzy zakładkę lub folder pod określonym identyfikatorem parentId. Jeśli adres URL jest pusty lub nie ma go w ogóle, będzie to folder.

Parametry

Zwroty

  • Obietnica<BookmarkTreeNode>

    Chrome 90+

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność z wcześniejszymi wersjami. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

get()

Obietnice 
chrome.bookmarks.get(
  idOrIdList: string | [string, ...string[]],
  callback?: function,
)

Pobiera określone węzły BookmarkTreeNode.

Parametry

  • idOrIdList

    ciąg znaków | [ciąg znaków, ...ciągi znaków[]]

    Pojedynczy identyfikator o typie ciągu znaków lub tablica identyfikatorów o typie ciągu znaków

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (results: BookmarkTreeNode[]) => void

Zwroty

  • Promise<BookmarkTreeNode[]>

    Chrome 90+

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność z wcześniejszymi wersjami. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

getChildren()

Obietnice 
chrome.bookmarks.getChildren(
  id: string,
  callback?: function,
)

Pobiera podrzędne określonego identyfikatora BookmarkTreeNode.

Parametry

Zwroty

  • Promise<BookmarkTreeNode[]>

    Chrome 90+

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność z wcześniejszymi wersjami. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

getRecent()

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

Pobiera ostatnio dodane zakładki.

Parametry

  • numberOfItems

    liczba

    Maksymalna liczba elementów do zwrotu.

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (results: BookmarkTreeNode[]) => void

Zwroty

  • Promise<BookmarkTreeNode[]>

    Chrome 90+

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność z wcześniejszymi wersjami. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

getSubTree()

Obietnice 
chrome.bookmarks.getSubTree(
  id: string,
  callback?: function,
)

Pobiera część hierarchii zakładek, zaczynając od określonego węzła.

Parametry

  • id

    ciąg znaków

    Identyfikator korzenia poddrzewa do pobrania.

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (results: BookmarkTreeNode[]) => void

Zwroty

  • Promise<BookmarkTreeNode[]>

    Chrome 90+

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność z wcześniejszymi wersjami. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

getTree()

Obietnice 
chrome.bookmarks.getTree(
  callback?: function,
)

Pobiera całą hierarchię zakładek.

Parametry

Zwroty

  • Promise<BookmarkTreeNode[]>

    Chrome 90+

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność z wcześniejszymi wersjami. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

move()

Obietnice 
chrome.bookmarks.move(
  id: string,
  destination: object,
  callback?: function,
)

Przenosi określony węzeł BookmarkTreeNode do podanej lokalizacji.

Parametry

  • id

    ciąg znaków

  • usługa docelowa | konto usługi docelowej

    obiekt

    • indeks

      numer opcjonalny

    • parentId

      string opcjonalny

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (result: BookmarkTreeNode) => void

Zwroty

  • Obietnica<BookmarkTreeNode>

    Chrome 90+

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność z wcześniejszymi wersjami. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

remove()

Obietnice 
chrome.bookmarks.remove(
  id: string,
  callback?: function,
)

Usuwa zakładkę lub pusty folder z zakładkami.

Parametry

  • id

    ciąg znaków

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Chrome 90+

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność z wcześniejszymi wersjami. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

removeTree()

Obietnice 
chrome.bookmarks.removeTree(
  id: string,
  callback?: function,
)

Rekursywnie usuwa folder zakładek.

Parametry

  • id

    ciąg znaków

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Chrome 90+

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność z wcześniejszymi wersjami. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

Obietnice 
chrome.bookmarks.search(
  query: string | object,
  callback?: function,
)

Wyszukuje węzłów BookmarkTreeNode pasujących do podanego zapytania. Zapytania określone za pomocą obiektu zwracają węzły drzewa zakładek pasujące do wszystkich określonych właściwości.

Parametry

  • zapytanie

    ciąg znaków | obiekt

    Albo ciąg znaków z wyrazami i cytowanymi wyrażeniami, które są dopasowywane do adresów URL i tytułów zakładek, albo obiekt. Jeśli jest to obiekt, można określić właściwości query, url i title, a następnie wygenerować zakładki pasujące do wszystkich określonych właściwości.

    • zapytanie

      string opcjonalny

      ciąg wyrazów i wyrażeń, które są porównywane z adresami URL i tytułami zakładek;

    • tytuł

      string opcjonalny

      Tytuł zakładki; dopasowanie dokładne.

    • URL

      string opcjonalny

      Adres URL zakładki; dopasowanie do dosłownego tekstu. Pamiętaj, że foldery nie mają adresów URL.

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (results: BookmarkTreeNode[]) => void

Zwroty

  • Promise<BookmarkTreeNode[]>

    Chrome 90+

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność z wcześniejszymi wersjami. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

update()

Obietnice 
chrome.bookmarks.update(
  id: string,
  changes: object,
  callback?: function,
)

Zaktualizuj właściwości zakładki lub folderu. Określ tylko te właściwości, które chcesz zmienić. Nieokreślone właściwości pozostaną bez zmian. Uwaga: obecnie obsługiwane są tylko parametry „title” i „url”.

Parametry

  • id

    ciąg znaków

  • Zmiany

    obiekt

    • tytuł

      string opcjonalny

    • URL

      string opcjonalny

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (result: BookmarkTreeNode) => void

Zwroty

  • Obietnica<BookmarkTreeNode>

    Chrome 90+

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność z wcześniejszymi wersjami. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

Wydarzenia

onChanged

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

Wywoływany, gdy zmieni się zakładka lub folder. Uwaga: obecnie wywołuje to tylko zmiana tytułu i adresu URL.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

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

    • id

      ciąg znaków

    • changeInfo

      obiekt

      • tytuł

        ciąg znaków

      • URL

        string opcjonalny

onChildrenReordered

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

Wywoływany, gdy kolejność elementów podrzędnych folderu uległa zmianie z powodu sortowania elementów w interfejsie. Nie jest on wywoływany w wyniku wywołania move().

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

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

    • id

      ciąg znaków

    • reorderInfo

      obiekt

      • childIds

        string[]

onCreated

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

Wywoływane po utworzeniu zakładki lub folderu.

Parametry

onImportBegan

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

Uruchamiane, gdy rozpoczyna się sesja importowania zakładek. Obserwatorzy generujący wysokie koszty powinni ignorować aktualizacje onCreated do momentu wywołania onImportEnded. Obserwatorzy powinni nadal natychmiast reagować na inne powiadomienia.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

    () => void

onImportEnded

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

Uruchamiane po zakończeniu sesji importowania zakładek.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

    () => void

onMoved

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

Wywoływany, gdy zakładka lub folder zostanie przeniesiony do innego folderu nadrzędnego.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

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

    • id

      ciąg znaków

    • moveInfo

      obiekt

      • indeks

        liczba

      • oldIndex

        liczba

      • oldParentId

        ciąg znaków

      • parentId

        ciąg znaków

onRemoved

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

Wywoływane, gdy zakładka lub folder zostanie usunięty. Gdy folder jest usuwany rekurencyjnie, wysyłane jest pojedyncze powiadomienie o tym folderze, ale nie o jego zawartości.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

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

    • id

      ciąg znaków

    • removeInfo

      obiekt