@tmsfe/tms-core 0.0.94 → 0.0.96

package/src/runtime/login.ts

@@ -1,6 +1,8 @@
 /* eslint-disable valid-jsdoc */
 /**
  * @copyright 2021-present, Tencent, Inc. All rights reserved.
+ * @module: runtime-login
+ * @desc: 登录相关
  * @brief login.js 用于维护 runtime 框架的用户登录流程，获取用户的登录的可信凭证.
  * runtime初始化时，会调用登录流程，基于runtime的后续业务代码，不必关注用户的登录状态，
  * 当前，登录流程仅支持【腾讯出行服务小程序】，我们计划支持出行服务公众号的H5开发，基于runtime的
@@ -69,11 +71,15 @@ const loginFn = async () => {
  * @returns { object } resData 用户信息
  */
 async function login() {
-  let userData = {};
+  let userData: {
+    errCode?: any,
+    resData?: any
+  } = {};
 
   try {
     const code = await getCode();
 
+    // @ts-ignore
     const { trafficEntrence: registerSource, scene: sceneId } = getOpenAppTrafficData();
 
     userData = await getApp().tms.createRequest({ withAuth: false }).post('user/login', { code, registerSource, sceneId });
@@ -204,9 +210,24 @@ const getPhone = () => getApp().tms.createRequest({ withAuth: true }).post('user
     return Promise.reject(res);
   });
 
-
 /**
- * 绑定手机号
+ * @description 绑定手机号
+ * @param {Object} data    params 加密数据对象
+ * @param {string} data.encryptedData button组件bindgetphonenumber事件返回的encryptedData字段
+ * @param {string} data.iv button组件bindgetphonenumber事件返回的iv字段
+ * @returns {Object} data    绑定结果回调
+ * @returns {number} data.success 是否绑定成功 boolean类型
+ * @returns {number} data.phone  绑定成功时的手机号，失败则为空
+ * @returns {number} data.errMsg 绑定结果描述信息
+ * @example
+ * const { tms } = getApp({ allowDefault: true });
+ * const res = await tms.registerPhone({ encryptedData, iv })
+ * if(res.success) {
+ *    console.log('phone', res.phone)
+ * } else {
+ *    // 注册失败处理逻辑
+ *    console.log(res.errMsg)
+ * }
  */
 async function registerPhone({ encryptedData, iv }: {encryptedData: string, iv: string}): Promise<PhoneRegisterResult> {
   try {

package/src/storage.js

@@ -1,3 +1,7 @@
+/**
+ * @desc: 处理localstorage相关函数
+ */
+
 /**
  * 保存数据到localstorage
  * @param key
@@ -17,7 +21,7 @@ function setItem(key, data) {
  * 从localstorage取数据
  * @param key
  * @param defaultValue wx接口报错时返回默认值
- * @returns {null|any}
+ * @returns {any}
  */
 function getItem(key, defaultValue = null) {
   try {
@@ -60,10 +64,10 @@ function cleanTask() {
 }
 
 /**
- * 缓存组件或页面的缓存data
- * @param key
- * @param version 低于该版本号的缓存会被异步清除
- * @param data
+ * 缓存组件或页面的缓存data，会缓存到localStorage里
+ * @param {string} key localStorage的唯一标志
+ * @param {string} version 版本号，低于该版本号的缓存会被异步清除
+ * @param {object} data 页面缓存的数据
  * @returns {boolean}
  */
 function setCacheData(key, version, data) {
@@ -81,10 +85,10 @@ function setCacheData(key, version, data) {
 
 /**
  * 获取组件或页面的缓存data
- * @param key
- * @param version
- * @param defaultData
- * @returns {*|null}
+ * @param {string} key localStorage的唯一标志
+ * @param {string} version 版本号
+ * @param {object} defaultData 接口报错时返回默认值
+ * @returns {any}
  */
 function getCacheData(key, version, defaultData = null) {
   const str = `${key}_v${version}`;

package/src/stringUtils.js

@@ -1,3 +1,7 @@
+/**
+ * @desc: 字符串处理相关函数
+ */
+
 /**
  * 字符串截断，处理时按可见字符长度进行截断
  * 可见字符的含义是指：字母、数字、汉字、表情等均等价于一个字符
@@ -115,13 +119,12 @@ const isValidPlate = (plate) => {
  * 四舍五入，并返回格式化的字符串
  * 支持保留n位小数，n>=0，如 roundStr(1.325, 2)=1.33
  * 支持格式化字符串时取出末尾的0，如roundStr(1.109, 2, true)=1.1
- * @param {any} x 原数字
- *                如果n不是合法数字或者无法转换为合法数字，roundStr结果返回''
+ * @param {any} x 原数字， 如果n不是合法数字或者无法转换为合法数字，roundStr结果返回''
  * @param {any} n 保留几位小数，默认0
- *                如果n不是合法数字或者无法转换为合法数字，roundStr结果返回''
- *                如果n小于0，roundStr结果返回''
- *                如果n的值包含小数部分，roundStr处理时只关注n的整数部分值
  * @param {boolean} removeTrailingZero 是否移除字符串末尾的无效数字0
+ 1. 如果n不是合法数字或者无法转换为合法数字，roundStr结果返回''
+ 2. 如果n小于0，roundStr结果返回''
+ 3. 如果n的值包含小数部分，roundStr处理时只关注n的整数部分值
  * @returns {string} 返回四舍五入后的字符串，异常情况下返回空字符串''
  */
 const roundStr = (x, n = 2, removeTrailingZero = false) => {

package/src/syncfnmanager.js

@@ -1,5 +1,5 @@
 /**
- * 本文件负责对小程序调用wx同步方法的管理
+ * @desc: 本文件负责对小程序调用wx同步方法的管理
  */
 let systemInfo = null; // 系统信息。
 let launchOptions = null; // 启动参数
@@ -25,7 +25,7 @@ const getSystemInfoSync = () => {
 
 /**
  * 重置系统信息，仅用于单元测试
- * @returns {undefined}
+ * @returns {void}
  */
 const resetSystemInfoSync = () => {
   systemInfo = null;
@@ -66,7 +66,7 @@ const getPlatform = () => {
 };
 
 /**
- * 获取字符串类型的启动参数
+ * 获取字符串类型的启动参数, 同wx.getLaunchOptionsSync进行JSON.stringify
  * @returns {String} 序列化的参数字符串
  */
 const getLaunchParamOfString = () => {

package/src/timeUtils.js

@@ -1,10 +1,6 @@
 /**
- * Tencent Inc. All Rights Reserved.
- * @author:
- * Created:
- * Description: format time.
- * History:
- *    2017-07-26 @davislu modify.
+ * @desc: 时间处理相关函数
+ * @author:2017-07-26 @davislu modify.
  */
 
 import { round } from './numUtils';
@@ -14,17 +10,16 @@ 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天的部分
+ * @returns {Object} result 以下是各计数单位下的数值：
+ * @returns {Number} result.year    - 年；  当maxUnit < 'year' 时，此字段永远为0；此字段为-1时，表示 seconds 参数非法 或 minUnit > maxUnit等异常情况
+ * @returns {Number} result.month   - 月；  当maxUnit < 'month' 时，此字段永远为0；
+ * @returns {Number} result.day     - 天；  当maxUnit < 'day' 时，此字段永远为0；
+ * @returns {Number} result.hour    - 小时；当maxUnit < 'hour' 时，此字段永远为0；
+ * @returns {Number} result.minute  - 分钟；当maxUnit < 'minute' 时，此字段永远为0；
+ * @returns {Number} result.second  - 秒；
+ * @returns {Number} result.decimal - 不足最小单位的部分，具体含义与 minUnit 参数相关；例如 minUnit = day 时，此字段表示不足1天的部分
  */
 const groupTimeDuration = (seconds, maxUnit = 'year', minUnit = 'second', decimal = 2) => {
   // 时间参数（seconds）检查
@@ -65,10 +60,9 @@ const groupTimeDuration = (seconds, maxUnit = 'year', minUnit = 'second', decima
  * 将时间段进行聚合计算并格式化，得出方便人阅读的文案，例如：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} 示例见测试用例
+ * @returns {String}
  */
 const formatTimeDuration = (seconds, maxUnit = 'year', minUnit = 'second', decimal = 2) => {
   const result = groupTimeDuration(seconds, maxUnit, minUnit, decimal);
@@ -89,9 +83,9 @@ const formatTimeDuration = (seconds, maxUnit = 'year', minUnit = 'second', decim
 
 /**
  * @function
- * @description 格式化时间
+ * @description 格式化时间，>24小时的显示 【x天】；<1小时的显示  【x分钟】；<24小时&>1小时的显示  【x小时y分钟】
  * @param {Number} seconds 秒数
- * @returns {String} 格式化的时间 -> 2小时47分钟或者12天
+ * @returns {String} 格式化的时间
  */
 const formatTime = (seconds) => {
   if (typeof seconds !== 'number') return seconds;
@@ -109,7 +103,7 @@ const formatTime = (seconds) => {
 
 /**
  * @function
- * @description 将秒数格式化为x天y小时z分钟
+ * @description 将秒数格式化： 秒数多于1天显示【x天y小时z分钟】；秒数小于1小时【x分钟】；秒数介于1天和1小时之间显示【x小时y分钟】
  * @param       {Number} seconds 秒数
  * @returns      {String} 格式化后的文案
  */
@@ -212,17 +206,17 @@ const dateToString = (date, withTime = false, withSeconds = false, join = '-') =
 /**
  * 将时间字符串转换为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
+1. 支持对日期完整但时间部分缺失的情况进行处理，如：
+2. 2022-03-24 20:02 -> Date(1648123320000)
+3. 2022-03-24 20:   -> Date(1648123200000)
+4. 2022-03-24 20    -> Date(1648123200000)
+5. 2022-03-24       -> Date(1648051200000)
+6. 小于10的数字可以省略0：
+7. 2022-3-24 20:2   -> Date(1648123320000)
+8. 支持任意分割符，如：
+9. 2022年03月24日 20时02分 -> Date(1648123320000)
+10. 2022/03/24 20:02:05   -> Date(1648123325000)
+ * @returns {Date} 时间对象；转换失败时返回null
  */
 const parseDateTime = (str) => {
   const arr = new RegExp(/(\d{4})[^\d]+(\d{1,2})[^\d]+(\d{1,2})(.*)/, 'g').exec(str); // 分割日期和时间

package/tmsdoc.config.js

@@ -0,0 +1,12 @@
+const path = require('path');
+function resolve(dir) {
+  return path.resolve(__dirname, dir);
+}
+
+module.exports = {
+  [resolve('dist/src')]: {
+    title: 'tms-core',
+    exclude: '/docs\\/|node_modules|\\.test\\.js|utils|tmsuiUtils/',
+    outputPath: '../../prod/tmsapidocs/docs/tmscore/api.md',
+  },
+};

package/tsconfig.json

@@ -1,28 +1,30 @@
 {
-    "compilerOptions": {
-      "sourceMap": false,
-      "target": "esnext",
-      "module": "esnext",
-      "moduleResolution": "node",
-      "allowJs": true,
-      "strict": true,
-      "declarationMap": false,
-      "noUnusedLocals": true,
-      "experimentalDecorators": true,
-      "resolveJsonModule": true,
-      "esModuleInterop": true,
-      "removeComments": false,
-      "jsx": "preserve",
-      "lib": ["esnext", "dom"],
-      "rootDir": ".",
-      "typeRoots": [
-        "./node_modules/miniprogram-api-typings"
-      ],
-      "paths": {
-      }
-    },
-    "include": [
-      "src"
-    ]
-  }
-  
+  "compilerOptions": {
+    "sourceMap": false,
+    "target": "esnext",
+    "module": "esnext",
+    "moduleResolution": "node",
+    "allowJs": true,
+    "strict": false,
+    "declarationMap": false,
+    "noUnusedLocals": false,
+    "experimentalDecorators": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "removeComments": false,
+    "jsx": "preserve",
+    "lib": ["esnext"],
+    "rootDir": ".",
+    "types": [
+      "miniprogram-api-typings"
+    ],
+    "outDir": "dist",
+    "paths": {
+    }
+  },
+  "include": [
+    "src/**/*.js",
+    "src/**/*.ts"
+  ]
+}
+