browser.bookmarks

Opis

Używaj interfejsu API chrome.bookmarks do tworzenia i porządkowania zakładek oraz wykonywania innych działań na nich. Zobacz też Zastępowanie stron, gdzie 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 Bookmarks API, musisz zadeklarować uprawnienie „bookmarks” w pliku manifestu rozszerzenia. Na przykład:

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

Pojęcia i użycie

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 browser.bookmarks. Na przykład gdy wywołujesz bookmarks.create, przekazujesz element nadrzędny nowego węzła (parentId) i 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 artykule bookmarks.BookmarkTreeNode.

Przykłady

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

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

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

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

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

Typy

BookmarkTreeNode

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

Właściwości

  • dzieci

    BookmarkTreeNode[] opcjonalny

    Lista uporządkowana elementów podrzędnych tego węzła.

  • dateAdded

    number optional

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

  • dateGroupModified

    number optional

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

  • dateLastUsed

    number optional

    Chrome 114 lub nowsza browser.* od Chrome 148

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

  • folderType

    FolderType opcjonalny

    Chrome 134 lub nowsza wersja browser.* od Chrome 148

    Jeśli jest obecny, jest to folder dodany przez przeglądarkę, którego nie może zmodyfikować użytkownik ani rozszerzenie. Węzły podrzędne mogą zostać zmodyfikowane, jeśli ten węzeł nie ma ustawionej właściwości unmodifiable. Pomijane, jeśli węzeł może być modyfikowany przez użytkownika i rozszerzenie (domyślnie).

    Może być zero, jeden lub wiele węzłów każdego typu folderu. Folder może zostać dodany lub usunięty przez przeglądarkę, ale nie przez interfejs API rozszerzeń.

  • id

    tekst

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

  • indeks

    number optional

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

  • parentId

    ciąg znaków opcjonalny

    id folderu nadrzędnego. Pominięto w przypadku węzła głównego.

  • synchronizacja

    wartość logiczna

    Chrome 134 lub nowsza wersja browser.* od Chrome 148

    Określa, czy ten węzeł jest synchronizowany przez przeglądarkę z miejscem na koncie zdalnym użytkownika. Można go używać do odróżniania wersji konta i wersji lokalnej tego samego elementu 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: odzwierciedla to, czy węzeł jest zapisany we wbudowanym dostawcy konta przeglądarki. Możliwe, że węzeł zostanie zsynchronizowany przez inną firmę, nawet jeśli ta wartość to „false” (fałsz).

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

  • tytuł

    tekst

    Tekst wyświetlany w węźle.

  • nie można modyfikować

    "managed"
     opcjonalny

    Wskazuje, dlaczego tego węzła nie można modyfikować. Wartość managed wskazuje, że ten węzeł został skonfigurowany przez administratora systemu lub opiekuna nadzorowanego użytkownika. Pomijane, jeśli węzeł może być modyfikowany przez użytkownika i rozszerzenie (domyślnie).

  • URL

    ciąg znaków opcjonalny

    URL, do którego następuje przekierowanie po kliknięciu zakładki przez użytkownika. Pominięte w przypadku folderów.

BookmarkTreeNodeUnmodifiable

Chrome 44 lub nowsza browser.* od Chrome 148

Wskazuje, dlaczego tego węzła nie można modyfikować. Wartość managed wskazuje, że ten węzeł został skonfigurowany przez administratora systemu. Pomijane, jeśli węzeł może być modyfikowany przez użytkownika i rozszerzenie (domyślnie).

Wartość

"managed"

CreateDetails

Obiekt przekazany do funkcji create().

Właściwości

  • indeks

    number optional

  • parentId

    ciąg znaków opcjonalny

    Domyślnie jest to folder Inne zakładki.

  • tytuł

    ciąg znaków opcjonalny

  • URL

    ciąg znaków opcjonalny

FolderType

Chrome 134 lub nowsza wersja browser.* od Chrome 148

Wskazuje typ folderu.

Typ wyliczeniowy

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

"other"
Zakładki, które są wyświetlane na pełnej liście zakładek na wszystkich platformach.

"mobile"
Zakładki ogólnie dostępne na urządzeniach mobilnych użytkownika, ale możliwe do modyfikacji przez rozszerzenie lub w menedżerze zakładek.

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

Właściwości

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

Wycofane

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

Wartość

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

Wycofane

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

Wartość

1000000

ROOT_NODE_ID

Chrome 145 lub nowsza browser.* od Chrome 148

id powiązany z węzłem na poziomie głównym.

Wartość

"0"

Metody

create()

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

Tworzy zakładkę lub folder w ramach określonego identyfikatora parentId. Jeśli adres URL ma wartość NULL lub go brakuje, będzie to folder.

Parametry

Zwroty

get()

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

