chrome.tabs (original) (raw)

Przejdź do głównej treści

chrome.tabs

Opis

Używaj interfejsu chrome.tabs API do interakcji z systemem kart przeglądarki. Za pomocą tego interfejsu API możesz tworzyć, modyfikować i przenosić karty w przeglądarce.

Interfejs Tabs API oferuje nie tylko funkcje manipulowania kartami i zarządzania nimi, ale też wykrywa język karty, robi zrzut ekranu i komunikuje się ze skryptami treści karty.

Uprawnienia

Większość funkcji nie wymaga żadnych uprawnień. Na przykład: utworzenie nowej karty, ponowne wczytanie karty, przejście do innego adresu URL itp.

Podczas korzystania z interfejsu Tabs API deweloperzy powinni pamiętać o 3 uprawnieniach.

Uprawnienie „karty”

To uprawnienie nie daje dostępu do przestrzeni nazw chrome.tabs. Zamiast tego umożliwia rozszerzeniu wywoływanie funkcji tabs.query() w przypadku 4 właściwości wrażliwych w instancjach tabs.Tab: url, pendingUrl, title i favIconUrl.

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

Uprawnienia hosta

Uprawnienia hosta umożliwiają rozszerzeniu odczytywanie i wykonywanie zapytań dotyczących 4 właściwości karty, które są wrażliwe:tabs.Tab Mogą też wchodzić w bezpośrednią interakcję z pasującymi kartami za pomocą metod takich jak tabs.captureVisibleTab(), scripting.executeScript(), scripting.insertCSS() i scripting.removeCSS().

{
  "name": "My extension",
  ...
  "host_permissions": [
    "http://*/*",
    "https://*/*"
  ],
  ...
}

Uprawnienie „activeTab”

activeTab przyznaje rozszerzeniu tymczasowe uprawnienia hosta do bieżącej karty w odpowiedzi na wywołanie przez użytkownika. W przeciwieństwie do uprawnień hosta activeTab nie powoduje wyświetlania żadnych ostrzeżeń.

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

Przypadki użycia

W kolejnych sekcjach przedstawiamy kilka typowych przypadków użycia.

Otwieranie strony rozszerzenia w nowej karcie

Częstym wzorcem w przypadku rozszerzeń jest otwieranie strony wprowadzającej w nowej karcie po zainstalowaniu rozszerzenia. Poniższy przykład pokazuje, jak to zrobić.

background.js:

chrome.runtime.onInstalled.addListener(({reason}) => {
  if (reason === 'install') {
    chrome.tabs.create({
      url: "onboarding.html"
    });
  }
});

Pobieranie bieżącej karty

Ten przykład pokazuje, jak proces roboczy usługi rozszerzenia może pobrać aktywną kartę z aktualnie aktywnego okna (lub ostatnio aktywnego okna, jeśli żadne okno Chrome nie jest aktywne). Można to zwykle traktować jako bieżącą kartę użytkownika.

  async function getCurrentTab() {
    let queryOptions = { active: true, lastFocusedWindow: true };
    // `tab` will either be a `tabs.Tab` instance or `undefined`.
    let [tab] = await chrome.tabs.query(queryOptions);
    return tab;
  }

  function getCurrentTab(callback) {
    let queryOptions = { active: true, lastFocusedWindow: true };
    chrome.tabs.query(queryOptions, ([tab]) => {
      if (chrome.runtime.lastError)
      console.error(chrome.runtime.lastError);
      // `tab` will either be a `tabs.Tab` instance or `undefined`.
      callback(tab);
    });
  }

Wyciszanie określonej karty

