Chrome hiện hỗ trợ không gian tên browser.* được chuẩn hoá (có từ Chrome 148). Chúng tôi đang dần cập nhật tài liệu. Hãy đọc thêm trong hướng dẫn chuyển đổi của chúng tôi.

Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

browser.runtime

Mô tả

Sử 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 URL đủ điều kiện.

Hầu hết các thành phần của API này đều không yêu cầu quyền. Bạn cần có quyền này để sử dụng connectNative(), sendNativeMessage() và onNativeConnect.

Ví dụ sau đây cho thấy 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 cung cấp các phương thức hỗ trợ một số khía cạnh mà tiện ích của bạn có thể sử dụng:

Truyền thông báo: Tiện ích của bạn có thể giao tiếp với nhiều bối cảnh trong tiện ích và với các tiện ích khác bằ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ằng cách sử dụng connectNative() và sendNativeMessage().

Truy cập vào 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ố 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ý vòng đời và các lựa chọn 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 cung cấp tiện ích như chuyển đổi cách trình bày 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 thức này chỉ có trên ChromeOS và chủ yếu dùng để hỗ trợ việc triển khai chế độ 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 chưa đóng gói được tải lại, thì thao tác này được coi là một bản cập nhật. Điều này có nghĩa là sự kiện browser.runtime.onInstalled sẽ kích hoạt với lý do "update". Điều này bao gồm cả trường hợp tiện ích được tải lại bằng browser.runtime.reload().

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

Thêm hình ảnh vào trang web

Để một trang web có thể truy cập vào một thành phần đượ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">). Điều này cũng áp dụng cho việc thêm một thành phần tiện ích vào một trang web. Hai điểm khác biệt là các 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à thường thì tập lệnh nội dung chịu trách nhiệm chèn các thành phần của 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, bạn phải khai báo thành phần này là tài nguyên có thể truy cập được 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 = browser.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ường, tập lệnh nội dung của tiện ích cần dữ liệu do một phần khác của tiện ích quản lý, chẳng hạn như trình chạy dịch vụ. Giống như hai cửa sổ trình duyệt mở cùng một trang web, hai ngữ cảnh này không thể trực tiếp truy cập vào giá trị của nhau. Thay vào đó, tiện ích có thể sử dụng tính năng truyền thông báo để điều phối trên các bối 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 chạy giao diện người dùng. Để lấy dữ liệu này, ứng dụng 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à trình chạy dịch vụ sẽ 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
browser.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'
};

browser.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 bản khảo sát sau khi gỡ cài đặt để tìm hiểu 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 đây cho thấy cách thêm chức năng này.

background.js:

browser.runtime.onInstalled.addListener(details => {
  if (details.reason === browser.runtime.OnInstalledReason.INSTALL) {
    browser.runtime.setUninstallURL('https://example.com/extension-survey');
  }
});

Ví dụ

Hãy xem Bản minh hoạ Manifest V3 – Tài nguyên có thể truy cập trên web để biết thêm các ví dụ về API thời gian chạy.

Loại

ContextFilter

Chrome 114 trở lên

Một bộ lọc để so khớp với một số bối cảnh tiện ích nhất định. Bối cảnh phù hợp phải khớp với tất cả bộ lọc được chỉ định; mọi bộ lọc không được chỉ định đều khớp với tất cả bối cảnh có sẵn. Do đó, bộ lọc `{}` sẽ khớp với tất cả bối cảnh hiện có.

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

Chrome 114 trở lên

Enum

"TAB"
Chỉ định loại bối cảnh là một thẻ

"POPUP"
Chỉ định loại ngữ cảnh là cửa sổ bật lên của tiện ích

"BACKGROUND"
Chỉ định loại bối cảnh là 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_PANEL"
Chỉ định loại bối cảnh là bảng điều khiển bên.

"DEVELOPER_TOOLS"
Chỉ định loại bối cảnh là công cụ cho nhà phát triển.

ExtensionContext

Chrome 114 trở lên

Bối cảnh lưu trữ nội dung tiện ích.

Thuộc tính

contextId

chuỗi

Giá trị nhận dạng riêng biệt cho bối cảnh này
contextType

ContextType

Loại bối cảnh tương ứng.
documentId

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

