หน้านี้ได้รับการแปลโดย 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 ขึ้นไป

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

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

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

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

แผงด้านข้างจะยังคงเปิดอยู่เมื่อไปยังแท็บต่างๆ (หากตั้งค่าไว้)
และใช้ได้กับบางเว็บไซต์เท่านั้น
ในฐานะหน้าส่วนขยาย แผงด้านข้างจะมีสิทธิ์เข้าถึง 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.tabs.onActivated.addListener(async ({ tabId }) => {
  const { path } = await chrome.sidePanel.getOptions({ tabId });
  if (path === welcomePage) {
    chrome.sidePanel.setOptions({ path: mainPage });
  }
});

ดูแผงด้านข้างหลายแผงเพื่อดูตัวอย่างทั้งหมดได้

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

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

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

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

เปิดผ่านท่าทางสัมผัสของผู้ใช้

คุณเปิดแผงด้านข้างผ่านการโต้ตอบของผู้ใช้ได้โดยใช้ sidePanel.open() และ sidePanel.setPanelBehavior() เช่น

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

ตัวอย่าง

หากต้องการดูการสาธิตส่วนขยาย API แผงด้านข้างเพิ่มเติม ให้ดูส่วนขยายต่อไปนี้

ประเภท

GetPanelOptions

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

tabId

ตัวเลข ไม่บังคับ

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

OpenOptions

Chrome 116 ขึ้นไป

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

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,
)

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

พารามิเตอร์

ตัวเลือก

GetPanelOptions

ระบุบริบทที่จะแสดงผลการกำหนดค่า
Callback

ฟังก์ชัน ไม่บังคับ

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

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

Promise<PanelOptions>

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

getPanelBehavior()

สัญญา

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

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

พารามิเตอร์

Callback

ฟังก์ชัน ไม่บังคับ

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

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

Promise<PanelBehavior>

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

open()

คำมั่นสัญญา Chrome 116 ขึ้นไป

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

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

พารามิเตอร์

ตัวเลือก

OpenOptions

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

ฟังก์ชัน ไม่บังคับ

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

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

Promise<void>

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

setOptions()

สัญญา

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

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

พารามิเตอร์

ตัวเลือก

PanelOptions

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

ฟังก์ชัน ไม่บังคับ

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

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

Promise<void>

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

setPanelBehavior()

สัญญา

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

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

พารามิเตอร์

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

PanelBehavior

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

ฟังก์ชัน ไม่บังคับ

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

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

Promise<void>

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