browser.bookmarks

Opis

Użyj interfejsu chrome.bookmarks API, aby tworzyć, porządkować i w inny sposób manipulować zakładkami. Zobacz też strony zastępowania, których możesz użyć do utworzenia niestandardowej strony menedżera zakładek.

Kliknięcie gwiazdki dodaje zakładkę
Kliknięcie gwiazdki dodaje zakładkę.

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 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 browser.bookmarks API. Na przykład podczas wywoływania funkcji bookmarks.create przekazujesz węzeł nadrzędny nowego węzła (parentId) oraz opcjonalnie właściwości index, title i url węzła. Więcej informacji o właściwościach węzła znajdziesz w sekcji 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 określa 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);
  },
);

Poniższy fragment kodu tworzy zakładkę wskazującą dokumentację dla deweloperów dotyczącą rozszerzeń. Ponieważ nic złego się nie stanie, jeśli utworzenie zakładki się nie powiedzie, ten kod nie definiuje funkcji 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

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

  • dateAdded

    number opcjonalny

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

  • dateGroupModified

    number opcjonalny

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

  • dateLastUsed

    number opcjonalny

    Chrome 114 lub nowsza

    Czas ostatniego otwarcia tego węzła w milisekundach od początku epoki. Nie można ustawić dla folderów.

  • folderType

    FolderType opcjonalny

    Chrome 134 lub nowsza

    Jeśli występuje, jest to folder dodany przez przeglądarkę, którego użytkownik ani rozszerzenie nie mogą modyfikować. Węzły podrzędne można modyfikować, jeśli w tym węźle nie jest ustawiona właściwość unmodifiable. Pomijane, jeśli węzeł może być modyfikowany przez użytkownika i rozszerzenie (domyślnie).

    Każdy typ folderu może mieć 0, 1 lub więcej węzłów. 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 opcjonalny

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

  • parentId

    ciąg znaków opcjonalny

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

  • synchronizacja

    wartość logiczna

    Chrome 134 lub nowsza

    Określa, czy ten węzeł jest synchronizowany z zdalnym miejscem na dane na koncie użytkownika przez przeglądarkę. Można go używać do rozróżniania wersji tego samego FolderType na koncie i wersji lokalnych. 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: ta wartość odzwierciedla, czy węzeł jest zapisany u wbudowanego dostawcy kont w przeglądarce. Węzeł może być synchronizowany przez firmę zewnętrzną, nawet jeśli ta wartość jest fałszywa.

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

  • tytuł

    tekst

    Tekst wyświetlany w przypadku węzła.

  • nie można go modyfikować,

    „managed”
     opcjonalnie

    Wskazuje powód, dla którego tego węzła nie można modyfikować. Wartość managed oznacza, ż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

    Adres URL, do którego użytkownik zostanie przekierowany po kliknięciu zakładki. Pomijane w przypadku folderów.

BookmarkTreeNodeUnmodifiable

Chrome 44 lub nowszy

Wskazuje powód, dla którego tego węzła nie można modyfikować. Wartość managed oznacza, ż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 opcjonalny

  • 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

Określa 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 ogólnie dostępne na urządzeniach mobilnych użytkownika, ale modyfikowane przez rozszerzenie lub w menedżerze zakładek.

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

Właściwości

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

Wycofano

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

Wartość

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

Wycofano

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

Wartość

1000000

ROOT_NODE_ID

Chrome 145 lub nowsza

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

Wartość

„0”

Metody

create()

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

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

Parametry

Zwroty

get()

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

Pobiera określone węzły BookmarkTreeNode.

Parametry

  • idOrIdList

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

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

Zwroty

getChildren()

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

Pobiera elementy podrzędne określonego węzła BookmarkTreeNode.

Parametry

  • id

    tekst

Zwroty

getRecent()

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

Pobiera ostatnio dodane zakładki.

Parametry

  • numberOfItems

    liczba

    Maksymalna liczba elementów do zwrócenia.

Zwroty

getSubTree()

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

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

Parametry

  • id

    tekst

    Identyfikator korzenia poddrzewa do pobrania.

Zwroty

getTree()

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

Pobiera całą hierarchię zakładek.

Zwroty

move()

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

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

Parametry

  • id

    tekst

  • usługa docelowa | konto usługi docelowej

    obiekt

    • indeks

      number opcjonalny

    • parentId

      ciąg znaków opcjonalny

Zwroty

remove()

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

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

Parametry

  • id

    tekst

Zwroty

  • Promise<void>

    Chrome w wersji 90 lub nowszej

removeTree()

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

Rekursywnie usuwa folder zakładek.

Parametry

  • id

    tekst

Zwroty

  • Promise<void>

    Chrome w wersji 90 lub nowszej 
chrome.bookmarks.search(
  query: string | object,
): Promise<BookmarkTreeNode[]>

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

Parametry

  • zapytanie

    string | object

    Ciąg słów i wyrażeń 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 wygenerowane zostaną zakładki pasujące do wszystkich określonych właściwości.

    • zapytanie

      ciąg znaków opcjonalny

      Ciąg słów i cytowanych wyrażeń, które są porównywane z adresami URL i tytułami zakładek.

    • tytuł

      ciąg znaków opcjonalny

      Tytuł zakładki, który musi być identyczny.

    • URL

      ciąg znaków opcjonalny

      Adres URL zakładki, który jest zgodny co do litery. Pamiętaj, że foldery nie mają adresu URL.

Zwroty

update()

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

Aktualizuje właściwości zakładki lub folderu. Podaj tylko właściwości, które chcesz zmienić. Właściwości, których nie podasz, pozostaną bez zmian. Uwaga: obecnie obsługiwane są tylko atrybuty „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

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

Wyzwalane, gdy zmieni się zakładka lub folder. Uwaga: obecnie tylko zmiany tytułu i adresu URL powodują wywołanie tego zdarzenia.

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

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

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

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

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

    • id

      tekst

    • reorderInfo

      obiekt

      • childIds

        string[]

onCreated

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

Uruchamiane, gdy zostanie utworzona zakładka lub folder.

Parametry

onImportBegan

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

Uruchamiane po rozpoczęciu sesji importowania zakładek. Kosztowne obserwatory powinny ignorować aktualizacje onCreated, dopóki nie zostanie wywołana funkcja onImportEnded. Obserwatorzy powinni jednak natychmiast reagować na inne powiadomienia.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    () => void

onImportEnded

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

Uruchamiane po zakończeniu sesji importowania zakładek.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    () => void

onMoved

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

Wywoływane, 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

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

Wywoływane, gdy zakładka lub folder zostaną usunięte. Gdy folder zostanie usunięty rekursywnie, zostanie wysłane 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