chrome.sidePanel

Nội dung mô tả

Sử dụng API chrome.sidePanel để lưu trữ nội dung trong bảng điều khiển bên của trình duyệt cùng với nội dung chính của trang web.

Quyền

sidePanel

Để sử dụng API Bảng điều khiển bên, hãy thêm quyền "sidePanel" vào tệp tệp kê khai của tiện ích:

manifest.json:

{
  "name": "My side panel extension",
  ...
  "permissions": [
    "sidePanel"
  ]
}

Phạm vi cung cấp

Chrome 114 trở lên MV3

Khái niệm và cách sử dụng

API Bảng điều khiển bên cho phép các tiện ích hiển thị giao diện người dùng của riêng chúng trong bảng điều khiển bên, mang lại trải nghiệm liên tục giúp bổ sung cho hành trình duyệt web của người dùng.

Trình đơn thả xuống của bảng điều khiển bên
Giao diện người dùng trên bảng điều khiển bên của trình duyệt Chrome.

Một số tính năng bao gồm:

  • Bảng điều khiển bên vẫn mở khi di chuyển giữa các thẻ (nếu bạn đặt chính sách này).
  • Tính năng này có thể chỉ hoạt động trên một số trang web.
  • Dưới dạng trang tiện ích, các bảng điều khiển bên có quyền truy cập vào tất cả API của Chrome.
  • Trong phần cài đặt của Chrome, người dùng có thể chỉ định phía bảng điều khiển sẽ xuất hiện.

Trường hợp sử dụng

Các phần sau đây minh hoạ một số trường hợp sử dụng phổ biến cho API Bảng điều khiển bên. Xem Mẫu phần mở rộng để biết ví dụ hoàn chỉnh về phần mở rộng.

Hiển thị cùng một bảng điều khiển bên trên mọi trang web

Ban đầu, bạn có thể đặt bảng điều khiển bên từ thuộc tính "default_path" trong khoá "side_panel" của tệp kê khai để hiện cùng một bảng điều khiển bên trên mọi trang web. Tham số này phải trỏ đến một đường dẫn tương đối trong thư mục tiện ích.

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>

Bật bảng điều khiển bên trên một trang web cụ thể

Tiện ích có thể dùng sidepanel.setOptions() để bật bảng điều khiển bên trên một thẻ cụ thể. Ví dụ này sử dụng chrome.tabs.onUpdated() để theo dõi mọi nội dung cập nhật đối với thẻ. Tính năng này kiểm tra xem URL có phải là www.google.com hay không và bật bảng điều khiển bên. Nếu không, chế độ này sẽ tắt chế độ đồng ý.

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
    });
  }
});

Khi người dùng tạm thời chuyển sang một thẻ mà bảng điều khiển bên chưa bật, bảng điều khiển bên sẽ bị ẩn. Cửa sổ này sẽ tự động hiển thị lại khi người dùng chuyển sang một thẻ đã mở trước đó.

Khi người dùng chuyển đến một trang web chưa bật bảng điều khiển bên, bảng điều khiển bên sẽ đóng và tiện ích sẽ không hiển thị trong trình đơn thả xuống của bảng điều khiển bên.

Để biết ví dụ đầy đủ, hãy xem mẫu Bảng điều khiển bên dành riêng cho thẻ.

Mở bảng điều khiển bên bằng cách nhấp vào biểu tượng thanh công cụ

Nhà phát triển có thể cho phép người dùng mở bảng điều khiển bên khi họ nhấp vào biểu tượng thanh công cụ thao tác bằng sidePanel.setPanelBehavior(). Trước tiên, hãy khai báo khoá "action" trong tệp kê khai:

manifest.json:

{
  "name": "My side panel extension",
  ...
   "action": {
    "default_title": "Click to open panel"
  },
  ...
}

Bây giờ, hãy thêm mã này vào ví dụ trước:

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));
...

Mở bảng điều khiển bên khi người dùng tương tác theo phương thức lập trình

