chrome.runtime

Deskripsi

Gunakan chrome.runtime API untuk mengambil pekerja layanan, menampilkan detail tentang manifes, dan memproses serta merespons peristiwa dalam siklus proses ekstensi. Anda juga dapat menggunakan API ini untuk mengonversi jalur relatif URL menjadi URL yang sepenuhnya memenuhi syarat.

Sebagian besar anggota API ini tidak memerlukan izin apa pun. Izin ini diperlukan untuk connectNative(), sendNativeMessage(), dan onNativeConnect.

Contoh berikut menunjukkan cara mendeklarasikan izin "nativeMessaging" dalam manifes:

manifest.json:

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

Konsep dan penggunaan

Runtime API menyediakan metode untuk mendukung sejumlah area yang memerlukan ekstensi dapat menggunakan:

Penerusan pesan
Ekstensi Anda dapat berkomunikasi dengan berbagai konteks dalam ekstensi dan juga dengan ekstensi lain menggunakan metode dan peristiwa berikut: connect(), onConnect, onConnectExternal, sendMessage(), onMessage dan onMessageExternal. Selain itu, ekstensi Anda dapat meneruskan pesan ke aplikasi native di perangkat pengguna menggunakan connectNative() dan sendNativeMessage()
Mengakses metadata platform dan ekstensi
Metode ini memungkinkan Anda mengambil beberapa metadata tertentu tentang ekstensi dan terkelola sepenuhnya. Metode dalam kategori ini meliputi getManifest(), dan getPlatformInfo()
Mengelola opsi dan siklus proses ekstensi
Properti ini memungkinkan Anda menjalankan beberapa operasi meta pada ekstensi dan menampilkan halaman opsi. Metode dan peristiwa dalam kategori ini mencakup onInstalled, onStartup, openOptionsPage(), reload(), requestUpdateCheck(), dan setUninstallURL().
Utilitas bantuan
Metode ini menyediakan utilitas seperti konversi representasi resource internal menjadi format eksternal. Metode dalam kategori ini meliputi getURL()
Utilitas mode kios
Metode ini hanya tersedia di ChromeOS, dan terutama tersedia untuk mendukung implementasi kios. Metode dalam kategori ini meliputi restart() dan restartAfterDelay()`.

Perilaku ekstensi yang tidak dipaketkan

Saat ekstensi yang tidak dipaketkan dimuat ulang, ekstensi ini dianggap sebagai update. Ini berarti bahwa Peristiwa chrome.runtime.onInstalled akan diaktifkan dengan alasan "update". Ini disertakan saat ekstensi dimuat ulang dengan chrome.runtime.reload().

Kasus penggunaan

Menambahkan gambar ke halaman web

Agar dapat mengakses aset yang dihosting di domain lain, halaman web harus menentukan URL lengkap resource (misalnya, <img src="https://example.com/logo.png">). Hal yang sama berlaku untuk menyertakan aset ekstensi pada sebuah laman web. Dua perbedaan ini adalah aset ekstensi harus ditampilkan sebagai web resource yang dapat diakses dan biasanya skrip konten bertanggung jawab untuk memasukkan aset ekstensi.

Dalam contoh ini, ekstensi akan menambahkan logo.png ke halaman yang konten skrip sedang dimasukkan ke dalam dengan menggunakan runtime.getURL() untuk membuat URL yang sepenuhnya memenuhi syarat. Namun, pertama-tama, aset harus dideklarasikan sebagai resource yang dapat diakses dari web dalam manifes.

manifest.json:

{
  ...
  "web_accessible_resources": [
    {
      "resources": [ "logo.png" ],
      "matches": [ "https://*/*" ]
    }
  ],
  ...
}

content.js:

{ // Block used to avoid setting global variables
  const img = document.createElement('img');
  img.src = chrome.runtime.getURL('logo.png');
  document.body.append(img);
}

Mengirim data dari skrip konten ke pekerja layanan

Skrip konten ekstensi biasanya memerlukan data yang dikelola oleh bagian lain ekstensi, seperti pekerja layanan. Sama seperti dua jendela {i>browser<i} yang terbuka ke laman web yang sama, komputer dua konteks tidak dapat langsung mengakses nilai masing-masing. Sebagai gantinya, ekstensi dapat menggunakan message yang diteruskan untuk berkoordinasi dalam berbagai konteks tersebut.

Dalam contoh ini, skrip konten memerlukan beberapa data dari pekerja layanan ekstensi untuk melakukan inisialisasi UI-nya. Untuk mendapatkan data ini, metode ini akan meneruskan pesan get-user-data yang ditentukan developer ke pekerja layanan, dan ia merespons dengan salinan informasi pengguna.

content.js:

// 1. Send a message to the service worker requesting the user's data
chrome.runtime.sendMessage('get-user-data', (response) => {
  // 3. Got an asynchronous response with the data from the service worker
  console.log('received user data', response);
  initializeUI(response);
});

service-worker.js:

// Example of a simple user data object
const user = {
  username: 'demo-user'
};

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // 2. A page requested user data, respond with a copy of `user`
  if (message === 'get-user-data') {
    sendResponse(user);
  }
});

Kumpulkan masukan tentang uninstal

Banyak ekstensi menggunakan survei pasca-uninstal untuk memahami bagaimana ekstensi dapat melayaninya dengan lebih baik pengguna dan meningkatkan retensi. Contoh berikut menunjukkan cara menambahkan fungsi ini.

background.js:

chrome.runtime.onInstalled.addListener(details => {
  if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
    chrome.runtime.setUninstallURL('https://example.com/extension-survey');
  }
});

Contoh

Lihat demo Manifes V3 - Resource yang Dapat Diakses Web untuk contoh Runtime API lainnya.

Jenis

ContextFilter

Chrome 114 dan yang lebih baru

Filter yang akan dicocokkan dengan konteks ekstensi tertentu. Konteks yang cocok harus cocok dengan semua filter yang ditentukan; filter apa pun yang tidak ditentukan cocok dengan semua konteks yang tersedia. Dengan demikian, filter `{}` akan cocok dengan semua konteks yang tersedia.

Properti

  • contextIds

    string[] opsional

  • contextTypes

    ContextType[] opsional

  • documentIds

    string[] opsional

  • documentOrigins

    string[] opsional

  • documentUrls

    string[] opsional

  • frameIds

    number[] opsional

  • samaran

    boolean opsional

  • tabIds

    number[] opsional

  • windowIds

    number[] opsional

ContextType

Chrome 114 dan yang lebih baru

Enum

"TAB"
Menentukan jenis konteks sebagai tab

"POPUP"
Menentukan jenis konteks sebagai jendela pop-up ekstensi

"BACKGROUND"
Menentukan jenis konteks sebagai pekerja layanan.

"OFFSCREEN_DOCUMENT"
Menentukan jenis konteks sebagai dokumen di luar layar.

"SIDE_Panel"
Menentukan jenis konteks sebagai panel samping.

ExtensionContext

Chrome 114 dan yang lebih baru

Konteks yang menghosting konten ekstensi.

Properti

  • contextId

    string

    ID unik untuk konteks ini

  • contextType

    ContextType

    Jenis konteks yang sesuai dengan ini.

  • documentId

    string opsional

    UUID untuk dokumen yang terkait dengan konteks ini, atau tidak ditentukan jika konteks ini dihosting bukan dalam dokumen.

  • documentOrigin

    string opsional

    Asal dokumen yang terkait dengan konteks ini, atau tidak didefinisikan jika konteks tidak dihosting dalam dokumen.

  • documentUrl

    string opsional

    URL dokumen yang terkait dengan konteks ini, atau tidak didefinisikan jika konteks tidak dihosting dalam dokumen.

  • frameId

    angka

    ID frame untuk konteks ini, atau -1 jika konteks ini tidak dihosting dalam frame.

  • samaran

    boolean

    Apakah konteksnya terkait dengan profil samaran.

  • tabId

    angka

    ID tab untuk konteks ini, atau -1 jika konteks ini tidak dihosting dalam tab.

  • windowId

    angka

    ID jendela untuk konteks ini, atau -1 jika konteks ini tidak dihosting di jendela.

MessageSender

Objek yang berisi informasi tentang konteks skrip yang mengirim pesan atau permintaan.

Properti

  • documentId

    string opsional

    Chrome 106 dan yang lebih baru

    UUID dokumen yang membuka koneksi.

  • documentLifecycle

    string opsional

    Chrome 106 dan yang lebih baru

    Siklus proses dokumen yang membuka koneksi berada pada saat port dibuat. Perhatikan bahwa status siklus proses dokumen mungkin telah berubah sejak pembuatan port.

  • frameId

    angka opsional

    Frame yang membuka koneksi. 0 untuk frame level teratas, positif untuk frame turunan. Kunci ini hanya akan disetel saat tab disetel.

  • id

    string opsional

    ID ekstensi yang membuka koneksi, jika ada.

  • nativeApplication

    string opsional

    Chrome 74 dan yang lebih baru

    Nama aplikasi native yang membuka koneksi, jika ada.

  • asal

    string opsional

    Chrome 80 dan yang lebih baru

    Asal halaman atau frame yang membuka koneksi. Kolom ini dapat berbeda dari properti URL (mis., about:blank) atau bisa juga buram (mis., sandbox iframe). Hal ini berguna untuk mengidentifikasi apakah origin dapat dipercaya jika kami tidak dapat langsung mengetahui dari URL.

  • tab

    Tab opsional

    tabs.Tab yang membuka koneksi, jika ada. Properti ini hanya akan ada saat koneksi dibuka dari tab (termasuk skrip konten), dan hanya jika penerima adalah ekstensi, bukan aplikasi.

  • tlsChannelId

    string opsional

    ID saluran TLS halaman atau frame yang membuka koneksi, jika diminta oleh ekstensi, dan jika tersedia.

  • url

    string opsional

    URL halaman atau bingkai yang membuka koneksi. Jika pengirim berada dalam iframe, URL akan berupa URL iframe, bukan URL halaman yang menghostingnya.

OnInstalledReason

Chrome 44 dan yang lebih baru

Alasan peristiwa ini dikirim.

Enum

"install"
Menentukan alasan peristiwa sebagai penginstalan.

"update"
Menentukan alasan peristiwa sebagai update ekstensi.

&quot;chrome_update&quot;
Menentukan alasan peristiwa sebagai update Chrome.

"shared_module_update"
Menentukan alasan peristiwa sebagai update untuk modul bersama.

OnRestartRequiredReason

Chrome 44 dan yang lebih baru

Alasan peristiwa dikirim. 'app_update' (pembaruan_aplikasi) digunakan bila perlu mulai ulang karena aplikasi diperbarui ke versi yang lebih baru. 'os_update' (pembaruan_os) digunakan saat mulai ulang diperlukan karena browser/OS diperbarui ke versi yang lebih baru. 'berkala' digunakan saat sistem berjalan melebihi waktu beroperasi yang diizinkan yang ditetapkan dalam kebijakan perusahaan.

Enum

"app_update"
Menentukan alasan peristiwa sebagai update pada aplikasi.

&quot;os_update&quot;
Menentukan alasan peristiwa sebagai update pada sistem operasi.

"periodic"
Menentukan alasan peristiwa sebagai mulai ulang aplikasi secara berkala.

PlatformArch

Chrome 44 dan yang lebih baru

Arsitektur prosesor mesin.

Enum

"arm"
Menentukan arsitektur pemroses sebagai grup.

"arm64"
Menentukan arsitektur pemroses sebagai arm64.

"x86-32"
Menentukan arsitektur pemroses sebagai x86-32.

"x86-64"
Menentukan arsitektur pemroses sebagai x86-64.

"mips"
Menentukan arsitektur pemroses sebagai mips.

"mips64"
Menentukan arsitektur pemroses sebagai mips64.

PlatformInfo

Objek yang berisi informasi tentang platform saat ini.

Properti

  • Arsitektur prosesor mesin.

  • nacl_arch

    PlatformNaclArch

    Arsitektur klien native. Hal ini mungkin berbeda dengan arch di beberapa platform.

  • Sistem operasi yang dijalankan Chrome.

PlatformNaclArch

Chrome 44 dan yang lebih baru

Arsitektur klien native. Hal ini mungkin berbeda dengan arch di beberapa platform.

Enum

"arm"
Menentukan arsitektur klien native sebagai grup.

"x86-32"
Menentukan arsitektur klien native sebagai x86-32.

"x86-64"
Menentukan arsitektur klien native sebagai x86-64.

"mips"
Menentukan arsitektur klien native sebagai mips.

"mips64"
Menentukan arsitektur klien native sebagai mips64.

PlatformOs

Chrome 44 dan yang lebih baru

Sistem operasi yang dijalankan Chrome.

Enum

"mac"
Menentukan sistem operasi MacOS.

"win"
Menentukan sistem operasi Windows.

"android"
Menentukan sistem operasi Android.

"cros"
Menentukan sistem operasi Chrome.

"linux"
Menentukan sistem operasi Linux.

&quot;openbsd&quot;
Menentukan sistem operasi OpenBSD.

"fuchsia"
Menentukan sistem operasi Fuchsia.

Port

Objek yang memungkinkan komunikasi dua arah dengan halaman lain. Lihat Koneksi jangka panjang untuk informasi selengkapnya.

Properti

  • nama

    string

    Nama port, seperti yang ditentukan dalam panggilan ke runtime.connect.

  • onDisconnect

    Peristiwa<functionvoidvoid>

    Diaktifkan saat port terputus dari ujung lainnya. runtime.lastError dapat ditetapkan jika port terputus karena error. Jika port ditutup melalui putuskan sambungan, peristiwa ini hanya akan diaktifkan di sisi satunya. Peristiwa ini diaktifkan paling banyak sekali (lihat juga Masa aktif port).

    Fungsi onDisconnect.addListener akan terlihat seperti ini: 

    (callback: function) => {...}

    • callback

      fungsi

      Parameter callback terlihat seperti ini: 

      (port: Port) => void

  • onMessage

    Peristiwa<functionvoidvoid>

    Peristiwa ini diaktifkan saat postMessage dipanggil oleh ujung port yang lain.

    Fungsi onMessage.addListener akan terlihat seperti ini: 

    (callback: function) => {...}

    • callback

      fungsi

      Parameter callback terlihat seperti ini: 

      (message: any, port: Port) => void

      • pesan

        apa pun

      • port

        Port

  • pengirim

    MessageSender opsional

    Properti ini hanya akan ada pada port yang diteruskan ke pemroses onConnect / onConnectExternal / onConnectNative.

  • putuskan koneksi

    void

    Segera putuskan sambungan port. Memanggil disconnect() pada port yang sudah terputus tidak akan berpengaruh. Jika port terputus, tidak ada peristiwa baru yang akan dikirim ke port ini.

    Fungsi disconnect akan terlihat seperti ini: 

    () => {...}

  • postMessage

    void

    Kirim pesan ke ujung port yang lain. Jika port terputus, pesan error akan muncul.

    Fungsi postMessage akan terlihat seperti ini: 

    (message: any) => {...}

    • pesan

      apa pun

      Chrome 52 atau yang lebih baru

      Pesan yang akan dikirim. Objek ini harus dapat disetel ke JSON.

RequestUpdateCheckStatus

Chrome 44 dan yang lebih baru

Hasil pemeriksaan update.

Enum

"throttled"
Menentukan bahwa pemeriksaan status telah dibatasi. Hal ini dapat terjadi setelah pemeriksaan berulang dalam waktu singkat.

"no_update"
Menentukan bahwa tidak ada update yang tersedia untuk diinstal.

"update_available"
Menentukan bahwa ada update yang tersedia untuk diinstal.

Properti

id

ID ekstensi/aplikasi.

Jenis

string

lastError

Diisi dengan pesan error jika fungsi API gagal dipanggil; jika tidak terdefinisi. Ini hanya ditentukan dalam cakupan callback fungsi tersebut. Jika error dihasilkan, tetapi runtime.lastError tidak diakses dalam callback, pesan akan dicatat ke konsol yang mencantumkan fungsi API yang menghasilkan error. Fungsi API yang menampilkan promise tidak menetapkan properti ini.

Jenis

objek

Properti

  • pesan

    string opsional

    Detail tentang error yang terjadi.

Metode

connect()

chrome.runtime.connect(
  extensionId?: string,
  connectInfo?: object,
)

Berupaya menghubungkan pemroses dalam ekstensi (seperti halaman latar belakang), atau ekstensi/aplikasi lainnya. Hal ini berguna untuk skrip konten yang terhubung ke proses ekstensi, komunikasi antar-aplikasi/ekstensi, dan pesan web. Perhatikan bahwa ini tidak terhubung ke pemroses mana pun dalam skrip konten. Ekstensi dapat terhubung ke skrip konten yang disematkan di tab melalui tabs.connect.

Parameter

  • extensionId

    string opsional

    ID ekstensi yang akan dihubungkan. Jika dihilangkan, koneksi akan dicoba dengan ekstensi Anda sendiri. Diperlukan jika mengirim pesan dari halaman web untuk pesan web.

  • connectInfo

    objek opsional

    • includeTlsChannelId

      boolean opsional

      Apakah ID saluran TLS akan diteruskan ke onConnectExternal untuk proses yang memproses peristiwa koneksi.

    • nama

      string opsional

      Akan diteruskan ke onConnect untuk proses yang memproses peristiwa koneksi.

Hasil

  • Port tempat pesan dapat dikirim dan diterima. Peristiwa onDisconnect port akan diaktifkan jika ekstensi tidak ada.

connectNative()

chrome.runtime.connectNative(
  application: string,
)

Menghubungkan ke aplikasi native di mesin host. Metode ini memerlukan izin "nativeMessaging". Lihat Pesan Native untuk informasi selengkapnya.

Parameter

  • aplikasi

    string

    Nama aplikasi terdaftar yang akan dihubungkan.

Hasil

  • Porta yang dapat digunakan aplikasi untuk mengirim dan menerima pesan

getBackgroundPage()

Janji Hanya latar depan 
chrome.runtime.getBackgroundPage(
  callback?: function,
)

Mengambil 'jendela' JavaScript untuk halaman latar belakang yang berjalan di dalam ekstensi/aplikasi saat ini. Jika halaman latar belakang adalah halaman peristiwa, sistem akan memastikan halaman tersebut dimuat sebelum memanggil callback. Jika tidak ada halaman latar belakang, error akan muncul.

Parameter

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (backgroundPage?: Window) => void

    • backgroundPage

      Jendela opsional

      'Jendela' JavaScript untuk halaman latar belakang.

Hasil

  • Promise&lt;Window | tidak terdefinisi>

    Chrome 99 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

getContexts()

Janji Chrome 116 dan yang lebih baru MV3 atau yang lebih baru 
chrome.runtime.getContexts(
  filter: ContextFilter,
  callback?: function,
)

Mengambil informasi tentang konteks aktif yang terkait dengan ekstensi ini

Parameter

  • filter

    ContextFilter

    Filter untuk menemukan konteks yang cocok. Konteks cocok jika cocok dengan semua kolom yang ditentukan dalam filter. Kolom yang belum ditentukan dalam filter cocok dengan semua konteks.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (contexts: ExtensionContext[]) => void

Hasil

  • Promise&lt;ExtensionContext[]&gt;

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

getManifest()

chrome.runtime.getManifest()

Menampilkan detail tentang aplikasi atau ekstensi dari manifes. Objek yang ditampilkan adalah serialisasi file manifes lengkap.

Hasil

  • objek

    Detail manifes.

getPackageDirectoryEntry()

Janji Hanya latar depan 
chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
)

Menampilkan DirectoryEntry untuk direktori paket.

Parameter

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (directoryEntry: DirectoryEntry) => void

    • directoryEntry

      DirectoryEntry

Hasil

  • Promise&lt;DirectoryEntry&gt;

    Chrome 122 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

getPlatformInfo()

Janji 
chrome.runtime.getPlatformInfo(
  callback?: function,
)

Menampilkan informasi tentang platform saat ini.

Parameter

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (platformInfo: PlatformInfo) => void

Hasil

  • Promise&lt;PlatformInfo&gt;

    Chrome 99 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

getURL()

chrome.runtime.getURL(
  path: string,
)

Mengonversi jalur relatif dalam direktori penginstalan aplikasi/ekstensi menjadi URL yang sepenuhnya memenuhi syarat.

Parameter

  • jalur

    string

    Jalur ke resource dalam aplikasi/ekstensi yang dinyatakan relatif terhadap direktori penginstalannya.

Hasil

  • string

    URL yang sepenuhnya memenuhi syarat ke resource.

openOptionsPage()

Janji 
chrome.runtime.openOptionsPage(
  callback?: function,
)

Buka halaman opsi Ekstensi, jika memungkinkan.

Perilaku yang tepat mungkin bergantung pada kunci [options_ui](https://developer.chrome.com/docs/extensions/develop/ui/options-page#embedded_options) atau [options_page](https://developer.chrome.com/docs/extensions/develop/ui/options-page#full_page) manifes, atau dukungan yang didukung Chrome pada saat itu. Misalnya, halaman dapat dibuka di tab baru, di dalam chrome://extensions, dalam Aplikasi, atau mungkin hanya berfokus pada halaman opsi terbuka. Tindakan ini tidak akan menyebabkan halaman pemanggil dimuat ulang.

Jika Ekstensi Anda tidak menyatakan halaman opsi, atau Chrome gagal membuatnya karena alasan lain, callback akan menetapkan lastError.

Parameter

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    () => void

Hasil

  • Janji<void>

    Chrome 99 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

reload()

chrome.runtime.reload()

Memuat ulang aplikasi atau ekstensi. Metode ini tidak didukung dalam mode kios. Untuk mode kios, gunakan metode chrome.runtime.restart().

requestUpdateCheck()

Janji 
chrome.runtime.requestUpdateCheck(
  callback?: function,
)

Meminta pemeriksaan update langsung dilakukan untuk aplikasi/ekstensi ini.

Penting: Sebagian besar ekstensi/aplikasi tidak boleh menggunakan metode ini karena Chrome sudah melakukan pemeriksaan otomatis setiap beberapa jam, dan Anda dapat memproses peristiwa runtime.onUpdateAvailable tanpa perlu memanggil requestUpdateCheck.

Metode ini hanya sesuai untuk memanggil dalam situasi yang sangat terbatas, seperti jika ekstensi Anda berkomunikasi dengan layanan backend, dan layanan backend telah menyimpulkan bahwa versi ekstensi klien sudah sangat usang dan Anda ingin meminta pengguna untuk melakukan update. Sebagian besar penggunaan requestUpdateCheck lainnya, seperti memanggilnya tanpa syarat berdasarkan timer berulang, mungkin hanya akan membuang-buang resource klien, jaringan, dan server.

Catatan: Saat dipanggil dengan callback, fungsi ini akan menampilkan kedua properti sebagai argumen terpisah yang diteruskan ke callback, bukan menampilkan objek.

Parameter

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (result: object) => void

    • hasil

      objek

      Chrome 109 dan yang lebih baru

      Objek RequestUpdateCheckResult yang menyimpan status pemeriksaan update dan detail hasil jika ada update yang tersedia

      • Hasil pemeriksaan update.

      • versi

        string opsional

        Jika update tersedia, ini akan berisi versi update yang tersedia.

Hasil

  • Promise&lt;object&gt;

    Chrome 109 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

restart()

chrome.runtime.restart()

Mulai ulang perangkat ChromeOS saat aplikasi berjalan dalam mode kios. Jika tidak, maka tidak akan dioperasikan.

restartAfterDelay()

Janji Chrome 53 dan yang lebih baru 
chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

Mulai ulang perangkat ChromeOS saat aplikasi berjalan dalam mode kios setelah detik yang ditentukan. Jika dipanggil lagi sebelum waktu berakhir, mulai ulang akan ditunda. Jika dipanggil dengan nilai -1, mulai ulang akan dibatalkan. Ini adalah tanpa pengoperasian dalam mode non-kios. API ini hanya boleh dipanggil berulang kali oleh ekstensi pertama.

Parameter

  • detik

    angka

    Waktu tunggu dalam detik sebelum memulai ulang perangkat, atau -1 untuk membatalkan mulai ulang terjadwal.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    () => void

Hasil

  • Janji<void>

    Chrome 99 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

sendMessage()

Janji 
chrome.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
  callback?: function,
)

Mengirim satu pesan ke pemroses peristiwa dalam ekstensi Anda atau ekstensi/aplikasi yang berbeda. Serupa dengan runtime.connect tetapi hanya mengirim satu pesan, dengan respons opsional. Jika mengirim ke ekstensi Anda, peristiwa runtime.onMessage akan diaktifkan di setiap frame ekstensi (kecuali untuk frame pengirim), atau runtime.onMessageExternal, jika ekstensi yang berbeda. Perhatikan bahwa ekstensi tidak dapat mengirim pesan ke skrip konten menggunakan metode ini. Untuk mengirim pesan ke skrip konten, gunakan tabs.sendMessage.

Parameter

  • extensionId

    string opsional

    ID ekstensi yang akan dikirimi pesan. Jika dihilangkan, pesan akan dikirimkan ke ekstensi/aplikasi Anda sendiri. Diperlukan jika mengirim pesan dari halaman web untuk pesan web.

  • pesan

    apa pun

    Pesan yang akan dikirim. Pesan ini harus berupa objek JSON-ifiable.

  • opsi

    objek opsional

    • includeTlsChannelId

      boolean opsional

      Apakah ID saluran TLS akan diteruskan ke onMessageExternal untuk proses yang memproses peristiwa koneksi.

  • callback

    fungsi opsional

    Chrome 99 dan yang lebih baru

    Parameter callback terlihat seperti ini: 

    (response: any) => void

    • respons

      apa pun

      Objek respons JSON yang dikirim oleh pengendali pesan. Jika terjadi error saat menghubungkan ke ekstensi, callback akan dipanggil tanpa argumen dan runtime.lastError akan ditetapkan ke pesan error.

Hasil

  • Janjikan<any>

    Chrome 99 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

sendNativeMessage()

Janji 
chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
  callback?: function,
)

Mengirim satu pesan ke aplikasi native. Metode ini memerlukan izin "nativeMessaging".

Parameter

  • aplikasi

    string

    Nama host pesan native.

  • pesan

    objek

    Pesan yang akan diteruskan ke host pesan native.

  • callback

    fungsi opsional

    Chrome 99 dan yang lebih baru

    Parameter callback terlihat seperti ini: 

    (response: any) => void

    • respons

      apa pun

      Pesan respons yang dikirim oleh host pesan native. Jika terjadi error saat terhubung ke host pesan native, callback akan dipanggil tanpa argumen dan runtime.lastError akan ditetapkan ke pesan error.

Hasil

  • Janjikan<any>

    Chrome 99 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

setUninstallURL()

Janji 
chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
)

Menetapkan URL yang akan dikunjungi setelah uninstal. Hal ini dapat digunakan untuk membersihkan data sisi server, melakukan analisis, dan menerapkan survei. Maksimum 1.023 karakter.

Parameter

  • url

    string

    URL yang akan dibuka setelah ekstensi di-uninstal. URL ini harus memiliki skema http: atau https:. Menyetel string kosong agar tidak membuka tab baru setelah uninstal.

  • callback

    fungsi opsional

    Chrome 45 dan yang lebih baru

    Parameter callback terlihat seperti ini: 

    () => void

Hasil

  • Janji<void>

    Chrome 99 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

Acara

onBrowserUpdateAvailable

Tidak digunakan lagi
chrome.runtime.onBrowserUpdateAvailable.addListener(
  callback: function,
)

Harap gunakan runtime.onRestartRequired.

Diaktifkan saat update Chrome tersedia, tetapi tidak langsung diinstal karena browser perlu dimulai ulang.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti ini: 

    () => void

onConnect

chrome.runtime.onConnect.addListener(
  callback: function,
)

Diaktifkan saat koneksi dibuat dari proses ekstensi atau skrip konten (oleh runtime.connect).

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti ini: 

    (port: Port) => void

onConnectExternal

chrome.runtime.onConnectExternal.addListener(
  callback: function,
)

Diaktifkan saat koneksi dibuat dari ekstensi lain (oleh runtime.connect), atau dari situs yang dapat dihubungkan secara eksternal.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti ini: 

    (port: Port) => void

onConnectNative

Chrome 76 dan yang lebih baru 
chrome.runtime.onConnectNative.addListener(
  callback: function,
)

Diaktifkan saat koneksi dibuat dari aplikasi native. Acara ini memerlukan izin "nativeMessaging". Hanya didukung di Chrome OS.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti ini: 

    (port: Port) => void

onInstalled

chrome.runtime.onInstalled.addListener(
  callback: function,
)

Diaktifkan saat ekstensi pertama kali diinstal, saat ekstensi diupdate ke versi baru, dan saat Chrome diupdate ke versi baru.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti ini: 

    (details: object) => void

    • detail

      objek

      • id

        string opsional

        Menunjukkan ID ekstensi modul bersama yang diimpor yang diperbarui. Ini hanya ada jika 'alasan' adalah 'shared_module_update'.

      • previousVersion

        string opsional

        Menunjukkan ekstensi versi sebelumnya, yang baru saja diupdate. Ini hanya ada jika 'alasan' adalah 'pembaruan'.

      • Alasan peristiwa ini dikirim.

onMessage

chrome.runtime.onMessage.addListener(
  callback: function,
)

Diaktifkan saat pesan dikirim dari proses ekstensi (oleh runtime.sendMessage) atau skrip konten (oleh tabs.sendMessage).

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti ini: 

    (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

    • pesan

      apa pun

    • pengirim

      MessageSender

    • sendResponse

      fungsi

      Parameter sendResponse terlihat seperti ini: 

      () => void

    • akan menampilkan

      boolean | tidak ditentukan

onMessageExternal

chrome.runtime.onMessageExternal.addListener(
  callback: function,
)

Diaktifkan saat pesan dikirim dari ekstensi lain (oleh runtime.sendMessage). Tidak dapat digunakan dalam skrip konten.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti ini: 

    (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

    • pesan

      apa pun

    • pengirim

      MessageSender

    • sendResponse

      fungsi

      Parameter sendResponse terlihat seperti ini: 

      () => void

    • akan menampilkan

      boolean | tidak ditentukan

onRestartRequired

chrome.runtime.onRestartRequired.addListener(
  callback: function,
)

Diaktifkan jika aplikasi atau perangkat yang menjalankannya perlu dimulai ulang. Aplikasi harus menutup semua jendelanya pada waktu yang tepat agar proses mulai ulang dilakukan. Jika aplikasi tidak melakukan apa pun, mulai ulang akan diterapkan setelah masa tenggang 24 jam berakhir. Saat ini, peristiwa ini hanya diaktifkan untuk aplikasi kios Chrome OS.

Parameter

onStartup

chrome.runtime.onStartup.addListener(
  callback: function,
)

Diaktifkan saat profil yang menginstal ekstensi ini pertama kali dimulai. Peristiwa ini tidak diaktifkan saat profil samaran dimulai, meskipun ekstensi ini beroperasi dalam mode 'terpisah' mode samaran.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti ini: 

    () => void

onSuspend

chrome.runtime.onSuspend.addListener(
  callback: function,
)

Dikirim ke halaman acara tepat sebelum dihapus muatannya. Hal ini memberi ekstensi kesempatan untuk melakukan pembersihan. Perhatikan bahwa karena halaman menghapus muatan, semua operasi asinkron yang dimulai saat menangani peristiwa ini tidak dijamin akan selesai. Jika lebih banyak aktivitas untuk halaman acara terjadi sebelum pemuatannya, peristiwa onSuspendSuspend akan dikirim dan halaman tidak akan dihapus muatannya.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti ini: 

    () => void

onSuspendCanceled

chrome.runtime.onSuspendCanceled.addListener(
  callback: function,
)

Dikirim setelah onSuspend untuk menunjukkan bahwa aplikasi sama sekali tidak akan dihapus muatannya.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti ini: 

    () => void

onUpdateAvailable

chrome.runtime.onUpdateAvailable.addListener(
  callback: function,
)

Diaktifkan saat update tersedia, tetapi tidak langsung diinstal karena aplikasi sedang berjalan. Jika Anda tidak melakukan apa pun, update akan diinstal saat halaman latar belakang dihapus muatannya, jika Anda ingin menginstalnya lebih cepat, Anda dapat memanggil chrome.runtime.reload() secara eksplisit. Jika ekstensi Anda menggunakan halaman latar belakang persisten, halaman latar belakang tentu saja tidak akan pernah dihapus muatannya, jadi kecuali Anda memanggil chrome.runtime.reload() secara manual sebagai respons terhadap peristiwa ini, update tidak akan diinstal hingga Chrome dimulai ulang lagi. Jika tidak ada pengendali yang memproses peristiwa ini, dan ekstensi Anda memiliki halaman latar belakang persisten, aplikasi akan berperilaku seolah-olah chrome.runtime.reload() dipanggil sebagai respons terhadap peristiwa ini.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti ini: 

    (details: object) => void

    • detail

      objek

      • versi

        string

        Nomor versi update yang tersedia.

onUserScriptConnect

Chrome 115 dan yang lebih baru MV3 dan yang lebih baru 
chrome.runtime.onUserScriptConnect.addListener(
  callback: function,
)

Diaktifkan saat koneksi dibuat dari skrip pengguna dari ekstensi ini.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti ini: 

    (port: Port) => void

onUserScriptMessage

Chrome 115 dan yang lebih baru MV3 dan yang lebih baru 
chrome.runtime.onUserScriptMessage.addListener(
  callback: function,
)

Diaktifkan saat pesan dikirim dari skrip pengguna yang terkait dengan ekstensi yang sama.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti ini: 

    (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

    • pesan

      apa pun

    • pengirim

      MessageSender

    • sendResponse

      fungsi

      Parameter sendResponse terlihat seperti ini: 

      () => void

    • akan menampilkan

      boolean | tidak ditentukan