Обновите свой код

Обновления, не связанные с другими вопросами.

Это первый из трех разделов, описывающих изменения, необходимые для кода, не являющегося частью обработчика службы расширения. Этот раздел посвящен необходимым изменениям кода, не связанным с другими вопросами. Следующие два раздела посвящены замене блокирующих веб-запросов и повышению безопасности .

Замените tabs.executeScript() на scripting.executeScript()

В Manifest V3 executeScript() перенесена из API tabs в API scripting . Это требует внесения изменений в права доступа в файле манифеста в дополнение к изменениям в самом коде.

Для метода executeScript() вам потребуется:

• Разрешение "scripting" .
• Либо права доступа хоста, либо права доступа "activeTab" .

Метод scripting.executeScript() работает аналогично методу tabs.executeScript() . Есть несколько отличий.

• Если старый метод мог обрабатывать только один файл, то новый метод может обрабатывать массив файлов.
• Также вы передаете объект ScriptInjection вместо InjectDetails . Между ними есть несколько различий. Например, tabId теперь передается как член ScriptInjection.target , а не как аргумент метода.

В примере показано, как это сделать.

async function getCurrentTab() {/* ... */}
let tab = await getCurrentTab();

browser.tabs.executeScript(
  tab.id,
  {
    file: 'content-script.js'
  }
);

async function getCurrentTab()
let tab = await getCurrentTab();

browser.scripting.executeScript({
  target: {tabId: tab.id},
  files: ['content-script.js']
});

Замените tabs.insertCSS() и tabs.removeCSS() на scripting.insertCSS() и scripting.removeCSS()

В Manifest V3 insertCSS() и removeCSS() перенесены из API tabs в API scripting . Это требует внесения изменений в права доступа в файле манифеста в дополнение к изменениям в коде:

• Разрешение "scripting" .
• Либо права доступа хоста, либо права доступа "activeTab" .

Функции API для scripting аналогичны функциям tabs . Есть несколько отличий.

• При вызове этих методов вы передаете объект CSSInjection вместо InjectDetails .
• Теперь tabId передается как член класса CSSInjection.target , а не как аргумент метода.

В примере показано, как это сделать для insertCSS() . Процедура для removeCSS() аналогична.

browser.tabs.insertCSS(tabId, injectDetails, () => {
  // callback code
});

const insertPromise = await browser.scripting.insertCSS({
  files: ["style.css"],
  target: { tabId: tab.id }
});
// Remaining code. 

Замените действия браузера и действия страницы на другие действия.

Действия браузера и действия страниц в Manifest V2 представляли собой отдельные концепции. Хотя изначально они выполняли разные функции, со временем различия между ними уменьшились. В Manifest V3 эти концепции объединены в Action API. Это требует внесения изменений в ваш manifest.json и код расширения, отличающихся от тех, которые вы бы указали в фоновом скрипте Manifest V2.

Действия в Manifest V3 наиболее точно соответствуют действиям браузера; однако API action не предоставляет hide() и show() , как это было pageAction . Если вам все еще нужны действия страницы, вы можете либо эмулировать их с помощью декларативного содержимого , либо вызвать enable() или disable() с идентификатором вкладки.

Замените "browser_action" и "page_action" на "action".

В файле manifest.json замените поля "browser_action" и "page_action" на поле "action" . Для получения дополнительной информации о поле "action" обратитесь к справочнику.

{
  ...
  "page_action": { ... },
  "browser_action": {
    "default_popup": "popup.html"
   }
  ...
}

{
  ...
  "action": {
    "default_popup": "popup.html"
  }

  ...
}

Замените API browserAction и pageAction на API action.

В версиях Manifest V2, где использовались API browserAction и pageAction , теперь следует использовать API action .

browser.browserAction.onClicked.addListener(tab => { ... });
browser.pageAction.onClicked.addListener(tab => { ... });

browser.action.onClicked.addListener(tab => { ... });

Замените коллбэки на промисы.