Ten przykład pokazuje, jak rozszerzenie może przełączać stan wyciszenia danej karty.

  async function toggleMuteState(tabId) {
    const tab = await chrome.tabs.get(tabId);
    const muted = !tab.mutedInfo.muted;
    await chrome.tabs.update(tabId, {muted});
    console.log(`Tab <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mrow><mi>t</mi><mi>a</mi><mi>b</mi><mi mathvariant="normal">.</mi><mi>i</mi><mi>d</mi></mrow><mi>i</mi><mi>s</mi></mrow><annotation encoding="application/x-tex">{tab.id} is </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.6944em;"></span><span class="mord"><span class="mord mathnormal">t</span><span class="mord mathnormal">ab</span><span class="mord">.</span><span class="mord mathnormal">i</span><span class="mord mathnormal">d</span></span><span class="mord mathnormal">i</span><span class="mord mathnormal">s</span></span></span></span>{muted ? "muted" : "unmuted"}`);
  }

  function toggleMuteState(tabId) {
    chrome.tabs.get(tabId, async (tab) => {
      let muted = !tab.mutedInfo.muted;
      await chrome.tabs.update(tabId, { muted });
      console.log(`Tab <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mrow><mi>t</mi><mi>a</mi><mi>b</mi><mi mathvariant="normal">.</mi><mi>i</mi><mi>d</mi></mrow><mi>i</mi><mi>s</mi></mrow><annotation encoding="application/x-tex">{tab.id} is </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.6944em;"></span><span class="mord"><span class="mord mathnormal">t</span><span class="mord mathnormal">ab</span><span class="mord">.</span><span class="mord mathnormal">i</span><span class="mord mathnormal">d</span></span><span class="mord mathnormal">i</span><span class="mord mathnormal">s</span></span></span></span>{ muted ? "muted" : "unmuted" }`);
    });
  }

Przenoszenie bieżącej karty na pierwszą pozycję po kliknięciu

Ten przykład pokazuje, jak przenieść kartę, gdy przeciąganie może być w toku lub nie. W tym przykładzie użyto chrome.tabs.move, ale możesz zastosować ten sam wzorzec oczekiwania w przypadku innych wywołań, które modyfikują karty podczas przeciągania.

  chrome.tabs.onActivated.addListener(moveToFirstPosition);

  async function moveToFirstPosition(activeInfo) {
    try {
      await chrome.tabs.move(activeInfo.tabId, {index: 0});
      console.log("Success.");
    } catch (error) {
      if (error == "Error: Tabs cannot be edited right now (user may be dragging a tab).") {
        setTimeout(() => moveToFirstPosition(activeInfo), 50);
      } else {
        console.error(error);
      }
    }
  }

  chrome.tabs.onActivated.addListener(moveToFirstPositionMV2);

  function moveToFirstPositionMV2(activeInfo) {
    chrome.tabs.move(activeInfo.tabId, { index: 0 }, () => {
      if (chrome.runtime.lastError) {
        const error = chrome.runtime.lastError;
        if (error == "Error: Tabs cannot be edited right now (user may be dragging a tab).") {
          setTimeout(() => moveToFirstPositionMV2(activeInfo), 50);
        } else {
          console.error(error);
        }
      } else {
        console.log("Success.");
      }
    });
  }

Przekazywanie wiadomości do skryptu treści wybranej karty

Ten przykład pokazuje, jak proces roboczy usługi rozszerzenia może komunikować się ze skryptami treści w określonych kartach przeglądarki za pomocą interfejsu tabs.sendMessage().

function sendMessageToActiveTab(message) {
  const [tab] = await chrome.tabs.query({ active: true, lastFocusedWindow: true });
  const response = await chrome.tabs.sendMessage(tab.id, message);
  // TODO: Do something with the response.
}

Przykłady rozszerzeń

Więcej demonstracji rozszerzeń interfejsu Tabs API znajdziesz w tych materiałach:

Typy

MutedInfo

Stan wyciszenia karty i przyczyna ostatniej zmiany stanu.

Właściwości

MutedInfoReason

Zdarzenie, które spowodowało zmianę stanu wyciszenia.

Typ wyliczeniowy

„user”
Użytkownik ustawił stan wyciszenia.

„capture”
Rozpoczęto nagrywanie karty, co spowodowało zmianę stanu wyciszenia.

„extension”
Rozszerzenie, zidentyfikowane przez pole extensionId, ustawiło stan wyciszenia.

Tab

Właściwości

TabStatus

