chrome.alarms

Mô tả

Sử dụng API chrome.alarms để lên lịch chạy mã định kỳ hoặc vào một thời điểm cụ thể trong tương lai.

Quyền

alarms

Tệp kê khai

Để sử dụng API chrome.alarms, hãy khai báo quyền "alarms" trong tệp kê khai:

{
  "name": "My extension",
  ...
  "permissions": [
    "alarms"
  ],
  ...
}

Ví dụ

Các ví dụ sau đây cho biết cách sử dụng và phản hồi báo thức. Để dùng thử API này, hãy cài đặt ví dụ về Alarm API từ kho lưu trữ chrome-extension-samples.

Đặt báo thức

Ví dụ sau đây đặt báo thức trong trình chạy dịch vụ khi tiện ích được cài đặt:

service-worker.js:

chrome.runtime.onInstalled.addListener(async ({ reason }) => {
  if (reason !== 'install') {
    return;
  }

  // Create an alarm so we have something to look at in the demo
  await chrome.alarms.create('demo-default-alarm', {
    delayInMinutes: 1,
    periodInMinutes: 1
  });
});

Phản hồi chuông báo

Ví dụ sau đây đặt biểu tượng thanh công cụ hành động dựa trên tên của báo thức đã tắt.

service-worker.js:

chrome.alarms.onAlarm.addListener((alarm) => {
  chrome.action.setIcon({
    path: getIconPath(alarm.name),
  });
});

Loại

Alarm

Thuộc tính

  • tên

    chuỗi

    Tên của chuông báo này.

  • periodInMinutes

    số không bắt buộc

    Nếu không phải là giá trị rỗng, thì báo thức này là báo thức lặp lại và sẽ kích hoạt lại sau periodInMinutes phút.

  • persistAcrossSessions

    boolean

    Chrome 150+

    Liệu báo thức có nên duy trì giữa các phiên (khởi động lại trình duyệt) hay không.

  • scheduledTime

    số

    Thời gian mà chuông báo này được lên lịch tắt, tính bằng mili giây kể từ thời gian bắt đầu của hệ thống (ví dụ: Date.now() + n). Vì lý do hiệu suất, chuông báo có thể bị trì hoãn một khoảng thời gian tuỳ ý ngoài thời gian này.

AlarmCreateInfo

Thuộc tính

  • delayInMinutes

    số không bắt buộc

    Khoảng thời gian tính bằng phút sau đó sự kiện onAlarm sẽ tắt.

  • periodInMinutes

    số không bắt buộc

    Nếu được đặt, sự kiện onAlarm sẽ tắt sau mỗi periodInMinutes phút sau sự kiện ban đầu được chỉ định bởi when hoặc delayInMinutes. Nếu không đặt, báo thức sẽ chỉ kích hoạt một lần.

  • persistAcrossSessions

    boolean không bắt buộc

    Chrome 150+

    Liệu báo thức có nên duy trì giữa các phiên (khởi động lại trình duyệt) hay không. Trong Chrome, giá trị này mặc định là true để phù hợp với hành vi trước đây, nhưng bạn nên đặt giá trị này một cách rõ ràng để tối đa hoá khả năng tương thích trên các trình duyệt.

  • khi

    số không bắt buộc

    Thời gian mà báo thức sẽ kích hoạt, tính bằng mili giây kể từ thời gian bắt đầu của hệ thống (ví dụ: Date.now() + n).

Phương thức

clear()

Lời hứa 
chrome.alarms.clear(
  name?: string,
  callback?: function,
): Promise<boolean>

Xoá chuông báo có tên đã cho.

Thông số

  • tên

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

    Tên của chuông báo cần xoá. Giá trị mặc định là chuỗi trống.

  • callback

    hàm không bắt buộc

    Tham số callback có dạng như sau: 

    (wasCleared: boolean) => void

    • wasCleared

      boolean

