# TimeBar

**Repository Path**: harmonyos_samples/timebar

## Basic Information

- **Project Name**: TimeBar
- **Description**: 可缩放时间轴UI效果
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 5
- **Created**: 2025-10-23
- **Last Updated**: 2026-01-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Zoomable Timeline

## Overview

This sample demonstrates how to implement video-timeline synchronization using **Canvas** and **Video** components. At its core, it enables timeline control through pan and pinch gestures to fast forward or rewind the video.

## Effect
| Zooming Out                                     | Zooming In                                      | Style Adjustment                                |
| ----------------------------------------------- | ----------------------------------------------- | ----------------------------------------------- |
| <img src='./screenshots/pic1_en.png' width=320> | <img src='./screenshots/pic2_en.png' width=320> | <img src='./screenshots/pic3_en.png' width=320> |

## Features

- Gesture control: pan to drag the timeline and pinch to zoom the timescale.
- Video-timeline synchronization: drag the timeline to locate a specific frame. The video progress syncs with the timeline in real time.
- Multi-video management: load and play multiple video files in chronological order.
- Dynamic timescale adjustment: zoom in or out to make the scale glide smoothly between hour and minute granularity, displaying the optimal level of detail.
- Playback state feedback: Video playback states (playing/paused) sync with the timeline for an enhanced user experience.

## How to Use

1. Import the application sample project into DevEco Studio for compilation, building, and debugging.

2. After installation and execution, check the sample's running effect on the device and perform related debugging.

## Project Directory

```
├───entry/src/main/ets 
│   ├───common                               
│   │   ├───contants                         
│   │   │   └───CommonConstants.ets             // Common constants 
│   │   └───utils                            
│   │       └───CommonUtils.ets                 // Common utilities 
│   ├───components 
│   │   └───VideoView.ets                       // Video playback component 
│   ├───entryability                         
│   │   └───EntryAbility.ets                    // Entry ability 
│   ├───entrybackupability                   
│   │   └───EntryBackupAbility.ets              // Data backup and restoration 
│   ├───model 
│   │   ├───SegmentIndexInfo.ets                // Information returned after locating a segment by timeline offset 
│   │   └───VideoInfo.ets                       // Video information 
│   └───pages 
│       ├───Index.ets                           // Home page 
│       ├───MultiStyleTimeBar.ets               // Demo for basic timeline functionalities 
│       └───TimeBarVideoLinkage.ets             // Demo for timeline and video synchronization 
├───entry/src/main/resources                    // Static resources 
└───time_bar/src/main/ets                       // Static shared library of the timeline 
    ├───components 
    │   ├───interface 
    │   │   ├───CustomDrawCallback.ets          // Custom drawing callback 
    │   │   ├───CustomDrawItem.ets              // Custom drawing configuration 
    │   │   ├───MiddleIndicatorOption.ets       // Middle indicator line style 
    │   │   ├───TimeBarOption.ets               // Timeline style 
    │   │   ├───TimePickedCallback.ets          // Timeline callback 
    │   │   ├───TimeScaleOption.ets             // Timescale style 
    │   │   ├───VideoAreaOption.ets             // Video area style 
    │   │   └───VideoTimeBounds.ets             // Time boundary of the video area 
    │   ├───viewModel                            
    │   │   ├───RecordSegment.ets               // Video segment information 
    │   │   └───TimeBarModel.ets                // Logic layer of the timeline 
    │   └───TimeBarView.ets                     // Timeline component 
    ├───contants 
    │   └───CommonConstants.ets                 // Constants 
    └───utils 
        └───CommonUtils.ets                     // Common utilities
```

## How to Implement

### TimeBarView API Information

The **TimeBarView** component exposes the following properties and callbacks via the @Prop decorator for configuring its appearance and behavior.

| Name                  | Type                                                         | Default Value                                                | Description                                                  |
| --------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| model                 | TimeBarModel                                                 | Mandatory (@Require)                                         | Timeline data model that centrally manages **timeRange**, **currentTime**, and **boundaries**. |
| middleIndicatorOption | MiddleIndicatorOption                                        | `{ length: 100, fillColor: '#0A59F7' }`                      | Style of the middle indicator line.                          |
| intervalWidth         | number                                                       | 10                                                           | Pixel pitch between adjacent minor ticks. 10 px corresponds to 10 minutes (1 px = 1 minute). |
| timeScaleOption       | TimeScaleOption                                              | `{ scaleLineWidth: 1, scaleLineHeight: 8, scaleTextColor: '#808080', scaleLineColor: 'rgb(206,206,205)', scaleAlignment: TOP }` | Style of the timescale and time text.                        |
| videoAreaOption       | VideoAreaOption                                              | `{ backgroundColor:'#606266', height:20, topOffset:40 }`     | Display style of the recording area (color bar).             |
| timeBarOption         | TimeBarOption                                                | `{ width:'100%', height:100, backgroundColor:'rgb(245,245,244)' }` | Width, height, and background color of the container canvas. |
| onContextReady        | (ctx: CanvasRenderingContext2D, component: TimeBarView) => void | -                                                            | Callback triggered when the canvas context is ready, exposing ctx and the component itself. |

### TimeBarView Public Methods

| Function Name          | Type                                                         | Description                                                  |
| ---------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| setTimeBarMoveListener | `(listener: TimePickedCallback) => void`                     | Registers a callback for timeline movement/auto-scroll, which returns the currently centered time and status (START/PLAYING/STOP). |
| registerCustomDraw     | `(callback: CustomDrawCallback, zIndex?: number, id?: string) => void` | Registers a custom drawing callback. The drawing is performed in ascending order of **zIndex**. |
| unregisterCustomDraw   | `(param: string \| CustomDrawCallback) => void`              | Unregisters a custom drawing callback.                       |
| clearAllCustomDraw     | `() => void`                                                 | Clears all custom drawing callbacks.                         |
| safeDraw               | `(cb: (ctx: CanvasRenderingContext2D) => void) => void`      | Performs one-off drawing within the protection of encapsulated **save()** and **restore()** methods, and triggers redrawing. |

## Required Permissions

1. ohos.permission.INTERNET: allows an application to play network videos.

## Dependencies

  - Third-party library [dayjs](https://ohpm.openharmony.cn/#/cn/detail/@mui%2Fdayjs).

## Constraints

1. This sample is only supported on Huawei phones running standard systems.

2. The HarmonyOS version must be HarmonyOS 6.0.0 Release or later.

3. The DevEco Studio version must be DevEco Studio 6.0.0 Release or later.

4. The HarmonyOS SDK version must be HarmonyOS 6.0.0 Release SDK or later.