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

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

  • แผงด้านข้างจะยังคงเปิดอยู่เมื่อไปยังส่วนต่างๆ ของแท็บ (หากตั้งค่าไว้)
  • โดยอาจใช้ได้เฉพาะในบางเว็บไซต์
  • แผงด้านข้างในฐานะหน้าส่วนขยายจะมีสิทธิ์เข้าถึง 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() หลังจากที่ผู้ใช้โต้ตอบ เช่น

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

ไอคอนปักหมุดใน UI ของแผงด้านข้าง
ปักหมุดไอคอนใน UI ของแผงด้านข้าง

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

ตัวอย่าง

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

ประเภท

CloseOptions

Chrome 141 ขึ้นไป

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

  • tabId

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

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

  • windowId

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

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

GetPanelOptions

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

  • tabId

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

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

OpenOptions

Chrome 116 ขึ้นไป

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

  • tabId

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

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

  • windowId

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

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

PanelBehavior

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

  • openPanelOnActionClick

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

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

PanelClosedInfo

Chrome 142 ขึ้นไป

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

  • เส้นทาง

    สตริง

    เส้นทางของทรัพยากรในเครื่องภายในแพ็กเกจส่วนขยายซึ่งเนื้อหาจะแสดงในแผง

  • tabId

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

    รหัสที่ไม่บังคับของแท็บที่ปิดแผงด้านข้าง ซึ่งจะแสดงเฉพาะเมื่อแผงนั้นๆ เป็นของแท็บนั้นๆ

  • windowId

    ตัวเลข

    รหัสของหน้าต่างที่ปิดแผงด้านข้าง โดยมีให้บริการทั้งสำหรับแผงทั่วโลกและแผงเฉพาะแท็บ

PanelLayout

Chrome 140 ขึ้นไป

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

PanelOpenedInfo

Chrome 141 ขึ้นไป

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

  • เส้นทาง

    สตริง

    เส้นทางของทรัพยากรในเครื่องภายในแพ็กเกจส่วนขยายซึ่งเนื้อหาจะแสดงในแผง

  • tabId

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

    รหัสที่ไม่บังคับของแท็บที่เปิดแผงด้านข้าง ซึ่งจะแสดงเฉพาะเมื่อแผงนั้นๆ เป็นของแท็บนั้นๆ

  • windowId

    ตัวเลข

    รหัสของหน้าต่างที่เปิดแผงด้านข้าง โดยมีให้บริการทั้งสำหรับแผงทั่วโลกและแผงเฉพาะแท็บ

PanelOptions

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

  • เปิดใช้อยู่

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

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

  • เส้นทาง

    สตริง ไม่บังคับ

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

  • tabId

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

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

Side

Chrome 140 ขึ้นไป

กำหนดการจัดแนวที่เป็นไปได้สำหรับแผงด้านข้างใน UI ของเบราว์เซอร์

ค่าแจกแจง

"left"

"right"

SidePanel

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

  • default_path

    สตริง

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

เมธอด

getLayout()

Chrome 140 ขึ้นไป 
chrome.sidePanel.getLayout(): Promise<PanelLayout>

แสดงผลเลย์เอาต์ปัจจุบันของแผงด้านข้าง

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

getOptions()

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

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

พารามิเตอร์

  • ตัวเลือก

    GetPanelOptions

    ระบุบริบทที่จะส่งคืนการกำหนดค่า

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

getPanelBehavior()

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

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

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

open()

Chrome 116 ขึ้นไป 
chrome.sidePanel.open(
  options: OpenOptions,
): Promise<void>

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

พารามิเตอร์

  • ตัวเลือก

    OpenOptions

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

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

  • Promise<void>

setOptions()

chrome.sidePanel.setOptions(
  options: PanelOptions,
): Promise<void>

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

พารามิเตอร์

  • ตัวเลือก

    PanelOptions

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

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

  • Promise<void>

setPanelBehavior()

chrome.sidePanel.setPanelBehavior(
  behavior: PanelBehavior,
): Promise<void>

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

พารามิเตอร์

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

    PanelBehavior

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

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

  • Promise<void>

กิจกรรม

onOpened

Chrome 141 ขึ้นไป 
chrome.sidePanel.onOpened.addListener(
  callback: function,
)

ทริกเกอร์เมื่อเปิดแผงด้านข้างของส่วนขยาย

พารามิเตอร์

  • callback

    ฟังก์ชัน

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    (info: PanelOpenedInfo) => void