หน้านี้ได้รับการแปลโดย Cloud Translation API

chrome.sidePanel

คำอธิบาย

ใช้ chrome.sidePanel API เพื่อโฮสต์เนื้อหาในแผงด้านข้างของเบราว์เซอร์ควบคู่ไปกับเนื้อหาหลักของหน้าเว็บ

สิทธิ์

sidePanel

หากต้องการใช้ Side Panel API ให้เพิ่มสิทธิ์ "sidePanel" ในไฟล์ Manifest ส่วนขยาย ดังนี้

manifest.json:

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

ความพร้อมใช้งาน

Chrome 114 ขึ้นไป MV3 ขึ้นไป

แนวคิดและการใช้งาน

API แผงด้านข้างช่วยให้ส่วนขยายแสดง UI ของตนเองในแผงด้านข้าง ทำให้เกิดประสบการณ์ที่ต่อเนื่องซึ่งช่วยส่งเสริมเส้นทางการท่องเว็บของผู้ใช้

เมนูแบบเลื่อนลงของแผงด้านข้าง — UI แผงด้านข้างของเบราว์เซอร์ Chrome

ฟีเจอร์บางอย่างมีดังนี้

แผงด้านข้างจะยังคงเปิดอยู่เมื่อไปยังแท็บต่างๆ (หากตั้งค่าไว้ให้เปิด)
โดยจะใช้ได้ในบางเว็บไซต์เท่านั้น
แผงด้านข้างมีสิทธิ์เข้าถึง Chrome API ทั้งหมดในฐานะหน้าส่วนขยาย
ภายในการตั้งค่าของ Chrome ผู้ใช้สามารถระบุด้านที่จะแสดงแผงได้

กรณีการใช้งาน

ส่วนต่อไปนี้จะแสดงกรณีการใช้งานทั่วไปสําหรับ Side Panel API ดูตัวอย่างส่วนขยายสำหรับตัวอย่างส่วนขยายที่สมบูรณ์

แสดงแผงด้านข้างเดียวกันในทุกเว็บไซต์

ตอนแรกคุณสามารถตั้งแผงด้านข้างจากคุณสมบัติ "default_path" ในคีย์ "side_panel" ของไฟล์ Manifest เพื่อแสดงแผงด้านข้างเดียวกันในทุกเว็บไซต์ ซึ่งควรชี้ไปยังเส้นทางที่เกี่ยวข้องภายในไดเรกทอรีส่วนขยาย

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>

เปิดใช้แผงด้านข้างในเว็บไซต์ที่เจาะจง

ส่วนขยายสามารถใช้ sidepanel.setOptions() เพื่อเปิดใช้แผงด้านข้างในแท็บเฉพาะ ตัวอย่างนี้ใช้ chrome.tabs.onUpdated() เพื่อฟังการอัปเดตในแท็บดังกล่าว โดยจะตรวจสอบว่า URL คือ www.google.com หรือไม่และเปิดใช้แผงด้านข้าง มิฉะนั้นจะเป็นการปิดใช้

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
    });
  }
});

เมื่อผู้ใช้เปลี่ยนไปยังแท็บที่ไม่ได้เปิดใช้แผงด้านข้างชั่วคราว ระบบจะซ่อนแผงด้านข้าง และจะแสดงอีกครั้งโดยอัตโนมัติเมื่อผู้ใช้สลับไปยังแท็บที่เคยเปิดไว้ก่อนหน้านี้

เมื่อผู้ใช้ไปยังเว็บไซต์ที่ไม่ได้เปิดใช้แผงด้านข้าง แผงด้านข้างจะปิดและส่วนขยายจะไม่แสดงในเมนูแบบเลื่อนลงของแผงด้านข้าง

ดูตัวอย่างที่สมบูรณ์ได้จากตัวอย่างแผงด้านข้างเฉพาะแท็บ

เปิดแผงด้านข้างโดยคลิกไอคอนแถบเครื่องมือ

นักพัฒนาแอปอนุญาตให้ผู้ใช้เปิดแผงด้านข้างเมื่อคลิกไอคอนแถบเครื่องมือการดำเนินการที่มี sidePanel.setPanelBehavior() ได้ ก่อนอื่นให้ประกาศคีย์ "action" ในไฟล์ Manifest

manifest.json:

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

จากนั้นเพิ่มโค้ดนี้ลงในตัวอย่างก่อนหน้านี้

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));
...

เปิดแผงด้านข้างแบบเป็นโปรแกรมเมื่อโต้ตอบกับผู้ใช้

Chrome 116 ขอแนะนำ sidePanel.open() ทำให้ส่วนขยายเปิดแผงด้านข้างผ่านท่าทางสัมผัสของผู้ใช้ส่วนขยายได้ เช่น การคลิกที่ไอคอนการทำงาน หรือการโต้ตอบของผู้ใช้ในหน้าส่วนขยายหรือสคริปต์เนื้อหา เช่น การคลิกปุ่ม ดูตัวอย่างที่สมบูรณ์จากส่วนขยายตัวอย่างเปิดแผงด้านข้าง