Stan wczytywania karty.

Typ wyliczeniowy

„unloaded”

„loading”

„complete”

Typ wyliczeniowy

„normal”

"popup"

„panel”

„app”

„devtools”

ZoomSettings

Określa, jak i w jakim zakresie mają być obsługiwane zmiany powiększenia na karcie.

Właściwości

ZoomSettingsMode

Określa sposób obsługi zmian powiększenia, czyli podmiot odpowiedzialny za rzeczywiste skalowanie strony. Domyślnie jest to automatic.

Typ wyliczeniowy

„automatyczne”
Zmiany powiększenia są obsługiwane automatycznie przez przeglądarkę.

„manual”
Zastępuje automatyczną obsługę zmian powiększenia. Zdarzenie onZoomChange nadal będzie wysyłane, a rozszerzenie będzie musiało nasłuchiwać tego zdarzenia i ręcznie skalować stronę. Ten tryb nie obsługuje powiększania per-origin, więc ignoruje ustawienie powiększenia scope i zakłada per-tab.

„disabled”
Wyłącza wszystkie opcje powiększania na karcie. Karta powróci do domyślnego poziomu powiększenia, a wszystkie próby zmiany powiększenia zostaną zignorowane.

ZoomSettingsScope

Określa, czy zmiany powiększenia mają być zachowywane dla źródła strony, czy mają obowiązywać tylko na tej karcie. W trybie automatic domyślnie jest to per-origin, a w innych trybach – per-tab.

Typ wyliczeniowy

„per-origin”
Zmiany powiększenia są zachowywane w źródle powiększonej strony, tzn. wszystkie inne karty, na których otwarte jest to samo źródło, są również powiększone. Ponadto per-origin zmiany powiększenia są zapisywane w domenie, co oznacza, że podczas przechodzenia do innych stron w tej samej domenie wszystkie są powiększane do tego samego współczynnika powiększenia. Zakres per-origin jest dostępny tylko w trybie automatic.

„na kartę”
Zmiany powiększenia są wprowadzane tylko na tej karcie, a zmiany powiększenia na innych kartach nie wpływają na powiększenie tej karty. Poza tym per-tabzmiany powiększenia są resetowane podczas nawigacji; nawigacja po karcie zawsze wczytuje strony z per-originwartościami powiększenia.

Właściwości

MAX_CAPTURE_VISIBLE_TAB_CALLS_PER_SECOND

Maksymalna liczba wywołań funkcji captureVisibleTab na sekundę. captureVisibleTab jest kosztowna i nie należy jej wywoływać zbyt często.

TAB_ID_NONE

Identyfikator reprezentujący brak karty przeglądarki.

TAB_INDEX_NONE

Indeks reprezentujący brak indeksu karty w obszarze tab_strip.

Metody

captureVisibleTab()

chrome.tabs.captureVisibleTab(
  windowId?: number,
  options?: ImageDetails,
): Promise

Rejestruje widoczny obszar obecnie aktywnej karty w określonym oknie. Aby wywołać tę metodę, rozszerzenie musi mieć uprawnienie <all_urls> lub activeTab. Oprócz stron, do których rozszerzenia mają zwykle dostęp, ta metoda umożliwia rozszerzeniom przechwytywanie wrażliwych stron, które są w inny sposób ograniczone, w tym stron ze schematem chrome:, stron innych rozszerzeń i adresów URL data:. Te wrażliwe strony można przechwytywać tylko za pomocą uprawnienia activeTab. Adresy URL plików można przechwytywać tylko wtedy, gdy rozszerzenie ma dostęp do plików.

Parametry

Zwroty

connect()

chrome.tabs.connect(
  tabId: number,
  connectInfo?: object,
): runtime.Port

Łączy się ze skryptami treści na określonej karcie. Zdarzenie runtime.onConnect jest wywoływane w każdym skrypcie treści działającym w określonej karcie bieżącego rozszerzenia. Więcej informacji znajdziesz w artykule Wysyłanie wiadomości do skryptu treści.

Parametry

Zwroty

create()

