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
Konsep dan penggunaan
Side Panel API memungkinkan ekstensi menampilkan UI-nya sendiri di panel samping, sehingga memungkinkan pengalaman persisten yang melengkapi perjalanan penjelajahan pengguna.
![Menu drop-down panel samping](https://developer.chrome.com/static/docs/extensions/reference/api/sidePanel/images/example-side-panel.png?hl=id)
Beberapa fiturnya antara lain:
- Panel samping tetap terbuka saat beralih di antara tab (jika disetel untuk melakukannya).
- Konfigurasi ini hanya tersedia di situs tertentu.
- Sebagai halaman ekstensi, panel samping memiliki akses ke semua Chrome API.
- Dalam setelan Chrome, pengguna dapat menentukan di 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 yang lengkap.
Tampilkan panel samping yang sama di setiap situs
Awalnya, panel samping dapat disetel dari properti "default_path"
di tombol "side_panel"
manifes untuk menampilkan panel samping yang sama di setiap situs. URL ini harus 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 dibuat pada tab. Google Play Protect memeriksa apakah URL-nya www.google.com dan mengaktifkan panel samping. Jika tidak, akan dinonaktifkan.
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 sementara beralih ke tab yang tidak mengaktifkan panel samping, panel samping akan disembunyikan. Aplikasi akan otomatis ditampilkan lagi saat pengguna beralih ke tab yang sebelumnya terbuka.
Saat pengguna membuka situs yang tidak mengaktifkan panel samping, panel samping akan ditutup, dan ekstensi tidak akan muncul 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 contoh ekstensi Buka Panel Samping.
Kode berikut menunjukkan cara membuka panel samping global pada jendela saat ini saat pengguna mengklik menu konteks. Saat menggunakan sidePanel.open()
, Anda harus memilih konteks tempat konteks akan terbuka. 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 sambutan 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.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
});
chrome.tabs.onActivated.addListener(async ({ tabId }) => {
const { path } = await chrome.sidePanel.getOptions({ tabId });
if (path === welcomePage) {
chrome.sidePanel.setOptions({ path: mainPage });
}
});
Lihat contoh Beberapa panel samping untuk mengetahui kode lengkapnya.
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
Untuk memungkinkan pengguna membuka panel samping, gunakan ikon tindakan yang dikombinasikan
dengan sidePanel.setPanelBehavior()
. Atau, lakukan panggilan ke sidePanel.open()
setelah interaksi pengguna, seperti:
- Klik tindakan
- Pintasan keyboard
- Menu konteks
- Gestur pengguna di halaman ekstensi atau skrip konten.
Menyematkan panel samping
![Ikon pin di UI panel samping.](https://developer.chrome.com/static/docs/extensions/reference/api/sidePanel/images/side-panel-pin.png?hl=id)
Toolbar panel samping menampilkan ikon pin saat panel samping terbuka. Mengklik ikon tersebut akan menyematkan ikon tindakan ekstensi Anda. Mengklik ikon tindakan setelah disematkan akan melakukan tindakan default untuk ikon tindakan Anda dan hanya membuka panel samping jika ini telah dikonfigurasi secara eksplisit.
Contoh
Untuk demo ekstensi Side Panel API lainnya, pelajari salah satu ekstensi berikut:
- Panel samping kamus.
- Panel samping global.
- Beberapa panel samping.
- Buka Panel samping.
- Panel samping khusus situs.
Jenis
GetPanelOptions
Properti
-
tabId
angka opsional
Jika ditentukan, opsi panel samping untuk tab tertentu akan ditampilkan. Jika tidak, menampilkan opsi panel samping default (digunakan untuk tab apa pun yang tidak memiliki setelan tertentu).
OpenOptions
Properti
-
tabId
angka opsional
Tab untuk membuka panel samping. 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 lainnya tanpa panel khusus tab yang saat ini terbuka. Tindakan ini akan mengganti panel samping yang saat ini aktif (khusus global atau tab) di tab yang sesuai. Setidaknya salah satunya atau
windowId
harus diberikan. -
windowId
angka opsional
Jendela tempat membuka panel samping. Hal ini hanya berlaku jika ekstensi memiliki panel samping global (tidak khusus tab) atau
tabId
juga ditentukan. Tindakan ini akan mengganti panel samping global yang saat ini aktif yang dibuka pengguna di jendela tertentu. Setidaknya salah satunya atautabId
harus diberikan.
PanelBehavior
Properti
-
openPanelOnActionClick
boolean opsional
Apakah mengklik ikon ekstensi akan menampilkan entri ekstensi di panel samping. Nilai defaultnya adalah false (salah).
PanelOptions
Properti
-
diaktifkan
boolean opsional
Apakah panel samping harus diaktifkan atau tidak. Langkah ini bersifat opsional. Nilai defaultnya adalah true (benar).
-
jalur
string opsional
Jalur ke file HTML panel samping yang akan digunakan. Harus berupa resource lokal dalam paket ekstensi.
-
tabId
angka opsional
Jika ditentukan, opsi panel samping hanya akan berlaku untuk tab dengan ID ini. Jika dihilangkan, opsi ini menetapkan perilaku default (digunakan untuk tab apa pun yang tidak memiliki setelan khusus). Catatan: jika jalur yang sama ditetapkan untuk tabId dan tabId default, panel untuk tabId ini akan menjadi instance yang berbeda dari panel untuk tabId default.
SidePanel
Properti
-
default_path
string
Jalur yang ditentukan developer untuk tampilan panel samping.
Metode
getOptions()
chrome.sidePanel.getOptions(
options: GetPanelOptions,
callback?: function,
)
Menampilkan konfigurasi panel aktif.
Parameter
-
opsi
Menentukan konteks untuk menampilkan konfigurasi.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:(options: PanelOptions) => void
-
opsi
-
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. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
getPanelBehavior()
chrome.sidePanel.getPanelBehavior(
callback?: function,
)
Menampilkan perilaku panel samping ekstensi saat ini.
Parameter
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:(behavior: PanelBehavior) => void
-
pelanggan
-
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. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
open()
chrome.sidePanel.open(
options: OpenOptions,
callback?: function,
)
Membuka panel samping untuk ekstensi. Fungsi ini hanya dapat dipanggil sebagai respons atas tindakan pengguna.
Parameter
-
opsi
Menentukan konteks untuk membuka panel samping.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:() => void
Hasil
-
Janji<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. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
setOptions()
chrome.sidePanel.setOptions(
options: PanelOptions,
callback?: function,
)
Mengonfigurasi panel samping.
Parameter
-
opsi
Opsi konfigurasi yang akan diterapkan ke panel.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:() => void
Hasil
-
Janji<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. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
setPanelBehavior()
chrome.sidePanel.setPanelBehavior(
behavior: PanelBehavior,
callback?: function,
)
Mengonfigurasi perilaku panel samping ekstensi. Ini adalah operasi pembaruan dan penyisipan.
Parameter
-
pelanggan
Perilaku baru yang akan ditetapkan.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:() => void
Hasil
-
Janji<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. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.