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
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](https://developer.chrome.com/static/docs/extensions/reference/api/sidePanel/images/example-side-panel.png?authuser=19&hl=vi)
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.](https://developer.chrome.com/static/docs/extensions/reference/api/sidePanel/images/side-panel-pin.png?authuser=19&hl=vi)
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:
- Bảng điều khiển bên từ điển.
- Bảng điều khiển bên chung.
- Nhiều bảng điều khiển bên.
- Mở Bảng điều khiển bên.
- Bảng điều khiển bên dành riêng cho trang web.
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
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ặctabId
.
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()
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
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 chọn
-
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()
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
-
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()
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
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()
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
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()
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
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.