คำอธิบาย
ใช้ chrome.sidePanel
API เพื่อโฮสต์เนื้อหาในแผงด้านข้างของเบราว์เซอร์ควบคู่ไปกับเนื้อหาหลักของหน้าเว็บ
สิทธิ์
sidePanel
หากต้องการใช้ Side Panel API ให้เพิ่มสิทธิ์ "sidePanel"
ในไฟล์ Manifest ของนามสกุล ดังนี้
manifest.json:
{
"name": "My side panel extension",
...
"permissions": [
"sidePanel"
]
}
ความพร้อมใช้งาน
แนวคิดและการใช้งาน
Side Panel API ช่วยให้ส่วนขยายแสดง UI ของตัวเองในแผงด้านข้าง ซึ่งจะช่วยเสริมประสบการณ์การท่องเว็บของผู้ใช้ได้อย่างต่อเนื่อง
![เมนูแบบเลื่อนลงของแผงด้านข้าง](https://developer.chrome.google.cn/static/docs/extensions/reference/api/sidePanel/images/example-side-panel.png?authuser=9&hl=th)
ฟีเจอร์บางอย่างมีดังนี้
- แผงด้านข้างจะยังคงเปิดอยู่เมื่อไปยังแท็บต่างๆ (หากตั้งค่าไว้)
- และใช้ได้กับบางเว็บไซต์เท่านั้น
- ในฐานะหน้าส่วนขยาย แผงด้านข้างจะมีสิทธิ์เข้าถึง API ของ Chrome ทั้งหมด
- ในการตั้งค่าของ Chrome ผู้ใช้สามารถระบุได้ว่าควรแสดงแผงในด้านใด
Use Case
ส่วนต่อไปนี้จะแสดงกรณีการใช้งานทั่วไปสำหรับ 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()
ช่วยให้ส่วนขยายเปิดแผงด้านข้างผ่านท่าทางสัมผัสของผู้ใช้ของส่วนขยายได้ เช่น การคลิกที่ไอคอนการทำงาน หรือการโต้ตอบของผู้ใช้บนหน้าส่วนขยายหรือสคริปต์เนื้อหา เช่น การคลิกปุ่ม หากต้องการดูการสาธิตทั้งหมด ให้ไปที่ส่วนขยายตัวอย่าง Open Side Panel
โค้ดต่อไปนี้แสดงวิธีเปิดแผงด้านข้างส่วนกลางในหน้าต่างปัจจุบันเมื่อผู้ใช้คลิกที่เมนูตามบริบท เมื่อใช้ 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()
หลังการโต้ตอบของผู้ใช้ เช่น
- การคลิกดำเนินการ
- แป้นพิมพ์ลัด
- เมนูตามบริบท
- ท่าทางสัมผัสของผู้ใช้ในหน้าส่วนขยายหรือสคริปต์เนื้อหา
ปักหมุดแผงด้านข้าง
![ไอคอนปักหมุดใน UI ของแผงด้านข้าง](https://developer.chrome.google.cn/static/docs/extensions/reference/api/sidePanel/images/side-panel-pin.png?authuser=9&hl=th)
แถบเครื่องมือแผงด้านข้างจะแสดงไอคอนหมุดเมื่อแผงด้านข้างเปิดอยู่ การคลิกที่ไอคอนจะเป็นการปักหมุดไอคอนการทำงานของส่วนขยาย เมื่อคลิกไอคอนการทำงานเมื่อปักหมุดไว้ ระบบจะดำเนินการเริ่มต้นสำหรับไอคอนการทำงานของคุณ และจะเปิดแผงด้านข้างเมื่อมีการกำหนดค่าไว้อย่างชัดแจ้งเท่านั้น
ตัวอย่าง
หากต้องการดูการสาธิตส่วนขยาย API แผงด้านข้างเพิ่มเติม ให้ดูส่วนขยายต่อไปนี้
- แผงด้านข้างของพจนานุกรม
- แผงด้านข้างส่วนกลาง
- แผงด้านข้างหลายแผง
- เปิดแผงด้านข้าง
- แผงด้านข้างเฉพาะเว็บไซต์
ประเภท
GetPanelOptions
พร็อพเพอร์ตี้
-
tabId
ตัวเลข ไม่บังคับ
หากระบุไว้ ระบบจะแสดงตัวเลือกแผงด้านข้างของแท็บที่ระบุ หรือจะแสดงตัวเลือกแผงด้านข้างเริ่มต้น (ใช้สำหรับแท็บที่ไม่มีการตั้งค่าที่เฉพาะเจาะจง)
OpenOptions
พร็อพเพอร์ตี้
-
tabId
ตัวเลข ไม่บังคับ
แท็บที่จะเปิดแผงด้านข้าง หากแท็บที่เกี่ยวข้องมีแผงด้านข้างเฉพาะแท็บ แผงจะเปิดเฉพาะสำหรับแท็บนั้น หากไม่มีแผงเฉพาะแท็บ แผงส่วนกลางจะเปิดในแท็บที่ระบุและแท็บอื่นๆ ที่ไม่มีแผงเฉพาะแท็บที่เปิดอยู่ ซึ่งจะลบล้างแผงด้านข้างที่ใช้งานอยู่ในปัจจุบัน (เฉพาะส่วนกลางหรือเฉพาะแท็บ) ในแท็บที่เกี่ยวข้อง ต้องระบุข้อมูลนี้หรือ
windowId
อย่างน้อย 1 รายการ -
windowId
ตัวเลข ไม่บังคับ
หน้าต่างสำหรับเปิดแผงด้านข้าง วิธีนี้จะใช้ได้เฉพาะเมื่อส่วนขยายมีแผงด้านข้าง (ไม่มีแท็บเฉพาะ) ส่วนกลางหรือมีการระบุ
tabId
ด้วย การดำเนินการนี้จะลบล้างแผงด้านข้างที่ใช้งานอยู่ในปัจจุบันซึ่งผู้ใช้เปิดในหน้าต่างที่กำหนดให้ ต้องระบุข้อมูลนี้หรือtabId
อย่างน้อย 1 รายการ
PanelBehavior
พร็อพเพอร์ตี้
-
openPanelOnActionClick
บูลีน ไม่บังคับ
การคลิกที่ไอคอนส่วนขยายจะเป็นการเปิด/ปิดการแสดงรายการส่วนขยายในแผงด้านข้างหรือไม่ ค่าเริ่มต้นคือ "เท็จ"
PanelOptions
พร็อพเพอร์ตี้
-
เปิดใช้อยู่
บูลีน ไม่บังคับ
ควรเปิดใช้แผงด้านข้างหรือไม่ ขั้นตอนนี้ไม่บังคับ ค่าเริ่มต้นคือ true
-
เส้นทาง
string ไม่บังคับ
เส้นทางไปยังไฟล์ HTML ของแผงด้านข้างเพื่อใช้งาน ซึ่งต้องเป็นทรัพยากรในเครื่องภายในแพ็กเกจส่วนขยาย
-
tabId
ตัวเลข ไม่บังคับ
หากระบุไว้ ตัวเลือกแผงด้านข้างจะมีผลกับแท็บที่มีรหัสนี้เท่านั้น หากละไว้ ตัวเลือกเหล่านี้จะกำหนดลักษณะการทํางานเริ่มต้น (ใช้สำหรับแท็บที่ไม่มีการตั้งค่าที่เฉพาะเจาะจง) หมายเหตุ: หากตั้งค่าเส้นทางเดียวกันสำหรับ TabId นี้และรหัสแท็บเริ่มต้น แผงสำหรับรหัสแท็บนี้จะต่างจากแผงสำหรับรหัสแท็บเริ่มต้น
SidePanel
พร็อพเพอร์ตี้
-
default_path
string
เส้นทางที่นักพัฒนาแอประบุสำหรับการแสดงแผงด้านข้าง
วิธีการ
getOptions()
chrome.sidePanel.getOptions(
options: GetPanelOptions,
callback?: function,
)
แสดงผลการกำหนดค่าแผงที่ใช้งานอยู่
พารามิเตอร์
-
ตัวเลือก
ระบุบริบทที่จะแสดงผลการกำหนดค่า
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้(options: PanelOptions) => void
-
ตัวเลือก
-
การคืนสินค้า
-
Promise<PanelOptions>
Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ
getPanelBehavior()
chrome.sidePanel.getPanelBehavior(
callback?: function,
)
แสดงลักษณะการทำงานของแผงด้านข้างในปัจจุบันของส่วนขยาย
พารามิเตอร์
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้(behavior: PanelBehavior) => void
-
ประโยชน์จากผู้อื่น
-
การคืนสินค้า
-
Promise<PanelBehavior>
Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ
open()
chrome.sidePanel.open(
options: OpenOptions,
callback?: function,
)
เปิดแผงด้านข้างสำหรับส่วนขยาย โดยจะเรียกใช้เพื่อตอบสนองต่อการดำเนินการของผู้ใช้เท่านั้น
พารามิเตอร์
-
ตัวเลือก
ระบุบริบทที่จะเปิดแผงด้านข้าง
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้() => void
การคืนสินค้า
-
Promise<void>
Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ
setOptions()
chrome.sidePanel.setOptions(
options: PanelOptions,
callback?: function,
)
กำหนดค่าแผงด้านข้าง
พารามิเตอร์
-
ตัวเลือก
ตัวเลือกการกำหนดค่าที่จะใช้กับแผงนี้
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้() => void
การคืนสินค้า
-
Promise<void>
Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ
setPanelBehavior()
chrome.sidePanel.setPanelBehavior(
behavior: PanelBehavior,
callback?: function,
)
กำหนดค่าลักษณะการทำงานของแผงด้านข้างของส่วนขยาย นี่คือการดำเนินการ Upsert
พารามิเตอร์
-
ประโยชน์จากผู้อื่น
ลักษณะการทำงานใหม่ที่จะตั้งค่า
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้() => void
การคืนสินค้า
-
Promise<void>
Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