Pobiera określone obiekty BookmarkTreeNode.

Parametry

  • idOrIdList

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

    Pojedynczy identyfikator w postaci ciągu tekstowego lub tablica identyfikatorów w postaci ciągów tekstowych.

Zwroty

getChildren()

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

Pobiera elementy podrzędne określonego identyfikatora BookmarkTreeNode.

Parametry

  • id

    tekst

Zwroty

getRecent()

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

Pobiera ostatnio dodane zakładki.

Parametry

  • numberOfItems

    liczba

    Maksymalna liczba elementów do zwrócenia.

Zwroty

getSubTree()

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

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

Parametry

  • id

    tekst

    Identyfikator katalogu głównego poddrzewa, które chcesz pobrać.

Zwroty

getTree()

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

Pobiera całą hierarchię zakładek.

Zwroty

move()

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

Przenosi określony BookmarkTreeNode do podanej lokalizacji.

Parametry

  • id

    tekst

  • usługa docelowa | konto usługi docelowej

    obiekt

    • indeks

      number optional

    • parentId

      ciąg znaków opcjonalny

Zwroty

remove()

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

Usuwa zakładkę lub pusty folder zakładek.

Parametry

  • id

    tekst

Zwroty

  • thought Promise<void>

    Chrome 90 lub nowsza browser.* od Chrome 148

removeTree()

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

Rekurencyjnie usuwa folder zakładek.

Parametry

  • id

    tekst

Zwroty

  • thought Promise<void>

    Chrome 90 lub nowsza browser.* od Chrome 148 
browser.bookmarks.search(
  query: string | object,
): Promise<BookmarkTreeNode[]>

Wyszukuje obiekty BookmarkTreeNode pasujące do podanego zapytania. Zapytania określone za pomocą obiektu generują węzły BookmarkTreeNodes pasujące do wszystkich określonych właściwości.

Parametry

  • zapytanie

    string | object

    Ciąg słów i fraz w cudzysłowie, które są dopasowywane do adresów URL i tytułów zakładek, lub obiekt. Jeśli jest to obiekt, można określić właściwości query, url i title, a zostaną utworzone zakładki pasujące do wszystkich określonych właściwości.

    • zapytanie

      ciąg znaków opcjonalny

      Ciąg słów i wyrażeń w cudzysłowie, które są dopasowywane do adresów URL i tytułów zakładek.

    • tytuł

      ciąg znaków opcjonalny

      Tytuł zakładki; dopasowanie dosłowne.

    • URL

      ciąg znaków opcjonalny

      Adres URL zakładki; dopasowanie dosłowne. Pamiętaj, że foldery nie mają adresu URL.

Zwroty

update()

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

Aktualizuje 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

    tekst

  • poniższych zmian

    obiekt

    • tytuł

      ciąg znaków opcjonalny

    • URL

      ciąg znaków opcjonalny

Zwroty

Wydarzenia

onChanged

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

Uruchamiane, gdy zmienia się zakładka lub folder. Uwaga: obecnie tylko zmiany tytułu i adresu URL powodują wywołanie tej funkcji.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

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

    • id

      tekst

    • changeInfo

      obiekt

      • tytuł

        tekst

      • URL

        ciąg znaków opcjonalny

onChildrenReordered

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

Uruchamiane, gdy elementy podrzędne folderu zmieniły kolejność z powodu sortowania w interfejsie. Ta metoda nie jest wywoływana w wyniku działania metody move().

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

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

    • id

      tekst

    • reorderInfo

      obiekt

      • childIds

        string[]

onCreated

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

Uruchamiane po utworzeniu zakładki lub folderu.

Parametry

onImportBegan

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

Uruchamiane po rozpoczęciu sesji importowania zakładek. Obserwatory, które wymagają dużej ilości zasobów, powinny ignorować aktualizacje onCreated, dopóki nie zostanie wywołane zdarzenie onImportEnded. Obserwatorzy powinni nadal natychmiast reagować na inne powiadomienia.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    () => void

onImportEnded

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

Uruchamiane po zakończeniu sesji importowania zakładek.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    () => void

onMoved

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

Uruchamiane, gdy zakładka lub folder zostaną przeniesione do innego folderu nadrzędnego.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

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

    • id

      tekst

    • moveInfo

      obiekt

      • indeks

        liczba

      • oldIndex

        liczba

      • oldParentId

        tekst

      • parentId

        tekst

onRemoved

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

Uruchamiane po usunięciu zakładki lub folderu. Gdy folder jest usuwany rekurencyjnie, wysyłane jest jedno powiadomienie dotyczące folderu, a nie jego zawartości.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

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

    • id

      tekst

    • removeInfo

      obiekt

      • indeks

        liczba

      • Chrome 48 lub nowsza browser.* od Chrome 148
      • parentId

        tekst