В Manifest V3 многие методы API расширений возвращают промисы. Промис — это прокси или заполнитель для значения, возвращаемого асинхронным методом. Если вы никогда не использовали промисы, вы можете прочитать о них на MDN . На этой странице описано, что вам нужно знать, чтобы использовать их в расширении Chrome.

Для обеспечения обратной совместимости многие методы продолжают поддерживать коллбэки после добавления поддержки промисов. Имейте в виду, что вы не можете использовать оба варианта в одном вызове функции. Если вы передадите коллбэк, функция не вернет промис, а если вы хотите получить промис, не передавайте коллбэк. Некоторые функции API, такие как обработчики событий, по-прежнему будут требовать коллбэков. Чтобы проверить, поддерживает ли метод промисы, найдите метку "Promise" в его справочнике API.

Чтобы преобразовать коллбэк в промис, удалите коллбэк и обработайте возвращаемый промис. Пример ниже взят из примера необязательных разрешений , а именно из файла newtab.js . Версия с коллбэком показывает, как бы выглядел вызов функции request() из примера с коллбэком. Обратите внимание, что версию с промисом можно переписать с использованием async и await.

browser.permissions.request(newPerms, (granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});

const newPerms = { permissions: ['topSites'] };
browser.permissions.request(newPerms)
.then((granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});

Замените функции, которые ожидают фоновый контекст Manifest V2.

Другие контексты расширений могут взаимодействовать с рабочими процессами служб расширений только посредством передачи сообщений . Следовательно, вам потребуется заменить вызовы, которые ожидают фоновый контекст, а именно:

• browser.runtime.getBackgroundPage()
• browser.extension.getBackgroundPage()
• browser.extension.getExtensionTabs()

В скриптах вашего расширения следует использовать передачу сообщений для связи между сервис-воркером и другими частями вашего расширения. В настоящее время это можно сделать с помощью sendMessage() и реализации browser.runtime.onMessage в сервис-воркере вашего расширения. В долгосрочной перспективе следует запланировать замену этих вызовов на postMessage() и обработчик событий сообщений сервис-воркера.

Замените неподдерживаемые API.

В Manifest V3 необходимо внести изменения в перечисленные ниже методы и свойства.

Обновления, не связанные с другими вопросами.

Это первый из трех разделов, описывающих изменения, необходимые для кода, не являющегося частью обработчика службы расширения. Этот раздел посвящен необходимым изменениям кода, не связанным с другими вопросами. Следующие два раздела посвящены замене блокирующих веб-запросов и повышению безопасности .

Замените tabs.executeScript() на scripting.executeScript()

В Manifest V3 executeScript() перенесена из API tabs в API scripting . Это требует внесения изменений в права доступа в файле манифеста в дополнение к изменениям в самом коде.

Для метода executeScript() вам потребуется:

• Разрешение "scripting" .
• Либо права доступа хоста, либо права доступа "activeTab" .

Метод scripting.executeScript() работает аналогично методу tabs.executeScript() . Есть несколько отличий.

• Если старый метод мог обрабатывать только один файл, то новый метод может обрабатывать массив файлов.
• Также вы передаете объект ScriptInjection вместо InjectDetails . Между ними есть несколько различий. Например, tabId теперь передается как член ScriptInjection.target , а не как аргумент метода.

В примере показано, как это сделать.

async function getCurrentTab() {/* ... */}
let tab = await getCurrentTab();

browser.tabs.executeScript(
  tab.id,
  {
    file: 'content-script.js'
  }
);

async function getCurrentTab()
let tab = await getCurrentTab();

browser.scripting.executeScript({
  target: {tabId: tab.id},
  files: ['content-script.js']
});

Замените tabs.insertCSS() и tabs.removeCSS() на scripting.insertCSS() и scripting.removeCSS()

В Manifest V3 insertCSS() и removeCSS() перенесены из API tabs в API scripting . Это требует внесения изменений в права доступа в файле манифеста в дополнение к изменениям в коде:

• Разрешение "scripting" .
• Либо права доступа хоста, либо права доступа "activeTab" .

Функции API для scripting аналогичны функциям tabs . Есть несколько отличий.

• При вызове этих методов вы передаете объект CSSInjection вместо InjectDetails .
• Теперь tabId передается как член класса CSSInjection.target , а не как аргумент метода.

