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

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

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

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

Để đảm bảo hành vi đáng tin cậy, bạn nên tìm hiểu cách API hoạt động.

Chế độ ngủ của thiết bị

Chuông báo vẫn tiếp tục chạy khi thiết bị ở chế độ ngủ. Tuy nhiên, báo thức sẽ không đánh thức thiết bị. Khi thiết bị thức, mọi chuông báo bị bỏ lỡ sẽ đổ chuông. Báo thức lặp lại sẽ kích hoạt tối đa một lần, sau đó được lên lịch lại bằng khoảng thời gian đã chỉ định, bắt đầu từ thời điểm thiết bị thức, không tính đến bất kỳ khoảng thời gian nào đã trôi qua kể từ khi báo thức được đặt để chạy lần đầu.

Khả năng lưu trữ dài lâu

Bạn có thể kiểm soát trạng thái duy trì của báo thức tại thời điểm tạo bằng cách sử dụng cờ persistAcrossSessions. Bạn có thể đặt giá trị này thành true (duy trì cho đến khi tiện ích cập nhật) hoặc false (xoá nếu tiện ích được tải lại hoặc trình duyệt khởi động lại, và bất cứ khi nào tiện ích cập nhật).

Các trình duyệt khác và các phiên bản Chrome cũ

Thuộc tính này không được hỗ trợ trong các trình duyệt khác (vấn đề) hoặc trong các phiên bản Chrome trước Chrome 150, trong đó hành vi có thể không dự đoán được. Do đó, tốt nhất là bạn nên đảm bảo các chuông báo quan trọng xuất hiện mỗi khi trình chạy dịch vụ khởi động. Ví dụ:

async function checkAlarmState() {
  const alarm = await browser.alarms.get("my-alarm");

  if (!alarm) {
    await browser.alarms.create("my-alarm", { periodInMinutes: 1 });
  }
}

checkAlarmState();

Nếu báo thức được tạo động dựa trên hành động của người dùng, bạn có thể muốn lưu trữ thông tin về việc báo thức đã được tạo ở nơi khác để biết cần tạo lại báo thức nếu cần.

Ví dụ

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

Đặt báo thức

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

service-worker.js:

browser.runtime.onInstalled.addListener(async ({ reason }) => {
  // Create an alarm so we have something to look at in the demo
  await browser.alarms.create('demo-default-alarm', {
    delayInMinutes: 1,
    periodInMinutes: 1,
    persistAcrossSessions: true
  });
});

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

Ví dụ sau đây đặt biểu tượng thanh công cụ thao tác dựa trên tên của chuông báo đã đổ chuông.

service-worker.js:

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

Loại

Alarm

Thuộc tính

  • tên

    chuỗi

    Tên của báo thức này.

  • periodInMinutes

    number không bắt buộc

    Nếu không phải là giá trị rỗng, thì báo thức 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 chuông báo có nên duy trì trong 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 kích hoạt, tính bằng mili giây kể từ thời điểm bắt đầu (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 khoảng thời gian này.

AlarmCreateInfo

Thuộc tính

  • delayInMinutes

    number không bắt buộc

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

  • tên

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

    Chrome 152 trở lên

    Tên của báo thức này.

  • periodInMinutes

    number không bắt buộc

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

  • persistAcrossSessions

    boolean không bắt buộc

    Chrome 150+

    Liệu chuông báo có nên duy trì trong 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

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

chrome.alarms.clear(
  name?: string,
): 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.

Giá trị trả về

  • Promise<boolean>

    Chrome 91 trở lên

clearAll()

chrome.alarms.clearAll(): Promise<boolean | undefined>

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

Giá trị trả về

  • Promise<boolean | undefined>

    Chrome 91 trở lên

create()

chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
): Promise<void>

Tạo một báo thức. Gần(các) thời điểm do alarmInfo chỉ định, sự kiện onAlarm sẽ được kích hoạ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à được 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 số lượng chuông báo tối đa là 1 lần mỗi 30 giây 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 giá trị nhỏ hơn 0.5 sẽ không được chấp nhận và sẽ gây ra cảnh báo. Bạn có thể đặt when thành dưới 30 giây sau "bây giờ" mà không có cảnh báo, nhưng báo thức sẽ không thực sự 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 đó ở trạng thái chưa đóng gói, sẽ không có giới hạn về tần suất kích hoạt chuông báo.

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 dùng cả hai). Nếu bạn đặt periodInMinutes, báo thức sẽ lặp lại sau mỗi periodInMinutes phút kể từ sự kiện ban đầu. Nếu bạn không đặt when hoặc delayInMinutes cho một báo thức lặp lại, thì periodInMinutes sẽ được dùng làm giá trị mặc định cho delayInMinutes.

Giá trị trả về

  • Promise<void>

    Chrome 111 trở lên

    Promise sẽ phân giải khi báo thức được tạo.

get()

chrome.alarms.get(
  name?: string,
): 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.

Giá trị trả về

  • Promise<Alarm | undefined>

    Chrome 91 trở lên

getAll()

chrome.alarms.getAll(): Promise<Alarm[]>

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

Giá trị trả về

  • Promise<Alarm[]>

    Chrome 91 trở lên

Sự kiện

onAlarm

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

Được kích hoạt khi báo thức đã hết thời gian. 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