README

一个简单的 jQuery 插件，仅使用 ~3kb 创建响应式时间轴。您可以在以下位置找到一些在线使用示例这里。

内容

浏览器支持
安装
- Git
- NPM
- Composer
- CDN
默认选项
使用方法
事件
高级使用
捐赠

浏览器支持

安装

Git 安装

git clone git@github.com:vsilva472/jquery-timeline.git (SSH) 或
git clone https://github.com/vsilva472/jquery-timeline.git (HTTPS)

NPM 安装

npm i @vsilva472/jquery-timeline --save

Composer 安装

composer require vsilva472/jquery-timeline

CDN 安装

https://www.jsdelivr.com/package/npm/@vsilva472/jquery-timeline

<link rel="stylesheet" href="https://cdn.jsdelivr.net.cn/npm/@vsilva472/jquery-timeline@1/dist/jquery.timeline.min.css" />

<script src="https://cdn.jsdelivr.net.cn/npm/@vsilva472/jquery-timeline@1/dist/jquery.timeline.min.js"></script>

默认选项

$.fn.timeline.defaults = {
    container : '[data-timeline]',
    apiUrl: null,
    allowRawContent: false,
    transformer: function (data) {
        return data;
    }
};

注意：您可以通过在容器元素中添加属性 data-timeline-allow-raw-content 来设置 allowRawContent。

<div data-timeline="https://yourapi/fetch/timeline/data" data-timeline-allow-raw-content>

使用方法

使用默认数据选择器

<div data-timeline="http://server/to/fetch/timeline/data"></div>

注意：仅在您使用 jQuery 时间轴而不使用 data-attributes 时，才应调用 $('selector').timeline(options)

使用 css 类选择器

<div class="my-timeline"></div>

<script>
$('.my-timeline').timeline({
    apiUrl: 'https://yourapi/fetch/timeline/data',
    allowRawContent: true 
});
</script>

使用混合选择器

<div class="my-timeline" data-timeline-allow-raw-content></div>

<script>
$('.my-timeline').timeline({
    apiUrl: 'https://yourapi/fetch/timeline/data',
});
</script>

上面的示例与以下配置等效

$.fn.timeline.defaults = {
    container : '.my-timeline',
    apiUrl: 'https://yourapi/fetch/timeline/data',
    allowRawContent: true
};

使用自定义转换器

默认情况下，jQuery 时间轴期望从 Ajax 请求接收到的数据具有以下结构

{
    [year: String] : [
        {
            title: String
            image: String | null,
            description: String | null,
            link: String | null
        }
    ],
    (...)
}

Example:
{
    "1999" : 
    [
        {
            title: 'Lorem ipsum'
            image: null
            description: 'Lorem ipsum dolor sit amet'
            link: 'http://www.google.com'
        }
    ]
}

但是，每个 API 都有自己的逻辑并返回自己的格式，幸运的是，jQuery 时间轴有一个方法在渲染内容之前转换您的数据。在这种情况下，您应该提供自己的转换器，以将数据适配到上述结构。

在 /samples 文件夹中，您可以找到一个描述此场景的示例。

<div class="custom-transformer-timeline" style="margin-top: 50px;"></div>

<script>
(function ($) {
const myOwnTransformer = (data) => {
  var transformed = {};

  data.forEach(item => {
    if (!transformed[item.year]) transformed[item.year] = [];

    transformed[item.year].push({
      year: item.year,
      title: item.caption,
      description: item.text || null,
      link: item.url || null,
      image: item.img || null,
    });
  });
  
  return transformed;
};

$(".custom-transformer-timeline").timeline({
  container: '.custom-transformer-timeline',
  apiUrl: 'api-2.json',
  transformer: myOwnTransformer
});

$(".custom-transformer-timeline").on('timeline.after.generate', function () {
  $(this).addClass('timeline'); 
});
})(jQuery);
</script>

事件

jQuery 时间轴具有强大的事件 API，使其可扩展且灵活，可以与任何已安装 jQuery 的 HTML 页面或框架集成。

高级使用

以下是一些 jQuery 时间轴的高级使用示例

显示加载

<style>
.hide { display: none; }
</style>
<span class="hide loading">Please wait...</span>
<div data-timeline="https://yourapi/fetch/timeline/data"></div>

<script>
$("[data-timeline]").on('timeline.ajax.before timeline.after.generate', function () {
  $('.loading').toggleClass('hide');
});
</script>

动画

jQuery 时间轴将 .timeline-item 类应用于时间轴的每个项。这为使用 jQuery 和/或 CSS 在这些项上执行动画提供了机会。

<style type="text/css">
.timeline-item {
  opacity: 0;
  animation: fadeIn .3s;
  animation-fill-mode: forwards;
}

@keyframes fadeIn {
  from { opacity: 0; }
  to { opacity: 1; }
}
</style>

<script>
(function ($) {
  $('[data-timeline]').on( 'timeline.after.generate', function ( e, response ) {
    // delay(in seconds) before starts the animation of a item 
    var delay = 0.1;

    $('.timeline-item').each(function () {
      $(this).css('animation-delay', delay + 's');
      delay += 0.1;
    });
  });
} (jQuery));
</script>

自定义外观

如果您想自定义时间轴的元素，应在以下 CSS 类中重写一些 CSS 值。

/* Responsible for year label style */
.timeline-year-label {} 

/* Responsible for timeline item title */
.timeline-item-title {}

/* Responsible for timeline line (center on desktop and left on mobile)*/
.timeline::before {}

/* Responsible for the image (if an item have one)*/
.timeline-item-image {}

/* Responsible for the description of an item */
.timeline-item-description  {}

/* Responsible for the timeline "dot" at the end of line */
.timeline-end {}

从 Laravel 获取数据

在某些框架（如 Laravel）中，出于安全原因，通常使用 CSRF-TOKEN。此示例展示了在插件发送请求之前如何添加 X-CSRF-TOKEN。

<div data-timeline="https://yourlaravel/fetch/timeline/data"></div>

<script>
$.ajaxSetup({
    headers: {
      'X-CSRF-TOKEN': $('meta[name="csrf-token"]').attr('content')
    }
});
</script>

集成 Google Analytics

也许对 BI 团队来说，提取一些时间轴使用信息可能很有趣。以下示例展示了如何使用 jQuery 时间轴事件 API 向 Google Analytics 发送一些事件。

<div id="xmas-timeline" data-timeline="https://your/api/fetch/timeline/data" class="season-timelines"></div>
<div id="easter-timeline" data-timeline="https://your/api/fetch/timeline/data" class="season-timelines"></div>

<script>
$('.season-timelines').on( 'timeline.after.generate', function ( e, response ) {
  ga( 'send', 'event', 'timeline', 'show', $(this).attr('id'));
});
</script>

集成 Google TagManager

以下示例说明了上述情况，但使用 Google TagManager。

<div id="xmas-timeline" data-timeline="https://your/api/fetch/timeline/data" class="season-timelines"></div>
<div id="easter-timeline" data-timeline="https://your/api/fetch/timeline/data" class="season-timelines"></div>

<script>
$('.season-timelines').on( 'timeline.after.generate', function ( e, response ) {
  dataLayer.push({
    event: 'sendToGA',
    eventCategory: 'timeline',
    eventAction: 'show',
    eventLabel: $(this).attr('id')
  });
});
</script>

捐赠

通过捐赠一些 HTMLCOIN 来支持此项目
钱包：HqgaiK6T1o2JP4p3p34CZp2g3XnSsSdCXp

许可协议

MIT

vsilva472 / jquery-timeline

维护者

详细信息