TimelineJS JSON 数据格式 - 译文 [原创]

张明云的知识共享

2018-05-29

TimelineJS 是用于绘制时间轴的 Javascript 开源脚本，目前是 TimelineJS3 版。参阅 https://github.com/NUKnightLab/TimelineJS3。
原文：https://timeline.knightlab.com/docs/json-format.html
译文：http://www.cnblogs.com/popapa/p/timelinejs_data.html
采集日期：2018-5-29

TimelineJS JSON 数据格式

Timeline 需要将事件相关的数据出来，多数人喜欢用 Google spreadsheet 配置 Timeline 数据。但如果想编写代码动态创建或更新时间轴，则需要了解生成结构化数据的方法。

如果只是想速战速决，或许复制一份示例数据（比如 Whitney Houston）就可以了。不然的话，就请阅读完整的文档，如下所示。

当知道如何为时间轴创建 JSON 数据后，还需要将其放在页面上。

TimelineJS 的 JSON 格式数据由一个 JSON 对象组成，包含以下属性：

名称	是否必填	说明
`events`	是	由 slide 对象组成的 JSON 列表（参阅下文）
`title`	否	slide 对象（参阅下文）
`eras`	否	由 era 对象（参阅下文）构成的 JSON 列表
`scale`	否	`human` 或 `cosmological`。未给出时的缺省值为`human`。当时间为非常遥远的古代或将来时，才会用到 `cosmological`。（早于公元前271821年4月20日星期二，或者晚于公元275760年9月13日星期六。）使用 `cosmological` 时，最小刻度单位是“年”。不过公元前271821年和公元275760年之间的时间，也是可以用 `cosmological` 的。

Slide 对象 带有以下属性：

名称	是否必填	说明
`start_date`	是（对 `title` 除外）	date 对象（参阅下文）
`end_date`	否	date 对象（参阅下文）
`text`	否（但推荐给出）	text 对象(参阅下文)
`media`	否	media 对象（参阅下文）
`group`	否	可填入任意文本。如果给出，则 Timeline 会将 `group` 值相同的事件归在同一行或相邻行，以明显与其他组的事件分隔开。同组的 group 值会作为标签显示在导航条的左侧。
`display_date`	否	Timeline 显示日期时用到的字符串。如果给出本值，就会覆盖此事件的开始或结束日期中的 display_date 值。如果要表达两个日期之间的相互关系，本值就非常有用。
`background`	否	Javascript 对象。可以带有以下属性： `url`：指向背景图片的完全限定格式 URL `color`：十六进制格式的 CSS 色彩值（如：`#0f9bd1`），或者合法的CSS 色彩关键字
`autolink`	否	布尔值（`true` 或 `false`）。默认为 `true`，表示 Timeline 会扫描 text 字段并自动添加 `<a>` 标签，使得链接和邮件地址“可被点击”。如果设置为 `false`，在需要用到链接时仍可以在字段中手动添加 `<a>` 标签。本自动链接属性适用于 `text` 对象中的 `text` 字段，以及 `media` 对象中的 `caption` 和 `credit` 字段。
`unique_id`	否	在 Timeline 所有 slide 中保持唯一的字符串值。如果未指定，TimelineJS 将根据标题构建一个 ID。但如果以后对标题进行了修改，自动生成的 ID 也将会随着更改。当在配置中启用了 `hash_bookmark` 参数时，本值才会生效。还可以与timeline.goToId()方法配合起来使用，以编程方式将时间线移动到指定的 slide。

Era 对象用于在时间轴导航组件上标记一段时间。本质上是个加了严格限制的 slide 对象。

名称	是否必填	说明
`start_date`	是	date 对象（参阅下文）
`end_date`	否	date 对象（参阅下文）
`text`	否（但推荐给出）	text 对象(参阅下文)

Date 对象带有以下属性：

Text 对象带有以下属性。slide 的 text 是可选项。

名称	是否必填	说明
`headline`	否	任意文本。可以包含 HTML 标记，也可以为空。
`text`	否	任意文本。可以包含 HTML 标记，也可以为空。对 era 对象不适用。

Media 对象带有以下属性。slide 的 Media 是可选项。

名称	是否必填	说明
`url`	是	多数情况下是个 URL，完整说明详见media 类型文档类型文档。
`caption`	否	任意文本。可以包含 HTML 标记。
`credit`	否	任意文本。可以包含 HTML 标记。
`thumbnail`	否	指向图片的 URL，供事件的 timenav 标记使用。如果省略，Timeline 将根据媒体类型自行选择图标。本属性与 `title` 型 slide 无关，因为它们不带标记。
`alt`	否	供图片的 alt 标记使用。如果未给出，则会用已给出的 caption。
`title`	否	图片的 title。如果未给出，则会用已给出的 caption。
`link_target`	否	如果用到了 link，则可供其 target 使用。