โค้ดต่อไปนี้แสดงวิธีเปิดแผงด้านข้างส่วนกลางในหน้าต่างปัจจุบันเมื่อผู้ใช้คลิกที่เมนูตามบริบท เมื่อใช้ sidePanel.open() คุณต้องเลือกบริบทที่ควรจะเปิดขึ้น ใช้ windowId เพื่อเปิดแผงด้านข้างส่วนกลาง อีกวิธีหนึ่งคือตั้งค่า tabId ให้เปิดแผงด้านข้างเฉพาะในแท็บที่ต้องการ

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 });
  }
});

เปลี่ยนไปใช้แผงอื่น

ส่วนขยายสามารถใช้ sidepanel.getOptions() เพื่อดึงข้อมูลแผงด้านข้างปัจจุบัน ตัวอย่างต่อไปนี้ตั้งค่าแผงด้านข้างสำหรับต้อนรับใน runtime.onInstalled() จากนั้นเมื่อผู้ใช้ไปยังแท็บอื่น แท็บนั้นจะแทนที่ด้วยแผงด้านข้างหลัก

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 });
  }
});

ดูตัวอย่างโค้ดทั้งหมดได้จากตัวอย่างแผงด้านข้างหลายแผง

ประสบการณ์ของผู้ใช้แผงด้านข้าง

ผู้ใช้จะเห็นแผงด้านข้างในตัวของ Chrome ก่อน แผงด้านข้างแต่ละแผงจะแสดงไอคอนของส่วนขยายในเมนูแผงด้านข้าง หากไม่ได้รวมไอคอนไว้ ไอคอนจะแสดงตัวยึดตำแหน่งที่มีอักษรตัวแรกของชื่อส่วนขยาย

เปิดแผงด้านข้าง

หากต้องการอนุญาตให้ผู้ใช้เปิดแผงด้านข้าง ให้ใช้ไอคอนการดำเนินการร่วมกัน ด้วย sidePanel.setPanelBehavior() หรือโทรหา sidePanel.open() ตามการโต้ตอบของผู้ใช้ เช่น

การคลิกการกระทำ
แป้นพิมพ์ลัด
เมนูตามบริบท
ท่าทางสัมผัสของผู้ใช้บนหน้าส่วนขยายหรือสคริปต์เนื้อหา

ปักหมุดแผงด้านข้าง

แถบเครื่องมือแผงด้านข้างจะแสดงไอคอนหมุดเมื่อแผงด้านข้างเปิดอยู่ การคลิกไอคอนจะปักหมุดไอคอนการทำงานของส่วนขยาย คลิกไอคอนการทำงาน เมื่อปักหมุดไว้ จะมีการดำเนินการเริ่มต้นสำหรับไอคอนการดำเนินการ และจะ เปิดแผงด้านข้างหากมีการกำหนดค่าไว้อย่างชัดแจ้ง

ตัวอย่าง

หากต้องการดูการสาธิตส่วนขยาย Side Panel API เพิ่มเติม ให้สำรวจส่วนขยายใดก็ได้ต่อไปนี้

ประเภท

GetPanelOptions

พร็อพเพอร์ตี้

tabId

หมายเลข ไม่บังคับ

หากระบุไว้ ระบบจะแสดงผลตัวเลือกแผงด้านข้างของแท็บที่กำหนด มิเช่นนั้น ก็จะแสดงตัวเลือกแผงด้านข้างเริ่มต้น (ใช้สำหรับแท็บที่ไม่มีการตั้งค่าเฉพาะ)

OpenOptions

Chrome 116 ขึ้นไป

พร็อพเพอร์ตี้

tabId

หมายเลข ไม่บังคับ

แท็บที่จะเปิดแผงด้านข้าง หากแท็บที่เกี่ยวข้องมีแผงด้านข้างเฉพาะแท็บ แผงจะเปิดขึ้นเฉพาะสำหรับแท็บนั้น หากไม่มีแผงเฉพาะแท็บ แผงส่วนกลางจะเปิดในแท็บที่ระบุและแท็บอื่นๆ โดยไม่มีแผงเฉพาะแท็บที่เปิดอยู่ในขณะนี้ การดำเนินการนี้จะลบล้างแผงด้านข้างที่ใช้งานอยู่ (ทั่วโลกหรือเฉพาะแท็บ) ในแท็บที่เกี่ยวข้อง ต้องระบุอย่างน้อย 1 รายการหรือ windowId
windowId

หมายเลข ไม่บังคับ

