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() ตามการโต้ตอบของผู้ใช้ เช่น

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

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

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

ตัวอย่าง

หากต้องการดูการสาธิตส่วนขยาย 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

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

  • Promise&lt;PanelOptions&gt;

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

getPanelBehavior()

สัญญา 
chrome.sidePanel.getPanelBehavior(
  callback?: function,
)

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

พารามิเตอร์

  • Callback

    ไม่บังคับ

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

    (behavior: PanelBehavior) => void

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

      PanelBehavior

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

  • Promise&lt;PanelBehavior&gt;

    รองรับคำสัญญาในไฟล์ 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