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

chrome.runtime

Mô tả

Sử dụng chrome.runtime API để 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 viên của API này không yêu cầu bất kỳ quyền nào. Quyền này cần thiết cho connectNative(), sendNativeMessage() và onNativeConnect.

Ví dụ sau đây trình bà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ố lĩnh vực mà tiện ích của bạn có thể sử dụng:

Đang chuyển thông báo: 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 bằng những 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ể chuyể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à chủ. 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 tuỳ 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 pháp này mang lại sự tiện ích, chẳng hạn như chuyển đổi các bản trình bày tài nguyên nội bộ thành các đị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 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, thì đâ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 "update". Chiến dịch này tính cả 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

Để một trang web có thể truy cập vào thành phần được lưu trữ trên một miền khác, trang đó 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 đúng khi đưa thành phần tiện ích vào một trang web. Hai sự 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 web các tài nguyên dễ truy cập và thông thường, tập lệnh nội dung chịu trách nhiệm chèn thành phần tiện ích.

Trong ví dụ này, tiện ích sẽ thêm logo.png vào trang mà nội dung tập lệnh đ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, trong tệp kê khai phải khai báo tài sản đó là tài nguyên có thể truy cập trên web.

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ường, các 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 được mở ra cùng một trang web, hai ngữ cảnh 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 có thể sử dụng tin nhắn truyền để phối hợp giữa 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 chạy giao diện người dùng. Để nhận được 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 cho trình chạy dịch vụ và trình chạy này phản hồi bằng 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 bản khảo sát sau khi gỡ cài đặt để hiểu cách tiện ích có thể phân phát tốt hơn người dùng và cải thiện tỷ lệ giữ chân. Ví dụ sau đây trình bà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 – Tài nguyên có thể truy cập web để biết thêm ví dụ về Runtime API.

Loại

ContextFilter

Chrome 114 trở lên

Bộ lọc để so khớp với một số ngữ cảnh nhất định của phần mở rộng. Ngữ cảnh khớp phải khớp với tất cả bộ lọc được chỉ định; bất kỳ bộ lọc nào không được chỉ định phù hợp với tất cả ngữ cảnh có sẵn. Do đó, bộ lọc `{}` sẽ khớp với tất cả cá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

Chrome 114 trở lên

Enum

"TAB"
Chỉ định loại ngữ cảnh dưới dạng thẻ

"mpn"
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 ngữ cảnh là một 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_console"
Chỉ định loại bối cảnh dưới dạng bảng điều khiển bên.

ExtensionContext

Chrome 114 trở lên

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

ContextType

Loại ngữ cảnh tương ứng với giá trị 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 được 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 đượ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 gắn 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.
documentUrl

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

URL của tài liệu được 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 một tài liệu.
frameId

số

Mã nhận dạng 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 bối cảnh có liên kết với hồ sơ ẩn danh hay không.
tabId

số

Mã của thẻ 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 thẻ.
windowId

số

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 tin nhắn hoặc yêu cầu.

Thuộc tính

documentId

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

Chrome 106 trở lên

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

Vò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 sẽ 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ê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. Thuộc tính 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ó thể đáng tin cậy hay không nếu chúng tôi không thể nhận biết ngay nguồn gốc đó từ URL.
phím 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 kết nối được mở từ một thẻ (bao gồm cả tập lệnh nội dung) và chỉ khi receiver là 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 iframe, thì đó sẽ là URL của iframe chứ không phải là URL của trang lưu trữ iframe đó.

OnInstalledReason

Chrome 44 trở lên

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

Enum

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

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

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

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

OnRestartRequiredReason

Chrome 44 trở lên

Lý do khiến 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. "định kỳ" được dùng khi hệ thống chạy nhiều hơn thời gian hoạt động cho phép đã đặt trong chính sách doanh nghiệp.

Enum

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

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

"định kỳ"
Chỉ định lý do 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 cấu trúc trình xử lý làm nhóm.

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

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

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

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

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

PlatformInfo

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

Thuộc tính

hình cung

PlatformArch

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

PlatformNaclArch

Cấu trúc ứng dụng gốc. Định dạng này có thể khác với vòm trên một số nền tảng.
hệ điều hành

PlatformOs

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

PlatformNaclArch

Chrome 44 trở lên

Cấu trúc ứng dụng gốc. Định dạng này có thể khác với vòm trên một số nền tảng.

Enum

"arm"
Chỉ định kiến trúc ứng dụng gốc làm nhóm thử nghiệm.

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

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

"mips"
Chỉ định kiến trúc ứng dụng gốc dưới dạng 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 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.

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

Được kích hoạt khi cổng bị ngắt kết nối khỏi(các) đầu khác. 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 Thời gian tồn tại của cổng).

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

Sự kiện<functionvoidvoid>

