工具函数库文档

简介

JavaScript/TypeScript 工具函数库，包含各种常用的数据处理、格式化、类型判断等功能。

安装

npm install tv-tools

功能列表

环境判断

• isAndroid: 判断是否为 Android 环境
• isiOS: 判断是否为 iOS 环境
• isPC: 判断是否为 PC 环境
• isMicroMessenger: 判断是否为微信环境

类型判断

• isFunction: 判断是否为函数
• isNumber: 判断是否为数字
• isString: 判断是否为字符串
• isObject: 判断是否为对象
• isArray: 判断是否为数组

数据处理

• cleanArray: 清理数组中的空值
• object2param: 将对象转换为 URL 参数字符串
• param2Object: 将 URL 参数字符串转换为对象
• formatObjToUrlParams: 将对象转换为 URL 参数字符串
• mergeOptions: 深度合并多个对象
• getObjectValue: 根据路径字符串获取对象内对应的值，例如 a.b[0].c

格式化函数

文本格式化

• formatNickname: 格式化用户昵称，超出指定长度部分显示为省略号
• encryptMobile: 手机号码加星号
• formatPhone: 格式化手机号显示
• formatCdn(url: string, width?: number, quality?: number): 将图片地址拼接阿里CDN图片处理参数
• formatUnicodeWordCount: 获取中文字符的Unicode编码，并计算字符长度，英文算0.5
• formatLogo: 根据相关id转换logo地址

数字格式化

• formatZero: 格式化数字，四舍五入并补零
• formatNumberWithCommas: 将数字格式化为千分位表示
• formatNumber: 数据格式化保留小数点
• formatNumberUnit: 大数值转换单位（万/亿）
• yuanToFen: 将金额从元转换为分（1元 = 100分）
• fenToYuan: 将金额从分转换为元（100分 = 1元）
• bytesToSize: 将字节数转换为KB、MB、GB……

时间日期格式化

• formatTimeDiff: 根据毫秒数格式化为天、时、分、秒
• formatDate: 格式化日期
• calculateAge: 根据出生日期计算年龄
• getNearestTime: 获取离当前时间最近的时间点
• formatTimestamp: 将时间数据格式化为时间戳
• humanizeTimeDiff: 根据两个时间的差值返回人性化时间显示
• normalizeDate: 将各种日期格式转换为Date对象

树形结构操作

• getTreeItem: 在树形结构中查找指定值的节点
• updateTreeItem: 更新树形结构中匹配的节点
• removeTreeItem: 从树形结构中删除指定节点

颜色处理

• contrastColor: 根据16进制颜色值获取对比色
• hexToRgba: 将16进制颜色值转换为RGBA格式
• randomColor: 随机生成颜色值

文件处理

• getVideoInfo: 获取视频属性信息，Promise
• getImageInfo: 获取图片属性信息，Promise

存储操作

• local_storage: localStorage 操作封装
• session_storage: sessionStorage 操作封装

使用示例

基本使用

import { formatDate, formatNumberWithCommas } from 'tv-tools';

// 格式化日期
console.log(formatDate(new Date())); // 输出: "2023-07-20 10:30:45"

// 格式化数字
console.log(formatNumberWithCommas(1234567.89)); // 输出: "1,234,567.89"

类型判断

import { isFunction, isArray } from 'tv-tools';

console.log(isFunction(() => {})); // true
console.log(isArray([1, 2, 3])); // true
console.log(isArray({})); // false

树形结构操作

import { getTreeItem, updateTreeItem } from 'tv-tools';

const treeData = [
  {
    id: 1,
    name: 'Node 1',
    children: [
      { id: 2, name: 'Node 1.1' }
    ]
  }
];

// 查找节点
const node = getTreeItem(treeData, 2, { field: 'id' });
console.log(node); // { id: 2, name: 'Node 1.1' }

// 更新节点
const updatedTree = updateTreeItem(treeData, { id: 2, name: 'Updated Node' }, { field: 'id' });

颜色处理

import { contrastColor, randomColor } from 'tv-tools';

// 获取对比色
console.log(contrastColor('#336699')); // "#ffffff"

// 生成随机颜色
console.log(randomColor({ format: 'rgb' })); // "rgb(123, 45, 67)"

API 详细说明

环境判断函数

isHalo

判断是否为嗨量客户端内部环境。

返回值: boolean

isAndroid

判断是否为 Android 环境。

返回值: boolean

isiOS

判断是否为 iOS 环境。

返回值: boolean

isPC

判断是否为 PC 环境。

返回值: boolean

isMicroMessenger

判断是否为微信环境。

返回值: boolean

类型判断函数

isFunction(value: any)

判断值是否为函数类型。

参数:

• value: 要判断的值

返回值: boolean

isNumber(value: any)

判断值是否为数字类型。

参数:

• value: 要判断的值

返回值: boolean

isString(value: any)

判断值是否为字符串类型。

参数:

• value: 要判断的值

返回值: boolean

isObject(value: any)

判断值是否为对象类型。

参数:

• value: 要判断的值

返回值: boolean

isArray(value: any)

判断值是否为数组类型。

参数:

• value: 要判断的值

返回值: boolean

数据处理函数

cleanArray(actual: any)

清理数组中的空值。

参数:

• actual: 要清理的数组

返回值: 清理后的新数组

object2param(json: any)

将对象转换为 URL 参数字符串。

参数:

• json: 要转换的对象

返回值: URL 参数字符串

param2Object(param: string)

将 URL 参数字符串转换为对象。

参数:

• param: URL 参数字符串

返回值: 解析后的对象

