chrome.alarms

Nội dung mô tả

Sử dụng API chrome.alarms để lên lịch chạy mã theo định kỳ hoặc vào một thời điểm nhất định 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 minh hoạ cách sử dụng và phản hồi một 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 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 đã 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 giá trị này không rỗng, thì chuông báo này là chuông báo lặp lại và sẽ kích hoạt lại sau periodInMinutes phút.

  • scheduledTime

    number

    Thời gian mà vào lúc đó chuông báo này được lên lịch kích hoạt, tính bằng mili giây trước thời gian bắt đầu của hệ thống (ví dụ: Date.now() + n). Vì lý do về hiệu suất, chuông báo có thể đã bị trễ một khoảng thời gian tuỳ ý vượt quá khoảng 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 bạn đặt chính sách này, thì 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 chính sách này, thì 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 trước thời gian bắt đầu của hệ thống (ví dụ: Date.now() + n).

Phương thức

clear()

Cam kết 
chrome.alarms.clear(
  name?: string,
  callback?: function,
)

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

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

Cam kết 
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 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()

Cam kết 
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
)

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

Để giảm tải cho máy của người dùng, Chrome sẽ 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 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ẽ tạo ra cảnh báo. Bạn có thể đặt when thành chưa đến 30 giây sau "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 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. Thời gian ban đầu phải được chỉ định 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 periodInMinutes phút một lần sau sự kiện đầu tiên. 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 chế độ 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ề

  • Promise<void>

    Chrome 111 trở lên

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

Cam kết 
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 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ề

  • Hứa hẹn<Báo thức|không xác định>

    Chrome 91 trở lên

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

Cam kết 
chrome.alarms.getAll(
  callback?: function,
)

Lấy một loạt 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ề

  • Hứa<Chuông báo[]>

    Chrome 91 trở lên

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

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