Chrome 116 giới thiệu sidePanel.open(). Tiện ích này cho phép tiện ích mở bảng điều khiển bên thông qua cử chỉ của người dùng của tiện ích, chẳng hạn như nhấp vào biểu tượng hành động. Hoặc tương tác của người dùng trên trang tiện ích hoặc tập lệnh nội dung, chẳng hạn như nhấp vào một nút. Để xem bản minh hoạ đầy đủ, hãy xem phần mở rộng mẫu Open Side Panel (Mở bảng điều khiển bên).

Mã sau đây cho biết cách mở bảng điều khiển bên chung trên cửa sổ hiện tại khi người dùng nhấp vào trình đơn theo bối cảnh. Khi sử dụng sidePanel.open(), bạn phải chọn bối cảnh mà ứng dụng sẽ mở. Dùng windowId để mở một bảng điều khiển bên chung. Ngoài ra, bạn có thể thiết lập tabId để chỉ mở bảng điều khiển bên trên một thẻ cụ thể.

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 });
  }
});

Chuyển sang bảng điều khiển khác

Các tiện ích có thể sử dụng sidepanel.getOptions() để truy xuất bảng điều khiển bên hiện tại. Ví dụ sau đây đặt bảng điều khiển bên chào mừng trên runtime.onInstalled(). Sau đó, khi người dùng chuyển đến một thẻ khác, thẻ đó sẽ được thay thế bằng bảng điều khiển bên chính.

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 });
  }
});

Vui lòng xem Nhiều bảng điều khiển bên để xem mẫu đầy đủ.

Trải nghiệm người dùng trên bảng điều khiển bên

Người dùng sẽ thấy các bảng điều khiển bên tích hợp sẵn của Chrome trước tiên. Mỗi bảng điều khiển bên hiển thị biểu tượng của tiện ích trong trình đơn bảng điều khiển bên. Nếu không có biểu tượng nào được đưa vào, thì trình giữ chỗ sẽ hiển thị biểu tượng phần giữ chỗ có chữ cái đầu tiên của tên tiện ích.

Mở bảng điều khiển bên

Chuyển đến trình đơn bảng điều khiển bên
Người dùng có thể tìm thấy các bảng điều khiển bên có sẵn trong trình đơn bảng điều khiển bên. Sau đó, họ có thể chọn một phần mở rộng trong trình đơn thả xuống.
Trình đơn thả xuống của bảng điều khiển bên
Giao diện người dùng trong bảng điều khiển bên của trình duyệt Chrome.
Mở thông qua cử chỉ của người dùng

Bạn có thể mở bảng điều khiển bên thông qua các hoạt động tương tác của người dùng bằng sidePanel.open() và sidePanel.setPanelBehavior(), chẳng hạn như:

Ví dụ

Để xem thêm bản minh hoạ tiện ích API Bảng điều khiển bên, hãy khám phá bất kỳ tiện ích nào sau đây:

Loại

GetPanelOptions

Thuộc tính

  • tabId

    số không bắt buộc

    Nếu được chỉ định, các tuỳ chọn bảng điều khiển bên cho thẻ đã cho sẽ được trả về. Nếu không, hãy trả về các tuỳ chọn bảng điều khiển bên mặc định (dùng cho bất kỳ thẻ nào không có chế độ cài đặt cụ thể).

OpenOptions

Chrome 116 trở lên

Thuộc tính

  • tabId

    số không bắt buộc

    Thẻ để mở bảng điều khiển bên. Nếu thẻ tương ứng có một bảng điều khiển bên dành riêng cho thẻ, bảng điều khiển sẽ chỉ mở cho thẻ đó. Nếu không có bảng điều khiển riêng cho thẻ, bảng điều khiển chung sẽ mở trong thẻ được chỉ định và mọi thẻ khác mà không có bảng điều khiển cụ thể cho từng thẻ hiện đang mở. Thao tác này sẽ ghi đè mọi bảng điều khiển bên đang hoạt động (toàn cầu hoặc theo thẻ cụ thể) trong thẻ tương ứng. Bạn phải cung cấp ít nhất một trong các giá trị này hoặc windowId.

  • windowId

    số không bắt buộc

    Cửa sổ để mở bảng điều khiển bên. Điều này chỉ có thể áp dụng nếu tiện ích có bảng điều khiển bên chung (không dành riêng cho thẻ) hoặc tabId cũng được chỉ định. Thao tác này sẽ ghi đè mọi bảng điều khiển bên chung đang hoạt động mà người dùng đã mở trong cửa sổ cụ thể. Bạn phải cung cấp ít nhất một trong các giá trị này hoặc tabId.

