MonitoringPlaybackTimelineView

一个功能强大、可高度定制的 Android 监控回放时间轴视图控件。专为视频监控、行车记录仪等需要进行时间选择和事件展示的回放场景设计。

A powerful and highly customizable timeline view for Android, perfect for video surveillance playback interfaces, dashcam footage review, and any application requiring intuitive time selection and event visualization.

---

效果演示 (Demo)

---

功能特性 (Features)

• 平滑手势操作：支持流畅的单指拖动和双指捏合缩放。
• 无限历史滚动：可以向过去无限滚动，查看任意时间点的记录。
• 精准中心点缩放：无论手指在何处缩放，时间轴都严格围绕中心指示线进行，确保时间点在缩放过程中保持不变。
• 动态刻度生成：根据缩放级别，自动、平滑地生成易于阅读的时间刻度（从2小时到1分钟级别）。
• 灵敏度可调：缩放手感灵敏度可配置，提供更自然、更“跟手”的体验。
• 事件块展示：可以在时间轴上方绘制不同颜色的矩形块，用于可视化特殊事件（如移动侦测、声音报警等）。
• 动态事件管理：支持在运行时动态地添加、清除和根据类型过滤事件。
• 直播模式支持：可以平滑滚动到最新的“直播”时间点。
• 双回调机制：
  • 持续回调 (OnTimeUpdatingListener)：在滑动/缩放过程中实时触发，用于更新UI上的时间显示。
  • 最终选择回调 (OnTimeSelectedListener)：在用户停止操作后（带防抖）触发，用于发起网络请求等重量级操作。
• 精细的交互打磨：内置滑动、缩放、惯性滚动的灵敏度阈值，防止误触和意外的抖动，手感专业。
• XML自定义样式：支持通过XML属性配置颜色、尺寸等外观。

---

如何集成 (Installation)

目前，最简单的方式是直接将代码文件复制到您的项目中。

1. 复制 MonitoringPlaybackTimelineView.kt 文件到您的项目源码目录中（例如 your.package.name/views/）。

2. 复制 TimelineEvent.kt 数据类文件。

3. 将下面的自定义属性代码添加到您的 res/values/attrs.xml 文件中。

   <resources>
       <declare-styleable name="MonitoringPlaybackTimelineView">
           <attr name="timelineColor" format="color" />
           <attr name="timelineHeight" format="dimension" />
           <attr name="centerIndicatorColor" format="color" />
           <attr name="centerIndicatorWidth" format="dimension" />
           <attr name="majorTickColor" format="color" />
           <attr name="majorTickHeight" format="dimension" />
           <attr name="minorTickColor" format="color" />
           <attr name="minorTickHeight" format="dimension" />
           <attr name="textColor" format="color" />
           <attr name="textSize" format="dimension" />
       </declare-styleable>
   </resources>

---

使用方法 (Usage)

1. 在 XML 布局中添加

<org.loka.timeline.MonitoringPlaybackTimelineView
    android:id="@+id/timelineView"
    android:layout_width="match_parent"
    android:layout_height="120dp"
    app:centerIndicatorColor="#FF0000"
    app:timelineColor="#888888"
    app:textColor="#333333" />

2. 在 Kotlin/Java 代码中进行交互

import java.text.SimpleDateFormat
import java.util.Date
import java.util.Locale

// ... 在您的 Activity 或 Fragment 中

// 获取控件实例
val timelineView = findViewById<MonitoringPlaybackTimelineView>(R.id.timelineView)
val timeTextView = findViewById<TextView>(R.id.timeTextView) // 用于显示时间的TextView

// 1. 设置初始时间
timelineView.setInitialTime(System.currentTimeMillis())

// 2. 设置“持续更新”监听器 (用于刷新UI)
timelineView.setOnTimeUpdatingListener { timestamp ->
    val formattedTime = SimpleDateFormat("yyyy-MM-dd HH:mm:ss", Locale.getDefault()).format(Date(timestamp))
    timeTextView.text = formattedTime
}

// 3. 设置“最终选择”监听器 (用于发起网络请求)
timelineView.setOnTimeSelectedListener { timestamp ->
    Log.d("TimelineView", "最终选择的时间: $timestamp. 准备请求视频流...")
    // 在这里执行您的网络请求
    requestPlaybackStream(timestamp)
}

// 4. 设置事件数据
val events = listOf(
    TimelineEvent(startTime1, endTime1, Color.BLUE, type = 1), // 类型1: 移动侦测
    TimelineEvent(startTime2, endTime2, Color.GREEN, type = 2) // 类型2: 声音报警
)
timelineView.setEvents(events)

// 5. 过滤事件：只显示类型为1的事件
timelineView.filterEvents(listOf(1))

// 6. 清除所有过滤器，显示全部事件
timelineView.filterEvents(null)

---

API 参考 (Public Methods)

方法名 (Method)	描述 (Description)
setInitialTime(timestamp: Long)	设置时间轴的初始定位时间。
setOnTimeUpdatingListener(...)	设置实时时间更新回调（用于UI）。
setOnTimeSelectedListener(...)	设置最终时间选择回调（带防抖，用于数据请求）。
setEvents(events: List<TimelineEvent>)	完全替换当前的所有事件。
addEvents(newEvents: List<TimelineEvent>)	增量添加新的事件。
filterEvents(typesToShow: List<Int>?)	根据事件类型 type 过滤显示。传入null显示全部。
clearEvents()	清除时间轴上的所有事件。
updateLiveTimestamp(timestamp: Long)	在直播模式下，更新当前最新时间。
followLive()	让时间轴滚动到最新的直播时间点。
scrollToTime(timestamp: Long, animated: Boolean)	以动画或瞬移方式跳转到指定时间。

---

贡献 (Contributing)

欢迎提交 Pull Request 或创建 Issue 来帮助改进这个项目。

---

许可证 (License)

该项目使用 MIT 许可证。详情请见 LICENSE.md 文件。

MIT License

Copyright (c) 2025 [Your Name or Organization]

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.