mergeOptions(target: any, ...sources: any[])

深度合并多个对象。

参数:

• target: 目标对象
• ...sources: 要合并的源对象

返回值: 合并后的新对象

格式化函数

formatNickname(value: string = '', length: number = 6)

格式化用户昵称，超出指定长度部分显示为省略号。

参数:

• value: 用户昵称（默认为空字符串）
• length: 最大显示长度（英文字符算0.5，中文字符算1，默认为6）

返回值: 格式化后的昵称字符串

encryptMobile(val: string)

手机号码加星号处理。

参数:

• val: 手机号码字符串

返回值: 加星号后的手机号码字符串

formatPhone(phone: string)

格式化手机号显示。

参数:

• phone: 手机号码字符串

返回值: 格式化后的手机号码字符串

formatZero(number: number = 0, n: number = 2)

格式化数字，四舍五入并补零。

参数:

• number: 要格式化的数字（默认0）
• n: 保留小数位数（默认2）

返回值: 格式化后的字符串

formatNumberWithCommas(num: number | string)

将数字格式化为千分位表示。

参数:

• num: 要格式化的数字或数字字符串

返回值: 格式化后的千分位字符串

formatNumber(value = 0, precision = 2, separate = false)

数据格式化保留小数点。

参数:

• value: 要格式化的值
• precision: 保留小数点位数
• separate: 是否添加千分位分隔符

返回值: 格式化后的数字

formatNumberUnit(value: number, options = {})

大数值转换单位（万/亿）。

参数:

• value: 要转换的数值
• options: 配置选项
  • separate: 是否添加千分位分隔符（默认false）
  • locale: 本地化设置

返回值: 格式化后的字符串

formatTimeDiff(milliseconds: number)

根据毫秒数格式化为天、时、分、秒。

参数:

• milliseconds: 毫秒数

返回值: 包含天、时、分、秒的对象

formatDate(time: any, format = 'yyyy-MM-dd hh:mm:ss')

格式化日期。

参数:

• time: 日期对象或可转换的值
• format: 格式字符串（默认'yyyy-MM-dd hh:mm:ss'）

返回值: 格式化后的日期字符串

calculateAge(birthDate: Date | string, options = {})

根据出生日期计算年龄。

参数:

• birthDate: 出生日期（Date对象或可被Date解析的字符串）
• options: 配置选项
  • withSuffix: 是否包含"岁"字后缀（默认true）
  • precise: 是否返回精确年龄（包含月、日，默认false）

返回值: 年龄字符串或精确年龄对象

getNearestTime(timeArray: (string | Date)[])

获取离当前时间最近的时间点。

参数:

• timeArray: 时间字符串或Date对象数组

返回值: 最近的时间点Date对象

树形结构操作

getTreeItem(data: TreeNode[], value: any, options = {})

在树形结构中查找指定值的节点。

参数:

• data: 树形数据数组
• value: 要查找的值
• options: 配置选项
  • field: 查找的字段名（默认为'key'）
  • childrenField: 子节点字段名（默认为'children'）

返回值: 找到的节点或null

updateTreeItem(nodes: TreeNode[], detail: any, options = {})

更新树形结构中匹配的节点。

参数:

• nodes: 树形数据数组
• detail: 要更新的节点详情（必须包含匹配字段）
• options: 配置选项
  • field: 用于匹配的字段名（默认'key'）
  • childrenField: 子节点字段名（默认'children'）

返回值: 更新后的树形数据

removeTreeItem(nodes: TreeNode[], detail: any, options = {})

从树形结构中删除指定节点。

参数:

• nodes: 树形数据数组
• detail: 要删除的节点键值
• options: 配置选项
  • field: 用于匹配的字段名（默认'key'）
  • childrenField: 子节点字段名（默认'children'）

返回值: 删除指定节点后的新树形数据

颜色处理函数

contrastColor(hexString: string, options = {})

根据16进制颜色值获取对比色。

参数:

• hexString: 16进制颜色值（如"#RRGGBB"）
• options: 配置选项
  • lightColor: 浅色背景时返回的颜色（默认'#ffffff'）
  • darkColor: 深色背景时返回的颜色（默认'#000000'）
  • threshold: 亮度阈值（默认200，范围0-255）

返回值: 对比色

hexToRgba(hex: string, options = {})

将16进制颜色值转换为RGBA格式。

参数:

• hex: 16进制颜色值（支持3位或6位，带或不带#）
• options: 配置选项
  • alpha: 透明度（默认1）
  • format: 返回格式（'string'或'object'，默认'string'）

返回值: RGBA颜色字符串或对象

randomColor(options = {})

随机生成颜色值。

参数:

• options: 配置选项
  • format: 颜色格式：'hex'或'rgb'（默认'hex'）
  • alpha: 透明度（仅当format为'rgb'时有效，默认1）
  • uppercase: 是否大写（仅当format为'hex'时有效，默认true）

返回值: 随机颜色值（16进制或RGB格式）

存储操作

local_storage

localStorage 操作封装，提供以下方法：

• get(key): 获取值
• set(key, value): 设置值
• remove(key): 删除值
• clear(): 清空所有

session_storage

sessionStorage 操作封装，提供以下方法：

• get(key): 获取值
• set(key, value): 设置值
• remove(key): 删除值
• clear(): 清空所有

注意事项

1. 所有函数都经过类型定义，建议在 TypeScript 项目中使用以获得更好的类型提示
2. 部分函数对输入参数有严格校验，无效输入可能会返回默认值或抛出错误
3. 树形结构操作函数支持自定义字段名，但需要确保数据结构一致性