@tmsfe/tms-core 0.0.61 → 0.0.64

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tmsfe/tms-core",
-  "version": "0.0.61",
+  "version": "0.0.64",
   "description": "tms运行时框架",
   "repository": {
     "type": "git",

package/src/index.js

@@ -25,11 +25,14 @@ import {
   round,
 } from './numUtils';
 import {
+  groupTimeDuration,
+  formatTimeDuration,
   formatTime,
   formatTimeStr,
   formatTimeWithDetails,
   formatDateTime,
   dateToString,
+  parseDateTime,
 } from './timeUtils';
 import {
   ipxInit,
@@ -157,11 +160,14 @@ const api = {
   round,
 
   /* 时间方法 */
+  groupTimeDuration,
+  formatTimeDuration,
   formatTime,
   formatTimeStr,
   formatTimeWithDetails,
   formatDateTime,
   dateToString,
+  parseDateTime,
 
   /* IPX方法 */
   ipxInit,

package/src/report/README.md

@@ -0,0 +1,201 @@
+# 埋点
+
+### 目前支持的数据能力
+<img width="700" src="https://tai-static-1251316161.cos.ap-chengdu.myqcloud.com/reportcos/tms-data.png"/>
+
+### 埋点展示网站：https://tmsgo.testsite.woa.com/reportManage/list
+
+### 目录结构
+```
+┌─ proxy        # 全埋点逻辑
+│  ├─ clone     # 负责对象的克隆
+│  ├─ component # 负责组件的全埋点
+│  ├─ helper    # 全埋点辅助类
+│  ├─ index     # 负责页面和组件的全埋点初始化
+│  ├─ page      # 负责页面的全埋点
+│  └─ types     # 全埋点ts类型定义
+│
+├─ formatV1     # 格式化旧埋点
+├─ formatV2     # 格式化新埋点
+├─ helper       # 埋点辅助函数
+├─ index        # 埋点入口
+├─ sender       # 负责发送埋点
+└─ types        # ts类型定义
+```
+
+### 埋点的基础字段有哪些？
+不管是全埋点还是手动埋点，都会携带相同的基础字段，具体请查看```formatV2.ts```代码
+
+### 手动添加埋点
+```coffeescript
+1. const reporter = getApp().tms.getReporter();
+   // 点击登录按钮|用户名
+2. reporter.report2('login_btn_click', this.data.username);
+```
+#### 说明：
+1. 新埋点函数名为```report2()```，旧埋点函数名为```report()```，不建议再用旧埋点
+2. 埋点上方一定要写注释说明埋点每个参数的定义，用"|"隔开
+3. 构建平台在每次构建时会调用工具分析代码提取出埋点列表更新到展示网站数据库
+4. 埋点函数第一个参数为事件名，必须为string，其他参数为该事件附带数据，可以是基础类型，也可以是json对象
+
+#### 问题
+1. 代码中已有的旧埋点怎么办？可以保留，但是不建议再新增旧埋点
+2. 埋点发送机制是怎么样的？普通埋点采用合并上报的方式，通常3s上报一次，如果小程序关闭则会立即上报
+3. 如果有埋点需要立即上报该怎么办？可以把```report2()```改为调用```fastReport2()```
+4. ```report2()```与```fastReport2()```的区别是什么？```fastReport2()```上报时携带的"省"、"市"等需要异步请求的基础字段会从缓存中读取，如果无缓存则为空，```report2()```则一定会携带这些字段
+
+### 全埋点
+#### 页面自动上报事件
+##### 一、必须上报的生命周期事件：
+1. onLoad: 页面加载
+2. onShow: 页面显示
+3. onReady: 页面初次渲染完成
+4. onHide: 页面隐藏
+5. onUnload: 页面卸载
+
+##### 二、可能会上报的生命周期事件（取决于页面是否实现该函数）：
+1. onPullDownRefresh: 用户下拉动作
+2. onReachBottom: 页面上拉触底
+3. onShareAppMessage: 用户点击右上角转发
+4. onShareTimeline: 用户点击右上角转发到朋友圈
+5. onAddToFavorites: 用户点击右上角收藏
+6. onReportPageTouch: 用户触摸页面 - 如果页面wxml有view节点则会注入该事件
+
+##### 三、页面的其他bind事件，通过分析wxml得出
+#### 组件自动上报事件
+1. ready: 组件加载（会携带组件data）
+2. 组件的其他bind事件，通过分析wxml得出（会携带组件data）
+
+#### 其他自动上报事件
+1. App_onLaunch: 小程序启动
+2. wx_navigateTo_before: 页面即将跳转
+3. wx_redirectTo_before: 页面即将重定向
+4. wx_reLaunch_before: 小程序即将重启
+
+#### 注意事项
+1. bind事件函数上方要写注释，工具提取该事件时会把注释也提取出来，用作该事件说明
+2. Page或者Component的data要写注释，工具会提取data代码附到埋点说明中
+3. 某个事件触发很频繁觉得上报没意义，在函数注释中加上```ignoreReport```这个单词就不会上报该函数
+```coffeescript
+/**
+ * 拖动组件
+ * ignoreReport
+ */
+onTouchMove(e) {
+  ...
+}
+or
+// ignoreReport
+onTouchMove(e) {
+  ...
+}
+```
+
+#### 哪种bind事件的写法会使全埋点上报时把最新的data也带上？
+ps：tms-core会先执行事件函数，然后判断返回值是否promise，如果时则会等promise.then或catch之后再上报，非promise则直接上报
+1. 函数中直接setData
+```coffeescript
+/**
+ * 点击关闭按钮
+ */
+onCloseBtnTap() {
+  this.setData({ show: false });
+}
+```
+2. 函数返回promise的
+```coffeescript
+/**
+ * 点击登录按钮
+ */
+onLoginBtnTap() {
+  return tms.login().then((res) => {
+    this.setData({ userName: res.userName });
+  });
+}
+or
+/**
+ * 点击登录按钮
+ */
+async onLoginBtnTap() {
+  const res = await tms.login();
+  this.setData({ userName: res.userName });
+}
+```
+
+#### 哪种bind事件的写法会使全埋点上报时不把最新的data也带上？
+1. 函数中异步setData但是没有返回promise的
+```coffeescript
+/**
+ * 点击登录按钮
+ */
+onLoginBtnTap() {
+  tms.login().then((res) => {
+    this.setData({ userName: res.userName });
+  });
+}
+```
+
+#### 如何在开发过程中开启全埋点？
+1. 切到新脚手架的小程序目录下
+  ```
+  cd miniprogram/programs/sinan/dist
+  ```
+2. 运行工具
+  ```
+  node ../../../../tools/tms-prebuild/main.js
+  ```
+3. 等待工具跑完
+
+
+#### 如何判断全埋点是否满足产品需求？
+1. 目标事件是页面生命周期函数触发时上报，且不需要带data
+2. 目标事件是组件挂载(ready)，并且需要携带的参数在组件data中
+3. 目标事件是页面或者组件的bind事件，并且需要携带的参数在data或者函数的首个参数中(event的dataset、mark、detail)
+
+#### 埋点提取工具AST匹配规则
+```coffeescript
+/**
+ * 提取旧埋点
+ * @param content {string}
+ * @param rootAst {GoGoAST}
+ * @returns {DataInfo[]}
+ */
+function extractV1(content, rootAst) {
+  const paramsKey = '$$$0';
+  const selector = [
+    `report({ ${paramsKey} })`,
+    `Report({ ${paramsKey} })`,
+    `reportLog({ ${paramsKey} })`,
+    `fastReport({ ${paramsKey} })`,
+    `$_$1.report({ ${paramsKey} })`,
+    `$_$1.Report({ ${paramsKey} })`,
+    `$_$1.reportLog({ ${paramsKey} })`,
+    `$_$1.fastReport({ ${paramsKey} })`,
+  ];
+  const ast = rootAst.find(selector);
+  const result = [];
+  ast.each((node) => { 处理逻辑... });
+  return result;
+}
+
+
+/**
+ * 提取新埋点
+ * @param content
+ * @param rootAst {GoGoAST}
+ * @returns {DataInfo[]}
+ */
+function extractV2(content, rootAst) {
+  const paramsKey = '$$$0';
+  const selector = [
+    `report2(${paramsKey})`,
+    `fastReport2(${paramsKey})`,
+    `$_$1.report2(${paramsKey})`,
+    `$_$1.fastReport2(${paramsKey})`,
+  ];
+  const ast = rootAst.find(selector);
+  const result = [];
+  ast.each((node) => { 处理逻辑... });
+  return result;
+}
+```

package/src/report/proxy/component.ts

@@ -12,9 +12,12 @@ let originalComponent: any = null;
 // 劫持Component的生命周期
 function proxyLifeMethod(componentName: string, componentOptions: any, methodName: string): void {
   /* eslint-disable */
-  componentOptions.lifetimes = componentOptions.lifetimes || {};
-  let original = helper.emptyFunc;
-  const proxyMethod = function (...args: any[]): any {
+  let obj = componentOptions;
+  if (componentOptions.lifetimes?.hasOwnProperty(methodName)) {
+    obj = componentOptions.lifetimes;
+  }
+  let original = obj[methodName] || helper.emptyFunc;
+  obj[methodName] = function (...args: any[]): any {
     // 生命周期函数先发埋点，避免次过程用户退出而丢失埋点
     const data = clone.deepClone(this.data);
     const eventName = `Component_${componentName}_${methodName}`;
@@ -22,15 +25,6 @@ function proxyLifeMethod(componentName: string, componentOptions: any, methodNam
     // 执行原函数
     return helper.executeFunc(this, original, args, helper.emptyFunc);
   }
-  if (componentOptions.lifetimes[methodName]) {
-    original = componentOptions.lifetimes[methodName];
-    componentOptions.lifetimes[methodName] = proxyMethod;
-  } else if (componentOptions[methodName]) {
-    original = componentOptions[methodName];
-    componentOptions[methodName] = proxyMethod;
-  } else {
-    componentOptions.lifetimes[methodName] = proxyMethod;
-  }
   /* eslint-enable */
 }
 

package/src/report/proxy/helper.ts

@@ -1,5 +1,5 @@
 /**
- * 自动埋点辅助类
+ * 全埋点辅助类
  */
 
 // / <reference path='./types.ts'/>

package/src/report/proxy/page.ts

@@ -29,9 +29,8 @@ function proxyLifeMethod(pageOptions: any, methodName: string): void {
   // eslint-disable-next-line no-param-reassign
   pageOptions[methodName] = function (...args: any[]): any {
     // 生命周期函数先发埋点，避免次过程用户退出而丢失埋点
-    const options = methodName === pageTouchEvent ? '' : clone.deepClone(args[0], 0, 1);
     const extra = getPageLifeExtra(this, methodName, args);
-    helper.reportData(`Page_${methodName}`, options, extra);
+    helper.reportData(`Page_${methodName}`, extra);
 
     // 执行原函数
     return helper.executeFunc(this, original, args, helper.emptyFunc);
@@ -126,11 +125,11 @@ function proxyNavigateApi(api: string): void {
     enumerable: true,
     configurable: true,
     value(...args: any) {
-      originalApi.apply(this, args);
-
       const { url = '' } = args[0] || {};
       const [path, params = ''] = url.split('?');
-      helper.reportData('wx_navigate_before', api, path, params);
+      helper.reportData(`wx_${api}_before`, path, params);
+
+      originalApi.apply(this, args);
     },
   });
 }
@@ -139,8 +138,8 @@ function proxyNavigateApi(api: string): void {
 function init(): void {
   proxyPage();
   proxyNavigateApi('navigateTo');
-  proxyNavigateApi('reLaunch');
   proxyNavigateApi('redirectTo');
+  proxyNavigateApi('reLaunch');
 }
 
 export default {

package/src/storage.js

@@ -46,10 +46,14 @@ const cleanQueue = [];
 let cleanTimerId = 0;
 
 function cleanTask() {
+  const { keys } = wx.getStorageInfoSync();
   while (cleanQueue.length > 0) {
     const { key, version } = cleanQueue.pop();
     for (let i = version - 1; i > version - 10 && i > 0; i--) {
-      removeItem(`${key}_v${i}`);
+      const str = `${key}_v${i}`;
+      if (keys.includes(str)) {
+        removeItem(str);
+      }
     }
   }
   cleanTimerId = 0;
@@ -64,9 +68,11 @@ function cleanTask() {
  */
 function setCacheData(key, version, data) {
   // 异步清理旧数据，不要阻塞当前线程
-  cleanQueue.push({ key, version });
-  if (cleanTimerId === 0) {
-    cleanTimerId = setTimeout(cleanTask, 2000);
+  if (!cleanQueue.some(q => q.key === key && q.version === version)) {
+    cleanQueue.push({ key, version });
+    if (cleanTimerId === 0) {
+      cleanTimerId = setTimeout(cleanTask, 2000);
+    }
   }
 
   const str = `${key}_v${version}`;

package/src/stringUtils.js

@@ -125,19 +125,21 @@ const isValidPlate = (plate) => {
  * @returns {string} 返回四舍五入后的字符串，异常情况下返回空字符串''
  */
 const roundStr = (x, n = 2, removeTrailingZero = false) => {
-  let xNum = Number(x); // x转换为数字
   const nNum = Math.floor(Number(n)); // n转换为数字，且只保留整数部分
+  let xNum = Number(x); // x转换为数字
 
   // 异常情况，返回''
-  if (isNaN(xNum) || isNaN(nNum) || nNum < 0) return '';
+  if (isNaN(xNum) || isNaN(nNum) || nNum < 0) {
+    return '';
+  }
 
   // 仅保留整数的情况
-  if (nNum === 0) return Math.round(xNum);
+  if (nNum === 0) {
+    return Math.round(xNum).toString();
+  }
 
-  // 保留n位小数的情况
-  const xStr = xNum.toString();
   const rexExp = new RegExp(`\\.\\d{${nNum}}5`);
-
+  // 保留n位小数的情况
   // 1. 大部分情况下，四舍五入使用Number.toFixed即可
   // 2. 然而，Number.toFixed方法在某些情况下对第n+1位是5的四舍五入存在问题，如1.325保留2小数时结果为1.32（期望为1.33）
   //    对此种情况下，有两种处理方式：
@@ -146,18 +148,21 @@ const roundStr = (x, n = 2, removeTrailingZero = false) => {
   //    2.2 Number.toFixed是四舍6入，对于第n+1位是5的情况，增加2*10^(-n-1)，保证满足第n+1位>6
   //        增加2*10^(-n-1)而不是增加1*10^(-n-1)是因为后者不能保证第n+1位>=6，例如1.325+0.001=1.32599999...第n+1位仍然为5
   // 此处，采用2.2方式，解决Number.toFixed的问题，又能避免2.1方式中数字超过Infinity的问题
-  if (rexExp.test(xStr)) { // 情况2，处理方式2.1：如果小数部分第n+1位是5，增加2*10^(-n-1)
+  // 情况2，处理方式2.1：如果小数部分第n+1位是5，增加2*10^(-n-1)
+  if (rexExp.test(xNum.toString())) {
     xNum += 2 * (10 ** (-nNum - 1));
   }
 
   const str = xNum.toFixed(nNum);
-  if (!removeTrailingZero) return str;
+  if (!removeTrailingZero) {
+    return str;
+  }
 
   // 去除末尾的0
   if (/^\d+\.0*$/.test(str)) { // 小数部分全是0
     return str.replace(/^(\d+)(\.0*)$/, (_m, s1) => s1);
   }
-  return str.replace(/^(\d+\.\d*[1-9]{1})(0*)$/, (_m, s1) => s1);
+  return str.replace(/^(\d+\.\d*[1-9])(0*)$/, (_m, s1) => s1);
 };
 
 export {

package/src/timeUtils.js

@@ -7,6 +7,86 @@
  *    2017-07-26 @davislu modify.
  */
 
+import { round } from './numUtils';
+import { roundStr } from './stringUtils';
+
+/**
+ * 将时间段进行聚合计算，得出不同时间单位的计数值，例如：3601秒 -> { hour: 1, minute: 0, second: 1 }，即：1小时0分1秒
+ * @param {Number} seconds 时间段的总秒数
+ * @param {String} maxUnit 最大计数单位：second-秒，minute-分，hour-小时，day-天，month-月，year-年；默认 year
+ *                         单位大小：year > Month > day > hour > month > second
+ * @param {String} minUnit 最小计数单位：second-秒，minute-分，hour-小时，day-天，month-月，year-年；默认 second
+ * @param {Number} decimal 有不足最小单位数值的情况下，保留几位小数；默认 2
+ * @returns {Object} result 各计数单位下的数值：
+ *   {Number} result.year    - 年；  当maxUnit < 'year' 时，此字段永远为0；此字段为-1时，表示 seconds 参数非法 或 minUnit > maxUnit等异常情况
+ *   {Number} result.month   - 月；  当maxUnit < 'month' 时，此字段永远为0；
+ *   {Number} result.day     - 天；  当maxUnit < 'day' 时，此字段永远为0；
+ *   {Number} result.hour    - 小时；当maxUnit < 'hour' 时，此字段永远为0；
+ *   {Number} result.minute  - 分钟；当maxUnit < 'minute' 时，此字段永远为0；
+ *   {Number} result.second  - 秒；
+ *   {Number} result.decimal - 不足最小单位的部分，具体含义与 minUnit 参数相关；例如 minUnit = day 时，此字段表示不足1天的部分
+ */
+const groupTimeDuration = (seconds, maxUnit = 'year', minUnit = 'second', decimal = 2) => {
+  // 时间参数（seconds）检查
+  const sec = typeof seconds === 'number' ? seconds : parseFloat(seconds);
+  if (isNaN(sec)) return { year: -1, month: 0, day: 0, hour: 0, minute: 0, second: 0, decimal: 0 };
+
+  // 各时间单位对应的秒数
+  const unitSeconds = { year: 31536000, month: 2592000, day: 86400, hour: 3600, minute: 60, second: 1 };
+
+  // 时间单位参数（minUnit，maxUnit）检查
+  const minSeconds = unitSeconds[minUnit] || unitSeconds.second;
+  const maxSeconds = unitSeconds[maxUnit] || unitSeconds.year;
+  if (maxSeconds < minSeconds) return { year: -1, month: 0, day: 0, hour: 0, minute: 0, second: 0, decimal: 0 };
+
+  // 截取在 minUnit maxUnit 之间的计数单位，并按从大到小排序
+  const allUnitKeys = Object.keys(unitSeconds);
+  const groupUnits = allUnitKeys
+    .filter(unit => unitSeconds[unit] >= minSeconds && unitSeconds[unit] <= maxSeconds) // 过滤超出范围的单位
+    .sort((a, b) => unitSeconds[b] - unitSeconds[a]) // 排序
+    .map(unit => ({ name: unit, seconds: unitSeconds[unit] })); // 转换为 { name, seconds } 的形式，方便后面用
+
+  // 各返回字段初始赋值
+  const result = { decimal: 0 };
+  allUnitKeys.forEach(unit => result[unit] = 0);
+  // 从大到小逐个计算赋值
+  // const periodArr = [];
+  let restSeconds = sec; // 剩余待统计描述
+  groupUnits.forEach((unit) => {
+    const curUnitNum = Math.floor(restSeconds / unit.seconds); // 高于当前计数单位的数值
+    result[unit.name] = curUnitNum; // 例如 { year: 1 }
+    restSeconds %= unit.seconds;
+    if (unit.seconds === minSeconds) result.decimal = round(restSeconds / minSeconds, decimal);
+  });
+  return result;
+};
+
+/**
+ * 将时间段进行聚合计算并格式化，得出方便人阅读的文案，例如：3601秒 -> 1小时0分1秒
+ * @param {Number} seconds 时间段的总秒数
+ * @param {String} maxUnit 最大计数单位：second-秒，minute-分，hour-小时，day-天，month-月，year-年；默认 year
+ *                         单位大小：year > Month > day > hour > month > second
+ * @param {String} minUnit 最小计数单位：second-秒，minute-分，hour-小时，day-天，month-月，year-年；默认 second
+ * @param {Number} decimal 有不足最小单位数值的情况下，保留几位小数；默认 2
+ * @returns {String} 示例见测试用例
+ */
+const formatTimeDuration = (seconds, maxUnit = 'year', minUnit = 'second', decimal = 2) => {
+  const result = groupTimeDuration(seconds, maxUnit, minUnit, decimal);
+  if (result.year === -1) return ''; // seconds 不合法 或 maxUnit < minUnit
+  const unitWording = { year: '年', month: '月', day: '天', hour: '小时', minute: '分钟', second: '秒' };
+  const periodArr = [];
+  ['year', 'month', 'day', 'hour', 'minute', 'second'].forEach((unit) => {
+    if (unit !== minUnit) {
+      if (result[unit] > 0) periodArr.push(`${result[unit]}${unitWording[unit]}`); // 如2小时
+    } else { // 当前unit是最小单位，处理不足最小单位的部分
+      const min = round(result[unit] + result.decimal, decimal);
+      if (min > 0) periodArr.push(`${roundStr(min, 2, true)}${unitWording[unit]}`); // 如1.2，0.2
+      else if (periodArr.length === 0) periodArr.push(`1${unitWording[unit]}内`); // 1 unit内
+    }
+  });
+  return periodArr.join('');
+};
+
 /**
  * @function
  * @description 格式化时间
@@ -15,72 +95,44 @@
  */
 const formatTime = (seconds) => {
   if (typeof seconds !== 'number') return seconds;
-
-  const PER_MINUTE = 60 * 1;
-  const PER_HOUR = 60 * PER_MINUTE;
-  const PRE_DAY = 24 * PER_HOUR;
-  let cost = '';
+  const { day, hour, minute, decimal } = groupTimeDuration(seconds, 'day', 'minute', 2);
   // >24小时的显示  【x天】
-  if (seconds >= PRE_DAY) {
-    cost = `${Math.floor(seconds / PRE_DAY)}天`;
+  if (day > 0) return `${day}天`;
   // <1小时的显示  【x分钟】 ，x取整数上限，最低为1分钟。
-  } else if (seconds < PER_HOUR) {
-    cost = `${Math.ceil(seconds / PER_MINUTE)}分钟`;
+  if (hour === 0) return `${Math.ceil(minute + decimal)}分钟`;
   // <24小时&>1小时的显示  【x小时y分钟】 ，分钟取整数上限
-  } else {
-    cost = `${Math.floor(seconds / PER_HOUR)}小时`;
-    const s = seconds % PER_HOUR;
-    if (s > 0) {
-      cost += `${Math.ceil(s / PER_MINUTE)}分钟`;
-    }
-  }
-
+  let cost = `${hour}小时`;
+  const min = Math.ceil(minute + decimal);
+  if (min > 0) cost += `${min}分钟`;
   return cost;
 };
 
 /**
  * @function
  * @description 将秒数格式化为x天y小时z分钟
- * @param       {Number} oriSeconds 秒数
+ * @param       {Number} seconds 秒数
  * @returns      {String} 格式化后的文案
  */
-const formatTimeWithDetails = (oriSeconds) => {
-  let seconds = oriSeconds;
+const formatTimeWithDetails = (seconds) => {
   // 非Number类型，直接返回，不进行处理
   if (typeof seconds !== 'number') return seconds;
   // 参数为NaN类型，直接抛出异常
   if (isNaN(seconds)) throw new Error(`formatTimeWithDetails方法的参数seconds必须时一个非NaN数字，现在的值为${seconds}`);
 
-  // 定义一些常量
-  // 1分钟包含的秒数
-  const PER_MINUTE = 60 * 1;
-  // 1小时包含的秒数
-  const PER_HOUR = 60 * PER_MINUTE;
-  // 1天包含的秒数
-  const PRE_DAY = 24 * PER_HOUR;
+  const { day, hour, minute, decimal } = groupTimeDuration(seconds, 'day', 'minute', 2);
   let cost = '';
-
-  // 秒数多于1天
-  if (seconds >= PRE_DAY) {
-    cost = `${Math.floor(seconds / PRE_DAY)}天`;
-    seconds %= PRE_DAY;
-  }
-
-  // 秒数小于1小时
-  if (seconds < PER_HOUR) {
-    if (cost) {
-      cost += '0小时';
-    }
-    cost += `${Math.ceil(seconds / PER_MINUTE)}分钟`;
-  } else {
-    // 秒数介于1天和1分钟之间
-    cost += `${Math.floor(seconds / PER_HOUR)}小时`;
-    const s = seconds % PER_HOUR;
-    if (s > 0) {
-      cost += `${Math.ceil(s / PER_MINUTE)}分钟`;
-    }
+  const min = Math.ceil(minute + decimal);
+  if (day > 0) { // 秒数多于1天
+    cost = `${day}天${hour}小时`;
+    // 这里大概率是有bug的，从测试用例里能看出：formatTime(86400) => 1天0小时0分钟
+    // 但为了不改变方法原有表现，先这样吧
+    if (min > 0 || hour === 0) cost += `${min}分钟`;
+  } else if (hour === 0) { // 秒数小于1小时
+    cost = `${min}分钟`;
+  } else { // 秒数介于1天和1分钟之间
+    cost = `${hour}小时`;
+    if (min > 0) cost += `${min}分钟`;
   }
-
   return cost;
 };
 
@@ -157,10 +209,49 @@ const dateToString = (date, withTime = false, withSeconds = false, join = '-') =
   return formatDateTime(date || new Date(), fmt);
 };
 
+/**
+ * 将时间字符串转换为Date对象
+ * @param {String} str  时间字符串，如：2022-03-24 20:02:05
+ *   支持对日期完整但时间部分缺失的情况进行处理，如：
+ *     2022-03-24 20:02 -> Date(1648123320000)
+ *     2022-03-24 20:   -> Date(1648123200000)
+ *     2022-03-24 20    -> Date(1648123200000)
+ *     2022-03-24       -> Date(1648051200000)
+ *   小于10的数字可以省略0：
+ *     2022-3-24 20:2   -> Date(1648123320000)
+ *   支持任意分割符，如：
+ *     2022年03月24日 20时02分 -> Date(1648123320000)
+ *     2022/03/24 20:02:05   -> Date(1648123325000)
+ * @returns {Date|Null} 时间对象；转换失败时返回null
+ */
+const parseDateTime = (str) => {
+  const arr = new RegExp(/(\d{4})[^\d]+(\d{1,2})[^\d]+(\d{1,2})(.*)/, 'g').exec(str); // 分割日期和时间
+  if (!(arr && arr.index > -1)) return null; // 日期不合法，转换失败
+  const timeArr = new RegExp(/[^\d]?(\d{1,2})([^\d]+(\d{1,2})([^\d]+(\d{1,2}))?)?/, 'g').exec(arr[4]); // 分割时间
+  const [, year = 0, month = 0, day = 0] = arr; // 解析日期
+  const [, hour = 0, , minute = 0, , second = 0] = timeArr || []; // 解析时间
+
+  const date = new Date();
+  date.setFullYear(year);
+  // 解决js setMonth bug，在setMonth前先将day设置为1号，保证setMonth结果正确
+  // https://www.google.com/search?q=js+setmonth+bug&oq=js+setMonth&aqs=chrome.1.69i57j0i512j0i8i30j0i5i30j69i61.4323j0j4&sourceid=chrome&ie=UTF-8
+  date.setDate(1);
+  date.setMonth(month - 1);
+  date.setDate(day);
+  date.setHours(hour);
+  date.setMinutes(minute);
+  date.setSeconds(second);
+  date.setMilliseconds(0);
+  return date;
+};
+
 export {
+  groupTimeDuration,
+  formatTimeDuration,
   formatDateTime,
   formatTime,
   formatTimeStr,
   formatTimeWithDetails,
   dateToString,
+  parseDateTime,
 };

package/src/timeUtils.test.js

@@ -0,0 +1,131 @@
+import { formatTimeDuration, formatTime, formatTimeWithDetails, parseDateTime } from './timeUtils';
+
+describe('timeUtils', () => {
+  describe('formatTimeDuration test cases', () => {
+    test.each([
+      [0.001, undefined, undefined, undefined, '1秒内'],
+      [0.01, 'year', 'second', 2, '0.01秒'],
+      [0.01, 'year', 'minute', 2, '1分钟内'],
+      [0.1, 'year', 'second', 2, '0.1秒'],
+      [0.1, 'year', 'minute', 2, '1分钟内'],
+      [1, 'year', 'second', 2, '1秒'],
+      [1, 'year', 'minute', 2, '0.02分钟'],
+      [1, 'year', 'hour', 0, '1小时内'],
+      [1.1, 'year', 'second', 1, '1.1秒'],
+      [60, 'second', 'second', 2, '60秒'],
+      [60, 'year', 'second', 2, '1分钟'],
+      [60, 'year', 'hour', 2, '0.02小时'],
+      [60, 'year', 'hour', 1, '1小时内'],
+      [60, 'year', 'month', 0, '1月内'],
+      [61, 'year', 'second', 0, '1分钟1秒'],
+      [61, 'year', 'minute', 2, '1.02分钟'],
+      [3600, 'year', 'second', 0, '1小时'],
+      [3600, 'year', 'minute', 0, '1小时'],
+      [3600, 'year', 'hour', 0, '1小时'],
+      [3600, 'second', 'second', 2, '3600秒'],
+      [3600, 'minute', 'second', 2, '60分钟'],
+      [3600, 'year', 'day', 2, '0.04天'],
+      [3600, 'year', 'month', 2, '1月内'],
+      [3601, 'year', 'second', 2, '1小时1秒'],
+      [3601, 'year', 'minute', 2, '1小时0.02分钟'],
+      [3601, 'year', 'hour', 2, '1小时'],
+      [86400, 'year', 'second', 2, '1天'],
+      [86400, 'year', 'minute', 2, '1天'],
+      [86400, 'year', 'hour', 2, '1天'],
+      [86400, 'year', 'day', 2, '1天'],
+      [86400, 'hour', 'second', 2, '24小时'],
+      [86400, 'minute', 'second', 2, '1440分钟'],
+      [86400, 'year', 'month', 2, '0.03月'],
+      [86400, 'year', 'year', 2, '1年内'],
+      [86401, 'year', 'second', 2, '1天1秒'],
+      [86401, 'year', 'minute', 2, '1天0.02分钟'],
+      [86401, 'year', 'minute', 0, '1天'],
+      [86401, 'year', 'hour', 2, '1天'],
+      [31536000, 'year', 'second', 2, '1年'],
+      [31536000, 'month', 'second', 2, '12月5天'],
+      [31626061, 'year', 'second', 2, '1年1天1小时1分钟1秒'],
+    ])('formatTimeDuration(%s, %s, %s, %d) => %s', (seconds, maxUnit, minUnit, decimal, expected) => {
+      expect(formatTimeDuration(seconds, maxUnit, minUnit, decimal)).toBe(expected);
+    });
+  });
+
+  describe('formatTime', () => {
+    test.each([
+      ['invalid', 'invalid'],
+      [172800, '2天'],
+      [172799, '1天'],
+      [86401, '1天'],
+      [86400, '1天'],
+      [86399, '23小时60分钟'],
+      [86341, '23小时60分钟'],
+      [86340, '23小时59分钟'],
+      [7200, '2小时'],
+      [3601, '1小时1分钟'],
+      [3600, '1小时'],
+      [3599, '60分钟'],
+      [3541, '60分钟'],
+      [3540, '59分钟'],
+      [61, '2分钟'],
+      [60, '1分钟'],
+      [59, '1分钟'],
+      [1, '1分钟'],
+    ])('formatTime(%s) => %s', (seconds, result) => expect(formatTime(seconds)).toBe(result));
+  });
+
+  describe('formatTimeWithDetails', () => {
+    test('数据非法', () => expect(formatTimeWithDetails('invalid')).toBe('invalid'));
+    test('NaN', () => expect(() => formatTimeWithDetails(parseInt('invalid', 10))).toThrow());
+
+    test.each([
+      [172800, '2天0小时0分钟'],
+      [172799, '1天23小时60分钟'],
+      [172741, '1天23小时60分钟'],
+      [172740, '1天23小时59分钟'],
+      [90001, '1天1小时1分钟'],
+      [90000, '1天1小时'],
+      [86401, '1天0小时1分钟'],
+      [86400, '1天0小时0分钟'],
+      [86399, '23小时60分钟'],
+      [86341, '23小时60分钟'],
+      [86340, '23小时59分钟'],
+      [7200, '2小时'],
+      [7199, '1小时60分钟'],
+      [7141, '1小时60分钟'],
+      [7140, '1小时59分钟'],
+      [3601, '1小时1分钟'],
+      [3600, '1小时'],
+      [3599, '60分钟'],
+      [3541, '60分钟'],
+      [3540, '59分钟'],
+      [61, '2分钟'],
+      [60, '1分钟'],
+      [59, '1分钟'],
+      [1, '1分钟'],
+    ])('formatTime(%s) => %s', (seconds, result) => expect(formatTimeWithDetails(seconds)).toBe(result));
+  });
+
+  describe('parseDateTime', () => {
+    // 转换失败的情况
+    test('不合法转换', () => {
+      const date = parseDateTime('invalid');
+      expect(date).toBe(null);
+    });
+
+    // 转换成功的情况
+    test.each([
+      ['2022-03-24 20:02:05', 1648123325000],
+      ['2022/03/24 20:02', 1648123320000],
+      ['2022/03/24 20:', 1648123200000],
+      ['2022/03/24 20', 1648123200000],
+      ['2022/03/24', 1648051200000],
+      ['2022/03/24 20:2', 1648123320000],
+      ['2022年03月24日20时02分', 1648123320000],
+      ['2022年4月1日20时02分', 1648814520000],
+      ['2022年6月1日', 1654012800000],
+    ])('parseDateTime(%s) => Date(%d)', (str, timeStamp) => {
+      const date = parseDateTime(str);
+      expect(date).not.toBe(null);
+      expect(date.getTime()).toBe(timeStamp);
+    });
+  });
+});