UUID cho 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 này không được lưu trữ trong 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 kết với ngữ cảnh này hoặc không xác định nếu ngữ cảnh không được lưu trữ trong 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 ngữ cảnh này hoặc không xác định nếu ngữ cảnh không được lưu trữ trong tài liệu.
frameId

số

Mã nhận dạng của khung cho bối cảnh này hoặc -1 nếu bối cảnh này không được lưu trữ trong một khung.
ẩn danh

boolean

Liệu bối cảnh có liên kết với hồ sơ ẩn danh hay không.
tabId

số

Mã nhận dạng của thẻ cho bối cảnh này hoặc -1 nếu bối cảnh này không được lưu trữ trong một thẻ.
windowId

số

Mã nhận dạng của cửa sổ cho bối cảnh này hoặc -1 nếu bối cảnh này không được lưu trữ trong một cửa sổ.

ExtensionLoadDetails

Chrome 157 trở lên

Thông tin chi tiết về sự kiện tải tiện ích.

Thuộc tính

previousVersion

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

Cho biết phiên bản trước của tiện ích. Trường này chỉ xuất hiện nếu "reason" là "update" hoặc "enable". Nếu "reason" là "update", thì đây là phiên bản của tiện ích trước khi được cập nhật. Nếu "reason" là "enable", thì đây là phiên bản hiện tại của tiện ích.
lý do

OnLoadedReason

Lý do sự kiện này được gửi đi.

MessageSender

Một đố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ên

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ên

Vòng đời của tài liệu đã mở kết nối tại thời điểm cổng được tạo. 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

number không bắt buộc

Khung đã mở kết nối. 0 cho khung cấp cao nhất, số dương cho khung con. Giá trị này chỉ được đặt khi tab được đặt.
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ên

Tê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ên

Nguồn gốc của trang hoặc khung đã mở kết nối. Nguồn gốc có thể khác với thuộc tính url (ví dụ: about:blank) hoặc có thể không rõ ràng (ví dụ: iframe trong hộp cát). Điều này giúp 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ể biết ngay từ URL.
thẻ

Tab 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 kết nối được mở từ một thẻ (bao gồm cả tập lệnh nội dung) và chỉ khi trình nhận là một tiện ích chứ không phải ứng dụng.
tlsChannelId

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

Mã nhận dạng kênh TLS 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 một iframe, thì đó sẽ là URL của iframe chứ không phải URL của trang lưu trữ iframe đó.

OnInstalledReason

Chrome 44 trở lên

Lý do sự kiện này được gửi đi.

Enum

"install"
Chỉ định lý do của sự kiện là một lượt cài đặt.

"update"
Chỉ định lý do của sự kiện là bản cập nhật tiện ích.

"chrome_update"
Chỉ định lý do của sự kiện là bản cập nhật Chrome.

"shared_module_update"
Chỉ định lý do của sự kiện là bản cập nhật cho một mô-đun dùng chung.

OnLoadedReason

Chrome 157 trở lên

Lý do sự kiện này được gửi đi.

Enum

"install"
Tiện ích mới được cài đặt.

"update"
Tiện ích đã được tải lại sau khi cập nhật.

"browser_update"
Trình duyệt đã được cập nhật lên phiên bản mới.

"enable"
Tiện ích đã được bật lại từ trạng thái tắt.

"startup"
Tiện ích đang được tải trong quá trình khởi động trình duyệt.

"reload"
Tiện ích đã được tải lại (ví dụ: thông qua chrome.runtime.reload() hoặc người dùng đã tải lại tiện ích theo cách thủ công).

OnRestartRequiredReason

Chrome 44 trở lên

Lý do sự kiện đượ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 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. "periodic" đượ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.

Enum

"app_update"
Chỉ định lý do của sự kiện là bản cập nhật cho ứng dụng.

"os_update"
Chỉ định lý do của sự kiện là bản cập nhật cho hệ điều hành.

"periodic"
Chỉ định lý do của sự kiện là khởi động lại ứng dụng định kỳ.

PlatformArch

Chrome 44 trở lên

Kiến trúc bộ xử lý của máy.

Enum

"arm"
Chỉ định kiến trúc bộ xử lý là arm.

"arm64"
Chỉ định kiến trúc bộ xử lý là arm64.