Sự kiện này được kích hoạt khi đầu bên kia của cổng gọi postMessage.

Hàm onMessage.addListener có dạng như sau:
```
(callback: function) => {...}
```
- số gọi lại
  
  hàm
  
  Tham số callback sẽ 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 chuyể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ó 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 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 thì hệ thống sẽ báo 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 hỗ trợ định dạng JSON.

RequestUpdateCheckStatus

Chrome 44 trở lên

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

Enum

"được điều tiết"
Chỉ định rằng hoạt động kiểm tra trạng thái đã được điều tiết. Điều này có thể xảy ra sau các lần kiểm tra lặp đi lặp lại 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ài đặt.

Thuộc tính

id

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

Loại

string

lastError

Điền sẵn thông báo lỗi nếu không gọi được một hàm API; 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 xảy ra lỗi 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 lại 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ề hứa hẹn 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 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, cũng như nhắn tin trên web. 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.

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 thuộc tính này, hệ thống sẽ thử 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 tin nhắn từ một trang web để nhắn tin qua 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 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à tin nhắn có thể được gửi và nhận qua đó. 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,
)

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

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

getBackgroundPage()

Lời hứa Chỉ ở nền trước

chrome.runtime.getBackgroundPage(
  callback?: function,
)

Truy xuất 'cửa sổ' 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, thì 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ì hệ thống đã đặt 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:
```
(backgroundPage?: Window) => void
```
- backgroundPage
  
  Thời lượng không bắt buộc
  
  "Cửa sổ" JavaScript cho trang nền.

Giá trị trả về

Promise<Window | không xác định>

Chrome 99 trở lên

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.

getContexts()

Lời hứa Chrome 116 trở lên Video nhạc 3 trở lên

chrome.runtime.getContexts(
  filter: ContextFilter,
  callback?: function,
)

Tìm nạp thông tin về ngữ cảnh đang hoạt động được liên kết với tiện ích này

Tham số

filter

ContextFilter

Bộ lọc để tìm ngữ cảnh phù hợp. Ngữ cảnh khớp nếu khớp với tất cả các trường được chỉ định trong bộ lọc. Bất kỳ trường chưa chỉ định nào 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
  
  ExtensionContext[]
  
  Ngữ cảnh phù hợ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 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.

getManifest()

chrome.runtime.getManifest()

Trả về thông tin chi tiết về ứng dụng hoặc tiện ích qua 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()

Lời hứa Chỉ ở nền trước

chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
)

Trả về 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ên

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.

getPlatformInfo()

Lời hứa

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
  
  PlatformInfo

Giá trị trả về

Promise<PlatformInfo>

Chrome 99 trở lên

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.

getURL()

chrome.runtime.getURL(
  path: string,
)

Chuyển đổi một đườ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.

Tham số

đường dẫn

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 tài nguyên đó.

Giá trị trả về

string

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

openOptionsPage()

Lời hứa

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 những gì Chrome hỗ trợ tại thời điểm đó. Ví dụ: bạn có thể mở trang trong một thẻ mới, trong chrome://extensions, trong một Ứng dụng, hoặc chỉ tập trung vào một trang tuỳ chọn đang mở. Việc này sẽ không bao giờ yêu cầu trang 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ề

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

Chrome 99 trở lên

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.

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 dùng phương thức chrome.runtime.restart().

requestUpdateCheck()

Lời hứa

chrome.runtime.requestUpdateCheck(
  callback?: function,
)

Yêu cầu kiểm tra bản cập nhật ngay lập tức đối với ứ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 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ỉ phù hợp để gọi trong những 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 ứng dụng đã lỗi thời và bạn muốn nhắc người dùng cập nhật. Trong hầu hết các trường hợp sử dụng requestUpdateCheck khác, chẳng hạn như gọi phương thức này vô điều kiện dựa trên bộ tính giờ lặp lại, có thể chỉ làm 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ề 2 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 quả
  
  đối tượng
  
  Chrome 109 trở lên
  
  Đối tượng RequestUpdateCheckResult chứa trạng thái của quá trình kiểm tra bản cập nhật và mọi thông tin chi tiết về kết quả (nếu có)
  - trạng thái
    
    RequestUpdateCheckStatus
    
    Kết quả của lần 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ì đó là 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ên

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.

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()

Lời hứa Chrome 53 trở lên

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 vài giây đã cho. Nếu được gọi lại trước khi thời gian kết thúc, 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ỷ. Hoạt động không hoạt động ở chế độ không phải kiosk. Chỉ tiện ích đầu tiên chỉ cho phép gọi lại API này nhiều lần để gọi API này.

Tham 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 nhấn -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ề

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

Chrome 99 trở lên

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.

sendMessage()

Lời hứa

chrome.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
  callback?: function,
)

