get-time-diff

可以快速获得两个时间的差值 --- 一个可配置的字符串 & 差值参数

暂无 git repo，bug feedback 可联系 [email protected]

1.0.0 存在严重 bug，建议升级。请尽可能在 Typescript 环境中使用。

使用方式

获取差值字符串

const timeDiffStr = require('get-time-diff');

const nowadays = new Date().getTime();

const ans = timeDiffStr({
  startDate: nowadays - 1000 * 60,
  endDate: nowadays,
});

console.log(ans);

1 分钟 0 秒 0 毫秒

支持自定义展示

const timeDiffStr = require('get-time-diff');

const nowadays = new Date().getTime();

const ans = timeDiffStr({
  startDate: nowadays - 1000 * 60,
  endDate: nowadays,
  options: {
    normalConfig: {
      units: {
        milliseconds: false, // 不展示 毫秒
      },
    },
  },
});

console.log(ans);

1 分钟 0 秒

本包依赖了 timediff，在 options.normalConfig 支持部分 timediff 功能。

国际化（暂不支持自定义，写死了中文和英文

const timeDiffStr = require('get-time-diff');

const nowadays = new Date().getTime();

const ans = timeDiffStr({
  startDate: nowadays - 1000 * 60 * 2,
  endDate: nowadays,
  options: {
    extraConfig: {
      lang: 'en',
      upper: 'first'
    }
  },
});

console.log(ans);

2 Minutes 0 Second 0 Millisecond

兜底策略（这个可以自定义

const timeDiffStr = require('get-time-diff');

const nowadays = new Date().getTime();

const ans = timeDiffStr({
  startDate: nowadays - 1000 * 60 * 2,
  endDate: nowadays,
  options: {
    extraConfig: {
      lang: 'en',
      upper: 'first',
      minimum: 1, // 最小值，需要配合 minimumKey 使用
      minimumKey: 'hours', // 最小单位
      // 这样如果两个时间差小于 1 hour，则会触发兜底
      minimumFallback: 'Too close! Just @@value@@ @@key@@'
      // 可以使用 @@ 来表示占位符
      // 默认是 "Less than @@value@@ @@key@@"
    }
  },
});

console.log(ans);

Too close! Just 1 Hour

================================================================

配置

总体配置

导入模块后，其就是一个函数，接受 1 个配置对象作为参数，第一层配置对象属性如下：

|参数名称|参数类型|意义|备注| |:---|:---|:---|:---| |startDate| 日期对象、字符串、数字 或 其它 |作为时间轴上的开始时间|日期对象会直接被使用，字符串或数字会传入 Date 构造函数中，如果是 其它 类型，则默认取当前时间| |endDate| 同 startDate |作为时间轴上的结束时间|同 startDate| |options| 配置对象 或一个 Callback| 进一步配置|配置对象的具体描述下文会说，但如果传递一个回调函数，这个函数将会在转换成功之后调用|

回调函数定义：(diff: Object, value: string, summaryDiff: Object) => void

• diff，记录了具体每一个值的差值，但结果可能会受 options 配置对象的影响
• value，原先函数的返回值，即一个字符串
• summaryDiff，绝对时间差值（1.0.3 支持）

注意，如果传入了 Callback，那么此时 get-time-diff 方法会 非异步调用 Callback，且将不再会有返回值，即 undefined

diff & summaryDiff 参数定义：

type Diff = {
  years?: number;
  months?: number;
  weeks?: number;
  days?: number;
  hours?: number;
  minutes?: number;
  seconds?: number;
  milliseconds?: number;
};

配置对象 options

|参数名称|意义| |:---|:---|:---| |normalConfig|timediff 库所支持的部分配置项| |extraConfig|额外配置项|

normalConfig 基础配置项

const normalConfig = {
  units: {
    years: true, // 年差值
    months: true, // 月差值
    weeks: true, // 周差值
    days: true, // 天差值
    hours: true, // 小时差值
    minutes: true, // 分钟差值
    seconds: true, // 秒差值
    milliseconds: true, // 毫秒差值
  },
  returnZeros: true, // 默认保留所有的值为 0 的项
  // 去掉了这里原本的  Callback！切勿在 normalConfig 中配置回调函数！
};

extraConfig 额外配置项

const extraConfig = {
  sequence: {}, // 时间单位，后续会详细描述

  lang: 'zh', // 默认是中文的时间单位，仅支持 'zh' 或 'en'

  // 'none'  不大写
  // 'first' 首字母大写
  // 'all'   全大写
  upper: 'none', // 仅针对 en 有效，是否大写单词

  // 最小兜底值的设置
  // 默认最小是 1 单位时间（1.0.7
  // 可以接受一个 数字类型 为值
  minimum: 1,

  // 最大天花板值，同 minimum
  maximum: Number.MAX_SAFE_INTEGER, // 天花板设置成最大值（1.0.7

  // 最小兜底值对应的单位
  // 如果 minimum 是 1
  // 那么配合 minimumKey 可得知，最小兜底是 1 毫秒
  // 详细取值为 sequence 时间单位的各个 key 值
  // 也是 normalConfig.units 的各个 key 值
  minimumKey: 'milliseconds', // 小于 x 毫秒

  // 同 minimumKey
  maximumKey: 'years', // 大于 x 年

  // 兜底文案，当触发某种兜底时可以自定义输出
  // 接受一个字符串，代表设置
  // 任何空值（包括 空字符串）都代表不设置
  // 字符串中可以使用占位符 @@ 来替换某些特殊的值：
  //    @@value@@，代表当前兜底时间值，即 minimum 或 maximum
  //    @@key@@，代表当前兜底单位，即 minimumKey 或 maximumKey
  // 默认兜底文案是：
  //     中文：
  //         minimum: '小于 @@value@@ @@key@@'
  //         maximum: 'Less than @@value@@ @@key@@'
  //     英文：
  //         minimum: '大于 @@value@@ @@key@@'
  //         maximum: 'More than @@value@@ @@key@@'
  minimumFallback: '',
  maximumFallback: '',

  savePrefixZero: false, // 默认不保留前缀 0
  saveSuffixZero: true, // 默认保留后缀 0

  // 1.0.3 新增
  // 可以自定义天花板溢出
  // 默认为 'years'（因为日常生活时间最长单位就是年
  // 例如 1 天 2 小时 0 分钟
  // 设置 ceilIgnore 为 'hours'
  // 结果就会变为
  // 26 小时 0 分钟
  ceilIgnore: 'years', 

  // 可以在 extraConfig 中单独设置 callback
  // 使用方法同直接传入
  callback: (diff: Diff, value: string): void => {},
};

CHANGELOG

|版本号|Fix|Feature|Other| |:---|:---|:---|:---| |1.0.7|修改兜底策略，调整天花板值|-|-| |1.0.6|-|-|将中文【日】改为【天】| |1.0.5|修复 returnZero 配置失效问题|-|-| |1.0.4|-|-|完善 README| |1.0.3|修复兜底策略逻辑问题|Callback 增加第三个参数，可以得到每个时间单位的绝对差值；extraConfig 增加配置项 ceilIgnore，可以设置最高单位，采用时间绝对差值|-| |1.0.2|-|-|修复 Markdown 样式问题| |1.0.1|修复部分 bug，完善 TypeScript 兼容|-|-| |1.0.0|-|-|初次发包|