"x86-32"
Chỉ định kiến trúc bộ xử lý là x86-32.

"x86-64"
Chỉ định kiến trúc bộ xử lý là x86-64.

"mips"
Chỉ định cấu trúc bộ xử lý là mips.

"mips64"
Chỉ định kiến trúc bộ xử lý là mips64.

"riscv64"
Chỉ định cấu trúc bộ xử lý là riscv64.

PlatformInfo

Một đối tượng chứa thông tin về nền tảng hiện tại.

Thuộc tính

vòm

PlatformArch

Kiến trúc bộ xử lý của máy.
nacl_arch

PlatformNaclArch không bắt buộc

Ngừng sử dụng kể từ Chrome 149

Thuộc tính này không còn được dùng nữa sau khi Native Client bị xoá hoàn toàn.
Kiến trúc ứng dụng gốc. Giá trị này có thể khác với arch trên một số nền tảng.
os

PlatformOs

Hệ điều hành mà Chrome đang chạy.

PlatformNaclArch

Chrome 44 trở lên Không dùng nữa kể từ Chrome 149

Enum này không còn được dùng nữa sau khi Native Client bị xoá hoàn toàn.

Kiến trúc ứng dụng gốc. Điều này có thể khác với kiến trúc trên một số nền tảng.

Enum

"arm"
Chỉ định kiến trúc ứng dụng gốc là arm.

"x86-32"
Chỉ định kiến 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 kiến trúc ứng dụng gốc là mips.

"mips64"
Chỉ định kiến trúc ứng dụng gốc là mips64.

PlatformOs

Chrome 44 trở lên

Hệ điều hành mà Chrome đang chạy.

Enum

"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.

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

chuỗi

Tên của cổng, như được chỉ định trong lệnh gọi đến runtime.connect.
onDisconnect

Event<functionvoidvoid>

Được kích hoạt khi cổng bị ngắt kết nối khỏi(các) đầu kia. runtime.lastError có thể được đặt nếu cổng bị ngắt kết nối do lỗi. Nếu cổng bị đóng thông qua disconnect, 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 hoạt động của cổng).

Hàm onDisconnect.addListener có dạng như sau:
```
(callback: function) => {...}
```
- callback
  
  hàm
  
  Tham số callback có dạng như sau:
```
(port: Port) => void
```
  - cổng
    
    Cổng
onMessage

Event<functionvoidvoid>

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 có dạng như sau:
```
(callback: function) => {...}
```
- callback
  
  hàm
  
  Tham số callback có dạng như sau:
```
(message: any, port: Port) => void
```
  - tin nhắn
    
    bất kỳ
  - cổng
    
    Cổng
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 truyền đến 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 sẽ không có hiệu lực. 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 có dạng như sau:
```
() => {...}
```
postMessage

void

Gửi thông báo đến đầu kia của cổng. Nếu cổng bị ngắt kết nối, hệ thống sẽ gửi một lỗi.

Hàm postMessage có dạng như sau:
```
(message: any) => {...}
```
- tin nhắn
  
  bất kỳ
  
  Chrome 52 trở lên
  
  Tin nhắn cần gửi. Đối tượng này phải có thể chuyển đổi thành JSON.

RequestUpdateCheckStatus

Chrome 44 trở lên

Kết quả của việc kiểm tra bản cập nhật.

Enum

"throttled"
Cho biết rằng quá trình kiểm tra trạng thái đã bị điều tiết. Điều này có thể xảy ra sau khi bạn 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ó một bản cập nhật để cài đặt.

Thuộc tính

id

Mã của tiện ích/ứng dụng.

Loại

chuỗi

lastError

Được điền sẵn thông báo lỗi nếu không gọi được hàm API; nếu không thì không xác định. Giá trị này chỉ được xác định trong phạm vi của lệnh gọi lại của hàm đó. Nếu xảy ra lỗi nhưng runtime.lastError không được truy cập 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 đã tạo 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,
): Port

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 cho 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à nhắn tin trên web. Xin lưu ý rằng thao tá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. Tiện ích có thể kết nối với tập lệnh nội dung được nhúng trong các thẻ thông qua tabs.connect.

Thông số

extensionId

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

Mã nhận dạng 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 gửi tin nhắn từ một trang web cho tính năng nhắn tin trên web.
connectInfo