chrome.tabs.create(
  createProperties: object,
): Promise<Tab>

Tworzy nową kartę.

Parametry

Zwroty

detectLanguage()

chrome.tabs.detectLanguage(
  tabId?: number,
): Promise

wykrywa główny język treści na karcie;

Zwroty

discard()

chrome.tabs.discard(
  tabId?: number,
): Promise<Tab | undefined>

Zwalnia pamięć zajmowaną przez kartę. Odrzucone karty są nadal widoczne na pasku kart i są ponownie wczytywane po aktywowaniu.

Parametry

Zwroty

duplicate()

chrome.tabs.duplicate(
  tabId: number,
): Promise<Tab | undefined>

Duplikuje kartę.

Parametry

Zwroty

get()

chrome.tabs.get(
  tabId: number,
): Promise<Tab>

Pobiera szczegóły określonej karty.

Parametry

Zwroty

getCurrent()

chrome.tabs.getCurrent(): Promise<Tab | undefined>

Pobiera kartę, z której wywoływany jest ten skrypt. Zwraca undefined, jeśli jest wywoływana w kontekście innym niż karta (np. na stronie w tle lub w widoku wyskakującym).

Zwroty

getZoom()

chrome.tabs.getZoom(
  tabId?: number,
): Promise

Pobiera bieżący współczynnik powiększenia określonej karty.

Parametry

Zwroty

getZoomSettings()

chrome.tabs.getZoomSettings(
  tabId?: number,
): Promise<ZoomSettings>

Pobiera bieżące ustawienia powiększenia określonej karty.

Parametry

Zwroty

goBack()

Chrome w wersji 72 lub nowszej

chrome.tabs.goBack(
  tabId?: number,
): Promise

Wróć na poprzednią stronę, jeśli jest dostępna.

Parametry

Zwroty

goForward()

Chrome w wersji 72 lub nowszej

chrome.tabs.goForward(
  tabId?: number,
): Promise

Przechodzi do następnej strony, jeśli jest dostępna.

Parametry

Zwroty

group()

chrome.tabs.group(
  options: object,
): Promise

Dodaje jedną lub więcej kart do określonej grupy. Jeśli grupa nie jest określona, dodaje podane karty do nowo utworzonej grupy.

Parametry

Zwroty

highlight()

chrome.tabs.highlight(
  highlightInfo: object,
): Promise<windows.Window>

Wyróżnia podane karty i skupia się na pierwszej z nich. Jeśli określona karta jest obecnie aktywna, nie będzie to miało żadnego wpływu.

Parametry

Zwroty

move()

chrome.tabs.move(
  tabIds: number | number[],
  moveProperties: object,
): Promise<Tab | Tab[]>

Przenosi jedną lub więcej kart w nowe miejsce w oknie lub do nowego okna. Pamiętaj, że karty można przenosić tylko do i z normalnych okien (window.type === "normal").

Parametry

Zwroty

query()

chrome.tabs.query(
  queryInfo: object,
): Promise<Tab[]>

Pobiera wszystkie karty, które mają określone właściwości, lub wszystkie karty, jeśli nie określono żadnych właściwości.

Parametry

Zwroty

reload()

chrome.tabs.reload(
  tabId?: number,
  reloadProperties?: object,
): Promise

ponownie załadować kartę,

Parametry

Zwroty

remove()

chrome.tabs.remove(
  tabIds: number | number[],
): Promise

Zamyka co najmniej 1 kartę.

Parametry

Zwroty

sendMessage()

chrome.tabs.sendMessage(
  tabId: number,
  message: any,
  options?: object,
): Promise

Wysyła pojedynczą wiadomość do skryptów treści na określonej karcie z opcjonalnym wywołaniem zwrotnym, które ma zostać uruchomione po odesłaniu odpowiedzi. Zdarzenie runtime.onMessage jest wywoływane w każdym skrypcie treści działającym w określonej karcie bieżącego rozszerzenia.

Parametry

Zwroty

setZoom()

chrome.tabs.setZoom(
  tabId?: number,
  zoomFactor: number,
): Promise

