chrome.sidePanel

Deskripsi

Gunakan chrome.sidePanel API untuk menghosting konten di panel samping browser bersama dengan konten utama halaman web.

Izin

sidePanel

Untuk menggunakan Side Panel API, tambahkan izin "sidePanel" dalam file manifes ekstensi:

manifest.json:

{
  "name": "My side panel extension",
  ...
  "permissions": [
    "sidePanel"
  ]
}

Ketersediaan

Chrome 114+ MV3+

Konsep dan penggunaan

Dengan Side Panel API, ekstensi dapat menampilkan UI-nya sendiri di panel samping, sehingga memberikan pengalaman persisten yang melengkapi perjalanan pengguna dalam melakukan penjelajahan.

Menu drop-down panel samping
UI panel samping browser Chrome.

Beberapa fiturnya meliputi:

  • Panel samping tetap terbuka saat bernavigasi di antara tab (jika disetel untuk melakukannya).
  • Data ini hanya dapat tersedia di situs tertentu.
  • Sebagai halaman ekstensi, panel samping memiliki akses ke semua Chrome API.
  • Dalam setelan Chrome, pengguna dapat menentukan sisi mana panel akan ditampilkan.

Kasus penggunaan

Bagian berikut menunjukkan beberapa kasus penggunaan umum untuk Side Panel API. Lihat Contoh ekstensi untuk mengetahui contoh ekstensi lengkap.

Menampilkan panel samping yang sama di setiap situs

Awalnya, panel samping dapat ditetapkan dari properti "default_path" di kunci "side_panel" manifes untuk menampilkan panel samping yang sama di setiap situs. Ini seharusnya mengarah ke jalur relatif dalam direktori ekstensi.

manifest.json:

{
  "name": "My side panel extension",
  ...
  "side_panel": {
    "default_path": "sidepanel.html"
  }
  ...
}

sidepanel.html:

<!DOCTYPE html>
<html>
  <head>
    <title>My Sidepanel</title>
  </head>
  <body>
    <h1>All sites sidepanel extension</h1>
    <p>This side panel is enabled on all sites</p>
  </body>
</html>

Mengaktifkan panel samping di situs tertentu

Ekstensi dapat menggunakan sidepanel.setOptions() untuk mengaktifkan panel samping di tab tertentu. Contoh ini menggunakan chrome.tabs.onUpdated() untuk memproses pembaruan yang dilakukan pada tab. Tag Assistant akan memeriksa apakah URL-nya adalah www.google.com dan mengaktifkan panel samping. Jika tidak, Chromebook akan menonaktifkannya.

service-worker.js:

const GOOGLE_ORIGIN = 'https://www.google.com';

chrome.tabs.onUpdated.addListener(async (tabId, info, tab) => {
  if (!tab.url) return;
  const url = new URL(tab.url);
  // Enables the side panel on google.com
  if (url.origin === GOOGLE_ORIGIN) {
    await chrome.sidePanel.setOptions({
      tabId,
      path: 'sidepanel.html',
      enabled: true
    });
  } else {
    // Disables the side panel on all other sites
    await chrome.sidePanel.setOptions({
      tabId,
      enabled: false
    });
  }
});

Jika pengguna beralih untuk sementara ke tab yang tidak mengaktifkan panel samping, panel samping akan disembunyikan. Tab tersebut akan otomatis ditampilkan lagi saat pengguna beralih ke tab tempat tab sebelumnya dibuka.

Jika pengguna membuka situs yang tidak mengaktifkan panel samping, panel samping akan ditutup dan ekstensinya tidak akan ditampilkan di menu drop-down panel samping.

Untuk contoh lengkapnya, lihat contoh Panel samping khusus tab.

Buka panel samping dengan mengklik ikon toolbar

Developer dapat mengizinkan pengguna membuka panel samping saat mereka mengklik ikon toolbar tindakan dengan sidePanel.setPanelBehavior(). Pertama, deklarasikan kunci "action" dalam manifes:

manifest.json:

{
  "name": "My side panel extension",
  ...
   "action": {
    "default_title": "Click to open panel"
  },
  ...
}

Sekarang, tambahkan kode ini ke contoh sebelumnya:

service-worker.js:

const GOOGLE_ORIGIN = 'https://www.google.com';

// Allows users to open the side panel by clicking on the action toolbar icon
chrome.sidePanel
  .setPanelBehavior({ openPanelOnActionClick: true })
  .catch((error) => console.error(error));
...

Membuka panel samping secara terprogram pada interaksi pengguna

Chrome 116 memperkenalkan sidePanel.open(). Fitur ini memungkinkan ekstensi membuka panel samping melalui gestur pengguna ekstensi, seperti mengklik ikon tindakan. Atau interaksi pengguna di halaman ekstensi atau skrip konten, seperti mengklik tombol. Untuk demo lengkap, lihat ekstensi contoh Buka Panel Samping.

Kode berikut menunjukkan cara membuka panel samping global di jendela saat ini saat pengguna mengklik menu konteks. Saat menggunakan sidePanel.open(), Anda harus memilih konteks yang akan dibuka. Gunakan windowId untuk membuka panel samping global. Atau, setel tabId untuk membuka panel samping hanya di tab tertentu.

service-worker.js:

chrome.runtime.onInstalled.addListener(() => {
  chrome.contextMenus.create({
    id: 'openSidePanel',
    title: 'Open side panel',
    contexts: ['all']
  });
});

chrome.contextMenus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === 'openSidePanel') {
    // This will open the panel in all the pages on the current window.
    chrome.sidePanel.open({ windowId: tab.windowId });
  }
});

Beralih ke panel lain