object 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 chuyể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

Cổng mà qua đó bạn có thể gửi và nhận thư. Sự kiện onDisconnect của cổng sẽ được kích hoạt nếu tiện ích không tồn tại.

connectNative()

chrome.runtime.connectNative(
  application: string,
): Port

Kết nối với một ứng dụng gốc trong máy chủ lưu trữ. Phương thức này yêu cầu quyền "nativeMessaging". Hãy xem phần Nhắn tin gốc để biết thêm thông tin.

Thông số

ứng dụng

chuỗi

Tên của ứng dụng đã đăng ký để kết nối.

Giá trị trả về

Cổng

Cổng mà qua đó có thể gửi và nhận tin nhắn bằng ứng dụng

getBackgroundPage()

Chỉ chạy trên nền trước Ngừng sử dụng kể từ Chrome 133

chrome.runtime.getBackgroundPage(): Promise<Window | undefined>

Trang nền không tồn tại trong tiện ích MV3.

Truy xuất đối tượng "window" JavaScript cho trang nền đang 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.

Giá trị trả về

Promise<Window | undefined>

Chrome 99 trở lên

getContexts()

Chrome 116 trở lên MV3 trở lên

chrome.runtime.getContexts(
  filter: ContextFilter,
): Promise<ExtensionContext[]>

Tìm nạp thông tin về bối cảnh đang hoạt động liên quan đến tiện ích này

Thông số

filter

ContextFilter

Bộ lọc để tìm bối cảnh phù hợp. Một bối cảnh sẽ khớp nếu khớp với tất cả các trường được chỉ định trong bộ lọc. Mọi trường không được chỉ định trong bộ lọc đều khớp với tất cả bối cảnh.

Giá trị trả về

<ExtensionContext[]> hứa hẹn

Lời hứa sẽ giải quyết bằng các bối cảnh phù hợp (nếu có).

getManifest()

chrome.runtime.getManifest(): object

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 chuyển đổ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()

Chỉ nền trước

chrome.runtime.getPackageDirectoryEntry(): Promise<DirectoryEntry>

Trả về DirectoryEntry cho thư mục gói.

Giá trị trả về

Promise<DirectoryEntry>

Chrome 122 trở lên

getPlatformInfo()

chrome.runtime.getPlatformInfo(): Promise<PlatformInfo>

Trả về thông tin về nền tảng hiện tại.

Giá trị trả về

Promise<PlatformInfo>

Chrome 99 trở lên

Lời hứa sẽ giải quyết bằng thông tin về nền tảng hiện tại.

getURL()

chrome.runtime.getURL(
  path: string,
): 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 URL đủ điều kiện.

Thông số

đường dẫn

chuỗi

Đường dẫn đến một tài nguyên trong ứng dụng/tiện ích được biểu thị tương ứng với thư mục cài đặt của tài nguyên đó.

Giá trị trả về

chuỗi

URL đủ điều kiện đến tài nguyên.

getVersion()

Chrome 143 trở lên

chrome.runtime.getVersion(): string

Trả về phiên bản của tiện ích như được khai báo trong tệp kê khai.

Giá trị trả về

chuỗi

Phiên bản của tiện ích.

openOptionsPage()

chrome.runtime.openOptionsPage(): Promise<void>

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 hoặc options_page của tệp kê khai hoặc nội dung mà Chrome hỗ trợ tại thời điểm đó. Ví dụ: trang này 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ở. Thao tác này sẽ không bao giờ khiến trang của 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ì một lý do nào khác, thì lệnh gọi lại sẽ đặt lastError.

Giá trị trả về

Promise<void>

Chrome 99 trở lên

reload()

chrome.runtime.reload(): void

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(): Promise<object>

Yêu cầu kiểm tra ngay lập tức xem có bản cập nhật cho ứng dụng/tiện ích này hay không.

Quan trọng: Hầu hết các tiện ích/ứng dụng không nên sử 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ố trường hợp rất hạn chế, chẳng hạn như nếu tiện ích của bạn giao tiếp với một dịch vụ phụ trợ và dịch vụ phụ trợ đó xác định rằng phiên bản tiện ích của ứng dụng khách đã quá cũ và bạn muốn nhắc người dùng cập nhật. Hầu hết các cách sử dụng khác của requestUpdateCheck, chẳng hạn như gọi hàm này vô điều kiện dựa trên bộ hẹn giờ lặp lại, có thể chỉ làm lãng phí tài nguyên của 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.

