chrome.alarms

Mô tả

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

Quyền

alarms

Để sử dụng API chrome.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 cầ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 khi một thiết bị đang ngủ. Tuy nhiên, chuông báo sẽ không đánh thức thiết bị. Khi thiết bị bật lên, mọi chuông báo bị nhỡ sẽ kích hoạt. Các chuông báo 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 cụ thể bắt đầu từ khi thiết bị bật, không tính đến bất kỳ thời điểm nào đã trôi qua kể từ khi báo thức được đặt ban đầu để chạy.

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

Các chuông báo thường sẽ chạy cho đến khi bạn cập nhật một tiện ích. Tuy nhiên, việc này không đảm bảo được, và các chuông báo có thể bị xoá khi trình duyệt được khởi động lại. Do đó, hãy cân nhắc việc thiết lập giá trị trong bộ nhớ khi chuông báo được tạo và sau đó đảm bảo chuông báo tồn tại mỗi khi trình chạy dịch vụ của bạn 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 minh hoạ cách sử dụng và phản hồi chuông báo. Để dùng thử API này, cài đặt ví dụ về API Alarm API trong chrome-extension-samples kho lưu trữ.

Đặ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ụ hành động dựa vào tên của chuông báo được kêu.

service-worker.js:

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

Loại

Alarm

Thuộc tính

  • tên

    string

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

  • periodInMinutes

    số không bắt buộc

    Nếu không rỗng, chuông báo là một 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 mà chuông báo này được lên lịch kích hoạt, tính bằng mili giây sau 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ể đã trễ một khoảng thời gian tuỳ ý vượt quá 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 mà 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 periodInMinutes phút một lần sau sự kiện ban đầu do when hoặc delayInMinutes chỉ định. Nếu bạn không đặt chính sách này, 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 mà chuông báo sẽ kích hoạt, tính bằng mili giây sau 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,
)

Xoá báo thức theo 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.

  • số gọi lại

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

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

clearAll()

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

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

Tham số

  • số gọi lại

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

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

create()

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

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

Để giảm tải cho máy của người dùng, Chrome giới hạn tối đa các chuông báo là 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 tuân thủ và sẽ dẫn đến cảnh báo. Có thể đặt when thành chưa đến 30 giây sau sự kiện "ngay bây giờ" mà không cảnh báo nhưng sẽ không thực sự khiến chuông báo 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 đã giải nén, sẽ không có giới hạn về tần suất kích hoạt chuông báo.

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. Thời gian ban đầu phải được chỉ định bằng when hoặc delayInMinutes (nhưng không được dùng cả hai). Nếu bạn đặt periodInMinutes, chuông báo sẽ lặp lại periodInMinutes phút một lần 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 mặc định cho delayInMinutes.

  • số gọi lại

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

    Chrome 111 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 111 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.

get()

Lời hứa 
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 bạn muốn nhận. Giá trị mặc định là chuỗi trống.

  • số gọi lại

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

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

    (alarm?: Alarm) => void

Giá trị trả về

  • Promise&lt;Alarm | không xác định>

    Chrome 91 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.

getAll()

Lời hứa 
chrome.alarms.getAll(
  callback?: function,
)

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

Tham số

  • số gọi lại

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

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

    (alarms: Alarm[]) => void

Giá trị trả về

  • Lời hứa<Alarm[]>

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

onAlarm

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

Được kích hoạt khi một chuông báo đã trôi qua. Hữu ích cho các trang sự kiện.

Tham số

  • số gọi lại

    hàm

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

    (alarm: Alarm) => void