TimelineJS3 项目API详解与使用指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00509/article/details/148755308

TimelineJS3 项目API详解与使用指南

TimelineJS3 TimelineJS v3: A Storytelling Timeline built in JavaScript. http://timeline.knightlab.com 项目地址: https://gitcode.com/gh_mirrors/ti/TimelineJS3

项目概述

TimelineJS3是一个功能强大的时间轴可视化工具，它允许开发者通过简单的JSON数据格式创建交互式的时间轴展示。本文将深入解析TimelineJS3的API接口，帮助开发者更好地掌握其核心功能和使用方法。

核心概念解析

在使用TimelineJS3 API前，需要理解两个关键概念：

事件索引(event_index)：指向时间轴数据对象中已排序事件数组的索引
幻灯片索引(slide_index)：指向渲染时间轴中实际显示的幻灯片索引

特别需要注意的是：

标题幻灯片(title)没有event_index，其slide_index固定为0
当存在标题幻灯片时，第一个事件的event_index为0，slide_index为1
当不存在标题幻灯片时，第一个事件的event_index和slide_index均为0

事件系统详解

TimelineJS3提供了丰富的事件系统，开发者可以通过监听这些事件来实现自定义交互逻辑。

基本事件监听模式

var timeline = new TL.Timeline(...);

timeline.on("事件名称", function(data) {
    // 事件处理逻辑
});

主要事件类型

导航相关事件
- back_to_start：用户点击返回起始点控件时触发
- nav_next：点击"下一项"按钮时触发
- nav_previous：点击"上一项"按钮时触发
幻灯片变化事件
- change：当前幻灯片变更时触发
  - data.unique_id：新幻灯片的唯一ID
- color_change：当前幻灯片背景色变化时触发
  - data.unique_id：新幻灯片的唯一ID
加载相关事件
- dataloaded：数据加载完成后触发
- loaded：故事滑块和时间导航器加载完成后触发
  - data.scale：时间尺度类型("human"或"cosmological")
  - data.eras：时代数组
  - data.events：事件数组
  - data.title：标题幻灯片数据(如果存在)
缩放事件
- zoom_in：用户放大时间导航器时触发
- zoom_out：用户缩小时间导航器时触发
  - data.zoom_level：当前缩放级别(整数)
幻灯片操作事件
- added：添加幻灯片后触发
- removed：移除幻灯片后触发
  - data.unique_id：被修改幻灯片的ID
URL哈希事件
- hash_updated：URL中的哈希书签更新时触发
  - data.unique_id：当前幻灯片的ID
  - data.hashbookmark：哈希值

导航控制API

TimelineJS3提供了完整的导航控制方法：

基础导航
- goTo(slide_index)：跳转到指定索引的幻灯片
- goToId(id)：跳转到指定ID的幻灯片
- goToNext()：跳转到下一张幻灯片
- goToPrev()：跳转到上一张幻灯片
- goToStart()：跳转到第一张幻灯片
- goToEnd()：跳转到最后一张幻灯片

数据操作API

删除操作
- remove(event_index)：通过事件索引删除事件
- removeId(id)：通过ID删除事件
添加操作
- add(data)：添加新事件，参数为事件数据对象

数据访问API

获取数据
- getData(slide_index)：通过幻灯片索引获取数据
- getDataById(id)：通过ID获取幻灯片数据
获取幻灯片对象
- getSlide(slide_index)：通过索引获取TL.Slide对象
- getSlideById(id)：通过ID获取TL.Slide对象

事件数据格式规范

TimelineJS3使用标准化的JSON格式来定义事件数据：

{
    "start_date": {         // 必填
        "year": "字符串",   // 必须包含年份
        "month": "字符串", // 可选
        "day": "字符串",    // 可选
        "hour": "字符串",   // 可选
        "minute": "字符串", // 可选
        "second": "字符串", // 可选
        "millisecond": "字符串", // 可选
        "format": "字符串", // 可选
        "display_text": "字符串" // 可选
    },
    "end_date": {           // 可选
        // 同start_date结构
    },
    "location": {           // 可选
        "icon": "字符串",   // 图标URL
        "lat": 浮点数,     // 纬度
        "lon": 浮点数,     // 经度
        "line": 布尔值,    // 是否显示线
        "name": "字符串",  // 地点名称
        "zoom": 整数       // 缩放级别
    },
    "media": {             // 媒体信息
        "caption": "字符串", // 说明文字
        "credit": "字符串",  // 来源信息
        "url": "字符串",    // 媒体URL
        "thumbnail": "字符串" // 缩略图URL
    },
    "text": {              // 文本内容
        "headline": "字符串", // 标题
        "text": "字符串"     // 正文
    },
    "unique_id": "字符串"   // 可选唯一标识
}