Giá trị trả về

<object> hứa hẹn

Chrome 109 trở lên

restart()

chrome.runtime.restart(): void

Khởi động lại thiết bị ChromeOS khi ứng dụng chạy ở chế độ kiosk. Nếu không, thì không có hoạt động nào.

restartAfterDelay()

Chrome 53 trở lên

chrome.runtime.restartAfterDelay(
  seconds: number,
): Promise<void>

Khởi động lại thiết bị ChromeOS khi ứng dụng chạy ở chế độ kiosk sau số giây đã cho. Nếu được gọi lại trước khi hết thời gian, quá trình khởi động lại sẽ bị trì hoãn. Nếu được gọi với giá trị -1, thì quá trình khởi động lại sẽ bị huỷ. Đây là lệnh không hoạt động ở chế độ không phải kiosk. Chỉ tiện ích đầu tiên gọi API này mới được phép gọi nhiều lần.

Thông số

giây

số

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ỷ một lần khởi động lại theo lịch.

Giá trị trả về

Promise<void>

Chrome 99 trở lên

Lời hứa sẽ được thực hiện khi yêu cầu khởi động lại được lên lịch lại thành công.

sendMessage()

chrome.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
): Promise<any>

Gửi một thông báo đế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 thông báo, kèm theo phản hồi không bắt buộc. Nếu gửi đến tiện ích của bạn, sự kiện runtime.onMessage sẽ được kích hoạt trong mọi khung hình của tiện ích (ngoại trừ khung hình của người gửi) hoặc runtime.onMessageExternal nếu là một tiện ích khác. Xin lưu ý rằng các 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.

Thông số

extensionId

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

Mã của tiện ích để gửi thông báo. 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 gửi thông báo từ một trang web cho nhắn tin trên web.
tin nhắn

bất kỳ

Tin nhắn cần gửi. Thông báo này phải là một đối tượng có thể chuyển đổi thành JSON.
tùy chọn

object 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 truyền vào onMessageExternal cho các quy trình đang theo dõi sự kiện kết nối hay không.

Giá trị trả về

Promise<any>

Chrome 99 trở lên

Tính năng hỗ trợ Promise đã được thêm vào bối cảnh tiện ích trong Chrome 99. Khi giao tiếp từ một trang web đến một tiện ích, bạn có thể sử dụng lời hứa từ Chrome 118.

sendNativeMessage()

chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
): Promise<any>

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".

Thông số

ứng dụng

chuỗi

Tên của máy chủ nhắn tin gốc hoặc thông tin chi tiết về mục tiêu.
tin nhắn

đối tượng

Thông báo sẽ được chuyển đến máy chủ nhắn tin gốc.

Giá trị trả về

Promise<any>

Chrome 99 trở lên

setUninstallURL()

chrome.runtime.setUninstallURL(
  url: string,
): Promise<void>

Đặt URL cần truy cập khi gỡ cài đặt. Dữ liệu 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 khảo sát. Tối đa 1023 ký tự.

Thông số

url

chuỗi

URL sẽ mở sau khi tiện ích được gỡ cài đặt. 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.

Giá trị trả về

Promise<void>

Chrome 99 trở lên

Lời hứa sẽ giải quyết khi URL gỡ cài đặt được đặt. Nếu URL đã cho không hợp lệ, thì lời hứa sẽ bị từ chối.

Sự kiện

onBrowserUpdateAvailable

Không dùng nữa

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 không được cài đặt ngay lập tức vì cần phải khởi động lại trình duyệt.

Thông số

callback

hàm

Tham số callback 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ừ một quy trình tiện ích hoặc tập lệnh nội dung (bằng runtime.connect).

Thông số

callback

hàm

Tham số callback có dạng như sau:
```
(port: Port) => void
```
- cổng
  
  Cổng

onConnectExternal

chrome.runtime.onConnectExternal.addListener(
  callback: function,
)

Được kích hoạt khi một kết nối được tạo 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 bên ngoài.

Thông số

callback

hàm

Tham số callback có dạng như sau:
```
(port: Port) => void
```
- cổng
  
  Cổng

