Nội dung mô tả
Dùng API chrome.runtime
để truy xuất trình chạy dịch vụ, trả về thông tin chi tiết về tệp kê khai, cũng như theo dõi và phản hồi các sự kiện trong vòng đời của tiện ích. Bạn cũng có thể sử dụng API này để chuyển đổi đường dẫn tương đối của URL thành các URL đủ điều kiện.
Hầu hết thành phần của API này không yêu cầu bất kỳ quyền nào. connectNative()
, sendNativeMessage()
và onNativeConnect
cần có quyền này.
Ví dụ sau đây minh hoạ cách khai báo quyền "nativeMessaging"
trong tệp kê khai:
manifest.json:
{
"name": "My extension",
...
"permissions": [
"nativeMessaging"
],
...
}
Khái niệm và cách sử dụng
Runtime API (API Thời gian chạy) cung cấp các phương thức để hỗ trợ một số khu vực mà tiện ích của bạn có thể sử dụng:
- Truyền tin nhắn
- Tiện ích của bạn có thể giao tiếp với nhiều ng�� cảnh trong tiện ích cũng như với các tiện ích khác sử dụng các phương thức và sự kiện sau:
connect()
,onConnect
,onConnectExternal
,sendMessage()
,onMessage
vàonMessageExternal
. Ngoài ra, tiện ích của bạn có thể truyền thông báo đến các ứng dụng gốc trên thiết bị của người dùng bằngconnectNative()
vàsendNativeMessage()
.
- Truy cập siêu dữ liệu của tiện ích và nền tảng
- Các phương thức này cho phép bạn truy xuất một số phần siêu dữ liệu cụ thể về tiện ích và nền tảng. Các phương thức trong danh mục này bao gồm
getManifest()
vàgetPlatformInfo()
. - Quản lý các lựa chọn và vòng đời của tiện ích
- Các thuộc tính này cho phép bạn thực hiện một số thao tác meta trên tiện ích và hiển thị trang tuỳ chọn.
Các phương thức và sự kiện trong danh mục này bao gồm
onInstalled
,onStartup
,openOptionsPage()
,reload()
,requestUpdateCheck()
vàsetUninstallURL()
. - Tiện ích trợ giúp
- Các phương thức này mang lại sự tiện ích như chuyển đổi các biểu diễn tài nguyên nội bộ sang định dạng bên ngoài. Các phương thức trong danh mục này bao gồm
getURL()
. - Tiện ích chế độ kiosk
- Các phương pháp này chỉ hoạt động trên ChromeOS và chủ yếu tồn tại để hỗ trợ việc triển khai kiosk.
Các phương thức trong danh mục này bao gồm
restart()
vàrestartAfterDelay()
`.
Hành vi của tiện ích đã giải nén
Khi một tiện ích đã giải nén được tải lại, đây được coi là một bản cập nhật. Điều này có nghĩa là sự kiện chrome.runtime.onInstalled
sẽ kích hoạt với lý do là "update"
. Điều này cũng áp dụng cho thời điểm tiện ích được tải lại bằng chrome.runtime.reload()
.
Trường hợp sử dụng
Thêm hình ảnh vào trang web
Để truy cập vào nội dung được lưu trữ trên một miền khác, trang web phải chỉ định URL đầy đủ của tài nguyên (ví dụ: <img src="https://example.com/logo.png">
). Tương tự như vậy khi thêm nội dung tiện ích vào trang web. Hai điểm khác biệt là thành phần của tiện ích ph��i được hiển thị dưới dạng tài nguyên có thể truy cập trên web và tập lệnh nội dung thường chịu trách nhiệm chèn tài sản tiện ích.
Trong ví dụ này, tiện ích sẽ thêm logo.png
vào trang mà tập lệnh nội dung đang được chèn vào bằng cách sử dụng runtime.getURL()
để tạo một URL đủ điều kiện. Nhưng trước tiên, tài sản đó phải được khai báo dưới dạng một tài nguyên có thể truy cập trên web trong tệp kê khai.
manifest.json:
{
...
"web_accessible_resources": [
{
"resources": [ "logo.png" ],
"matches": [ "https://*/*" ]
}
],
...
}
content.js:
{ // Block used to avoid setting global variables
const img = document.createElement('img');
img.src = chrome.runtime.getURL('logo.png');
document.body.append(img);
}
Gửi dữ liệu từ tập lệnh nội dung đến trình chạy dịch vụ
Thường thì tập lệnh nội dung của một tiện ích cần dữ liệu được quản lý bởi một phần khác của tiện ích, chẳng hạn như trình chạy dịch vụ. Giống như hai cửa sổ trình duyệt được mở đến cùng một trang web, hai ngữ cảnh này không thể truy cập trực tiếp vào các giá trị của nhau. Thay vào đó, tiện ích này có thể sử dụng tính năng truyền tin nhắn để điều phối trên các ngữ cảnh khác nhau này.
Trong ví dụ này, tập lệnh nội dung cần một số dữ liệu từ trình chạy dịch vụ của tiện ích để khởi động giao diện người dùng. Để có được dữ liệu này, dịch vụ sẽ truyền thông báo get-user-data
do nhà phát triển xác định đến trình chạy dịch vụ và phản hồi bằng một bản sao thông tin của người dùng.
content.js:
// 1. Send a message to the service worker requesting the user's data
chrome.runtime.sendMessage('get-user-data', (response) => {
// 3. Got an asynchronous response with the data from the service worker
console.log('received user data', response);
initializeUI(response);
});
service-worker.js:
// Example of a simple user data object
const user = {
username: 'demo-user'
};
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
// 2. A page requested user data, respond with a copy of `user`
if (message === 'get-user-data') {
sendResponse(user);
}
});
Thu thập ý kiến phản hồi về việc gỡ cài đặt
Nhiều tiện ích sử dụng các cuộc khảo sát sau khi gỡ cài đặt để hiểu rõ cách tiện ích có thể phục vụ người dùng tốt hơn và cải thiện tỷ lệ giữ chân người dùng. Ví dụ sau cho thấy cách thêm chức năng này.
background.js:
chrome.runtime.onInstalled.addListener(details => {
if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
chrome.runtime.setUninstallURL('https://example.com/extension-survey');
}
});
Ví dụ
Xem bản minh hoạ Manifest V3 – Web Accessible Tài nguyên để biết thêm các ví dụ về Runtime API (API Thời gian chạy).
Loại
ContextFilter
Bộ lọc để so khớp theo một số ngữ cảnh nhất định của tiện ích. Ngữ cảnh trùng khớp phải khớp với tất cả bộ lọc đã chỉ định; mọi bộ lọc không được chỉ định sẽ khớp với mọi ngữ cảnh hiện có. Do đó, bộ lọc `{}` sẽ khớp với tất cả ngữ cảnh có sẵn.
Thuộc tính
-
contextIds
string[] không bắt buộc
-
contextTypes
ContextType[] không bắt buộc
-
documentIds
string[] không bắt buộc
-
documentOrigins
string[] không bắt buộc
-
documentUrls
string[] không bắt buộc
-
frameIds
number[] không bắt buộc
-
ẩn danh
boolean không bắt buộc
-
tabIds
number[] không bắt buộc
-
windowIds
number[] không bắt buộc
ContextType
Liệt kê
"TAB"
Chỉ định loại ngữ cảnh làm thẻ
"SR"
Chỉ định loại ngữ cảnh dưới dạng cửa sổ bật lên của tiện ích
"NỀN"
Chỉ định loại ngữ cảnh làm trình chạy dịch vụ.
"OFFSCREEN_DOCUMENT"
Chỉ định loại ngữ cảnh là tài liệu ngoài màn hình.
"SIDE_ACTIVE"
Chỉ định loại bối cảnh làm bảng điều khiển bên.
ExtensionContext
Ngữ cảnh lưu trữ nội dung tiện ích.
Thuộc tính
-
contextId
string
Giá trị nhận dạng duy nhất cho ngữ cảnh này
-
contextType
Loại bối cảnh tương ứng với sự kiện này.
-
documentId
chuỗi không bắt buộc
Mã nhận dạng duy nhất (UUID) cho tài liệu liên kết với ngữ cảnh này hoặc không xác định nếu ngữ cảnh này được lưu trữ không phải trong một tài liệu.
-
documentOrigin
chuỗi không bắt buộc
Nguồn gốc của tài liệu liên quan đến bối cảnh này hoặc không xác ��ịnh nếu bối cảnh này không được lưu trữ trong một tài liệu.
-
documentUrl
chuỗi không bắt buộc
URL của tài liệu liên kết với bối cảnh này hoặc không xác định nếu bối cảnh không được lưu trữ trong một tài liệu.
-
frameId
number
Mã của khung cho ngữ cảnh này hoặc -1 nếu ngữ cảnh này không được lưu trữ trong một khung.
-
ẩn danh
boolean
Liệu ngữ cảnh có được liên kết với hồ sơ ẩn danh hay không.
-
tabId
number
Mã của thẻ tương ứng với ngữ cảnh này hoặc -1 nếu ngữ cảnh này không được lưu trữ trong một thẻ.
-
windowId
number
Mã của cửa sổ cho ngữ cảnh này hoặc -1 nếu ngữ cảnh này không được lưu trữ trong một cửa sổ.
MessageSender
Đối tượng chứa thông tin về ngữ cảnh tập lệnh đã gửi thông báo hoặc yêu cầu.
Thuộc tính
-
documentId
chuỗi không bắt buộc
Chrome 106 trở lênMã nhận dạng duy nhất (UUID) của tài liệu đã mở kết nối.
-
documentLifecycle
chuỗi không bắt buộc
Chrome 106 trở lênVòng đời của tài liệu đã mở kết nối tại thời điểm tạo cổng. Xin lưu ý rằng trạng thái vòng đời của tài liệu có thể đã thay đổi kể từ khi tạo cổng.
-
frameId
số không bắt buộc
Khung đã mở kết nối. 0 đối với khung cấp cao nhất, dương đối với khung con. Chế độ này chỉ được thiết lập khi bạn đặt
tab
. -
id
chuỗi không bắt buộc
Mã của tiện ích đã mở kết nối, nếu có.
-
nativeApplication
chuỗi không bắt buộc
Chrome 74 trở lênTên của ứng dụng gốc đã mở kết nối, nếu có.
-
nguồn gốc
chuỗi không bắt buộc
Chrome 80 trở lênNguồn gốc của trang hoặc khung đã mở kết nối. URL này có thể khác với thuộc tính url (ví dụ: about:blank) hoặc có thể mờ (ví dụ: iframe hộp cát). Điều này rất hữu ích trong việc xác định xem nguồn gốc có đáng tin cậy hay không nếu chúng tôi không thể xác định ngay từ URL.
-
tab
Thẻ không bắt buộc
tabs.Tab
đã mở kết nối, nếu có. Thuộc tính này sẽ chỉ xuất hiện khi bạn mở kết nối từ một thẻ (bao gồm cả tập lệnh nội dung) và chỉ khi dịch vụ nhận là một tiện ích, không phải trong ứng dụng. -
tlsChannelId
chuỗi không bắt buộc
Mã kênh TLS (Bảo mật tầng truyền tải) của trang hoặc khung đã mở kết nối, nếu tiện ích yêu cầu và nếu có.
-
url
chuỗi không bắt buộc
URL của trang hoặc khung đã mở kết nối. Nếu người gửi nằm trong iframe, thì đó sẽ là URL của iframe chứ không phải URL của trang lưu trữ iframe.
OnInstalledReason
Lý do khiến sự kiện này đang được gửi đi.
Liệt kê
"install"
Chỉ định lý do sự kiện là một lượt cài đặt.
"update"
Chỉ định lý do sự kiện làm bản cập nhật tiện ích.
"chrome_update"
Chỉ định lý do sự kiện làm bản cập nhật Chrome.
"shared_module_update"
Chỉ định lý do sự kiện dưới dạng nội dung cập nhật cho một mô-đun dùng chung.
OnRestartRequiredReason
Lý do khiến sự kiện đang được gửi đi. "app_update" được dùng khi cần khởi động lại vì ứng dụng đã được cập nhật lên một phiên bản mới hơn. "os_update" được dùng khi cần khởi động lại vì trình duyệt/hệ điều hành đã được cập nhật lên phiên bản mới hơn. Thuộc tính "định kỳ" được dùng khi hệ thống chạy lâu hơn thời gian hoạt động được phép đã đặt trong chính sách doanh nghiệp.
Liệt kê
"app_update"
Chỉ định lý do sự kiện dưới dạng một bản cập nhật cho ứng dụng.
"os_update"
Chỉ định lý do sự kiện dưới dạng một bản cập nhật cho hệ điều hành.
"định kỳ"
Chỉ định lý do sự kiện là hoạt động khởi động lại ứng dụng định kỳ.
PlatformArch
Cấu trúc bộ xử lý của máy.
Liệt kê
"arm"
Chỉ định cấu trúc bộ xử lý là arm.
"arm64"
Chỉ định kiến trúc trình xử lý là arm64.
"x86-32"
Chỉ định kiến trúc xử lý là x86-32.
"x86-64"
Chỉ định kiến trúc xử lý là x86-64.
"mips"
Chỉ định cấu trúc bộ xử lý dưới dạng mips.
"mips64"
Chỉ định kiến trúc trình xử lý là mips64.
PlatformInfo
Đối tượng chứa thông tin về nền tảng hiện tại.
Thuộc tính
-
hình vòm
Cấu trúc bộ xử lý của máy.
-
nacl_arch
Cấu trúc ứng dụng gốc. Giao diện này có thể khác với vòm trên một số nền tảng.
-
os
Hệ điều hành mà Chrome đang chạy.
PlatformNaclArch
Cấu trúc ứng dụng gốc. Giao diện này có thể khác với vòm trên một số nền tảng.
Liệt kê
"arm"
Chỉ định cấu trúc ứng dụng gốc là arm.
"x86-32"
Chỉ định cấu trúc ứng dụng gốc là x86-32.
"x86-64"
Chỉ định cấu trúc ứng dụng gốc là x86-64.
"mips"
Chỉ định cấu trúc ứng dụng gốc dưới dạng mips.
"mips64"
Chỉ định cấu trúc ứng dụng gốc là mips64.
PlatformOs
Hệ điều hành mà Chrome đang chạy.
Liệt kê
"mac"
Chỉ định hệ điều hành MacOS.
"win"
Chỉ định hệ điều hành Windows.
"android"
Chỉ định hệ điều hành Android.
"cros"
Chỉ định hệ điều hành Chrome.
"linux"
Chỉ định hệ điều hành Linux.
"openbsd"
Chỉ định hệ điều hành OpenBSD.
"fuchsia"
Chỉ định hệ điều hành Fuchsia.
Port
Một đối tượng cho phép giao tiếp hai chiều với các trang khác. Xem phần Kết nối lâu dài để biết thêm thông tin.
Thuộc tính
-
tên
string
Tên cổng, như được chỉ định trong lệnh gọi đến
runtime.connect
. -
onDisconnect
Sự kiện<functionvoid>
Được kích hoạt khi cổng bị ngắt kết nối với(các) đầu kia. Bạn có thể đặt
runtime.lastError
nếu cổng bị ngắt kết nối do lỗi. Nếu cổng bị đóng thông qua tính năng ngắt kết nối, thì sự kiện này chỉ được kích hoạt ở đầu bên kia. Sự kiện này được kích hoạt tối đa một lần (xem thêm phần Thời gian tồn tại của cổng).Hàm
onDisconnect.addListener
sẽ có dạng như sau:(callback: function) => {...}
-
onMessage
Sự kiện<functionvoid>
Sự kiện này được kích hoạt khi postMessage được gọi bởi đầu kia của cổng.
Hàm
onMessage.addListener
sẽ có dạng như sau:(callback: function) => {...}
-
người gửi
MessageSender không bắt buộc
Thuộc tính này sẽ chỉ xuất hiện trên các cổng được chuyển tới trình nghe onConnect / onConnectExternal / onConnectNative.
-
ngắt kết nối
void
Ngắt kết nối cổng ngay lập tức. Việc gọi
disconnect()
trên một cổng đã ngắt kết nối không có tác dụng. Khi một cổng bị ngắt kết nối, sẽ không có sự kiện mới nào được gửi đến cổng này.Hàm
disconnect
sẽ có dạng như sau:() => {...}
-
postMessage
void
Gửi tin nhắn đến đầu bên kia của cổng. Nếu cổng bị ngắt kết nối, hệ thống sẽ gửi ra một lỗi.
Hàm
postMessage
sẽ có dạng như sau:(message: any) => {...}
-
tin nhắn
Bất kỳ
Chrome 52 trở lênTin nhắn cần gửi. Bạn phải cung cấp đối tượng này ở định dạng JSON.
-
RequestUpdateCheckStatus
Kết quả kiểm tra bản cập nhật.
Liệt kê
"bị điều tiết"
Chỉ định rằng hoạt động kiểm tra trạng thái đã bị điều tiết. Tình trạng này có thể xảy ra sau khi kiểm tra nhiều lần trong một khoảng thời gian ngắn.
"no_update"
Chỉ định rằng không có bản cập nhật nào để cài đặt.
"update_available"
Chỉ định rằng có bản cập nhật có thể cài đặt.
Thuộc tính
id
Mã của tiện ích/ứng dụng.
Loại
string
lastError
Được điền sẵn thông báo lỗi nếu gọi một hàm API không th��nh công; nếu không thì không xác định. Mã này chỉ được xác định trong phạm vi lệnh gọi lại của hàm đó. Nếu có một lỗi xảy ra, nhưng không truy cập được runtime.lastError
trong lệnh gọi lại, thì một thông báo sẽ được ghi vào bảng điều khiển để liệt kê hàm API gây ra lỗi. Các hàm API trả về lời hứa không đặt thuộc tính này.
Loại
đối tượng
Thuộc tính
-
tin nhắn
chuỗi không bắt buộc
Thông tin chi tiết về lỗi đã xảy ra.
Phương thức
connect()
chrome.runtime.connect(
extensionId?: string,
connectInfo?: object,
)
Cố gắng kết nối trình nghe trong một tiện ích (chẳng hạn như trang nền) hoặc các tiện ích/ứng dụng khác. Điều này rất hữu ích đối với các tập lệnh nội dung kết nối với quy trình tiện ích, giao tiếp giữa các ứng dụng/tiện ích và gửi thông báo trên web. Lưu ý rằng phương thức này không kết nối với bất kỳ trình nghe nào trong tập lệnh nội dung. Các tiện ích có thể kết nối với tập lệnh nội dung được nhúng trong thẻ thông qua tabs.connect
.
Tham số
-
extensionId
chuỗi không bắt buộc
Mã của tiện ích cần kết nối. Nếu bạn bỏ qua, hệ thống sẽ cố gắng kết nối với tiện ích của riêng bạn. Bắt buộc nếu bạn gửi thư từ một trang web để gửi thông báo trên web.
-
connectInfo
đối tượng không bắt buộc
-
includeTlsChannelId
boolean không bắt buộc
Liệu mã nhận dạng kênh TLS có được chuyển vào onConnectExternal cho các quy trình đang theo dõi sự kiện kết nối hay không.
-
tên
chuỗi không bắt buộc
Sẽ được truyền vào onConnect cho các quy trình đang theo dõi sự kiện kết nối.
-
Giá trị trả về
-
Cổng mà tin nhắn có thể được gửi và nhận. Sự kiện onDisconnect của cổng sẽ được kích hoạt nếu không có phần mở rộng đó.
connectNative()
chrome.runtime.connectNative(
application: string,
)
Kết nối với một ứng dụng gốc trong máy chủ. Phương thức này yêu cầu quyền "nativeMessaging"
. Xem phần Nhắn tin gốc để biết thêm thông tin.
Tham số
-
ứng dụng
string
Tên của ứng dụng đã đăng ký để kết nối.
Giá trị trả về
-
Cổng mà tin nhắn có thể được gửi và nhận bằng ứng dụng
getBackgroundPage()
chrome.runtime.getBackgroundPage(
callback?: function,
)
Truy xuất đối tượng 'window' JavaScript cho trang nền chạy bên trong tiện ích/ứng dụng hiện tại. Nếu trang nền là trang sự kiện, hệ thống sẽ đảm bảo trang được tải trước khi gọi lệnh gọi lại. Nếu không có trang nền, thì lỗi sẽ được đặt.
Tham số
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(backgroundPage?: Window) => void
-
backgroundPage
Cửa sổ không bắt buộc
Đối tượng "cửa sổ" JavaScript cho trang nền.
-
Giá trị trả về
-
Promise<Window | undefined>
Chrome 99 trở lênLờ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.
getContexts()
chrome.runtime.getContexts(
filter: ContextFilter,
callback?: function,
)
Tìm nạp thông tin về ngữ cảnh hoạt động liên quan đến tiện ích này
Tham số
-
filter
Bộ lọc để tìm ngữ cảnh phù hợp. Ngữ cảnh sẽ khớp nếu ngữ cảnh khớp với tất cả các trường được chỉ định trong bộ lọc. Mọi trường chưa chỉ định trong bộ lọc đều khớp với tất cả ngữ cảnh.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(contexts: ExtensionContext[]) => void
-
bối cảnh
Ngữ cảnh trùng khớp, nếu có.
-
Giá trị trả về
-
Promise<ExtensionContext[]>
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.
getManifest()
chrome.runtime.getManifest()
Trả về thông tin chi tiết về ứng dụng hoặc tiện ích từ tệp kê khai. Đối tượng được trả về là một chuỗi tuần tự của tệp kê khai đầy đủ.
Giá trị trả về
-
đối tượng
Thông tin chi tiết về tệp kê khai.
getPackageDirectoryEntry()
chrome.runtime.getPackageDirectoryEntry(
callback?: function,
)
Trả về một DirectoryEntry cho thư mục gói.
Tham số
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(directoryEntry: DirectoryEntry) => void
-
directoryEntry
DirectoryEntry
-
Giá trị trả về
-
Promise<DirectoryEntry>
Chrome 122 trở lênLờ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.
getPlatformInfo()
chrome.runtime.getPlatformInfo(
callback?: function,
)
Trả về thông tin về nền tảng hiện tại.
Tham số
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(platformInfo: PlatformInfo) => void
-
platformInfo
-
Giá trị trả về
-
Promise<PlatformInfo>
Chrome 99 trở lênLờ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.
getURL()
chrome.runtime.getURL(
path: string,
)
Chuyển đổi đường dẫn tương đối trong thư mục cài đặt ứng dụng/tiện ích thành một URL đủ điều kiện.
Tham số
-
path
string
Đường dẫn đến tài nguyên trong một ứng dụng/tiện ích được biểu thị tương ứng với thư mục cài đặt của ứng dụng/tiện ích đó.
Giá trị trả về
-
string
URL đủ điều kiện cho tài nguyên.
openOptionsPage()
chrome.runtime.openOptionsPage(
callback?: function,
)
Mở trang tuỳ chọn của Tiện ích, nếu có thể.
Hành vi chính xác có thể phụ thuộc vào khoá [options_ui](https://developer.chrome.com/docs/extensions/develop/ui/options-page#embedded_options)
hoặc [options_page](https://developer.chrome.com/docs/extensions/develop/ui/options-page#full_page)
của tệp kê khai hoặc tuỳ chọn mà Chrome hỗ trợ tại thời điểm đó. Ví dụ: trang có thể được mở trong một thẻ mới, trong chrome://extensions, trong một Ứng dụng hoặc có thể chỉ tập trung vào một trang tuỳ chọn đang mở. Việc này sẽ không bao giờ khiến trang phương thức gọi tải lại.
Nếu Tiện ích của bạn không khai báo trang tuỳ chọn hoặc Chrome không tạo được trang tuỳ chọn vì lý do nào đó, thì lệnh gọi lại sẽ đặt lastError
.
Tham số
-
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>
Chrome 99 trở lênLờ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.
reload()
chrome.runtime.reload()
Tải lại ứng dụng hoặc tiện ích. Phương thức này không được hỗ trợ ở chế độ kiosk. Đối với chế độ kiosk, hãy sử dụng phương thức chrome.runtime.restart().
requestUpdateCheck()
chrome.runtime.requestUpdateCheck(
callback?: function,
)
Yêu cầu kiểm tra bản cập nhật ngay cho ứng dụng/tiện ích này.
Lưu ý quan trọng: Hầu hết tiện ích/ứng dụng không nên dùng phương thức này, vì Chrome đã tự động kiểm tra vài giờ một lần và bạn có thể theo dõi sự kiện runtime.onUpdateAvailable
mà không cần gọi requestUpdateCheck.
Phương thức này chỉ thích hợp để gọi trong một số rất ít trường hợp, chẳng hạn như nếu tiện ích của bạn dùng được với một dịch vụ phụ trợ, đồng thời dịch vụ phụ trợ đã xác định rằng phiên bản tiện ích ứng dụng đã lỗi thời và bạn muốn nhắc người dùng cập nhật. Hầu hết các trường hợp sử dụng khác của requestUpdateCheck, chẳng hạn như gọi lệnh này vô điều kiện dựa trên bộ tính giờ lặp lại, có thể chỉ phục vụ việc lãng phí tài nguyên máy khách, mạng và máy chủ.
Lưu ý: Khi được gọi bằng lệnh gọi lại, thay vì trả về một đối tượng, hàm này sẽ trả về hai thuộc tính dưới dạng các đối số riêng biệt được truyền đến lệnh gọi lại.
Tham số
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(result: object) => void
-
kết quả
đối tượng
Chrome 109 trở lênĐối tượng RequestUpdateCheckResult chứa trạng thái kiểm tra bản cập nhật và mọi thông tin chi tiết của kết quả nếu có bản cập nhật
-
status
Kết quả kiểm tra bản cập nhật.
-
version
chuỗi không bắt buộc
Nếu có bản cập nhật, thì bản cập nhật này sẽ chứa phiên bản của bản cập nhật hiện có.
-
-
Giá trị trả về
-
Promise<object>
Chrome 109 trở lênLờ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.
restart()
chrome.runtime.restart()
Khởi động lại thiết bị ChromeOS khi ứng dụng chạy ở chế độ kiosk. Nếu không, trang web đó không hoạt động.
restartAfterDelay()
chrome.runtime.restartAfterDelay(
seconds: number,
callback?: function,
)
Khởi động lại thiết bị ChromeOS khi ứng dụng chạy ở chế độ kiosk sau số giây nhất định. Nếu được gọi lại trước khi hết thời gian này, quá trình khởi động lại sẽ bị trì hoãn. Nếu được gọi với giá trị -1, quá trình khởi động lại sẽ bị huỷ. Chính sách này không hoạt động ở chế độ không có kiosk. Tiện ích đầu tiên chỉ được phép gọi API này nhiều lần để gọi API này.
Tham số
-
giây
number
Thời gian ch�� (tính bằng giây) trước khi khởi động lại thiết bị hoặc -1 để huỷ quá trình khởi động lại theo lịch.
-
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>
Chrome 99 trở lênLờ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.
sendMessage()
chrome.runtime.sendMessage(
extensionId?: string,
message: any,
options?: object,
callback?: function,
)
Gửi một tin nhắn duy nhất đến trình nghe sự kiện trong tiện ích của bạn hoặc một tiện ích/ứng dụng khác. Tương tự như runtime.connect
nhưng chỉ gửi một tin nhắn, kèm theo phản hồi không bắt buộc. Nếu bạn gửi tới tiện ích của mình, sự kiện runtime.onMessage
sẽ được kích hoạt trong mọi khung của tiện ích (ngoại trừ khung của người gửi) hoặc runtime.onMessageExternal
nếu một tiện ích khác. Xin lưu ý rằng tiện ích không thể gửi thông báo đến tập lệnh nội dung bằng phương thức này. Để gửi thông báo đến tập lệnh nội dung, hãy sử dụng tabs.sendMessage
.
Tham số
-
extensionId
chuỗi không bắt buộc
Mã của tiện ích sẽ nhận tin nhắn. Nếu bạn bỏ qua, thông báo sẽ được gửi đến tiện ích/ứng dụng của riêng bạn. Bắt buộc nếu bạn gửi tin nhắn từ một trang web để gửi thông báo qua web.
-
tin nhắn
Bất kỳ
Tin nhắn cần gửi. Thông báo này phải là một đối tượng có thể JSON.
-
tùy chọn
đối tượng không bắt buộc
-
includeTlsChannelId
boolean không bắt buộc
Liệu mã nhận dạng kênh TLS có được chuyển vào onMessageExternal cho các quy trình đang theo dõi sự kiện kết nối hay không.
-
-
số gọi lại
hàm không bắt buộc
Chrome 99 trở lênTham số
callback
sẽ có dạng như sau:(response: any) => void
-
phản hồi
Bất kỳ
Đối tượng phản hồi JSON do trình xử lý thông báo gửi. Nếu xảy ra lỗi trong khi kết nối với tiện ích, lệnh gọi lại sẽ được gọi mà không có đối số và
runtime.lastError
sẽ được đặt thành thông báo lỗi.
-
Giá trị trả về
-
Hứa hẹn<any>
Chrome 99 trở lênLờ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.
sendNativeMessage()
chrome.runtime.sendNativeMessage(
application: string,
message: object,
callback?: function,
)
Gửi một thông báo đến một ứng dụng gốc. Phương thức này yêu cầu quyền "nativeMessaging"
.
Tham số
-
ứng dụng
string
Tên của máy chủ nhắn tin gốc.
-
tin nhắn
đối tượng
Tin nhắn sẽ được chuyển đến máy chủ nhắn tin gốc.
-
số gọi lại
hàm không bắt buộc
Chrome 99 trở lênTham số
callback
sẽ có dạng như sau:(response: any) => void
-
phản hồi
Bất kỳ
Tin nhắn phản hồi do máy chủ nhắn tin gốc gửi. Nếu xảy ra lỗi trong khi kết nối với máy chủ nhắn tin gốc, lệnh gọi lại sẽ được gọi mà không có đối số và
runtime.lastError
sẽ được đặt thành thông báo lỗi.
-
Giá trị trả về
-
Hứa hẹn<any>
Chrome 99 trở lênLờ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.
setUninstallURL()
chrome.runtime.setUninstallURL(
url: string,
callback?: function,
)
Đặt URL được truy cập khi gỡ cài đặt. Dịch vụ này có thể được dùng để dọn dẹp dữ liệu phía máy chủ, phân tích và triển khai các cuộc khảo sát. Tối đa 1023 ký tự.
Tham số
-
url
string
URL sẽ được mở sau khi gỡ cài đặt tiện ích. URL này phải có giao thức http: hoặc https:. Đặt một chuỗi trống để không mở thẻ mới khi gỡ cài đặt.
-
số gọi lại
hàm không bắt buộc
Chrome 45 trở lênTham số
callback
sẽ có dạng như sau:() => void
Giá trị trả về
-
Promise<void>
Chrome 99 trở lênLờ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.
Sự kiện
onBrowserUpdateAvailable
chrome.runtime.onBrowserUpdateAvailable.addListener(
callback: function,
)
Vui lòng sử dụng runtime.onRestartRequired
.
Được kích hoạt khi có bản cập nhật Chrome nhưng chưa được cài đặt ngay lập tức vì cần phải khởi động lại trình duyệt.
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:() => void
onConnect
chrome.runtime.onConnect.addListener(
callback: function,
)
Được kích hoạt khi kết nối được thực hiện từ quá trình tiện ích hoặc tập lệnh nội dung (bằng runtime.connect
).
onConnectExternal
chrome.runtime.onConnectExternal.addListener(
callback: function,
)
Được kích hoạt khi kết nối được thực hiện từ một tiện ích khác (bằng runtime.connect
) hoặc từ một trang web có thể kết nối với bên ngoài.
onConnectNative
chrome.runtime.onConnectNative.addListener(
callback: function,
)
Được kích hoạt khi kết nối được thực hiện từ một ứng dụng gốc. Sự kiện này yêu cầu quyền "nativeMessaging"
. Tính năng này chỉ được hỗ trợ trên ChromeOS.
onInstalled
chrome.runtime.onInstalled.addListener(
callback: function,
)
Được kích hoạt khi tiện ích được cài đặt lần đầu tiên, khi tiện ích được cập nhật lên phiên bản mới và khi Chrome được cập nhật lên phiên bản mới.
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:(details: object) => void
-
chi tiết
đối tượng
-
id
chuỗi không bắt buộc
Cho biết mã của phần mở rộng về mô-đun chia sẻ đã nhập đã được cập nhật. Trường hợp này chỉ xuất hiện nếu "reason" là "shared_module_update".
-
previousVersion
chuỗi không bắt buộc
Cho biết phiên bản trước của tiện ích, vừa được cập nhật. Trạng thái này chỉ xuất hiện nếu "reason" là "update" (cập nhật).
-
lý do
Lý do khiến sự kiện này đang được gửi đi.
-
-
onMessage
chrome.runtime.onMessage.addListener(
callback: function,
)
Được kích hoạt khi thông báo được gửi từ quá trình mở rộng (bằng runtime.sendMessage
) hoặc tập lệnh nội dung (bằng tabs.sendMessage
).
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
tin nhắn
Bất kỳ
-
người gửi
-
sendResponse
hàm
Tham số
sendResponse
sẽ có dạng như sau:() => void
-
giá trị trả về
boolean | không xác định
-
onMessageExternal
chrome.runtime.onMessageExternal.addListener(
callback: function,
)
Được kích hoạt khi tin nhắn được gửi từ một tiện ích khác (của runtime.sendMessage
). Không thể sử dụng trong tập lệnh nội dung.
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
tin nhắn
Bất kỳ
-
người gửi
-
sendResponse
hàm
Tham số
sendResponse
sẽ có dạng như sau:() => void
-
giá trị trả về
boolean | không xác định
-
onRestartRequired
chrome.runtime.onRestartRequired.addListener(
callback: function,
)
Được kích hoạt khi một ứng dụng hoặc thiết bị chạy ứng dụng đó cần được khởi động lại. Ứng dụng nên đóng tất cả cửa sổ vào thời điểm thuận tiện nhất để quá trình khởi động lại diễn ra. Nếu ứng dụng không làm gì, thì quá trình khởi động lại sẽ được thực thi sau khi hết thời gian gia hạn 24 giờ. Hiện tại, sự kiện này chỉ được kích hoạt cho các ứng dụng kiosk Chrome OS.
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:(reason: OnRestartRequiredReason) => void
-
lý do
-
onStartup
chrome.runtime.onStartup.addListener(
callback: function,
)
Được kích hoạt khi hồ sơ đã cài đặt tiện ích này khởi động lần đầu. Sự kiện này không được kích hoạt khi hồ sơ ẩn danh bắt đầu, ngay cả khi tiện ích này đang hoạt động ở chế độ ẩn danh 'phân tách'.
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:() => void
onSuspend
chrome.runtime.onSuspend.addListener(
callback: function,
)
Được gửi đến trang sự kiện ngay trước khi sự kiện bị huỷ tải. Điều này giúp tiện ích có cơ hội dọn dẹp bộ nhớ. Xin lưu ý rằng vì trang đang huỷ tải, nên mọi hoạt động không đồng bộ bắt đầu trong khi xử lý sự kiện này sẽ không đảm bảo sẽ hoàn tất. Nếu có thêm hoạt động cho trang sự kiện xảy ra trước khi bị huỷ tải, sự kiện onSuspendCanceled sẽ được gửi và trang sẽ không bị huỷ tải.
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:() => void
onSuspendCanceled
chrome.runtime.onSuspendCanceled.addListener(
callback: function,
)
Được gửi sau onSuspend để cho biết rằng ứng dụng sẽ không bị huỷ tải.
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:() => void
onUpdateAvailable
chrome.runtime.onUpdateAvailable.addListener(
callback: function,
)
Được kích hoạt khi có bản cập nhật nhưng không được cài đặt ngay lập tức vì ứng dụng hiện đang chạy. Nếu bạn không làm gì, bản cập nhật sẽ được cài đặt vào lần tiếp theo trang nền được huỷ tải. Nếu muốn cài đặt trang nền sớm hơn, bạn có thể gọi chrome.runtime.reload() một cách rõ ràng. Nếu tiện ích của bạn đang sử dụng trang nền liên tục, trang nền tất nhiên sẽ không bao giờ được huỷ tải. Do đó, trừ phi bạn gọi chrome.runtime.reload() theo cách thủ công để phản hồi sự kiện này, bản cập nhật sẽ không được cài đặt cho đến khi Chrome khởi động lại. Nếu không có trình xử lý nào đang theo dõi sự kiện này và tiện ích của bạn có trang nền liên tục, thì tiện ích sẽ hoạt động như thể chrome.runtime.reload() được gọi để phản hồi sự kiện này.
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:(details: object) => void
-
chi tiết
đối tượng
-
version
string
Số phiên bản của bản cập nhật hiện có.
-
-
onUserScriptConnect
chrome.runtime.onUserScriptConnect.addListener(
callback: function,
)
Được kích hoạt khi kết nối được thực hiện từ một tập lệnh người dùng từ tiện ích này.
onUserScriptMessage
chrome.runtime.onUserScriptMessage.addListener(
callback: function,
)
Được kích hoạt khi một thông báo được gửi từ một tập lệnh người dùng được liên kết với cùng một tiện ích.
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
tin nhắn
Bất kỳ
-
người gửi
-
sendResponse
hàm
Tham số
sendResponse
sẽ có dạng như sau:() => void
-
giá trị trả về
boolean | không xác định
-