<template>
  <vue3TimePlaybar
    v-model="currentTime"
    :start-time="startTime"
    :end-time="endTime"
    @change="onTimeChange"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import vue3TimePlaybar from 'vue3-time-playbar'
import 'vue3-time-playbar/style.css'
import type { TimeChangePayload } from 'vue3-time-playbar'

const startTime = new Date('2025-01-01T00:00:00')
const endTime = new Date('2025-01-03T00:00:00')
const currentTime = ref<number>(startTime.getTime())

function onTimeChange(payload: TimeChangePayload) {
  console.log('Time:', payload.time, 'Index:', payload.index)
}
</script>

注意： 必须导入 CSS 文件，组件才能正确渲染。

Props

属性	类型	默认值	说明
`modelValue`	`number \| string \| Date`	—	当前时间（v-model）
`startTime`	`number \| string \| Date`	必填	时间轴起始时间
`endTime`	`number \| string \| Date`	必填	时间轴结束时间
`interval`	`number`	`1`	刻度间隔（小时）
`playInterval`	`number`	`1000`	基准播放间隔（毫秒），即 1x 倍速时每步的时间间隔
`speed`	`number`	`1`	默认播放倍率，值必须是 `speedOptions` 中的一项
`speedOptions`	`number[]`	`[0.5, 1, 2, 3]`	可选的播放倍率列表，显示在速度选择器中
`minTickSpacing`	`number`	自动	刻度之间的最小像素间距。未指定时根据 `tickLabelMode` 自动选择：`'all'` 模式为 `15`，`'major'` 模式为 `5`
`tickLabelMode`	`'all' \| 'major'`	`'all'`	刻度标签显示模式。`'all'`：所有刻度均显示小时数字；`'major'`：仅在 02、08、14、20 时显示数字标签，其余刻度线仍全部保留
`formatTooltip`	`(ts: number) => string`	内置	自定义 tooltip 格式化函数
`tickColors`	`Record<number, string>`	—	按刻度 index 指定颜色。时间轴按「一刻度一格」布局，刻度在格中心；有颜色时改变该格刻度线/文字与进度条（已到达满色，未到达半透明），以及当前格的手柄/Tooltip。未配置的 index 保持默认样式

事件

事件	载荷	说明
`update:modelValue`	`number`	时间变化时触发（v-model）
`change`	`{ time: number, index: number }`	时间变化时触发，包含时间戳和刻度索引

交互特性

点击定位：点击时间轴任意位置，自动吸附到最近的刻度
轨道拖动：在时间轴轨道上按住拖动可连续调整时间
Tooltip 拖动：鼠标悬浮至 Tooltip 时显示拖动图标（grab），按住拖动可直接带动播放位置
日期分界线：0 点刻度自动显示加长的分界线和日期标签，隐藏多余的 "00" 小时标签
滚轮滚动：当时间跨度较长产生溢出时，支持滚轮横向滚动浏览

插槽

插槽	参数	说明
`prev`	—	自定义"上一步"按钮内容
`play`	`{ isPlaying: boolean }`	自定义"播放/暂停"按钮内容
`next`	—	自定义"下一步"按钮内容

类型导出

import type {
  TimeInput,
  TickLabelMode,
  FormatTooltipFn,
  TimeChangePayload,
  Tick,
  TickColors,
} from 'vue3-time-playbar'

工具函数导出

包中还导出了一些实用的工具函数：

import {
  toTimestamp,
  getHour,
  getDayOfWeek,
  getWeekdayShort,
  formatHH,
  formatMD,
  formatHHmm,
  defaultTooltipFormat,
  getDateKey,
  formatDayLabel,
  addHours,
  diffHours,
  getNextMidnight,
  findNearestTickIndex,
  findTickIndex,
} from 'vue3-time-playbar'