onConnectNative

Chrome 76 trở lên

chrome.runtime.onConnectNative.addListener(
  callback: function,
)

Được kích hoạt khi một 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". Chỉ được hỗ trợ trên ChromeOS.

Thông số

callback

hàm

Tham số callback có dạng như sau:
```
(port: Port) => void
```
- cổng
  
  Cổng

onEnabled

Chrome 155 trở lên

chrome.runtime.onEnabled.addListener(
  callback: function,
)

Được kích hoạt khi một tiện ích chuyển từ trạng thái tắt sang trạng thái bật.

Thông số

callback

hàm

Tham số callback có dạng như sau:
```
() => void
```

onExtensionLoaded

Chrome 157 trở lên

chrome.runtime.onExtensionLoaded.addListener(
  callback: function,
)

Được kích hoạt khi tiện ích được thêm vào nhóm tiện ích đang hoạt động. Điều này có thể xảy ra trong nhiều trường hợp: khi tiện ích được cài đặt lần đầu, được cập nhật lên phiên bản mới, được bật lại sau khi bị tắt, được tải lại, được tải trong quá trình khởi động trình duyệt hoặc được tải khi trình duyệt được cập nhật lên phiên bản mới.

Thông số

callback

hàm

Tham số callback có dạng như sau:
```
(details: ExtensionLoadDetails) => void
```
- chi tiết
  
  ExtensionLoadDetails

onInstalled

chrome.runtime.onInstalled.addListener(
  callback: function,
)

Được kích hoạt khi tiện ích được cài đặt lần đầu, 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.

Thông số

callback

hàm

Tham số callback 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 tiện ích mô-đun dùng chung đã nhập và được cập nhật. Trường 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 này chỉ xuất hiện nếu "reason" (lý do) là "update" (cập nhật).
  - lý do
    
    OnInstalledReason
    
    Lý do sự kiện này được gửi đi.

onMessage

chrome.runtime.onMessage.addListener(
  callback: function,
)

Được kích hoạt khi một thông báo được gửi từ runtime.sendMessage hoặc tabs.sendMessage.

Thông số

callback

hàm

Tham số callback có dạng như sau:
```
(message: any, sender: MessageSender, sendResponse: function) => boolean | Promise<any> | undefined
```
- tin nhắn
  
  bất kỳ
- người gửi
  
  MessageSender
- sendResponse
  
  hàm
  
  Tham số sendResponse có dạng như sau:
```
(response?: any) => void
```
  - phản hồi
    
    bất kỳ không bắt buộc
    
    Nội dung phản hồi để trả về cho người gửi tin nhắn.
- returns
  boolean | Promise<any> | undefined

onMessageExternal

chrome.runtime.onMessageExternal.addListener(
  callback: function,
)

Được kích hoạt khi một thông báo được gửi từ một tiện ích khác (bằng runtime.sendMessage). Không thể dùng trong tập lệnh nội dung.

Thông số

callback

hàm

Tham số callback có dạng như sau:
```
(message: any, sender: MessageSender, sendResponse: function) => boolean | Promise<any> | undefined
```
- tin nhắn
  
  bất kỳ
- người gửi
  
  MessageSender
- sendResponse
  
  hàm
  
  Tham số sendResponse có dạng như sau:
```
(response?: any) => void
```
  - phản hồi
    
    bất kỳ không bắt buộc
    
    Nội dung phản hồi để trả về cho người gửi tin nhắn.
- returns
  boolean | Promise<any> | undefined

onRestartRequired

chrome.runtime.onRestartRequired.addListener(
  callback: function,
)

Được kích hoạt khi cần khởi động lại một ứng dụng hoặc thiết bị chạy ứng dụng đó. Ứng dụng nên đóng tất cả cửa sổ sớm nhất có thể để quá trình khởi động lại diễn ra. Nếu ứng dụng không làm gì, thì hệ thống sẽ buộc khởi động lại sau khi hết thời gian ân 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 của ChromeOS.

Thông số

callback

hàm

Tham số callback có dạng như sau:
```
(reason: OnRestartRequiredReason) => void
```
- lý do
  
  OnRestartRequiredReason

onStartup

chrome.runtime.onStartup.addListener(
  callback: function,
)

