Trang này được dịch bởi Cloud Translation API.

chrome.sidePanel

Mô tả

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 Video nhạc 3 trở lên

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

API bảng điều khiển bên cho phép tiện ích hiển thị giao diện người dùng riêng trong bảng điều khiển bên, mang lại trải nghiệm lâu dài 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 của 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 để làm vậy).
Tính năng này chỉ có thể 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 bảng điều khiển sẽ được hiển thị ở phía nào.

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 của API Bảng điều khiển bên. Xem Mẫu tiện ích để biết ví dụ đầy đủ về tiện ích.

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 thị cùng một bảng điều khiển bên trên mọi trang web. Mã 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ể sử 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ẻ này. Hộp cát về quyền riêng tư 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, Gemini sẽ vô hiệu hoá thiết bị đó.

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 đó đã mở.

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 nhấp vào biểu tượng thanh công cụ hành động có biểu tượ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 theo phương thức lập trình để tương tác của người dùng

Chrome 116 ra mắt sidePanel.open(). Tính năng này cho phép tiện ích mở bảng điều khiển bên thông qua một cử chỉ của người dùng tiện ích, chẳng hạn như nhấp vào biểu tượng hành động. Hoặc hành động tương tác của người dùng trên một 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 Mở Bảng điều khiển bên.

Đoạn mã sau đây cho biết cách mở một 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 một 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à theo đó hàm này sẽ mở. Sử dụng windowId để mở một bảng điều khiển bên chung. Hoặc đặt 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 một bảng điều khiển khác

Các tiện ích có thể dùng sidepanel.getOptions() để truy xuất bảng điều khiển bên hiện tại. Ví dụ sau đây thiết lập 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ẻ này sẽ thay thế thẻ này 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.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 });
  }
});

Xem mẫu Nhiều bảng điều khiển bên để biết mã đầy đủ.

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

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

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

Để cho phép người dùng mở bảng điều khiển bên, hãy sử dụng kết hợp biểu tượng hành động cùng với sidePanel.setPanelBehavior(). Ngoài ra, hãy thực hiện lệnh gọi đến sidePanel.open() sau một hoạt động tương tác của người dùng, chẳng hạn như:

Một lượt nhấp vào hành động
Phím tắt
Trình đơn theo bối cảnh
Cử chỉ của người dùng trên trang tiện ích hoặc tập lệnh nội dung.

Ghim bảng điều khiển bên

Biểu tượng ghim trong giao diện người dùng của bảng điều khiển bên.

Thanh công cụ của bảng điều khiển bên sẽ hiện biểu tượng ghim khi bảng điều khiển bên đang mở. Nhấp vào biểu tượng đó sẽ ghim biểu tượng hành động của tiện ích. Nhấp vào biểu tượng hành động khi được ghim sẽ thực hiện hành động mặc định cho biểu tượng hành động và sẽ chỉ hãy mở bảng điều khiển bên nếu đã định cấu hình rõ ràng.

Ví dụ

Để biết thêm các 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, sẽ trả về các tuỳ chọn bảng điều khiển bên mặc định (dùng cho mọi thẻ 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ẻ, thì bảng điều khiển sẽ chỉ mở cho thẻ đó. Nếu không có bảng điều khiển dành riêng cho thẻ, bảng điều khiển chung sẽ mở trong thẻ được chỉ định và bất kỳ thẻ nào khác không có bảng điều khiển thẻ cụ thể đang mở. Thao tác này sẽ ghi đè mọi bảng điều khiển bên hiện đang hoạt động (chung hoặc cụ thể cho thẻ) trong thẻ tương ứng. Bạn phải cung cấp ít nhất một trong hai 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ỉ á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ẽ thay thế 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 hai giá trị này hoặc tabId.

PanelBehavior

Thuộc tính

openPanelOnActionClick

boolean không bắt buộc

Việc bạn nhấp vào biểu tượng của tiện ích có bật/tắt chế độ hiển thị 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ó 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.
đường dẫn

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à 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 tuỳ chọn bảng điều khiển bên sẽ chỉ áp dụng cho thẻ có mã này. Nếu bị bỏ qua, các tùy chọn này sẽ đặt chế độ mặc định (được sử dụng cho bất kỳ thẻ nào không có cài đặt cụ thể). Lưu ý: nếu bạn đặt cùng một đường dẫn cho tabId này và tabId mặc định, thì bảng điều khiển cho tabId này sẽ là một phiên bản khác với bảng điều khiển cho tabId 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()

Lời hứa

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 chọ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
```
- tùy chọn
  
  PanelOptions

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 cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

getPanelBehavior()

Lời hứa

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

Trả về hành vi trên bảng điều khiển bên hiện tại 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
```
- lợi dụng
  
  PanelBehavior

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 cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

open()

Lời hứa 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 chọn

OpenOptions

Chỉ định bối cảnh mà bạn muố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ề

Lời hứa<vô hiệu>

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 cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

setOptions()

Lời hứa

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

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

Tham số

tùy chọn

PanelOptions

Các lựa chọn cấu hình sẽ á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ề

Lời hứa<vô hiệu>

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 cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

setPanelBehavior()

Lời hứa

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

Định cấu hình cách hoạt động trên 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 cần được thiết lập.
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ề

Lời hứa<vô hiệu>

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 cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.