Ekstensi dapat menggunakan sidepanel.getOptions() untuk mengambil panel samping saat ini. Contoh berikut menetapkan panel samping selamat datang di runtime.onInstalled(). Kemudian, saat pengguna membuka tab lain, tab tersebut akan diganti dengan panel samping utama.

service-worker.js:

const welcomePage = 'sidepanels/welcome-sp.html';
const mainPage = 'sidepanels/main-sp.html';

chrome.runtime.onInstalled.addListener(() => {
  chrome.sidePanel.setOptions({ path: welcomePage });
});

chrome.tabs.onActivated.addListener(async ({ tabId }) => {
  const { path } = await chrome.sidePanel.getOptions({ tabId });
  if (path === welcomePage) {
    chrome.sidePanel.setOptions({ path: mainPage });
  }
});

Lihat Beberapa panel samping untuk melihat contoh lengkap.

Pengalaman pengguna panel samping

Pengguna akan melihat panel samping bawaan Chrome terlebih dahulu. Setiap panel samping menampilkan ikon ekstensi di menu panel samping. Jika tidak ada ikon yang disertakan, ikon placeholder dengan huruf pertama dari nama ekstensi akan ditampilkan.

Buka panel samping

Membuka menu panel samping
Pengguna dapat menemukan panel samping yang tersedia di menu panel samping. Kemudian, mereka dapat memilih ekstensi dari menu drop-down.
Menu drop-down panel samping
UI panel samping browser Chrome.
Membuka melalui gestur pengguna

Anda dapat membuka panel samping melalui interaksi pengguna menggunakan sidePanel.open() dan sidePanel.setPanelBehavior(), seperti:

Contoh

Untuk demo ekstensi Side Panel API lainnya, pelajari salah satu ekstensi berikut:

Jenis

GetPanelOptions

Properti

  • tabId

    nomor opsional

    Jika ditentukan, opsi panel samping untuk tab yang ditentukan akan ditampilkan. Jika tidak, opsi panel samping default akan ditampilkan (digunakan untuk tab apa pun yang tidak memiliki setelan tertentu).

OpenOptions

Chrome 116 dan yang lebih baru

Properti

  • tabId

    nomor opsional

    Tab tempat panel samping akan dibuka. Jika tab yang sesuai memiliki panel samping khusus tab, panel hanya akan terbuka untuk tab tersebut. Jika tidak ada panel khusus tab, panel global akan terbuka di tab yang ditentukan dan tab lain tanpa panel khusus tab yang sedang terbuka. Tindakan ini akan mengganti panel samping yang sedang aktif (global atau khusus tab) di tab yang sesuai. Setidaknya salah satunya atau windowId harus diberikan.

  • windowId

    nomor opsional

    Jendela tempat panel samping akan dibuka. Ini hanya berlaku jika ekstensi memiliki panel samping global (tidak khusus tab) atau tabId juga ditentukan. Tindakan ini akan mengganti panel samping global yang sedang aktif yang dibuka pengguna di jendela tertentu. Setidaknya salah satunya atau tabId harus diberikan.

PanelBehavior

Properti

  • openPanelOnActionClick

    boolean opsional

    Apakah mengklik ikon ekstensi akan mengalihkan tampilan entri ekstensi di panel samping. Nilai defaultnya adalah false (salah).

PanelOptions

Properti

  • diaktifkan

    boolean opsional

    Apakah panel samping harus diaktifkan. Langkah ini bersifat opsional. Nilai defaultnya adalah benar (true).

  • jalur

    string opsional

    Jalur ke file HTML panel samping yang akan digunakan. Ini harus berupa resource lokal dalam paket ekstensi.

  • tabId

    nomor opsional

    Jika ditentukan, opsi panel samping hanya akan berlaku pada tab dengan ID ini. Jika dihilangkan, opsi ini akan menetapkan perilaku default (digunakan untuk tab yang tidak memiliki setelan tertentu). Catatan: jika jalur yang sama ditetapkan untuk tabId ini dan tabId default, panel untuk tabId ini akan menjadi instance yang berbeda dengan panel untuk tabId default.

SidePanel

Properti

  • default_path

    string

    Jalur yang ditentukan developer untuk tampilan panel samping.

Metode

getOptions()

Promise 
chrome.sidePanel.getOptions(
  options: GetPanelOptions,
  callback?: function,
)

Menampilkan konfigurasi panel aktif.

Parameter

Hasil

  • Promise<PanelOptions>

    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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

getPanelBehavior()

Promise 
chrome.sidePanel.getPanelBehavior(
  callback?: function,
)

Menampilkan perilaku panel samping ekstensi saat ini.

Parameter

Hasil

  • Promise<PanelBehavior>

    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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

open()

Promise Chrome 116+ 
chrome.sidePanel.open(
  options: OpenOptions,
  callback?: function,
)

Membuka panel samping ekstensi. Ini hanya dapat dipanggil sebagai respons terhadap tindakan pengguna.

Parameter

  • Menentukan konteks untuk membuka panel samping.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    ()=>void

Hasil

  • Promise<void>

    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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

setOptions()

Promise 
chrome.sidePanel.setOptions(
  options: PanelOptions,
  callback?: function,
)

Mengonfigurasi panel samping.

Parameter

  • Opsi konfigurasi yang akan diterapkan ke panel.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    ()=>void

Hasil

  • Promise<void>

    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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

setPanelBehavior()

Promise 
chrome.sidePanel.setPanelBehavior(
  behavior: PanelBehavior,
  callback?: function,
)

Mengonfigurasi perilaku panel samping ekstensi. Ini adalah operasi pembaruan dan penyisipan.

Parameter

  • pelanggan

    PanelBehavior

    Perilaku baru yang akan ditetapkan.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    ()=>void

Hasil

  • Promise<void>

    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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.