Được kích hoạt khi một hồ sơ đã cài đặt tiện ích này khởi động lần đầu tiên. Sự kiện này không được kích hoạt khi hồ sơ ẩn danh được khởi động, ngay cả khi tiện ích này đang hoạt động ở chế độ ẩn danh "phân tách".

Thông số

callback

hàm

Tham số callback 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 trang đó bị huỷ tải. Điều này giúp tiện ích có cơ hội dọn dẹp. Xin lưu ý rằng vì trang đang huỷ tải, nên mọi thao tác không đồng bộ bắt đầu trong khi xử lý sự kiện này đều không được đảm bảo sẽ hoàn tất. Nếu có thêm hoạt động cho trang sự kiện trước khi trang này bị huỷ tải, thì sự kiện onSuspendCanceled sẽ được gửi và trang sẽ không bị huỷ tải.

Thông số

callback

hàm

Tham số callback 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.

Thông số

callback

hàm

Tham số callback 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 đ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 sớm hơn, bạn có thể gọi rõ ràng chrome.runtime.reload(). Nếu tiện ích của bạn đang sử dụng trang nền cố định, thì tất nhiên trang nền sẽ không bao giờ được huỷ tải. Vì vậy, 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 lần tiếp theo Chrome tự 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 cố định, 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.

Thông số

callback

hàm

Tham số callback có dạng như sau:
```
(details: object) => void
```
- chi tiết
  
  đối tượng
  - phiên bản
    
    chuỗi
    
    Số phiên bản của bản cập nhật hiện có.

onUserScriptConnect

Chrome 115 trở lên MV3 trở lên

chrome.runtime.onUserScriptConnect.addListener(
  callback: function,
)

Được kích hoạt khi một kết nối được tạo từ tập lệnh người dùng của tiện ích này.

Thông số

callback

hàm

Tham số callback có dạng như sau:
```
(port: Port) => void
```
- cổng
  
  Cổng

onUserScriptMessage

Chrome 115 trở lên MV3 trở lên

chrome.runtime.onUserScriptMessage.addListener(
  callback: function,
)

Được kích hoạt khi một thông báo được gửi từ tập lệnh người dùng liên kết với cùng một tiện ích.

Thông số

callback

hàm

Tham số callback có dạng như sau:
```
(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
```
- tin nhắn
  
  bất kỳ
- người gửi
  
  MessageSender
- sendResponse
  
  hàm
  
  Tham số sendResponse có dạng như sau:
```
(response?: any) => void
```
  - phản hồi
    
    bất kỳ không bắt buộc
    
    Nội dung phản hồi để trả về cho người gửi tin nhắn.
- returns
  boolean | undefined

browser.runtime Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Mô tả

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

Hành vi của tiện ích đã giải nén

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

Thêm hình ảnh vào trang web

Gửi dữ liệu từ tập lệnh nội dung đến trình chạy dịch vụ

Thu thập ý kiến phản hồi về việc gỡ cài đặt

Ví dụ

Loại

ContextFilter

Thuộc tính

ContextType

Enum

ExtensionContext

Thuộc tính

ExtensionLoadDetails

Thuộc tính

MessageSender

Thuộc tính

OnInstalledReason

Enum

OnLoadedReason

Enum

OnRestartRequiredReason

Enum

PlatformArch

Enum

PlatformInfo

Thuộc tính

PlatformNaclArch

Enum

PlatformOs

Enum

Port

Thuộc tính

RequestUpdateCheckStatus

Enum

Thuộc tính

id

Loại

lastError

Loại

Thuộc tính

Phương thức

connect()

Thông số

Giá trị trả về

connectNative()

Thông số

Giá trị trả về

getBackgroundPage()

Giá trị trả về

getContexts()

Thông số

Giá trị trả về

getManifest()

Giá trị trả về

getPackageDirectoryEntry()

Giá trị trả về

getPlatformInfo()

Giá trị trả về

getURL()

Thông số

Giá trị trả về

getVersion()

Giá trị trả về

openOptionsPage()

Giá trị trả về

reload()

requestUpdateCheck()

Giá trị trả về

restart()

restartAfterDelay()

Thông số

Giá trị trả về

sendMessage()

Thông số

Giá trị trả về

sendNativeMessage()

browser.runtime