Giá trị trả về

  • Promise<boolean>

    Chrome 91+

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

clearAll()

Lời hứa 
chrome.alarms.clearAll(
  callback?: function,
): Promise<boolean>

Xoá tất cả chuông báo.

Thông số

  • callback

    hàm không bắt buộc

    Tham số callback có dạng như sau: 

    (wasCleared: boolean) => void

    • wasCleared

      boolean

Giá trị trả về

  • Promise<boolean>

    Chrome 91+

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

create()

Lời hứa 
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
): Promise<void>

Tạo chuông báo. Gần(các) thời điểm được chỉ định bởi alarmInfo, sự kiện onAlarm sẽ tắt. Nếu có một chuông báo khác có cùng tên (hoặc không có tên nếu không có tên nào được chỉ định), thì chuông báo đó sẽ bị huỷ và thay thế bằng chuông báo này.

Để giảm tải cho máy của người dùng, Chrome giới hạn chuông báo ở mức tối đa 30 giây một lần nhưng có thể trì hoãn thêm một khoảng thời gian tuỳ ý. Tức là việc đặt delayInMinutes hoặc periodInMinutes thành nhỏ hơn 0.5 sẽ không được thực hiện và sẽ gây ra cảnh báo. when có thể được đặt thành dưới 30 giây sau "now" mà không có cảnh báo nhưng sẽ không thực sự khiến báo thức kích hoạt trong ít nhất 30 giây.

Để giúp bạn gỡ lỗi ứng dụng hoặc tiện ích, khi bạn đã tải ứng dụng hoặc tiện ích đó xuống, sẽ không có giới hạn về tần suất chuông báo có thể tắt.

Thông số

  • tên

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

    Tên không bắt buộc để xác định chuông báo này. Giá trị mặc định là chuỗi trống.

  • alarmInfo

    AlarmCreateInfo

    Mô tả thời điểm báo thức sẽ kích hoạt. Bạn phải chỉ định thời gian ban đầu bằng when hoặc delayInMinutes (nhưng không được chỉ định cả hai). Nếu bạn đặt periodInMinutes, báo thức sẽ lặp lại sau mỗi periodInMinutes phút sau sự kiện ban đầu. Nếu bạn không đặt when hoặc delayInMinutes cho chuông báo lặp lại, thì periodInMinutes sẽ được dùng làm giá trị mặc định cho delayInMinutes.

  • callback

    hàm không bắt buộc

    Chrome 111+

    Tham số callback có dạng như sau: 

    () => void

Giá trị trả về

  • Promise<void>

    Chrome 111+

    Lời hứa phân giải khi chuông báo đã được tạo.

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

get()

Lời hứa 
chrome.alarms.get(
  name?: string,
  callback?: function,
): Promise<Alarm | undefined>

Truy xuất thông tin chi tiết về chuông báo đã chỉ định.

Thông số

  • tên

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

    Tên của chuông báo cần lấy. Giá trị mặc định là chuỗi trống.

  • callback

    hàm không bắt buộc

    Tham số callback có dạng như sau: 

    (alarm?: Alarm) => void

Giá trị trả về

  • Promise<Alarm | undefined>

    Chrome 91+

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

getAll()

Lời hứa 
chrome.alarms.getAll(
  callback?: function,
): Promise<Alarm[]>

Lấy một mảng gồm tất cả chuông báo.

Thông số

  • callback

    hàm không bắt buộc

    Tham số callback có dạng như sau: 

    (alarms: Alarm[]) => void

    • các báo thức

      Alarm[]

Giá trị trả về

  • Promise<Alarm[]>

    Chrome 91+

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

Sự kiện

onAlarm

chrome.alarms.onAlarm.addListener(
  callback: function,
)

Kích hoạt khi báo thức đã hết. Hữu ích cho các trang sự kiện.

Thông số

  • callback

    hàm

    Tham số callback có dạng như sau: 

    (alarm: Alarm) => void