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

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

{
  "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 hoạt động của API.

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

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

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

Chuông báo thường vẫn tồn tại cho đến khi tiện ích được cập nhật. Tuy nhiên, điều này không được đảm bảo và chuông báo có thể bị xoá khi trình duyệt khởi động lại. Do đó, hãy cân nhắc việc đặt giá trị trong bộ nhớ khi tạo chuông báo, sau đó đảm bảo giá trị đó tồn tại mỗi khi trình chạy dịch vụ khởi động. Ví dụ:

const STORAGE_KEY = "user-preference-alarm-enabled";

async function checkAlarmState() {
  const { alarmEnabled } = await chrome.storage.get(STORAGE_KEY);

  if (alarmEnabled) {
    const alarm = await chrome.alarms.get("my-alarm");

    if (!alarm) {
      await chrome.alarms.create({ periodInMinutes: 1 });
    }
  }
}

checkAlarmState();

Ví dụ

Các ví dụ sau đây cho biết 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 từ kho lưu trữ chrome-extension-samples.

Đặt chuông báo

Ví dụ sau đây đặt chuông báo 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ụ thao tác dựa trên tên của chuông báo đã bậ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 giá trị rỗng, chuông báo là chuông báo lặp lại và sẽ kích hoạt lại sau periodInMinutes phút.

  • scheduledTime

    số

    Thời gian 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 gian 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ỳ ý sau thời điểm 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ẽ kích hoạt.

  • periodInMinutes

    số không bắt buộc

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

  • khi

    số không bắt buộc

    Thời gian chuông báo 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()

Promise 
chrome.alarms.clear(
  name?: string,
  callback?: function,
)

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

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

  • lệnh gọi lại

    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 trở lên

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

clearAll()

Promise 
chrome.alarms.clearAll(
  callback?: function,
)

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

Tham số

  • lệnh gọi lại

    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 trở lên

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

create()

Promise 
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
)

Tạo chuông báo. 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), chuông báo đó sẽ bị huỷ và thay thế bằng chuông báo này.

Để giảm tải trên máy của người dùng, Chrome giới hạn chuông báo ở mức tối đa là một lần mỗi 30 giây nhưng có thể trì hoãn chuông báo 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. Bạn có thể đặt when thành ít hơn 30 giây sau "bây giờ" mà không cần cảnh báo, nhưng chuông báo 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 chưa giải nén, không có giới hạn về tần suất chuông báo có thể kích hoạt.

Tham 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 chuông báo 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, chuông báo 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 chuông báo lặp lại, thì periodInMinutes sẽ được dùng làm giá trị mặc định cho delayInMinutes.

  • lệnh gọi lại

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

    Chrome 111 trở lên

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

    () => void

Giá trị trả về

  • Promise<void>

    Chrome 111 trở lên

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

get()

Promise 
chrome.alarms.get(
  name?: string,
  callback?: function,
)

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

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

  • lệnh gọi lại

    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 trở lên

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

getAll()

Promise 
chrome.alarms.getAll(
  callback?: function,
)

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

Tham số

  • lệnh gọi lại

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

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

    (alarms: Alarm[]) => void

Giá trị trả về

  • Promise<Alarm[]>

    Chrome 91 trở lên

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ 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

onAlarm

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

Được kích hoạt khi chuông báo đã hết giờ. Hữu ích cho các trang sự kiện.

Tham số

  • lệnh gọi lại

    hàm

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

    (alarm: Alarm) => void