Powiększa określoną kartę.

Parametry

Zwroty

setZoomSettings()

chrome.tabs.setZoomSettings(
  tabId?: number,
  zoomSettings: ZoomSettings,
): Promise

Ustawia ustawienia powiększenia dla określonej karty, które określają sposób obsługi zmian powiększenia. Po przejściu na inną kartę te ustawienia zostaną przywrócone do wartości domyślnych.

Parametry

Zwroty

ungroup()

chrome.tabs.ungroup(
  tabIds: number | [number, ...number[]],
): Promise

Usuwa co najmniej jedną kartę z odpowiednich grup. Jeśli jakieś grupy staną się puste, zostaną usunięte.

Parametry

Zwroty

update()

chrome.tabs.update(
  tabId?: number,
  updateProperties: object,
): Promise<Tab | undefined>

Zmienia właściwości karty. Właściwości, które nie są określone w updateProperties, nie są modyfikowane.

Parametry

Zwroty

Wydarzenia

onActivated

chrome.tabs.onActivated.addListener(
  callback: function,
)

Wywoływane, gdy zmieni się aktywna karta w oknie. Pamiętaj, że adres URL karty może nie być ustawiony w momencie wywołania tego zdarzenia, ale możesz nasłuchiwać zdarzeń onUpdated, aby otrzymywać powiadomienia o ustawieniu adresu URL.

Parametry

onAttached

chrome.tabs.onAttached.addListener(
  callback: function,
)

Wywoływane, gdy karta jest dołączana do okna, np. po przeniesieniu jej między oknami.

Parametry

onCreated

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

Uruchamiane, gdy karta zostanie utworzona. Pamiętaj, że adres URL karty i członkostwo w grupie kart mogą nie być ustawione w momencie wywołania tego zdarzenia, ale możesz nasłuchiwać zdarzeń onUpdated, aby otrzymywać powiadomienia o ustawieniu adresu URL lub dodaniu karty do grupy kart.

Parametry

onDetached

chrome.tabs.onDetached.addListener(
  callback: function,
)

Wywoływane, gdy karta zostanie odłączona od okna, np. z powodu przeniesienia jej między oknami.

Parametry

onHighlighted

chrome.tabs.onHighlighted.addListener(
  callback: function,
)

Wysyłane, gdy zmienią się wyróżnione lub wybrane karty w oknie.

Parametry

onMoved

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

Wywoływane, gdy karta zostanie przeniesiona w oknie. Wywoływane jest tylko jedno zdarzenie przeniesienia, które reprezentuje kartę bezpośrednio przeniesioną przez użytkownika. Zdarzenia przeniesienia nie są wywoływane w przypadku innych kart, które muszą zostać przeniesione w odpowiedzi na ręcznie przeniesioną kartę. To zdarzenie nie jest wywoływane, gdy karta jest przenoszona między oknami. Więcej informacji znajdziesz w tabs.onDetached.

Parametry

onRemoved

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

Uruchamiane po zamknięciu karty.

Parametry

onReplaced

chrome.tabs.onReplaced.addListener(
  callback: function,
)

Wywoływane, gdy karta zostanie zastąpiona inną kartą z powodu wstępnego renderowania lub natychmiastowego wczytywania.

Parametry

onUpdated

chrome.tabs.onUpdated.addListener(
  callback: function,
)

Uruchamiane, gdy karta zostanie zaktualizowana.

Parametry

onZoomChange

chrome.tabs.onZoomChange.addListener(
  callback: function,
)

Uruchamiane, gdy karta zostanie powiększona.

Parametry

O ile nie stwierdzono inaczej, treść tej strony jest objęta licencją Creative Commons – uznanie autorstwa 4.0, a fragmenty kodu są dostępne na licencji Apache 2.0. Szczegółowe informacje na ten temat zawierają zasady dotyczące witryny Google Developers. Java jest zastrzeżonym znakiem towarowym firmy Oracle i jej podmiotów stowarzyszonych.

Ostatnia aktualizacja: 2025-09-15 UTC.