chrome.sidePanel (original) (raw)

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" di file manifest 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

UI panel samping browser Chrome.

Beberapa fitur mencakup:

Kasus penggunaan

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

Menampilkan panel samping yang sama di setiap situs

Panel samping dapat disetel pada awalnya dari properti "default_path" di kunci "side_panel" manifes untuk menampilkan panel samping yang sama di setiap situs. Nilai 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 setiap pembaruan yang dilakukan pada tab. Kode ini memeriksa apakah URL-nya adalah www.google.com dan mengaktifkan panel samping. Jika tidak, fitur ini 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 beralih sementara ke tab yang tidak mengaktifkan panel samping, panel samping akan disembunyikan. Iklan akan otomatis ditampilkan lagi saat pengguna beralih ke tab tempat iklan dibuka sebelumnya.

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

Untuk contoh lengkap, 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 saat interaksi pengguna

Chrome 116 memperkenalkan sidePanel.open(). Hal 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 Open Side Panel.

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 saat membukanya. Gunakan windowId untuk membuka panel samping global. Atau, tetapkan tabId untuk membuka panel samping hanya pada 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 digantikan 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 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 nama ekstensi akan ditampilkan.

Membuka panel samping

Untuk mengizinkan pengguna membuka panel samping, gunakan ikon tindakan bersama dengan sidePanel.setPanelBehavior(). Atau, lakukan panggilan ke sidePanel.open() setelah interaksi pengguna, seperti:

Menyematkan panel samping

Ikon pin di UI panel samping.

Ikon sematkan di UI panel samping.

Toolbar panel samping menampilkan ikon sematkan saat panel samping Anda terbuka. Mengklik ikon akan menyematkan ikon tindakan ekstensi Anda. Mengklik ikon tindakan setelah disematkan akan menjalankan tindakan default untuk ikon tindakan Anda dan hanya akan membuka panel samping jika telah dikonfigurasi secara eksplisit.

Contoh

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

Jenis

CloseOptions

Properti

GetPanelOptions

Properti

OpenOptions

Properti

PanelBehavior

Properti

PanelClosedInfo

Properti

PanelLayout

Properti

PanelOpenedInfo

Properti

PanelOptions

Properti

Side

Menentukan kemungkinan perataan untuk panel samping di UI browser.

Enum

SidePanel

Properti

Metode

getLayout()

chrome.sidePanel.getLayout(): Promise<PanelLayout>

Menampilkan tata letak panel samping saat ini.

Hasil

getOptions()

chrome.sidePanel.getOptions(
  options: GetPanelOptions,
): Promise<PanelOptions>

Menampilkan konfigurasi panel aktif.

Parameter

Hasil

getPanelBehavior()

chrome.sidePanel.getPanelBehavior(): Promise<PanelBehavior>

Menampilkan perilaku panel samping ekstensi saat ini.

Hasil

open()

chrome.sidePanel.open(
  options: OpenOptions,
): Promise

Membuka panel samping untuk ekstensi. Metode ini hanya dapat dipanggil sebagai respons terhadap tindakan pengguna.

Parameter

Hasil

setOptions()

chrome.sidePanel.setOptions(
  options: PanelOptions,
): Promise

Mengonfigurasi panel samping.

Parameter

Hasil

setPanelBehavior()

chrome.sidePanel.setPanelBehavior(
  behavior: PanelBehavior,
): Promise

Mengonfigurasi perilaku panel samping ekstensi. Ini adalah operasi upsert.

Parameter

Hasil

Acara

onClosed

chrome.sidePanel.onClosed.addListener(
  callback: function,
)

Diaktifkan saat panel samping ekstensi ditutup.

Parameter

onOpened

chrome.sidePanel.onOpened.addListener(
  callback: function,
)

Diaktifkan saat panel samping ekstensi dibuka.

Parameter