PanelBehavior

Thuộc tính

  • openPanelOnActionClick

    boolean không bắt buộc

    Việc nhấp vào biểu tượng của tiện ích có làm bật/tắt mục nhập của tiện ích đó trong bảng điều khiển bên hay không. Giá trị mặc định là false.

PanelOptions

Thuộc tính

  • đang bật

    boolean không bắt buộc

    Liệu có nên bật bảng điều khiển bên hay không. Việc này là không bắt buộc. Giá trị mặc định là true.

  • path

    chuỗi không bắt buộc

    Đường dẫn đến tệp HTML của bảng điều khiển bên để sử dụng. Đây phải là một tài nguyên cục bộ trong gói tiện ích.

  • tabId

    số không bắt buộc

    Nếu được chỉ định, các lựa chọn trong bảng điều khiển bên sẽ chỉ áp dụng cho thẻ có mã nhận dạng này. Nếu bị bỏ qua, các tuỳ chọn này sẽ đặt hành vi mặc định (dùng cho bất kỳ thẻ nào không có chế độ cài đặt cụ thể). Lưu ý: nếu bạn đặt cùng một đường dẫn cho mã thẻ này và mã thẻ mặc định, thì bảng điều khiển cho mã thẻ này sẽ là một phiên bản khác với bảng điều khiển cho mã thẻ mặc định.

SidePanel

Thuộc tính

  • default_path

    string

    Đường dẫn do nhà phát triển chỉ định để hiển thị bảng điều khiển bên.

Phương thức

getOptions()

Cam kết 
chrome.sidePanel.getOptions(
  options: GetPanelOptions,
  callback?: function,
)

Trả về cấu hình bảng điều khiển đang hoạt động.

Tham số

  • tùy chọn

    GetPanelOptions

    Chỉ định ngữ cảnh trả về cấu hình.

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    (options: PanelOptions)=>void

Giá trị trả về

  • Promise<PanelOptions>

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

getPanelBehavior()

Cam kết 
chrome.sidePanel.getPanelBehavior(
  callback?: function,
)

Trả về hành vi hiện tại của bảng điều khiển bên của tiện ích.

Tham số

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    (behavior: PanelBehavior)=>void

Giá trị trả về

  • Promise<PanelBehavior>

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

open()

Cam kết Chrome 116 trở lên 
chrome.sidePanel.open(
  options: OpenOptions,
  callback?: function,
)

Mở bảng điều khiển bên cho tiện ích. Lệnh này chỉ có thể được gọi để phản hồi hành động của người dùng.

Tham số

  • tùy chọn

    OpenOptions

    Chỉ định bối cảnh cần mở bảng điều khiển bên.

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    ()=>void

Giá trị trả về

  • Promise<void>

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

setOptions()

Cam kết 
chrome.sidePanel.setOptions(
  options: PanelOptions,
  callback?: function,
)

Định cấu hình bảng điều khiển bên.

Tham số

  • tùy chọn

    PanelOptions

    Các lựa chọn cấu hình để áp dụng cho bảng điều khiển.

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    ()=>void

Giá trị trả về

  • Promise<void>

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

setPanelBehavior()

Cam kết 
chrome.sidePanel.setPanelBehavior(
  behavior: PanelBehavior,
  callback?: function,
)

Định cấu hình hoạt động của bảng điều khiển bên của tiện ích. Đây là một thao tác chèn và cập nhật.

Tham số

  • lợi dụng

    PanelBehavior

    Hành vi mới sẽ được đặt.

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    ()=>void

Giá trị trả về

  • Promise<void>

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.