createWidget

createWidget là api dùng để tạo một Widget trên App Host.

Lưu ý

updateInterval tối thiểu là 5 giây.
duration tối đa là 1200 giây (20 phút). Sau khi hết thời gian, widget sẽ tự động bị xoá.
template hiện chỉ hỗ trợ: ride-hailing.
estimatedTime nếu có sẽ được ưu tiên để tính progress bar thay cho progressPercent. Là object gồm start và end (UTC milliseconds).
hideProgressBar nếu là true sẽ ẩn progress bar trên UI. estimatedTime vẫn hoạt động độc lập (tính {{rem_time}}).
description hỗ trợ placeholder {{rem_time}} — tự động thay thế bằng số phút còn lại (làm tròn lên) khi có estimatedTime.

Tham số

Thuộc tính	Kiểu dữ liệu	Bắt buộc	Mô tả
configs	WidgetConfigs	✓	Cấu hình của widget
success	Function		Callback khi tạo widget thành công. Trả về `{` `widgetId` `}`
fail	Function		Callback khi tạo widget thất bại
complete	Function		Callback sau khi thực hiện bất kể thành công hay thất bại

WidgetConfigs

Thuộc tính	Kiểu dữ liệu	Bắt buộc	Mô tả
updateInterval	number	✓	Chu kỳ cập nhật widget (giây). Tối thiểu 5 giây
duration	number	✓	Thời gian tồn tại của widget (giây). Tối đa 1200 giây
template	string	✓	Loại template: `ride-hailing`
data	object	✓	Dữ liệu hiển thị, tuỳ thuộc vào `template`. Xem chi tiết bên dưới

Template: `ride-hailing`

Dùng cho các tình huống gọi xe, theo dõi tài xế.

Thuộc tính	Kiểu dữ liệu	Bắt buộc	Mô tả
title	string	✓	Tiêu đề chính (VD: "Xanh SM Taxi")
description	string	✓	Trạng thái ngắn. Hỗ trợ placeholder `{{rem_time}}` — tự động thay bằng số phút còn lại (VD: "Tài xế đang đến trong `{{rem_time}}`" → "Tài xế đang đến trong 5 phút")
estimatedTime	object		Khoảng thời gian để tính progress. Xem chi tiết bên dưới. Khi có, progress bar được tính tự động thay vì dùng `progressPercent`
progressPercent	number		Tiến độ từ 0.0 đến 1.0. Hiển thị progress bar. Bị bỏ qua nếu có `estimatedTime`. Mặc định: 0.0
hideProgressBar	boolean		Ẩn progress bar trên UI. `estimatedTime` vẫn hoạt động (tính `{{rem_time}}`). Mặc định: `false`
iconUrl	string		URL icon hiển thị bên phải (VD: avatar tài xế)

estimatedTime

Khoảng thời gian để tính progress bar tự động. Nếu có, progressPercent sẽ bị bỏ qua.

Thuộc tính	Kiểu dữ liệu	Bắt buộc	Mô tả
start	number	✓	Thời điểm bắt đầu (UTC milliseconds, VD: `Date.now()`)
end	number	✓	Thời điểm kết thúc (UTC milliseconds, VD: `Date.now() + 300000`)

Ràng buộc: start < end, end > thời điểm hiện tại.

Công thức: progress = (now - start) / (end - start), clamp từ 0.0 đến 1.0.

Ưu tiên progress

Nếu có estimatedTime: progress bar tự động tính từ start đến end. Nếu không có estimatedTime: dùng progressPercent (mặc định 0.0). Nếu hideProgressBar là true: ẩn progress bar, nhưng {{rem_time}} vẫn hoạt động nếu có estimatedTime.

Ví dụ

Dùng `progressPercent` (thủ công)

import apis from '@v-miniapp/apis'

apis.createWidget({
  configs: {
    updateInterval: 5,
    duration: 300,
    template: 'ride-hailing',
    data: {
      title: 'Xanh SM Taxi',
      description: 'Tài xế đang đến',
      progressPercent: 0.45,
      iconUrl: 'https://example.com/driver.jpg',
    },
  },
  success: res => {
    console.log('Widget created:', res.widgetId)
  },
  fail: res => {
    apis.alert({
      title: 'Tạo widget thất bại',
      error: {
        code: res?.code,
        message: res?.message,
      },
    })
  },
})

Dùng `estimatedTime` (tự động tính progress + thời gian còn lại)

import apis from '@v-miniapp/apis'

const now = Date.now()
apis.createWidget({
  configs: {
    updateInterval: 5,
    duration: 600,
    template: 'ride-hailing',
    data: {
      title: 'Xanh SM Taxi',
      description: 'Tài xế đang đến trong {{rem_time}}',
      estimatedTime: {
        start: now,
        end: now + 5 * 60 * 1000, // 5 phút
      },
      iconUrl: 'https://example.com/driver.jpg',
    },
  },
  success: res => {
    console.log('Widget created:', res.widgetId)
    // description hiển thị: "Tài xế đang đến trong 5 phút"
    // progress bar tự động tính từ start đến end
  },
})

Ẩn progress bar nhưng vẫn hiển thị thời gian còn lại

import apis from '@v-miniapp/apis'

const now = Date.now()
apis.createWidget({
  configs: {
    updateInterval: 5,
    duration: 600,
    template: 'ride-hailing',
    data: {
      title: 'Xanh SM Taxi',
      description: 'Tài xế đang đến trong {{rem_time}}',
      estimatedTime: {
        start: now,
        end: now + 5 * 60 * 1000,
      },
      hideProgressBar: true,
      iconUrl: 'https://example.com/driver.jpg',
    },
  },
  success: res => {
    console.log('Widget created:', res.widgetId)
    // description hiển thị: "Tài xế đang đến trong 5 phút"
    // progress bar KHÔNG hiển thị
  },
})

Tham số​

WidgetConfigs​

Template: ride-hailing​

estimatedTime​

Ví dụ​

Dùng progressPercent (thủ công)​

Dùng estimatedTime (tự động tính progress + thời gian còn lại)​

Ẩn progress bar nhưng vẫn hiển thị thời gian còn lại​