Gửi một tin nhắn duy nhất cho 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 duy nhất, kèm theo phản hồi không bắt buộc. Nếu gửi tới tiện ích của bạn, 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 là một tiện ích khác. 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.

Tham số

extensionId

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

Mã của tiện ích mà bạn muốn gửi tin nhắn đến. Nếu bạn bỏ qua thuộc tính này, thông báo sẽ được gửi tới 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 để nhắn tin qua web.
tin nhắn

bất kỳ

Tin nhắn cần gửi. Thông báo này phải là đối tượng có thể định dạng JSON.
tùy chọ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 đối với 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ên

Tham số callback sẽ có dạng như sau:
```
(response: any) => void
```
- phản hồi
  
  bất kỳ
  
  Đố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, thì 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ề

Cam kết<bất kỳ>

Chrome 99 trở lên

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.

sendNativeMessage()

Lời hứa

chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
  callback?: function,
)

Gửi một tin nhắn duy nhất tới ứ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

Thông báo 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ên

Tham số callback sẽ có dạng như sau:
```
(response: any) => void
```
- phản hồi
  
  bất kỳ
  
  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, thì 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ề

Cam kết<bất kỳ>

Chrome 99 trở lên

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.

setUninstallURL()

Lời hứa

chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
)

Đặt URL được truy cập khi gỡ cài đặt. Công cụ này có thể dùng để dọn sạch dữ liệu phía máy chủ, phân tích và triển khai các bài khảo sát. Tối đa 1023 ký tự.

Tham số

url

string

URL được mở sau khi gỡ cài đặt tiện ích. URL này phải có lượ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ên

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

Giá trị trả về

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

Chrome 99 trở lên

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.

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 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ừ một quá trình mở rộng hoặc một tập lệnh nội dung (của runtime.connect).

Tham số

số gọi lại

hàm

Tham số callback sẽ 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 kết nối được thực hiện từ một tiện ích khác (của runtime.connect) hoặc từ một trang web có thể kết nối bên ngoài.

Tham số

số gọi lại

hàm

Tham số callback sẽ 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 kết nối được thực hiện từ ứng dụng gốc. Sự kiện này yêu cầu quyền "nativeMessaging". Ứng dụng này chỉ được hỗ trợ trên ChromeOS.

Tham số

số gọi lại

hàm

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

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

onMessage

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

Được kích hoạt khi thư được gửi từ quá trình gia hạn (của runtime.sendMessage) hoặc từ tập lệnh nội dung (của 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 kỳ
- người gửi
  
  MessageSender
- sendResponse
  
  hàm
  
  Tham số sendResponse sẽ có dạng như sau:
```
() => void
```
- returns
  boolean | chưa 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 kỳ
- người gửi
  
  MessageSender
- sendResponse
  
  hàm
  
  Tham số sendResponse sẽ có dạng như sau:
```
() => void
```
- returns
  boolean | chưa xác định

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 phải đóng tất cả cửa sổ sớm nhất có thể để quá trình khởi động lại có thể diễn ra. Nếu ứng dụng không làm gì cả, hệ thống sẽ thực thi quá trình khởi động lại 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
  
  OnRestartRequiredReason

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 tiên. Sự kiện này không được kích hoạt khi một hồ sơ ẩn danh đã bắt đầu, ngay cả khi tiện ích này đang hoạt động ở chế độ "phân chia" chế độ ẩn danh.

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,
)

Gửi đến trang sự kiện ngay trước khi huỷ tải. Điều này tạo cho tiện ích cơ hội thực hiện một số thao tác dọn dẹp. Xin lưu ý rằng vì trang đang huỷ tải, nên mọi hoạt động không đồng bộ được bắt đầu trong khi xử lý sự kiện này đều không đảm bảo sẽ hoàn tất. Nếu có nhiều hoạt động khác cho trang sự kiện xảy ra trước khi trang 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 sau cùng thì ứ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 vì ứng dụng đang chạy. Nếu bạn không làm gì cả, bản cập nhật sẽ được cài đặt vào lần tiếp theo khi trang nền bị huỷ tải. Nếu muốn cài đặt 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 một trang nền liên tục thì trang nền tất nhiên sẽ không bao giờ bị 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 tự khởi động lại vào lần tiếp theo. 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 115 trở lên Video nhạc 3 trở lên

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

Được kích hoạt khi kết nối được thực hiện từ tập lệnh người dùng từ tiện ích này.

Tham số

số gọi lại

hàm

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

onUserScriptMessage

Chrome 115 trở lên Video nhạc 3 trở lên

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

Được kích hoạt khi thư đượ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.

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 kỳ
- người gửi
  
  MessageSender
- sendResponse
  
  hàm
  
  Tham số sendResponse sẽ có dạng như sau:
```
() => void
```
- returns
  boolean | chưa xác định