前端数据可视化【免费下载链接】TimelineJSTimelineJS: A Storytelling Timeline built in JavaScript.项目地址https://gitcode.com/gh_mirrors/ti/TimelineJS点击查看免费下载本篇指南以 TimelineJSKnight Lab 出品的 JavaScript 时间线故事库为对象系统讲解如何在站点中嵌入时间线、全部可用的配置项语言、地图样式、字体、书签与调试等、四种数据来源格式JSON / JSONP / Google 表格 / Storify以及媒体自动识别机制并对照本仓库源码给出底层实现依据。读完本文你将能够从零搭建一个带多媒体、多语言、可自定义外观的时间线页面并理解其加载与数据解析的工作流程。版本状态提示本仓库对应 TimelineJS 的 2.x 一代实现。README 顶部明确声明该版本已停止开发GitHub issues 与 pull requests 均已关闭Knight Lab 已推出新一代 TimelineJS3。新一代兼容旧版 Google 表格数据但不兼容旧版 JSON 文件JSON 格式有变更且无直接转换工具。因此本文所述能力以当前仓库源码为准适用于维护旧项目或学习该库的设计接入新项目时应优先评估新版本。为什么用 TimelineJS网络上的时间线工具很多但几乎都难看得要命或者难用得要命README 原话hard on the eyes or hard to use。TimelineJS 的定位是同时做到美观与直观并且擅长聚合来自不同来源的媒体——只需粘贴一条 Twitter、YouTube、Flickr、Vimeo、Google Maps 或 SoundCloud 链接它就会自动拉取内容并格式化排版。制作一条时间线也非常灵活简单到填一张 Google 表格精细到手写 JSON。仓库中 examples 目录提供了完整的可直接运行的示例example_json.html、example_json.json、example_googlespreadsheet.html、example_storify.html 等是学习接入的最佳起点。嵌入到你的站点方式一内联配置最简单在页面body中放置一个空 div然后定义全局对象timeline_config最后引入storyjs-embed.js即可div idtimeline-embed/div script typetext/javascript var timeline_config { width: 100%, height: 600, source: path_to_json/or_link_to_googlespreadsheet, embed_id: timeline-embed, // 可选使用不同的 DIV ID start_at_end: false, // 可选从最新日期开始 start_at_slide: 4, // 可选从指定幻灯片开始 start_zoom_adjust: 3, // 可选微调默认缩放级别 hash_bookmark: true, // 可选在地址栏写入 hash 书签 font: Bevan-PotanoSans, // 可选字体组合 debug: true, // 可选向控制台输出调试信息 lang: fr, // 可选语言 maptype: watercolor, // 可选地图样式 css: path_to_css/timeline.css, // 可选自定义 CSS 路径 js: path_to_js/timeline-min.js // 可选自定义 JS 路径 } /script script typetext/javascript srcpath_to/storyjs-embed.js/script这里storyjs-embed.js可以从你本地构建产物加载参照 examples/example_json.html 中的../build/js/storyjs-embed.js也可以按 README 所述从 KnightLab CDN 加载。内联方式之所以最简单是因为嵌入脚本会自动探测全局配置。查看 source/js/Core/Embed/Embed.js 可以发现它按固定优先级检查四个全局变量url_config、timeline_config、storyjs_config、config一旦发现其中某个是对象就立即调用createStoryJS完成初始化。方式二调用 createStoryJS 方法进阶在storyjs-embed.js加载完成后也可以手动调用createStoryJS函数初始化时间线createStoryJS({ type: timeline, width: 800, height: 600, source: path_to_json/or_link_to_googlespreadsheet, embed_id: my-timeline // 目标 DIV 的 ID });结合 jQuery 的完整页面示例如下head !-- jQuery -- script typetext/javascript srcpath_to/jquery.min.js/script !-- BEGIN TimelineJS -- script typetext/javascript srcpath_to/storyjs-embed.js/script script $(document).ready(function() { createStoryJS({ type: timeline, width: 800, height: 600, source: path_to_json/or_link_to_googlespreadsheet, embed_id: my-timeline }); }); /script !-- END TimelineJS -- /head body div idmy-timeline/div /body加载文件CDN 与本地两种路径最省事的方式是只加载storyjs-embed.js它内部会自动完成其余资源jQuery、核心 JS、CSS、语言包、字体的按需加载。如果你需要更细粒度的控制可以分开加载 CSS 与 JS!-- 始终加载 CSS -- link relstylesheet typetext/css hrefpath_to/css/timeline.css !-- 二选一 -- script typetext/javascript srcpath_to/js/timeline.js/script !-- 或 -- script typetext/javascript srcpath_to/js/timeline-min.js/script !-- 不要两个都加载 --需要自建托管时可把构建产物build目录整个搬到自己服务器本地storyjs-embed.js会自动推导同源路径加载其余资源。这一机制在 source/js/Core/Embed/Embed.js 中有体现脚本通过扫描script标签找到storyjs-embed.js的 URL并据此推导embed_pathbase / css / js / locale 路径。加载流程源码级解析从 source/js/Core/Embed/Embed.js 可以看到完整的加载编排创建嵌入 divcreateEmbedDiv处理宽高为百分比或像素两种情况并行加载 CSS 与字体 CSS校验页面中已有的 jQuery 版本要求 ≥ 1.7.1不满足则从 CDN 拉取依次加载核心 JS、语言包非en时通过LazyLoad.js加载locale/xx.js每完成一项回调onloaded_check累计 40 次轮询上限每次间隔 250ms全部就绪后调用buildEmbed实例化VMM.Timeline并init(config)。字体方面内置了font_presets数组Embed.js每个预设对应一组 Google Fonts 族命中后通过 WebFont 加载器异步加载。配置选项Config Options除上述示例外README 还列出了以下配置项。下表汇总了所有选项、默认值与说明配置项默认值说明source必填JSON 资源路径、JS 数据对象或可自动识别的服务地址langen界面本地化语言start_at_endfalse设为true从最后一个日期开始start_at_slide0从指定幻灯片编号开始start_zoom_adjust0微调时间轴缩放级别正数放大、负数缩小hash_bookmarkfalse允许用地址栏 hash 书签定位幻灯片debugfalse向控制台输出事件日志gmap_key使用 maptype 时必须Google Maps API Keymaptype空地图样式Stamen / Google / OpenStreetMapfontdefault字体组合预设typetimeline组件类型width/height依嵌入方式时间线尺寸支持像素或百分比embed_idtimeline-embed目标容器 DIV 的 IDsource四种输入形态source既可以是 JSON 资源的路径也可以直接传入一个符合 Timeline 模型的 JavaScript 对象var dataObject {timeline: {headline: Headline, type: ...}} createStoryJS({ type: timeline, width: 800, height: 600, source: dataObject, embed_id: my-timeline });当source是字符串时加载器会自动识别资源类型。底层识别逻辑在 source/js/VMM.Timeline.DataObj.js 的getData中包含%23视为 Twitter 搜索包含spreadsheet视为 Google 表格包含storify.com视为 Storify 故事以.jsonp结尾视为 JSONP其余一律当作 JSON并自动拼接?callbackonJSONP_Data回调参数请求。Language 语言lang默认是enEnglish。README 列出的可用语言与仓库 source/js/Core/Language/locale 目录一一对应共 50 余种包括af南非荷兰语、ar阿拉伯语、hy亚美尼亚语、eu巴斯克语、be白俄罗斯语、bg保加利亚语、ca加泰罗尼亚语、zh-cn中文、hr克罗地亚语、cz捷克语、da丹麦语、nl荷兰语、en英语、en-24hr英语 24 小时制、eo世界语、et爱沙尼亚语、fo法罗语、fa波斯语、fi芬兰语、fr法语、fy弗里西语、gl加利西亚语、ka格鲁吉亚语、de德语、el希腊语、he希伯来语、hi印地语、hu匈牙利语、is冰岛语、id印度尼西亚语、ga爱尔兰语、it意大利语、ja日语、ko韩语、lv拉脱维亚语、lt立陶宛语、lb卢森堡语、ms马来语、ne尼泊尔语、no挪威语、pl波兰语、pt葡萄牙语、pt-br巴西葡萄牙语、ro罗马尼亚语、rm罗曼什语、ru俄语、sr-cy塞尔维亚语-西里尔、sr塞尔维亚语-拉丁、si僧伽罗语、sk斯洛伐克语、sl斯洛文尼亚语、es西班牙语、sv瑞典语、tl他加禄语、ta泰米尔语、zh-tw繁体中文、te泰卢固语、th泰语、tr土耳其语、uk乌克兰语等。语言文件结构可参考 en.js包含lang代码、date的月份/星期名、dateformats的日期格式模板和messages的界面文案。渲染时 VMM.Date.js 的setLanguage会用语言文件覆盖默认的月份名、缩写与日期格式。若想新增语言可按 DEVELOPER.md 的指引在 locale 目录添加以 ISO-639 代码命名的文件。其他行为类选项start_at_endtrue时时间线从最后一个日期开始。实现位于 VMM.Timeline.js 的build函数当config.start_at_end config.current_slide 0时把当前幻灯片设置为_dates.length - 1。start_at_slide从指定编号的幻灯片开始。对应 VMM.Timeline.jsparseInt(config.start_at_slide) 0时直接覆盖当前幻灯片。start_zoom_adjust微调时间轴缩放级别相当于按下指定次数的放大/缩小按钮负数缩小。在createConfig中被转换为config.nav.zoom.adjust见 VMM.Timeline.js时间轴导航组件据此调整缩放。hash_bookmarktrue时允许通过#哈希定位幻灯片。setHash会在滑动时将#编号写入地址栏VMM.Timeline.js同时window.onhashchange监听哈希变化驱动goToEvent跳转VMM.Timeline.js。debugtrue时向控制台输出事件日志。createStoryJS的buildEmbed会设置VMM.debug storyjs_e_config.debugEmbed.js随后各处trace()调用即受其控制同时debug还决定加载未压缩版timeline.js还是压缩版timeline-min.jsEmbed.js。Map Style Types 地图样式由于 Google Maps API 的变更使用自定义地图类型需要先提供 API Key。gmap_key是使用maptype的前提其值会在createConfig中被写入config.api_keys.googleVMM.Timeline.js供VMM.ExternalAPI.setKeys使用。maptype可选值Stamen Mapstoner、toner-lines、toner-labels、watercolor、sterrainGoogle MapsROADMAP、TERRAIN、HYBRID、SATELLITEOpenStreetMaposmFont Options 字体组合font用于切换标题与正文的字体组合预设包括配置值字体组合AbrilFatface-AverageAbril Fatface AverageArvo-PTSansArvo PT SansBevan-PotanoSansBevan Potano SansBreeSerif-OpenSansBree Serif Open SansDroidSerif-DroidSansDroid Serif Droid SansGeorgia-HelveticaGeorgia Helvetica NeueLekton-MolengoLekton MolengoMerriweather-NewsCycleMerriweather News CycleNewsCycle-MerriweatherNews Cycle MerriweatherNixieOne-LedgerNixie One LedgerPacifico-ArimoPacifico ArimoPlayfairDisplay-MuliPlayfair Display MuliPoiretOne-MolengoPoiret One MolengoPTSerif-PTSansPT Serif PT SansPTPT Sans PT Narrow PT SerifRancho-GudeaRancho GudeaSansitaOne-KameronSansita One Kameron也可以自行定制Or make your own。每个预设的 Google Fonts 定义与font_presets一一对应Embed.js同时对应 source/less/Core/Font 目录下的 LESS 主题文件如Bevan-PotanoSans.less构建时由 config.json 的lessc步骤编译为build/css/themes/font/*.css。各组合效果预览图见仓库本地副本文件格式File FormatsJSON原生数据格式JSON 是 TimelineJS 的原生数据格式。README 特别提醒JSON 非常挑剔一个放错的逗号或引号都可能导致时间线加载失败。以下是完整模型同时可对照 examples/example_json.json 的真实数据{ timeline: { headline:The Main Timeline Headline Goes here, type:default, text:pIntro body text goes here, some HTML is ok/p, asset: { media:http://yourdomain_or_socialmedialink_goes_here.jpg, credit:Credit Name Goes Here, caption:Caption text goes here }, date: [ { startDate:2011,12,10,07,02,10, endDate:2011,12,11,08,11, headline:Headline Goes Here, text:pBody text goes here, some HTML is OK/p, tag:This is Optional, classname:optionaluniqueclassnamecanbeaddedhere, asset: { media:http://twitter.com/ArjunaSoriano/status/164181156147900416, thumbnail:optional-32x32px.jpg, credit:Credit Name Goes Here, caption:Caption text goes here } } ], era: [ { startDate:2011,12,10, endDate:2011,12,11, headline:Headline Goes Here, text:pBody text goes here, some HTML is OK/p, tag:This is Optional } ] } }各字段含义顶层headline/type/text/asset构成封面幻灯片title slidedate数组为事件幻灯片startDate/endDate为起止日期headline/text为标题与正文支持 HTMLtag为标签classname可加自定义类名asset中的media为媒体链接、thumbnail为缩略图、credit为署名、caption为说明文字era数组用于时间轴上方的时代区间条。日期格式支持逗号分隔的年、月、日、时、分、秒、毫秒如2011,12,10,07,02,10也支持斜杠格式如12/10/2011。解析逻辑在 VMM.Date.js 的parse中逗号分隔按位setFullYear / setMonth / setDate / setHours / setMinutes / setSeconds并记录各部分精度年/月/日/时/分/秒用于决定日期显示粒度。事件在 VMM.Timeline.js 的buildDates中被逐一解析为内部日期对象并按时间排序若某条startDate为空会被跳过且当有效日期数与原始条数不一致时会提示Check for invalid date formats。JSONP跨域加载时间线支持 JSONP 变体以方便跨域加载数据。要点文件必须以.jsonp结尾且数据要赋给全局变量storyjs_jsonp_datastoryjs_jsonp_data { timeline: { headline:The Main Timeline Headline Goes here, type:default, text:pIntro body text goes here, some HTML is ok/p, asset: { media:http://yourdomain_or_socialmedialink_goes_here.jpg, credit:Credit Name Goes Here, caption:Caption text goes here }, date: [ { startDate:2011,12,10, endDate:2011,12,11, headline:Headline Goes Here, text:pBody text goes here, some HTML is OK/p, tag:This is Optional, classname:optionaluniqueclassnamecanbeaddedhere, asset: { media:http://twitter.com/ArjunaSoriano/status/164181156147900416, thumbnail:optional-32x32px.jpg, credit:Credit Name Goes Here, caption:Caption text goes here } } ], era: [ { startDate:2011,12,10, endDate:2011,12,11, headline:Headline Goes Here, tag:This is Optional } ] } }加载时 VMM.Timeline.DataObj.js 识别.jsonp后缀后用LoadLib.js动态注入该脚本脚本执行完毕后触发onJSONPLoaded读取全局storyjs_jsonp_data并派发data_ready事件。仓库提供了 examples/example_jsonp.html 与 examples/model.jsonp 可直接对照使用。Google DocsGoogle 表格不想手写 JSON 的话可以直接用 Google 表格构建时间线把日期、文本、链接填入 TimelineJS 模板的对应列即可。创建步骤如下将表格设为公开Google Docs 默认私有但时间线读取要求表格公开。点击右上角蓝色 Share 按钮在 Share settings 窗口中点击 Change...在 Visibility options 中选择 Public on the Web 并保存。发布到 Web在 File 菜单选择 Publish to the Web勾选 Automatically republish when changes are made取消其余勾选点击 start publishing得到可嵌入 HTML 的 URL。把 URL 粘贴进 HTML选择 Web Page 选项的链接而非 PDF、HTML、XLS 等粘贴到时间线 HTML 的source配置中。底层实现方面VMM.Timeline.DataObj.js 的extractSpreadsheetKey会从 URL 中解析表格 key兼容key参数与/spreadsheets/d/新版路径然后请求https://spreadsheets.google.com/feeds/list/{key}/{worksheet}/public/values?altjson解析数据16 秒超时且最多重试 3 次。数据行中type列为start/title时作为封面幻灯片为era时作为时代条其余作为事件幻灯片。若feed.entry缺失会提示检查是否有空行或表头是否被改动并降级尝试 cells 接口。示例页面见 examples/example_googlespreadsheet.html。StorifyStorify 支持仍处于早期阶段但可用直接把 Storify 故事链接作为source传入即可。底层 VMM.Timeline.DataObj.js 会调用 Storify API//api.storify.com/v1/stories/{user}/{slug}并把故事中的 image / quote / link / text / video 元素转换为事件幻灯片媒体链接与作者信息一并格式化。媒体Media仓库 zip 中附带一个 kitchen sink全功能演示示例展示如何整合 Twitter、YouTube、Flickr、Instagram、TwitPic、Wikipedia、Dailymotion、SoundCloud、Vimeo 等不同服务的媒体。用法极其简单把浏览器地址栏中的媒体 URL 复制粘贴到media参数即可TimelineJS 会通过各服务 API 自动拉取并格式化。媒体类型识别与渲染由 source/js/Core/Media/VMM.Media.js 与 VMM.MediaType.js 负责外部 API 封装集中在 VMM.ExternalAPI.js。最佳实践Best practicesREADME 给出了四条实战建议保持轻量不要被过量的文字或其他元素拖累选择有强时间线叙事的题材不适用于需要反复跳跃的时间线故事包含通向重大事件的过程性事件不要只放重大事件本身不要淹没用户几百个事件的时间线大概率不是该格式的最佳用法。源码结构与构建进阶阅读若需在本地构建或参与维护可参考 DEVELOPER.md 与 config.jsonsource目录为部署到 CDN 的资源源文件website目录为官方文档站点config.json 控制构建、暂存与部署。构建链路由 config.json 的build段落定义依次执行copy复制source下 CSS 图片与source/embed、lessc将 source/less/VMM.Timeline.less、source/less/Theme/Dark.less 与 source/less/Core/Font 编译为build/css/下的 CSS、process把 source/js/VMM.Timeline.js、source/js/VMM.Timeline.Min.js 及各 Embed 文件处理到build/js/、minify用 UglifyJS 压缩 locale 与核心 JS、usemin、banner写入版本与版权头。开发时可用fab serve在本地起服务预览fab build重新编译fab stage/fab stage_latest暂存到 CDN 仓库fab deploy部署文档站到 S3。注意环境要求 Python 2.7.x、Node.js、LESS 与 UglifyJS。许可证本项目采用 Mozilla Public License, v. 2.0MPL-2.0。完整声明见仓库根目录 LICENSE 文件。赞分享前端数据可视化【免费下载链接】TimelineJSTimelineJS: A Storytelling Timeline built in JavaScript.项目地址https://gitcode.com/gh_mirrors/ti/TimelineJS点击查看免费下载相关推荐SkyWalking OAP 动态配置接入 Nacos 2.x 完全指南配置项、存储模型与源码解析SkyWalking OAP 动态配置接入 Nacos 2.x 完全指南配置项、存储模型与源码解析 Nacos 2.x 可以作为 SkyWalking OAP可观测性APM链路追踪指标监控日志分析微服务Apache DolphinScheduler Oracle 数据源接入指南参数配置、ServiceName/SID 连接模式与源码实现解析Apache DolphinScheduler Oracle 数据源接入指南参数配置、ServiceName/SID 连接模式与源码实现解析 本指南以 Apa任务调度大数据后端前端ToolJet 接入 RethinkDB 数据源完整指南连接配置、13 种操作与源码实现解析ToolJet 接入 RethinkDB 数据源完整指南连接配置、13 种操作与源码实现解析 ToolJet 原生提供 RethinkDB 数据源连接器可让低代码后端前端AI 应用MCP 服务上一篇Atom多光标编辑技巧高效批量修改的终极指南下一篇xiaozhi-esp32 实操指南4 个场景把 ESP32 刷成 MCP 语音 AI 助手创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/25 2:43:47 · 阅读 1.2k TimelineJS 2.x 完整接入与配置指南：嵌入方式、数据模型与源码实现解析
前端数据可视化【免费下载链接】TimelineJSTimelineJS: A Storytelling Timeline built in JavaScript.项目地址https://gitcode.com/gh_mirrors/ti/TimelineJS点击查看免费下载本篇指南以 TimelineJSKnight Lab 出品的 JavaScript 时间线故事库为对象系统讲解如何在站点中嵌入时间线、全部可用的配置项语言、地图样式、字体、书签与调试等、四种数据来源格式JSON / JSONP / Google 表格 / Storify以及媒体自动识别机制并对照本仓库源码给出底层实现依据。读完本文你将能够从零搭建一个带多媒体、多语言、可自定义外观的时间线页面并理解其加载与数据解析的工作流程。版本状态提示本仓库对应 TimelineJS 的 2.x 一代实现。README 顶部明确声明该版本已停止开发GitHub issues 与 pull requests 均已关闭Knight Lab 已推出新一代 TimelineJS3。新一代兼容旧版 Google 表格数据但不兼容旧版 JSON 文件JSON 格式有变更且无直接转换工具。因此本文所述能力以当前仓库源码为准适用于维护旧项目或学习该库的设计接入新项目时应优先评估新版本。为什么用 TimelineJS网络上的时间线工具很多但几乎都难看得要命或者难用得要命README 原话hard on the eyes or hard to use。TimelineJS 的定位是同时做到美观与直观并且擅长聚合来自不同来源的媒体——只需粘贴一条 Twitter、YouTube、Flickr、Vimeo、Google Maps 或 SoundCloud 链接它就会自动拉取内容并格式化排版。制作一条时间线也非常灵活简单到填一张 Google 表格精细到手写 JSON。仓库中 examples 目录提供了完整的可直接运行的示例example_json.html、example_json.json、example_googlespreadsheet.html、example_storify.html 等是学习接入的最佳起点。嵌入到你的站点方式一内联配置最简单在页面body中放置一个空 div然后定义全局对象timeline_config最后引入storyjs-embed.js即可div idtimeline-embed/div script typetext/javascript var timeline_config { width: 100%, height: 600, source: path_to_json/or_link_to_googlespreadsheet, embed_id: timeline-embed, // 可选使用不同的 DIV ID start_at_end: false, // 可选从最新日期开始 start_at_slide: 4, // 可选从指定幻灯片开始 start_zoom_adjust: 3, // 可选微调默认缩放级别 hash_bookmark: true, // 可选在地址栏写入 hash 书签 font: Bevan-PotanoSans, // 可选字体组合 debug: true, // 可选向控制台输出调试信息 lang: fr, // 可选语言 maptype: watercolor, // 可选地图样式 css: path_to_css/timeline.css, // 可选自定义 CSS 路径 js: path_to_js/timeline-min.js // 可选自定义 JS 路径 } /script script typetext/javascript srcpath_to/storyjs-embed.js/script这里storyjs-embed.js可以从你本地构建产物加载参照 examples/example_json.html 中的../build/js/storyjs-embed.js也可以按 README 所述从 KnightLab CDN 加载。内联方式之所以最简单是因为嵌入脚本会自动探测全局配置。查看 source/js/Core/Embed/Embed.js 可以发现它按固定优先级检查四个全局变量url_config、timeline_config、storyjs_config、config一旦发现其中某个是对象就立即调用createStoryJS完成初始化。方式二调用 createStoryJS 方法进阶在storyjs-embed.js加载完成后也可以手动调用createStoryJS函数初始化时间线createStoryJS({ type: timeline, width: 800, height: 600, source: path_to_json/or_link_to_googlespreadsheet, embed_id: my-timeline // 目标 DIV 的 ID });结合 jQuery 的完整页面示例如下head !-- jQuery -- script typetext/javascript srcpath_to/jquery.min.js/script !-- BEGIN TimelineJS -- script typetext/javascript srcpath_to/storyjs-embed.js/script script $(document).ready(function() { createStoryJS({ type: timeline, width: 800, height: 600, source: path_to_json/or_link_to_googlespreadsheet, embed_id: my-timeline }); }); /script !-- END TimelineJS -- /head body div idmy-timeline/div /body加载文件CDN 与本地两种路径最省事的方式是只加载storyjs-embed.js它内部会自动完成其余资源jQuery、核心 JS、CSS、语言包、字体的按需加载。如果你需要更细粒度的控制可以分开加载 CSS 与 JS!-- 始终加载 CSS -- link relstylesheet typetext/css hrefpath_to/css/timeline.css !-- 二选一 -- script typetext/javascript srcpath_to/js/timeline.js/script !-- 或 -- script typetext/javascript srcpath_to/js/timeline-min.js/script !-- 不要两个都加载 --需要自建托管时可把构建产物build目录整个搬到自己服务器本地storyjs-embed.js会自动推导同源路径加载其余资源。这一机制在 source/js/Core/Embed/Embed.js 中有体现脚本通过扫描script标签找到storyjs-embed.js的 URL并据此推导embed_pathbase / css / js / locale 路径。加载流程源码级解析从 source/js/Core/Embed/Embed.js 可以看到完整的加载编排创建嵌入 divcreateEmbedDiv处理宽高为百分比或像素两种情况并行加载 CSS 与字体 CSS校验页面中已有的 jQuery 版本要求 ≥ 1.7.1不满足则从 CDN 拉取依次加载核心 JS、语言包非en时通过LazyLoad.js加载locale/xx.js每完成一项回调onloaded_check累计 40 次轮询上限每次间隔 250ms全部就绪后调用buildEmbed实例化VMM.Timeline并init(config)。字体方面内置了font_presets数组Embed.js每个预设对应一组 Google Fonts 族命中后通过 WebFont 加载器异步加载。配置选项Config Options除上述示例外README 还列出了以下配置项。下表汇总了所有选项、默认值与说明配置项默认值说明source必填JSON 资源路径、JS 数据对象或可自动识别的服务地址langen界面本地化语言start_at_endfalse设为true从最后一个日期开始start_at_slide0从指定幻灯片编号开始start_zoom_adjust0微调时间轴缩放级别正数放大、负数缩小hash_bookmarkfalse允许用地址栏 hash 书签定位幻灯片debugfalse向控制台输出事件日志gmap_key使用 maptype 时必须Google Maps API Keymaptype空地图样式Stamen / Google / OpenStreetMapfontdefault字体组合预设typetimeline组件类型width/height依嵌入方式时间线尺寸支持像素或百分比embed_idtimeline-embed目标容器 DIV 的 IDsource四种输入形态source既可以是 JSON 资源的路径也可以直接传入一个符合 Timeline 模型的 JavaScript 对象var dataObject {timeline: {headline: Headline, type: ...}} createStoryJS({ type: timeline, width: 800, height: 600, source: dataObject, embed_id: my-timeline });当source是字符串时加载器会自动识别资源类型。底层识别逻辑在 source/js/VMM.Timeline.DataObj.js 的getData中包含%23视为 Twitter 搜索包含spreadsheet视为 Google 表格包含storify.com视为 Storify 故事以.jsonp结尾视为 JSONP其余一律当作 JSON并自动拼接?callbackonJSONP_Data回调参数请求。Language 语言lang默认是enEnglish。README 列出的可用语言与仓库 source/js/Core/Language/locale 目录一一对应共 50 余种包括af南非荷兰语、ar阿拉伯语、hy亚美尼亚语、eu巴斯克语、be白俄罗斯语、bg保加利亚语、ca加泰罗尼亚语、zh-cn中文、hr克罗地亚语、cz捷克语、da丹麦语、nl荷兰语、en英语、en-24hr英语 24 小时制、eo世界语、et爱沙尼亚语、fo法罗语、fa波斯语、fi芬兰语、fr法语、fy弗里西语、gl加利西亚语、ka格鲁吉亚语、de德语、el希腊语、he希伯来语、hi印地语、hu匈牙利语、is冰岛语、id印度尼西亚语、ga爱尔兰语、it意大利语、ja日语、ko韩语、lv拉脱维亚语、lt立陶宛语、lb卢森堡语、ms马来语、ne尼泊尔语、no挪威语、pl波兰语、pt葡萄牙语、pt-br巴西葡萄牙语、ro罗马尼亚语、rm罗曼什语、ru俄语、sr-cy塞尔维亚语-西里尔、sr塞尔维亚语-拉丁、si僧伽罗语、sk斯洛伐克语、sl斯洛文尼亚语、es西班牙语、sv瑞典语、tl他加禄语、ta泰米尔语、zh-tw繁体中文、te泰卢固语、th泰语、tr土耳其语、uk乌克兰语等。语言文件结构可参考 en.js包含lang代码、date的月份/星期名、dateformats的日期格式模板和messages的界面文案。渲染时 VMM.Date.js 的setLanguage会用语言文件覆盖默认的月份名、缩写与日期格式。若想新增语言可按 DEVELOPER.md 的指引在 locale 目录添加以 ISO-639 代码命名的文件。其他行为类选项start_at_endtrue时时间线从最后一个日期开始。实现位于 VMM.Timeline.js 的build函数当config.start_at_end config.current_slide 0时把当前幻灯片设置为_dates.length - 1。start_at_slide从指定编号的幻灯片开始。对应 VMM.Timeline.jsparseInt(config.start_at_slide) 0时直接覆盖当前幻灯片。start_zoom_adjust微调时间轴缩放级别相当于按下指定次数的放大/缩小按钮负数缩小。在createConfig中被转换为config.nav.zoom.adjust见 VMM.Timeline.js时间轴导航组件据此调整缩放。hash_bookmarktrue时允许通过#哈希定位幻灯片。setHash会在滑动时将#编号写入地址栏VMM.Timeline.js同时window.onhashchange监听哈希变化驱动goToEvent跳转VMM.Timeline.js。debugtrue时向控制台输出事件日志。createStoryJS的buildEmbed会设置VMM.debug storyjs_e_config.debugEmbed.js随后各处trace()调用即受其控制同时debug还决定加载未压缩版timeline.js还是压缩版timeline-min.jsEmbed.js。Map Style Types 地图样式由于 Google Maps API 的变更使用自定义地图类型需要先提供 API Key。gmap_key是使用maptype的前提其值会在createConfig中被写入config.api_keys.googleVMM.Timeline.js供VMM.ExternalAPI.setKeys使用。maptype可选值Stamen Mapstoner、toner-lines、toner-labels、watercolor、sterrainGoogle MapsROADMAP、TERRAIN、HYBRID、SATELLITEOpenStreetMaposmFont Options 字体组合font用于切换标题与正文的字体组合预设包括配置值字体组合AbrilFatface-AverageAbril Fatface AverageArvo-PTSansArvo PT SansBevan-PotanoSansBevan Potano SansBreeSerif-OpenSansBree Serif Open SansDroidSerif-DroidSansDroid Serif Droid SansGeorgia-HelveticaGeorgia Helvetica NeueLekton-MolengoLekton MolengoMerriweather-NewsCycleMerriweather News CycleNewsCycle-MerriweatherNews Cycle MerriweatherNixieOne-LedgerNixie One LedgerPacifico-ArimoPacifico ArimoPlayfairDisplay-MuliPlayfair Display MuliPoiretOne-MolengoPoiret One MolengoPTSerif-PTSansPT Serif PT SansPTPT Sans PT Narrow PT SerifRancho-GudeaRancho GudeaSansitaOne-KameronSansita One Kameron也可以自行定制Or make your own。每个预设的 Google Fonts 定义与font_presets一一对应Embed.js同时对应 source/less/Core/Font 目录下的 LESS 主题文件如Bevan-PotanoSans.less构建时由 config.json 的lessc步骤编译为build/css/themes/font/*.css。各组合效果预览图见仓库本地副本文件格式File FormatsJSON原生数据格式JSON 是 TimelineJS 的原生数据格式。README 特别提醒JSON 非常挑剔一个放错的逗号或引号都可能导致时间线加载失败。以下是完整模型同时可对照 examples/example_json.json 的真实数据{ timeline: { headline:The Main Timeline Headline Goes here, type:default, text:pIntro body text goes here, some HTML is ok/p, asset: { media:http://yourdomain_or_socialmedialink_goes_here.jpg, credit:Credit Name Goes Here, caption:Caption text goes here }, date: [ { startDate:2011,12,10,07,02,10, endDate:2011,12,11,08,11, headline:Headline Goes Here, text:pBody text goes here, some HTML is OK/p, tag:This is Optional, classname:optionaluniqueclassnamecanbeaddedhere, asset: { media:http://twitter.com/ArjunaSoriano/status/164181156147900416, thumbnail:optional-32x32px.jpg, credit:Credit Name Goes Here, caption:Caption text goes here } } ], era: [ { startDate:2011,12,10, endDate:2011,12,11, headline:Headline Goes Here, text:pBody text goes here, some HTML is OK/p, tag:This is Optional } ] } }各字段含义顶层headline/type/text/asset构成封面幻灯片title slidedate数组为事件幻灯片startDate/endDate为起止日期headline/text为标题与正文支持 HTMLtag为标签classname可加自定义类名asset中的media为媒体链接、thumbnail为缩略图、credit为署名、caption为说明文字era数组用于时间轴上方的时代区间条。日期格式支持逗号分隔的年、月、日、时、分、秒、毫秒如2011,12,10,07,02,10也支持斜杠格式如12/10/2011。解析逻辑在 VMM.Date.js 的parse中逗号分隔按位setFullYear / setMonth / setDate / setHours / setMinutes / setSeconds并记录各部分精度年/月/日/时/分/秒用于决定日期显示粒度。事件在 VMM.Timeline.js 的buildDates中被逐一解析为内部日期对象并按时间排序若某条startDate为空会被跳过且当有效日期数与原始条数不一致时会提示Check for invalid date formats。JSONP跨域加载时间线支持 JSONP 变体以方便跨域加载数据。要点文件必须以.jsonp结尾且数据要赋给全局变量storyjs_jsonp_datastoryjs_jsonp_data { timeline: { headline:The Main Timeline Headline Goes here, type:default, text:pIntro body text goes here, some HTML is ok/p, asset: { media:http://yourdomain_or_socialmedialink_goes_here.jpg, credit:Credit Name Goes Here, caption:Caption text goes here }, date: [ { startDate:2011,12,10, endDate:2011,12,11, headline:Headline Goes Here, text:pBody text goes here, some HTML is OK/p, tag:This is Optional, classname:optionaluniqueclassnamecanbeaddedhere, asset: { media:http://twitter.com/ArjunaSoriano/status/164181156147900416, thumbnail:optional-32x32px.jpg, credit:Credit Name Goes Here, caption:Caption text goes here } } ], era: [ { startDate:2011,12,10, endDate:2011,12,11, headline:Headline Goes Here, tag:This is Optional } ] } }加载时 VMM.Timeline.DataObj.js 识别.jsonp后缀后用LoadLib.js动态注入该脚本脚本执行完毕后触发onJSONPLoaded读取全局storyjs_jsonp_data并派发data_ready事件。仓库提供了 examples/example_jsonp.html 与 examples/model.jsonp 可直接对照使用。Google DocsGoogle 表格不想手写 JSON 的话可以直接用 Google 表格构建时间线把日期、文本、链接填入 TimelineJS 模板的对应列即可。创建步骤如下将表格设为公开Google Docs 默认私有但时间线读取要求表格公开。点击右上角蓝色 Share 按钮在 Share settings 窗口中点击 Change...在 Visibility options 中选择 Public on the Web 并保存。发布到 Web在 File 菜单选择 Publish to the Web勾选 Automatically republish when changes are made取消其余勾选点击 start publishing得到可嵌入 HTML 的 URL。把 URL 粘贴进 HTML选择 Web Page 选项的链接而非 PDF、HTML、XLS 等粘贴到时间线 HTML 的source配置中。底层实现方面VMM.Timeline.DataObj.js 的extractSpreadsheetKey会从 URL 中解析表格 key兼容key参数与/spreadsheets/d/新版路径然后请求https://spreadsheets.google.com/feeds/list/{key}/{worksheet}/public/values?altjson解析数据16 秒超时且最多重试 3 次。数据行中type列为start/title时作为封面幻灯片为era时作为时代条其余作为事件幻灯片。若feed.entry缺失会提示检查是否有空行或表头是否被改动并降级尝试 cells 接口。示例页面见 examples/example_googlespreadsheet.html。StorifyStorify 支持仍处于早期阶段但可用直接把 Storify 故事链接作为source传入即可。底层 VMM.Timeline.DataObj.js 会调用 Storify API//api.storify.com/v1/stories/{user}/{slug}并把故事中的 image / quote / link / text / video 元素转换为事件幻灯片媒体链接与作者信息一并格式化。媒体Media仓库 zip 中附带一个 kitchen sink全功能演示示例展示如何整合 Twitter、YouTube、Flickr、Instagram、TwitPic、Wikipedia、Dailymotion、SoundCloud、Vimeo 等不同服务的媒体。用法极其简单把浏览器地址栏中的媒体 URL 复制粘贴到media参数即可TimelineJS 会通过各服务 API 自动拉取并格式化。媒体类型识别与渲染由 source/js/Core/Media/VMM.Media.js 与 VMM.MediaType.js 负责外部 API 封装集中在 VMM.ExternalAPI.js。最佳实践Best practicesREADME 给出了四条实战建议保持轻量不要被过量的文字或其他元素拖累选择有强时间线叙事的题材不适用于需要反复跳跃的时间线故事包含通向重大事件的过程性事件不要只放重大事件本身不要淹没用户几百个事件的时间线大概率不是该格式的最佳用法。源码结构与构建进阶阅读若需在本地构建或参与维护可参考 DEVELOPER.md 与 config.jsonsource目录为部署到 CDN 的资源源文件website目录为官方文档站点config.json 控制构建、暂存与部署。构建链路由 config.json 的build段落定义依次执行copy复制source下 CSS 图片与source/embed、lessc将 source/less/VMM.Timeline.less、source/less/Theme/Dark.less 与 source/less/Core/Font 编译为build/css/下的 CSS、process把 source/js/VMM.Timeline.js、source/js/VMM.Timeline.Min.js 及各 Embed 文件处理到build/js/、minify用 UglifyJS 压缩 locale 与核心 JS、usemin、banner写入版本与版权头。开发时可用fab serve在本地起服务预览fab build重新编译fab stage/fab stage_latest暂存到 CDN 仓库fab deploy部署文档站到 S3。注意环境要求 Python 2.7.x、Node.js、LESS 与 UglifyJS。许可证本项目采用 Mozilla Public License, v. 2.0MPL-2.0。完整声明见仓库根目录 LICENSE 文件。赞分享前端数据可视化【免费下载链接】TimelineJSTimelineJS: A Storytelling Timeline built in JavaScript.项目地址https://gitcode.com/gh_mirrors/ti/TimelineJS点击查看免费下载相关推荐SkyWalking OAP 动态配置接入 Nacos 2.x 完全指南配置项、存储模型与源码解析SkyWalking OAP 动态配置接入 Nacos 2.x 完全指南配置项、存储模型与源码解析 Nacos 2.x 可以作为 SkyWalking OAP可观测性APM链路追踪指标监控日志分析微服务Apache DolphinScheduler Oracle 数据源接入指南参数配置、ServiceName/SID 连接模式与源码实现解析Apache DolphinScheduler Oracle 数据源接入指南参数配置、ServiceName/SID 连接模式与源码实现解析 本指南以 Apa任务调度大数据后端前端ToolJet 接入 RethinkDB 数据源完整指南连接配置、13 种操作与源码实现解析ToolJet 接入 RethinkDB 数据源完整指南连接配置、13 种操作与源码实现解析 ToolJet 原生提供 RethinkDB 数据源连接器可让低代码后端前端AI 应用MCP 服务上一篇Atom多光标编辑技巧高效批量修改的终极指南下一篇xiaozhi-esp32 实操指南4 个场景把 ESP32 刷成 MCP 语音 AI 助手创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考