คำอธิบาย
ใช้ chrome.sidePanel API เพื่อโฮสต์เนื้อหาในแผงด้านข้างของเบราว์เซอร์ควบคู่ไปกับเนื้อหาหลักของหน้าเว็บ
สิทธิ์
sidePanelหากต้องการใช้ Side Panel API ให้เพิ่มสิทธิ์ "sidePanel" ในไฟล์ manifest ของส่วนขยาย
manifest.json:
{ "name": "My side panel extension", ... "permissions": [ "sidePanel" ] } ความพร้อมใช้งาน
แนวคิดและการใช้งาน
Side Panel API ช่วยให้ส่วนขยายแสดง UI ของตัวเองในแผงด้านข้างได้ ซึ่งจะช่วยให้ผู้ใช้ได้รับประสบการณ์การใช้งานที่ต่อเนื่องซึ่งเสริมเส้นทางการท่องเว็บของผู้ใช้
ฟีเจอร์บางอย่างมีดังนี้
- แผงด้านข้างจะยังคงเปิดอยู่เมื่อไปยังส่วนต่างๆ ของแท็บ (หากตั้งค่าไว้)
- โดยอาจใช้ได้ในบางเว็บไซต์เท่านั้น
- แผงด้านข้างในฐานะหน้าส่วนขยายจะมีสิทธิ์เข้าถึง 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() หลังจากที่ผู้ใช้โต้ตอบ เช่น
- คลิกการกระทำ
- แป้นพิมพ์ลัด
- เมนูตามบริบท
- ท่าทางของผู้ใช้ในหน้าส่วนขยายหรือ Content Script
ปักหมุดแผงด้านข้าง
แถบเครื่องมือแผงด้านข้างจะแสดงไอคอนหมุดเมื่อแผงด้านข้างเปิดอยู่ การคลิกไอคอนจะเป็นการปักหมุดไอคอนการดำเนินการของส่วนขยาย การคลิกไอคอนการดำเนินการเมื่อปักหมุดแล้วจะดำเนินการเริ่มต้นสำหรับไอคอนการดำเนินการ และจะเปิดแผงด้านข้างก็ต่อเมื่อมีการกำหนดค่าอย่างชัดเจนเท่านั้น
ตัวอย่าง
หากต้องการดูการสาธิตส่วนขยาย Side Panel API เพิ่มเติม ให้สำรวจส่วนขยายต่อไปนี้
- แผงด้านข้างของพจนานุกรม
- แผงด้านข้างส่วนกลาง
- แผงด้านข้างหลายแผง
- เปิดแผงด้านข้าง
- แผงด้านข้างเฉพาะเว็บไซต์
ประเภท
CloseOptions
พร็อพเพอร์ตี้
- tabId
หมายเลข ไม่บังคับ
แท็บที่จะปิดแผงด้านข้าง หากแผงด้านข้างเฉพาะแท็บเปิดอยู่ในแท็บที่ระบุ ระบบจะปิดแผงด้านข้างสำหรับแท็บนั้น ต้องระบุข้อมูลนี้หรือ
windowIdอย่างน้อย 1 รายการ - windowId
หมายเลข ไม่บังคับ
หน้าต่างที่จะปิดแผงด้านข้าง หากแผงด้านข้างส่วนกลางเปิดอยู่ในหน้าต่างที่ระบุ ระบบจะปิดแผงดังกล่าวสำหรับแท็บทั้งหมดในหน้าต่างนั้นซึ่งไม่มีแผงเฉพาะแท็บที่ใช้งานอยู่ ต้องระบุข้อมูลนี้หรือ
tabIdอย่างน้อย 1 รายการ
GetPanelOptions
พร็อพเพอร์ตี้
- tabId
หมายเลข ไม่บังคับ
หากระบุไว้ ระบบจะแสดงตัวเลือกแผงด้านข้างสำหรับแท็บที่ระบุ มิฉะนั้นจะแสดงตัวเลือกแผงด้านข้างเริ่มต้น (ใช้กับแท็บที่ไม่มีการตั้งค่าเฉพาะ)
OpenOptions
พร็อพเพอร์ตี้
- tabId
หมายเลข ไม่บังคับ
แท็บที่จะเปิดแผงด้านข้าง หากแท็บที่เกี่ยวข้องมีแผงด้านข้างเฉพาะแท็บ แผงจะเปิดเฉพาะแท็บนั้น หากไม่มีแผงเฉพาะแท็บ ระบบจะเปิดแผงส่วนกลางในแท็บที่ระบุและแท็บอื่นๆ ที่ไม่มีแผงเฉพาะแท็บที่เปิดอยู่ในปัจจุบัน การดำเนินการนี้จะลบล้างแผงด้านข้างที่ใช้งานอยู่ในปัจจุบัน (ส่วนกลางหรือเฉพาะแท็บ) ในแท็บที่เกี่ยวข้อง ต้องระบุข้อมูลนี้หรือ
windowIdอย่างน้อย 1 รายการ - windowId
หมายเลข ไม่บังคับ
หน้าต่างที่จะเปิดแผงด้านข้าง ซึ่งจะมีผลก็ต่อเมื่อส่วนขยายมีแผงด้านข้างแบบทั่วโลก (ไม่ใช่เฉพาะแท็บ) หรือมีการระบุ
tabIdด้วย การดำเนินการนี้จะลบล้างแผงด้านข้างส่วนกลางที่ใช้งานอยู่ในปัจจุบันซึ่งผู้ใช้เปิดไว้ในหน้าต่างที่ระบุ ต้องระบุข้อมูลนี้หรือtabIdอย่างน้อย 1 รายการ
PanelBehavior
พร็อพเพอร์ตี้
- openPanelOnActionClick
บูลีน ไม่บังคับ
การคลิกไอคอนของส่วนขยายจะสลับการแสดงรายการของส่วนขยายในแผงด้านข้างหรือไม่ ค่าเริ่มต้นคือ false
PanelLayout
พร็อพเพอร์ตี้
- ด้านข้าง
PanelOptions
พร็อพเพอร์ตี้
- เปิดใช้อยู่
บูลีน ไม่บังคับ
ควรเปิดใช้แผงด้านข้างไหม ขั้นตอนนี้ไม่บังคับ ค่าเริ่มต้นคือ True
- เส้นทาง
สตริง ไม่บังคับ
เส้นทางไปยังไฟล์ HTML ของแผงด้านข้างที่จะใช้ โดยต้องเป็นทรัพยากรในเครื่องภายในแพ็กเกจส่วนขยาย
- tabId
หมายเลข ไม่บังคับ
หากระบุไว้ ตัวเลือกแผงด้านข้างจะมีผลกับแท็บที่มีรหัสนี้เท่านั้น หากละไว้ ตัวเลือกเหล่านี้จะตั้งค่าลักษณะการทำงานเริ่มต้น (ใช้กับแท็บที่ไม่มีการตั้งค่าเฉพาะ) หมายเหตุ: หากตั้งค่าเส้นทางเดียวกันสำหรับ tabId นี้และ tabId เริ่มต้น แผงสำหรับ tabId นี้จะเป็นอินสแตนซ์ที่แตกต่างจากแผงสำหรับ tabId เริ่มต้น
Side
กำหนดการจัดแนวที่เป็นไปได้สำหรับแผงด้านข้างใน UI ของเบราว์เซอร์
ค่าแจกแจง
"left"
"right"
SidePanel
พร็อพเพอร์ตี้
- default_path
สตริง
เส้นทางที่นักพัฒนาแอปกำหนดสำหรับการแสดงแผงด้านข้าง
เมธอด
getLayout()
chrome.sidePanel.getLayout(): Promise<PanelLayout>
แสดงผลเลย์เอาต์ปัจจุบันของแผงด้านข้าง
การคืนสินค้า
-
Promise<PanelLayout>
getOptions()
chrome.sidePanel.getOptions(
options: GetPanelOptions,
): Promise<PanelOptions>
แสดงผลการกำหนดค่าแผงที่ใช้งานอยู่
พารามิเตอร์
- ตัวเลือก
ระบุบริบทที่จะส่งคืนการกำหนดค่า
การคืนสินค้า
-
Promise<PanelOptions>
getPanelBehavior()
chrome.sidePanel.getPanelBehavior(): Promise<PanelBehavior>
แสดงผลลักษณะการทำงานของแผงด้านข้างปัจจุบันของส่วนขยาย
การคืนสินค้า
-
Promise<PanelBehavior>
open()
chrome.sidePanel.open(
options: OpenOptions,
): Promise<void>
เปิดแผงด้านข้างสำหรับส่วนขยาย ซึ่งจะเรียกใช้ได้ก็ต่อเมื่อเป็นการตอบสนองต่อการกระทำของผู้ใช้เท่านั้น
พารามิเตอร์
- ตัวเลือก
ระบุบริบทที่จะเปิดแผงด้านข้าง
การคืนสินค้า
-
Promise<void>
setOptions()
chrome.sidePanel.setOptions(
options: PanelOptions,
): Promise<void>
กำหนดค่าแผงด้านข้าง
พารามิเตอร์
- ตัวเลือก
ตัวเลือกการกำหนดค่าที่จะใช้กับแผง
การคืนสินค้า
-
Promise<void>
setPanelBehavior()
chrome.sidePanel.setPanelBehavior(
behavior: PanelBehavior,
): Promise<void>
กำหนดค่าลักษณะการทำงานของแผงด้านข้างของส่วนขยาย นี่คือการดำเนินการ upsert
พารามิเตอร์
- ประโยชน์จากผู้อื่น
ลักษณะการทำงานใหม่ที่จะตั้งค่า
การคืนสินค้า
-
Promise<void>