Chrome obsługuje teraz standardową przestrzeń nazw browser.* (dostępną od Chrome 148). Stopniowo aktualizujemy dokumentację. Więcej informacji znajdziesz w naszym przewodniku dotyczącym przejścia.

Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

browser.permissions

Opis

Używaj interfejsu chrome.permissions API, aby prosić o zadeklarowane uprawnienia opcjonalne w czasie działania aplikacji, a nie podczas instalacji. Dzięki temu użytkownicy będą rozumieć, dlaczego uprawnienia są potrzebne, i przyznawać tylko te, które są niezbędne.

Pojęcia i zastosowanie

Ostrzeżenia o uprawnieniach opisują możliwości przyznane przez interfejs API, ale niektóre z nich mogą być nieoczywiste. Interfejs Permissions API umożliwia deweloperom wyjaśnianie ostrzeżeń dotyczących uprawnień i stopniowe wprowadzanie nowych funkcji, dzięki czemu użytkownicy mogą bez ryzyka zapoznać się z rozszerzeniem. Dzięki temu użytkownicy mogą określić, jaki zakres dostępu chcą przyznać i które funkcje chcą włączyć.

Na przykład główną funkcjonalnością rozszerzenia z opcjonalnymi uprawnieniami jest zastępowanie strony nowej karty. Jedną z funkcji jest wyświetlanie celu użytkownika na dany dzień. Ta funkcja wymaga tylko uprawnienia pamięć, które nie zawiera ostrzeżenia. Rozszerzenie ma dodatkową funkcję, którą użytkownicy mogą włączyć, klikając ten przycisk:

Przycisk rozszerzenia, który umożliwia korzystanie z dodatkowych funkcji.

Wyświetlanie najpopularniejszych witryn użytkownika wymaga uprawnienia topSites, które wiąże się z tym ostrzeżeniem:

Ostrzeżenie o rozszerzeniu interfejsu API topSites. — Ostrzeżenie o rozszerzeniu interfejsu `topSites` API

Wdrażanie uprawnień opcjonalnych

Krok 1. Określ, które uprawnienia są wymagane, a które opcjonalne

Rozszerzenie może deklarować zarówno wymagane, jak i opcjonalne uprawnienia. Ogólnie rzecz biorąc, wykonaj te czynności:

Używaj wymaganych uprawnień, gdy są one potrzebne do podstawowego działania rozszerzenia.
Używaj uprawnień opcjonalnych, gdy są one potrzebne do korzystania z opcjonalnych funkcji rozszerzenia.

Zalety uprawnień wymaganych:

Mniej próśb: rozszerzenie może poprosić użytkownika o zaakceptowanie wszystkich uprawnień tylko raz.
Prostsze tworzenie: wymagane uprawnienia są zawsze dostępne.

Zalety uprawnień opcjonalnych:

Większe bezpieczeństwo: rozszerzenia działają z mniejszą liczbą uprawnień, ponieważ użytkownicy włączają tylko te, które są potrzebne.
Lepsze informacje dla użytkowników: rozszerzenie może wyjaśnić, dlaczego potrzebuje określonego uprawnienia, gdy użytkownik włączy odpowiednią funkcję.
Łatwiejsze uaktualnianie: gdy uaktualnisz rozszerzenie, Chrome nie wyłączy go użytkownikom, jeśli uaktualnienie doda uprawnienia opcjonalne, a nie wymagane.

Krok 2. Zadeklaruj uprawnienia opcjonalne w pliku manifestu

Zadeklaruj opcjonalne uprawnienia w pliku manifestu rozszerzenia za pomocą klucza optional_permissions w tym samym formacie co pole permissions:

{
  "name": "My extension",
  ...
  "optional_permissions": ["tabs"],
  "optional_host_permissions": ["https://www.google.com/"],
  ...
}

Jeśli chcesz wysyłać żądania do hostów, które są wykrywane tylko w czasie działania, w polu optional_host_permissions rozszerzenia umieść "https://*/*". Dzięki temu możesz określić dowolne źródło w "Permissions.origins", o ile ma ono pasujący schemat.

Uprawnienia, których nie można określić jako opcjonalne

Większość uprawnień rozszerzeń do Chrome można określić jako opcjonalne, z wyjątkiem tych:

Uprawnienie	Opis
`"debugger"`	Interfejs browser.debugger API służy jako alternatywny transport dla protokołu zdalnego debugowania w Chrome.
`"declarativeNetRequest"`	Przyznaje rozszerzeniu dostęp do interfejsu browser.declarativeNetRequest API.
`"devtools"`	Umożliwia rozszerzeniu rozszerzanie funkcji Narzędzi deweloperskich w Chrome.
`"geolocation"`	Umożliwia rozszerzeniu korzystanie z interfejsu HTML5 geolokalizacji.
`"mdns"`	Przyznaje rozszerzeniu dostęp do interfejsu browser.mdns API.
`"proxy"`	Umożliwia rozszerzeniu dostęp do interfejsu browser.proxy API w celu zarządzania ustawieniami serwera proxy w Chrome.
`"tts"`	Interfejs browser.tts odtwarza zsyntetyzowaną zamianę tekstu na mowę (TTS).
`"ttsEngine"`	Interfejs browser.ttsEngine implementuje silnik zamiany tekstu na mowę (TTS) za pomocą rozszerzenia.
`"wallpaper"`	Tylko ChromeOS Użyj interfejsu browser.wallpaper API, aby zmienić tapetę w ChromeOS.

Więcej informacji o dostępnych uprawnieniach i ostrzeżeniach z nimi związanych znajdziesz w artykule Deklarowanie uprawnień.

Krok 3. Poproś o opcjonalne uprawnienia

Poproś o uprawnienia w ramach gestu użytkownika za pomocą funkcji permissions.request():

document.querySelector('#my-button').addEventListener('click', (event) => {
  // Permissions must be requested from inside a user gesture, like a button's
  // click handler.
  browser.permissions.request({
    permissions: ['tabs'],
    origins: ['https://www.google.com/']
  }, (granted) => {
    // The callback argument will be true if the user granted the permissions.
    if (granted) {
      doSomething();
    } else {
      doSomethingElse();
    }
  });
});

Chrome wyświetla użytkownikowi prośbę, jeśli dodanie uprawnień powoduje wyświetlenie innych komunikatów ostrzegawczych niż te, które użytkownik już widział i zaakceptował. Na przykład poprzedni kod może spowodować wyświetlenie takiego promptu:

Przykładowa prośba o potwierdzenie uprawnień. — Przykładowy komunikat z prośbą o potwierdzenie zgody.

Krok 4. Sprawdź bieżące uprawnienia rozszerzenia

Aby sprawdzić, czy rozszerzenie ma określone uprawnienie lub zestaw uprawnień, użyj:permission.contains()

browser.permissions.contains({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (result) => {
  if (result) {
    // The extension has the permissions.
  } else {
    // The extension doesn't have the permissions.
  }
});

Krok 5. Usuń uprawnienia

Gdy nie będziesz już potrzebować uprawnień, usuń je. Po usunięciu uprawnienia wywołanie funkcji permissions.request() zwykle przywraca uprawnienie bez wyświetlania użytkownikowi prośby o potwierdzenie.

browser.permissions.remove({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (removed) => {
  if (removed) {
    // The permissions have been removed.
  } else {
    // The permissions have not been removed (e.g., you tried to remove
    // required permissions).
  }
});

Typy

Permissions

Właściwości

pochodzenie,

string[] opcjonalnie

Lista uprawnień do hosta, w tym uprawnień określonych w kluczach optional_permissions lub permissions w pliku manifestu oraz uprawnień powiązanych ze skryptami treści.
uprawnienia

string[] opcjonalnie

Lista nazwanych uprawnień (nie obejmuje hostów ani źródeł).

Metody

addHostAccessRequest()

Chrome 133 lub nowszy MV3 lub nowszy

chrome.permissions.addHostAccessRequest(
  request: object,
): Promise<void>

Dodaje prośbę o dostęp dla gospodarza. Prośba zostanie wyświetlona użytkownikowi tylko wtedy, gdy rozszerzenie może uzyskać dostęp do hosta w prośbie. Żądanie zostanie zresetowane podczas nawigacji między domenami. Po zaakceptowaniu przyznaje trwały dostęp do głównego źródła witryny.

Parametry

żądanie

obiekt
- documentId
  
  ciąg znaków opcjonalny
  
  Identyfikator dokumentu, w którym mogą być wyświetlane prośby o dostęp do hosta. Musi to być dokument najwyższego poziomu na karcie. Jeśli zostanie podana, prośba będzie widoczna na karcie określonego dokumentu i zostanie usunięta, gdy dokument przejdzie do nowego źródła. Dodanie nowej prośby spowoduje zastąpienie dotychczasowej prośby o tabId. Należy określić tę wartość lub tabId.
- wzór
  
  ciąg znaków opcjonalny
  
  Wzorzec adresu URL, w którym mogą być wyświetlane żądania dostępu do hosta. Jeśli podasz ten wzorzec, prośby o dostęp do hosta będą wyświetlane tylko w przypadku adresów URL, które do niego pasują.
- tabId
  
  number opcjonalny
  
  Identyfikator karty, na której mogą być wyświetlane prośby o dostęp do hosta. Jeśli zostanie podany, żądanie będzie widoczne na określonej karcie i zostanie usunięte, gdy karta przejdzie do nowej domeny. Dodanie nowej prośby spowoduje zastąpienie istniejącej prośby o documentId. Należy określić tę wartość lub documentId.

Zwroty

Promise<void>

contains()

chrome.permissions.contains(
  permissions: Permissions,
): Promise<boolean>

Sprawdza, czy rozszerzenie ma określone uprawnienia.

Parametry

uprawnienia

Uprawnienia

Zwroty

Promise<boolean>

Chrome 96 lub nowsza

getAll()

chrome.permissions.getAll(): Promise<Permissions>

Pobiera bieżący zestaw uprawnień rozszerzenia.

Zwroty

Promise<Permissions>

Chrome 96 lub nowsza

remove()

chrome.permissions.remove(
  permissions: Permissions,
): Promise<boolean>

Usuwa dostęp do określonych uprawnień. Jeśli wystąpią problemy z usunięciem uprawnień, obietnica zostanie odrzucona.

Parametry

uprawnienia

Uprawnienia

Zwroty

Promise<boolean>

Chrome 96 lub nowsza

removeHostAccessRequest()

Chrome 133 lub nowszy MV3 lub nowszy

chrome.permissions.removeHostAccessRequest(
  request: object,
): Promise<void>

Usuwa prośbę o dostęp hosta, jeśli taka istnieje.

Parametry

żądanie

obiekt
- documentId
  
  ciąg znaków opcjonalny
  
  Identyfikator dokumentu, z którego zostanie usunięta prośba o dostęp do hosta. Musi to być dokument najwyższego poziomu na karcie. Należy określić tę wartość lub tabId.
- wzór
  
  ciąg znaków opcjonalny
  
  Wzorzec adresu URL, z którego zostanie usunięta prośba o dostęp hosta. Jeśli zostanie podany, musi dokładnie pasować do wzorca istniejącego żądania dostępu do hosta.
- tabId
  
  number opcjonalny
  
  Identyfikator karty, z której zostanie usunięta prośba o dostęp do hosta. Należy określić tę wartość lub documentId.

Zwroty

Promise<void>

request()

chrome.permissions.request(
  permissions: Permissions,
): Promise<boolean>

Prosi o dostęp do określonych uprawnień, a w razie potrzeby wyświetla użytkownikowi prośbę. Te uprawnienia muszą być zdefiniowane w polu optional_permissions pliku manifestu lub być wymaganymi uprawnieniami, które zostały odrzucone przez użytkownika. Ścieżki we wzorcach źródła będą ignorowane. Możesz poprosić o podzbiory opcjonalnych uprawnień dotyczących punktu początkowego. Jeśli na przykład w sekcji optional_permissions pliku manifestu określisz *://*\/*, możesz poprosić o http://example.com/. Jeśli podczas wysyłania prośby o uprawnienia wystąpią problemy, obietnica zostanie odrzucona.

Parametry

uprawnienia

Uprawnienia

Zwroty

Promise<boolean>

Chrome 96 lub nowsza

Wydarzenia

onAdded

chrome.permissions.onAdded.addListener(
  callback: function,
)

Uruchamiane, gdy rozszerzenie uzyska nowe uprawnienia.

Parametry

callback

funkcja

Parametr callback wygląda tak:
```
(permissions: Permissions) => void
```
- uprawnienia
  
  Uprawnienia

onRemoved

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

Wyzwalane, gdy dostęp do uprawnień został usunięty z rozszerzenia.

Parametry

callback

funkcja

Parametr callback wygląda tak:
```
(permissions: Permissions) => void
```
- uprawnienia
  
  Uprawnienia

browser.permissions Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Opis

Pojęcia i zastosowanie

Wdrażanie uprawnień opcjonalnych

Krok 1. Określ, które uprawnienia są wymagane, a które opcjonalne

Krok 2. Zadeklaruj uprawnienia opcjonalne w pliku manifestu

Krok 3. Poproś o opcjonalne uprawnienia

Krok 4. Sprawdź bieżące uprawnienia rozszerzenia

Krok 5. Usuń uprawnienia

Typy

Permissions

Właściwości

Metody

addHostAccessRequest()

Parametry

Zwroty

contains()

Parametry

Zwroty

getAll()

Zwroty

remove()

Parametry

Zwroty

removeHostAccessRequest()

Parametry

Zwroty

request()

Parametry

Zwroty

Wydarzenia

onAdded

Parametry

onRemoved

Parametry

browser.permissions