В примере показано, как это сделать для insertCSS() . Процедура для removeCSS() аналогична.

browser.tabs.insertCSS(tabId, injectDetails, () => {
  // callback code
});

const insertPromise = await browser.scripting.insertCSS({
  files: ["style.css"],
  target: { tabId: tab.id }
});
// Remaining code. 

Замените действия браузера и действия страницы на другие действия.

Действия браузера и действия страниц в Manifest V2 представляли собой отдельные концепции. Хотя изначально они выполняли разные функции, со временем различия между ними уменьшились. В Manifest V3 эти концепции объединены в Action API. Это требует внесения изменений в ваш manifest.json и код расширения, отличающихся от тех, которые вы бы указали в фоновом скрипте Manifest V2.

Действия в Manifest V3 наиболее точно соответствуют действиям браузера; однако API action не предоставляет hide() и show() , как это было pageAction . Если вам все еще нужны действия страницы, вы можете либо эмулировать их с помощью декларативного содержимого , либо вызвать enable() или disable() с идентификатором вкладки.

Замените "browser_action" и "page_action" на "action".

В файле manifest.json замените поля "browser_action" и "page_action" на поле "action" . Для получения дополнительной информации о поле "action" обратитесь к справочнику.

{
  ...
  "page_action": { ... },
  "browser_action": {
    "default_popup": "popup.html"
   }
  ...
}

{
  ...
  "action": {
    "default_popup": "popup.html"
  }

  ...
}

Замените API browserAction и pageAction на API action.

В версии Manifest V2, где использовались API browserAction и pageAction , теперь следует использовать API action .

browser.browserAction.onClicked.addListener(tab => { ... });
browser.pageAction.onClicked.addListener(tab => { ... });

browser.action.onClicked.addListener(tab => { ... });

Замените коллбэки на промисы.

В Manifest V3 многие методы API расширений возвращают промисы. Промис — это прокси или заполнитель для значения, возвращаемого асинхронным методом. Если вы никогда не использовали промисы, вы можете прочитать о них на MDN . На этой странице описано, что вам нужно знать, чтобы использовать их в расширении Chrome.

Для обеспечения обратной совместимости многие методы продолжают поддерживать коллбэки после добавления поддержки промисов. Имейте в виду, что вы не можете использовать оба варианта в одном вызове функции. Если вы передадите коллбэк, функция не вернет промис, а если вы хотите получить промис, не передавайте коллбэк. Некоторые функции API, такие как обработчики событий, по-прежнему будут требовать коллбэков. Чтобы проверить, поддерживает ли метод промисы, найдите метку "Promise" в его справочнике API.

Чтобы преобразовать коллбэк в промис, удалите коллбэк и обработайте возвращаемый промис. Пример ниже взят из примера необязательных разрешений , а именно из файла newtab.js . Версия с коллбэком показывает, как бы выглядел вызов функции request() из примера с коллбэком. Обратите внимание, что версию с промисом можно переписать с использованием async и await.

browser.permissions.request(newPerms, (granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});

const newPerms = { permissions: ['topSites'] };
browser.permissions.request(newPerms)
.then((granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});

Замените функции, которые ожидают фоновый контекст Manifest V2.

Другие контексты расширений могут взаимодействовать с рабочими процессами служб расширений только посредством передачи сообщений . Следовательно, вам потребуется заменить вызовы, которые ожидают фоновый контекст, а именно:

• browser.runtime.getBackgroundPage()
• browser.extension.getBackgroundPage()
• browser.extension.getExtensionTabs()

В скриптах вашего расширения следует использовать передачу сообщений для связи между сервис-воркером и другими частями вашего расширения. В настоящее время это можно сделать с помощью sendMessage() и реализации browser.runtime.onMessage в сервис-воркере вашего расширения. В долгосрочной перспективе следует запланировать замену этих вызовов на postMessage() и обработчик событий сообщений сервис-воркера.

Замените неподдерживаемые API.

В Manifest V3 необходимо внести изменения в перечисленные ниже методы и свойства.