หน้าต่างที่จะเปิดแผงด้านข้าง ซึ่งจะใช้ได้เมื่อส่วนขยายมีแผงด้านข้างแบบส่วนกลาง (ไม่มีแท็บ) หรือมีการระบุ tabId ด้วยเท่านั้น การทำเช่นนี้จะลบล้างแผงด้านข้างร่วมที่มีการใช้งานอยู่ทั้งหมดที่ผู้ใช้เปิดในหน้าต่างที่กำหนด ต้องระบุอย่างน้อย 1 รายการหรือ tabId

PanelBehavior

พร็อพเพอร์ตี้

openPanelOnActionClick

บูลีน ไม่บังคับ

การคลิกที่ไอคอนของส่วนขยายจะเป็นการสลับการแสดงรายการของส่วนขยายในแผงด้านข้างหรือไม่ ค่าเริ่มต้นคือ "เท็จ"

PanelOptions

พร็อพเพอร์ตี้

เปิดใช้อยู่

บูลีน ไม่บังคับ

ควรเปิดใช้แผงด้านข้างไหม ขั้นตอนนี้ไม่บังคับ ค่าเริ่มต้นคือ true
เส้นทาง

string ไม่บังคับ

เส้นทางไปยังไฟล์ HTML ของแผงด้านข้างที่จะใช้ ต้องเป็นทรัพยากรในเครื่องภายในแพ็กเกจส่วนขยาย
tabId

หมายเลข ไม่บังคับ

หากระบุไว้ ตัวเลือกแผงด้านข้างจะมีผลกับแท็บที่มีรหัสนี้เท่านั้น หากละไว้ ตัวเลือกเหล่านี้จะกำหนดลักษณะการทำงานเริ่มต้น (ใช้สำหรับแท็บที่ไม่มีการตั้งค่าเฉพาะ) หมายเหตุ: หากมีการตั้งค่าเส้นทางเดียวกันสําหรับ TabId นี้และ TabId เริ่มต้น แผงสําหรับ TabId นี้จะต่างจากแผงสําหรับ TabId เริ่มต้น

SidePanel

พร็อพเพอร์ตี้

default_path

สตริง

เส้นทางที่แสดงโดยนักพัฒนาแอปสำหรับการแสดงแผงด้านข้าง

เมธอด

getOptions()

สัญญา

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

แสดงผลการกำหนดค่าแผงที่ใช้งานอยู่

พารามิเตอร์

ตัวเลือก

GetPanelOptions

ระบุบริบทที่ต้องการส่งกลับการกำหนดค่า
Callback

ไม่บังคับ

พารามิเตอร์ callback มีลักษณะดังนี้
```
(options: PanelOptions) => void
```
- ตัวเลือก
  
  PanelOptions

การคืนสินค้า

Promise<PanelOptions>

รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback

getPanelBehavior()

สัญญา

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

แสดงลักษณะการทำงานของแผงด้านข้างปัจจุบันของส่วนขยาย

พารามิเตอร์

Callback

ไม่บังคับ

พารามิเตอร์ callback มีลักษณะดังนี้
```
(behavior: PanelBehavior) => void
```
- ประโยชน์จากผู้อื่น
  
  PanelBehavior

การคืนสินค้า

Promise<PanelBehavior>

รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback

open()

สัญญา Chrome 116 ขึ้นไป

chrome.sidePanel.open(
  options: OpenOptions,
  callback?: function,
)

เปิดแผงด้านข้างของส่วนขยาย สามารถเรียกใช้เพื่อตอบสนองต่อการดำเนินการของผู้ใช้เท่านั้น

พารามิเตอร์

ตัวเลือก

OpenOptions

ระบุบริบทที่จะเปิดแผงด้านข้าง
Callback

ไม่บังคับ

พารามิเตอร์ callback มีลักษณะดังนี้
```
() => void
```

การคืนสินค้า

คำมั่นสัญญา<โมฆะ>

รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback

setOptions()

สัญญา

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

กําหนดค่าแผงด้านข้าง

พารามิเตอร์

ตัวเลือก

PanelOptions

ตัวเลือกการกำหนดค่าที่จะใช้กับแผง
Callback

ไม่บังคับ

พารามิเตอร์ callback มีลักษณะดังนี้
```
() => void
```

การคืนสินค้า

คำมั่นสัญญา<โมฆะ>

รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback

setPanelBehavior()

สัญญา

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

กำหนดค่าลักษณะการทำงานของแผงด้านข้างของส่วนขยาย นี่คือการดำเนินการที่สูงขึ้น

พารามิเตอร์

ประโยชน์จากผู้อื่น

PanelBehavior

ลักษณะการทำงานใหม่ที่จะตั้งค่า
Callback

ไม่บังคับ

พารามิเตอร์ callback มีลักษณะดังนี้
```
() => void
```

การคืนสินค้า

คำมั่นสัญญา<โมฆะ>

รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback