SEPG框架-工具函数使用手册

返回目录

SEPG框架-工具函数使用手册

  • 框架版本: 2.1.0
  • 文档版本: 1.0.0
  • 生成时间: 2026-03-19 10:58:18

1. constant - 全局常量配置

本模块提供全局动画配置相关的工具函数。

setSpeed - 设置全局缓动动画速度

函数签名:

setSpeed(s: number) => void

功能说明:
设置全局缓动动画速度

参数:

示例:

// 设置全局动画速度为 2
setSpeed(2);

getSpeed - 获取全局缓动动画速度

函数签名:

getSpeed() => number

功能说明:
获取全局缓动动画速度

示例:

// 获取当前全局动画速度
const speed = getSpeed();
console.log(speed); // 输出当前速度值

setTimeFunction - 设置全局缓动动画函数

函数签名:

setTimeFunction(time_function: TTimeFunction) => void

功能说明:
设置全局缓动动画函数

参数:

示例:

// 设置全局缓动函数为 easeInOut
setTimeFunction('easeInOut');

getTimeFunction - 获取全局缓动动画函数

函数签名:

getTimeFunction() => TTimeFunction

功能说明:
获取全局缓动动画函数

示例:

// 获取当前全局缓动函数
const timeFunc = getTimeFunction();
console.log(timeFunc); // 输出当前缓动函数

2. functions - 核心工具函数

本模块提供各种核心工具函数，包括数据转换、时间处理、网络请求、动画等功能。

addZeros - 参数补零

函数签名:

addZeros(arg: number, range: number = 10, zero: string = '0') => string

功能说明:
参数补零

参数:

示例:

// 数字补零
addZeros(5); // '05'
addZeros(5, 100); // '005'
addZeros(15, 100); // '015'
addZeros(5, 100, '*'); // '**5'

collections - 数组集合操作

函数签名:

Collections.intersect(a: T[], b: T[], attr?: string) => T[]
Collections.union(a: T[], b: T[], attr?: string) => T[]
Collections.difference(a: T[], b: T[], attr?: string) => T[]
Collections.symmetricDifference(a: T[], b: T[], attr?: string) => T[]

功能说明:
提供数组集合操作的功能，包括求交集、并集、差集、补集

参数:

示例:

Collections.intersect([1, 2], [2, 3]); // [2] 求交集
Collections.intersect(
  [{ a: 'bob', b: 12 }, { a: 'john', b: 20 }],
  [{ a: 'bob', b: 32 }, { a: 'sam', b: 24 }],
  'a'
); // [{ "a": "bob", "b": 12 }] 求交集
Collections.union([1, 2], [2, 3]); // [1, 2, 3] 求并集
Collections.difference([1, 2], [2, 3]); // [1] 求差集
Collections.symmetricDifference([1, 2], [2, 3]); // [1, 3] 求补集

confirmInvoke - 间隔时间内调用

函数签名:

confirmInvoke<T>(invoke: Function, confirm: Function, interval: number = 1000) => (args: T) => void

功能说明:
间隔时间内调用(用于处理间隔时间内重复操作才执行某函数)

参数:

示例:

// 在3秒内连续点击只触发一次
const clickHandler = confirmInvoke(() => {
  console.log('Clicked!');
}, () => {
  console.log('Confirming...');
}, 3000);
clickHandler(); // Confirming...
setTimeout(() => {
  clickHandler(); // Clicked!
}, 2000);
setTimeout(() => {
  clickHandler(); // 无输出
}, 5000);

convertDate2UTC - 转换日期为UTC时间

函数签名:

convertDate2UTC(date: Date) => string

功能说明:
将日期转换为UTC时间格式的字符串

参数:

示例:

// 将当前日期转换为UTC时间
const utcTime = convertDate2UTC(new Date());
console.log(utcTime); // '20260319T090659Z'

convertDateStr2Stamp - 转换日期字符串为毫秒时间戳

函数签名:

convertDateStr2Stamp(str: string) => number

功能说明:
将日期字符串转换为毫秒时间戳

参数:

示例:

// 将日期字符串转换为时间戳
const timestamp = convertDateStr2Stamp('2021-02-01 01:10:30');
console.log(timestamp); // 1612113030000

convertJsonStr2Obj - 转换json字符串为json对象

函数签名:

convertJsonStr2Obj(jsonStr: string) => object

功能说明:
转换json字符串为json对象

参数:

示例:

// 将JSON字符串转换为对象
const jsonStr = '{"name":"test","value":123}';
const obj = convertJsonStr2Obj(jsonStr);
console.log(obj); // {name: 'test', value: 123}

convertObj2Str - 将参数对象转化为长字符串

函数签名:

convertObj2Str(paramObj: { [key: string]: any }) => string

功能说明:
将参数对象转化为长字符串

参数:

示例:

// 将对象转换为URL参数字符串
const paramObj = { index: '1', name: 'abc' };
const str = convertObj2Str(paramObj);
console.log(str); // 'index=1&name=abc'

convertObj2Style - 将样式对象转换为样式字符串

函数签名:

convertObj2Style(obj: Style) => string

功能说明:
将样式对象转换为样式字符串

参数:

示例:

// 将样式对象转换为样式字符串
const styleObj = { width: '100px', height: '200px', color: 'red' };
const styleStr = convertObj2Style(styleObj);
console.log(styleStr); // 'width:100px;height:200px;color:red'

convertPlayTime - 将播放秒数转换为指定时分秒格式

函数签名:

convertPlayTime(time: number = 0, units?: string, separate: string = ',') => string

功能说明:
将播放秒数转换为指定时分秒格式

参数:

示例:

// 将秒数转换为时间格式
convertPlayTime(100); // '00:01:40'
convertPlayTime(100, '时,分,秒'); // '1分40秒'
convertPlayTime(5000, 'hour,minute,second'); // '1hour23minute20second'
convertPlayTime(5000, 'hour,|minute,|second', '|'); // '1hour,23minute,20second'

convertStr2Date - 将时间字符串转换为 Date

函数签名:

convertStr2Date(str: string) => Date

功能说明:
将 yyyyMMddhhmmss 格式的字符串转换为 Date

参数:

示例:

// 将字符串转换为Date对象
const date = convertStr2Date('20210201101030');
console.log(date); // Date对象

convertStr2Obj - 将长字符串参数转化为对象

函数签名:

convertStr2Obj(paramStr: string, decode?: boolean) => object

功能说明:
将长字符串参数转化为对象

参数:

示例:

// 将URL参数字符串转换为对象
const paramStr = 'index=1&name=abc';
const obj = convertStr2Obj(paramStr);
console.log(obj); // { index: '1', name: 'abc' }

// 带解码
const encodedStr = 'index=1&name=%E5%BC%A0%E4%B8%89';
const decodedObj = convertStr2Obj(encodedStr, true);
console.log(decodedObj); // { index: '1', name: '张三' }

convertStr2Second - 将时间字符(hh:mm:ss)串转换为秒数

函数签名:

convertStr2Second(paramStr: string) => number

功能说明:
将时间字符(hh:mm:ss)串转换为秒数

参数:

示例:

// 将时间字符串转换为秒数
const seconds = convertStr2Second('00:01:40');
console.log(seconds); // 100

convertStyle2Obj - 将样式字符串转换为样式对象

函数签名:

convertStyle2Obj(style: string) => object

功能说明:
将样式字符串转换为样式对象

参数:

示例:

// 将样式字符串转换为对象
const styleStr = 'width:100px;height:200px;color:red';
const styleObj = convertStyle2Obj(styleStr);
console.log(styleObj); // { width: '100px', height: '200px', color: 'red' }

correctTime - 矫正超过24小时的时间

函数签名:

correctTime(paramStr: string) => string

功能说明:
将24:00:00后的时间字符(hh:mm或hh:mm:ss)串矫正为正常的时间字符串

参数:

示例:

// 矫正超过24小时的时间
correctTime('24:01:09'); // '00:01:09'
correctTime('26:10:20'); // '02:10:20'
correctTime('25:30'); // '01:30'

countDown - 倒计时函数

函数签名:

countDown(seconds: number, end: Function, run?: Function) => CountDown

功能说明:
倒计时

参数:

示例:

// 倒计时
const counter = countDown(10, 
  () => console.log('倒计时结束'),
  (seconds) => console.log(`剩余 ${seconds} 秒`)
);
// 手动停止倒计时
counter.stop();

cropText - 裁剪文字

函数签名:

cropText(text: string, length: number, ellipsis?: boolean) => CropText

功能说明:
裁剪文字

参数:

示例:

// 裁剪文字
// { over: true, origin: '这是一段很长的文字', value: '这是' }
cropText('这是一段很长的文字', 5);
// { over: true, origin: '这是一段很长的文字', value: '这是...' }
cropText('这是一段很长的文字', 5, true);
// { over: false, origin: '短文字', value: '短文字' }
cropText('短文字', 10);

debounce - 单实例函数防抖

函数签名:

debounce(fn: Function, interval: number = 1000) => void

功能说明:
单实例函数防抖

参数:

示例:

// 防抖处理
function handleInput() {
  debounce(() => {
    console.log('输入处理');
  }, 1000);
}

// 连续调用，1000ms内只会执行一次
handleInput();
handleInput();
handleInput();

cancelDebounce - 取消单实例函数防抖

函数签名:

cancelDebounce() => void

功能说明:
取消单实例函数防抖

示例:

// 取消防抖
cancelDebounce();

debounceBuilder - 函数防抖生成器

函数签名:

debounceBuilder(fn: Function, interval: number = 1000, immediate?: boolean) => {
  (...args: any): void;
  cancel: () => void;
  cancelThenCall: (...args: any) => void;
}

功能说明:
函数防抖生成器

参数:

示例:

// 防抖生成器
const debouncedFn = debounceBuilder(() => {
  console.log('执行');
}, 1000, true);

// 执行防抖函数
debouncedFn();
debouncedFn();
// 取消防抖函数执行
debouncedFn.cancel();
// 取消防抖函数执行，并立即调用
debouncedFn.cancelThenCall();

defaultGet - 获取并设置默认值

函数签名:

defaultGet(arg: any, defaultValue: any) => any

功能说明:
获取并设置默认值

参数:

示例:

// 获取并设置默认值
const value1 = defaultGet(null, 'default'); // 'default'
const value2 = defaultGet('actual', 'default'); // 'actual'
const value3 = defaultGet(undefined, 0); // 0

findTargetNode - 按条件查找节点

函数签名:

findTargetNode(dom: Element, condition: Function, direction: string = 'up') => Element | null

功能说明:
按条件查找节点

示例:

// 按条件查找节点
const container = document.getElementById('container');
const target = findTargetNode(container, (node) => {
  return node.classList.contains('target');
});

flatData - 打平数组数据

函数签名:

flatData<T>(data: T[], key?: string) => T[]

功能说明:
打平数组数据，默认以children为子集键

参数:

示例:

// 打平数组数据
const data = [
  { id: 1, name: 'A', children: [{ id: 2, name: 'B' }] },
  { id: 3, name: 'C' }
];
const flatDataResult = flatData(data);
console.log(flatDataResult);
// [ { id: 1, name: 'A', children: [{ id: 2, name: 'B' }] }, { id: 2, name: 'B' }, { id: 3, name: 'C' } ]

getDateData - 获取最近几天的时间数据

函数签名:

getDateData(num: number, fmt: string = 'yyyy.MM.dd') => IDate[]

功能说明:
获取最近几天的时间数据

参数:

示例:

// 获取最近几天的时间数据
const dates = getDateData(3);
console.log(dates);
// [
//   { time: '2026.03.19', dateStr: '今天' },
//   { time: '2026.03.18', dateStr: '昨天' },
//   { time: '2026.03.17', dateStr: '0317' }
// ]

getDeltaDate - 获取相差某天的时间

函数签名:

getDeltaDate(day: number = 0, date?: Date) => Date

功能说明:
获取相差某天的时间，默认当前时间

参数:

示例:

// 获取相差某天的时间
const deltaDate1 = getDeltaDate(1); // 当前时间的第二天
const deltaDate2 = getDeltaDate(-3); // 当前时间的三天前
console.log(deltaDate1, deltaDate2);

getFormatDateString - 获取格式化日期字符串

函数签名:

getFormatDateString(date: Date, fmt?: string) => string

功能说明:
获取格式化日期字符串，默认 yyyy-MM-dd hh:mm:ss

参数:

示例:

// 获取格式化日期字符串
const date = new Date('2021/05/27 10:30:45');
const formattedDate = getFormatDateString('yyyy年MM月dd日 hh时mm分ss秒', date);
console.log(formattedDate); // '2021年05月27日 10时30分45秒'

getOrigin - 获取页面origin

函数签名:

getOrigin() => string

示例:

// 获取页面origin
const origin = getOrigin();
console.log(origin); // 'https://example.com'

getRandomStr - 获取随机字符串

函数签名:

getRandomStr(length: number = 5) => string

功能说明:
获取指定长度的随机字符串

参数:

示例:

// 获取随机字符串
const str1 = getRandomStr(); // 5位随机字符串
const str2 = getRandomStr(10); // 10位随机字符串
console.log(str1, str2);

getRangeDate - 获取时间段内的日期数组

函数签名:

getRangeDate(before: number, after: number, current?: Date) => Date[]

功能说明:
获取时间段内的日期数组，默认当前时间

参数:

示例:

// 获取时间段内的日期数组
const dates = getRangeDate(2, 3); // 从今天起前两天到后三天的时间数据
console.log(dates);
// [
//   "2026-03-17T09:55:09.657Z",
//   "2026-03-18T09:55:09.657Z",
//   "2026-03-19T09:55:09.657Z",
//   "2026-03-20T09:55:09.657Z",
//   "2026-03-21T09:55:09.657Z",
//   "2026-03-22T09:55:09.657Z"
// ]

getStringByMark - 按标记分割字符串

函数签名:

getStringByMark(str: string = window.location.href, mark: string = '?', index: number = 0) => string

功能说明:
获取字符串中指定字符分割的指定位置字符串

参数:

示例:

// 按标记分割字符串
const url = 'http://example.com?index=1&name=abc';
const part1 = getStringByMark(url); // 'http://example.com'
const part2 = getStringByMark(url, '&'); // 'http://example.com?index=1'
const part3 = getStringByMark(url, '&', 1); // 'name=abc'

getUrlParamObj - 获取URL参数对象

函数签名:

getUrlParamObj(url: string = window.location.href, decode?: boolean) => {
  [key: string]: any
}

功能说明:
获取url中的参数并组装为参数对象

参数:

示例:

// 获取URL参数对象
const url = 'http://example.com?index=1&name=abc';
const params = getUrlParamObj(url);
console.log(params.index); // '1'
console.log(params.name); // 'abc'

getViewSize - 获取视口尺寸

函数签名:

getViewSize() => SafeDOMRect

示例:

// 获取视口尺寸
const size = getViewSize();
console.log(size.width, size.height);

updateViewSize - 更新视口尺寸

函数签名:

updateViewSize() => SafeDOMRect

示例:

// 更新视口尺寸
updateViewSize();

keepValidValue - 保持有效值

函数签名:

keepValidValue(obj: any) => any

功能说明:
仅保留对象中有效值（非undefined, null, NaN）

示例:

// 保持有效值
const obj = { a: undefined, b: 'hello', c: null, e: NaN, f: '', g: 0, h: false };
const validObj = keepValidValue(obj);
console.log(validObj); // { b: 'hello', f: '', g: 0, h: false }

loadImg - 加载图片

函数签名:

loadImg(options: ILoadImg) => void

功能说明:
图片加载，支持懒加载和错误处理

参数:

示例:

// 图片加载
const imgs = document.getElementsByTagName('img');
loadImg({ container: imgs, attr: 'data-src', error: '/path/to/default.png' });

loadScript - 动态加载脚本

函数签名:

loadScript(config: Config) => void

功能说明:
动态加载脚本，支持超时处理和多个脚本同时加载

参数:

示例:

// 动态加载脚本
loadScript({ 
  sources: ['/path/to/script1.js', '/path/to/script2.js'],
  timeout: 5000,
  onLoad: () => console.log('加载成功'),
  onError: (err) => console.error(err),
  onAllTimeout: () => console.warn('所有资源都超时了')
});

loadStyle - 动态加载样式

函数签名:

loadStyle(id: string, css: string) => void

功能说明:
动态加载样式，支持替换和新增

参数:

示例:

// 动态加载样式
loadStyle('my-style', 'body { background-color: #f0f0f0; }');

loop - 循环执行

函数签名:

loop(run: Function, interval: number = 1000, immediately: boolean = true) => {
  stop: () => void
}

功能说明:
循环执行
参数:

示例:

// 循环执行
const loopIns = loop(() => {
  console.log('执行中');
}, 1000, true);

// 停止循环
loopIns.stop();

nextTick - 下一个事件循环执行

函数签名:

nextTick(cb: Function) => void

功能说明:
将函数执行放到新的事件循环

参数:

示例:

// 下一个事件循环执行
nextTick(() => {
  console.log('在下一个事件循环中执行');
});

numberAnimate - 数字动画

函数签名:

numberAnimate(dom: HTMLElement, from: number, to: number, duration?: number, template?: string | ((num: number) => string), callback?: Function) => void

功能说明:
数字切换动画

参数:

示例:

// 数字动画
const scoreDom = document.querySelector('.score');
numberAnimate(scoreDom, 0, 100);
numberAnimate(scoreDom, 0, 100, 500, '<span>#number分</span>');
numberAnimate(scoreDom, 0, 100, 500, (num) => `<span>${num}分</span>`, () => console.log('动画结束'));

pageData - 分页数据

函数签名:

pageData<T>(data: T[], page: number, size: number) => T[]

功能说明:
获取数组中某一页的数据

参数:

示例:

// 分页数据
const data = [1, 2, 3, 4, 5];
const page1 = pageData(data, 1, 2); // [1, 2]
const page2 = pageData(data, 2, 2); // [3, 4]

parseUTC2Date - UTC时间戳转Date时间

函数签名:

parseUTC2Date(utcTime: string) => Date

功能说明:
将UTC时间戳转换为date时间

参数:

示例:

// UTC时间戳转Date
const date = parseUTC2Date('2021-02-01T01:10:30Z');
console.log(date);

preloadImg - 图片预加载

函数签名:

preloadImg(sources: string | string[], callback?: Function) => void

功能说明:
图片预加载

参数:

示例:

// 预加载图片
preloadImg(['img1.jpg', 'img2.jpg'], () => {
  console.log('所有图片加载完成');
});

randomData - 从数组随机获取N个数据

函数签名:

randomData<T>(data: T[], count: number = 0) => T[]

功能说明:
从数组随机获取N个数据

参数:

示例:

// 从数组随机获取N个数据
const data = [1, 2, 3, 4, 5];
const randoms = randomData(data, 3); // 例如：[3, 1, 5]
console.log(randoms);

randomNumber - 生成随机数

函数签名:

randomNumber(min: number, max: number) => number

功能说明:
生成一个介于min和max之间的随机整数

参数:

示例:

// 生成随机数
const num1 = randomNumber(1, 10); // 1-10之间的随机整数
const num2 = randomNumber(0, 100); // 0-100之间的随机整数
console.log(num1, num2);

request - AJAX请求

函数签名:

request(ajax: Ajax) => XMLHttpRequest

功能说明:
通用ajax请求

参数:

示例:

// AJAX请求
request({
  url: '/api/data',
  params: { index: 1 },
  timeout: 3000,
  success: (data) => console.log('成功', data),
  error: (err) => console.log('失败', err)
});

separate - 字符串分割处理

函数签名:

separate(target: string, separator: string) => string[]

功能说明:
字符串分割处理

参数:

示例:

// 字符串分割
const result = separate('name@123', '@');
console.log(result); // ['name', '123']

setBanner - 设置数据轮播

函数签名:

setBanner<T>(data: T[], config: BannerConfig<T>) => Banner<T>

功能说明:
设置数据轮播

参数:

返回值: 控制对象

示例:

// 设置数据轮播
const banner = setBanner(['a', 'b', 'c'], {
  index: 1,
  change: (item, index, prev) => console.log('当前项:', item, '当前索引:', index, '上一个索引:', prev),
});
banner.start(); // 启动轮播
console.log(banner.current()); // 当前轮播数据
console.log(banner.currentIndex()); // 当前轮播索引
banner.setCurrentIndex(2); // 设置当前轮播索引为2
banner.next(); // 切换到下一个
banner.prev(); // 切换到前
banner.stop(); // 停止自动轮播
banner.changeTo(2); // 切换到指定索引为2的轮播项

setRange - 设置数值范围

函数签名:

setRange(value: number, max: number, min: number = 0) => number

功能说明:
超出范围则设置为边界值

参数:

示例:

// 设置数值范围
const val1 = setRange(5, 10, 0); // 5
const val2 = setRange(15, 10, 0); // 10
const val3 = setRange(-5, 10, 0); // 0
console.log(val1, val2, val3);

sliceData - 裁剪数组并占位填充

函数签名:

sliceData<T>(data: T[], start?: number, end?: number) => T[]

功能说明:
裁剪数组并占位填充

参数:

示例:

// 裁剪数组并占位填充
const data = [1, 2, 3, 4, 5];
const result = sliceData(data, 1, 3); // [2, 3]
console.log(result);

sortIndexData - 数组数据按给定索引依次排序

函数签名:

sortIndexData<T>(data: T[], index: number) => T[]

功能说明:
数组数据按给定索引依次排序

参数:

示例:

// 数组数据按给定索引依次排序
const data = [3, 1, 2];
const result = sortIndexData(data, 1); // [1, 2, 3]
console.log(result);

throttle - 单实例节流处理

函数签名:

throttle(fn: Function, interval: number = 1000) => void

功能说明:
单实例函数节流

参数:

示例:

// 节流处理
const handleScroll = throttle(() => {
  console.log('滚动处理');
}, 1000);

window.addEventListener('scroll', handleScroll);

cancelThrottle - 取消单实例节流处理

函数签名:

cancelThrottle() => void

示例:

// 取消节流
cancelThrottle();

throttleBuilder - 函数节流生成器

函数签名:

throttleBuilder(fn: Function, interval: number = 1000, immediate?: boolean) => {
  (...args: any): void;
  cancel: () => void;
  cancelThenCall: (...args: any) => void;
}

功能说明:
函数节流生成器

参数:

示例:

// 节流生成器
const throttledFn = throttleBuilder(() => {
  console.log('执行');
}, 1000, true);

throttledFn();
throttledFn();

urlJoinParams - 为链接拼接参数

函数签名:

urlJoinParams<T>(url: string = window.location.href, paramObj: T) => string

功能说明:
为链接拼接参数

参数:

示例:

// 为链接拼接参数
const url1 = 'https://example.com';
const result = urlJoinParams(url1, { page: 2 }); // 'https://example.com?page=2'
console.log(result);

3. helpers - 辅助工具函数

本模块提供各种辅助工具函数，包括类型判断、DOM操作、浏览器兼容性检测等功能。

$、$ - 快速选择DOM元素

函数签名:

$<T extends Element>(selector: string): ExtendHTMLElement;
$$<T extends Element>(selector: string): ExtendHTMLElement[];

功能说明:
快速选择DOM元素，$返回单个元素，$$返回多个元素的数组。

参数:

示例:

// 通过ID选择元素
const element = $('id');
// 通过类名选择元素
const elements = $$('className');

requestAFrame - 请求动画帧

函数签名:

requestAFrame(fn: Function) => number

功能说明:
请求动画帧，返回一个唯一的标识符。

参数:

示例:

// 请求动画帧
const frameId = requestAFrame(() => {
  console.log('动画帧回调');
});

cancelAFrame - 取消动画帧

函数签名:

cancelAFrame(frameId: number) => void

功能说明:
取消动画帧，通过提供的标识符。

参数:

示例:

// 取消动画帧
cancelAFrame(frameId);

assign - 对象属性合并

函数签名:

assign<T, U extends Object>(target: T, obj?: U, fit?: boolean): T & U;

功能说明:
对象属性合并，fit=true时参照目标结构扩展，否则参照扩展对象结构。

参数:

示例:

// 对象属性合并
const target = { a: 1 };
const source = { b: 2 };
const result = assign(target, source);
console.log(result); // { a: 1, b: 2 }

checkAnimationEvent - 检查动画事件支持

函数签名:

checkAnimationEvent() => string

示例:

// 检查动画事件支持
const animationEnd = checkAnimationEvent();
element.addEventListener(animationEnd, handler);

checkTransitionEvent - 检查过渡事件支持

函数签名:

checkTransitionEvent() => string

示例:

// 检查过渡事件支持
const transitionEnd = checkTransitionEvent();
element.addEventListener(transitionEnd, handler);

clone - 深度克隆对象

函数签名:

clone<T>(obj: T): T;

功能说明:
深度克隆对象，支持数组和普通对象的深拷贝。

参数:

示例:

// 深度克隆对象
const original = { a: 1, b: [2, 3] };
const cloned = clone(original);
console.log(cloned); // { a: 1, b: [2, 3] }

debug - 打印调试信息

函数签名:

debug(info: string, ...rest: any) => void

功能说明:
打印debug信息

参数:

示例:

// 打印调试信息
debug('调试信息');
// 仅在一行显示的定制样式打印调试信息
debug('调试信息', { line: true, style: { color: 'red', fontSize: 30 } });

errorCapture - 错误捕获

函数签名:

errorCapture(options: ErrorCaptureOptions) => {
  destroy: () => void;
}

功能说明:
错误捕获

参数:

返回值: 实例对象，包含销毁监听器的函数destroy

示例:

// 错误捕获
const handler = errorCapture({
  error: new Error('测试错误'),
  callback: (error) => console.log('捕获到错误', error)
});

// 销毁监听器
handler.destroy();

extentDOM - 扩展DOM元素或节点

函数签名:

extentDOM(element?: Element | Node) => ExtendHTMLElement

功能说明:
扩展dom元素或节点

参数:

示例:

// 扩展DOM元素
const element = document.getElementById('test');
const extended = extentDOM(element);
console.log(extended); // 扩展后的元素

getHash - 获取字符串哈希值

函数签名:

getHash(string: string) => string

功能说明:
获取字符串生成哈希值

参数:

示例:

// 获取字符串哈希值
const hash = getHash('test string');
console.log(hash); // n59vna9

isDev - 判断是否为开发环境

函数签名:

isDev() => boolean

示例:

// 判断是否为开发环境
if (isDev()) {
  console.log('开发环境');
}

isDom - 判断是否为DOM节点

函数签名:

isDom() => boolean

功能说明:
判断数据是否为dom节点

示例:

// 判断是否为DOM节点
const element = document.getElementById('test');
console.log(isDom(element)); // true
console.log(isDom({})); // false

isNaN - 判断是否为NaN

函数签名:

isNaN(arg: any) => boolean

功能说明:
判断参数是否为NaN

参数:

示例:

// 判断是否为NaN
console.log(isNaN(NaN)); // true
console.log(isNaN(123)); // false

isObject - 判断是否为对象

函数签名:

isObject(obj: any) => boolean

示例:

// 判断是否为对象
console.log(isObject({})); // true
console.log(isObject([])); // false
console.log(isObject(null)); // false

isPc - 判断是否为PC端

函数签名:

isPc() => boolean

示例:

// 判断是否为PC端
if (isPc()) {
  console.log('是PC端');
} else {
  console.log('不是PC端');
}

nonEmpty - 检测数据是否非空

函数签名:

nonEmpty(data: any) => boolean

功能说明:
检测数据是否为空, 数组长度不为0、对象可枚举键值数不为0、字符串长度不为0或者数据有效(非undefined, null, NaN)

参数:

示例:

// 检测数据是否非空
console.log(nonEmpty('test')); // true
console.log(nonEmpty([1, 2, 3])); // true
console.log(nonEmpty({ a: 1 })); // true
console.log(nonEmpty('')); // false
console.log(nonEmpty([])); // false
console.log(nonEmpty({})); // false
console.log(nonEmpty(null)); // false

readObject - 读取对象属性值

函数签名:

readObject<T>(obj: T, path?: string, defaultValue?: any) => any

功能说明:
读取对象属性值，支持多级路径读取

参数:

示例:

// 读取对象属性值
const obj = { a: { b: { c: 1 } } };
console.log(readObject(obj, 'a.b.c')); // 1
console.log(readObject(obj, 'a.b.d', 2)); // 2

writeObject - 设置对象属性值

函数签名:

writeObject<T>(obj: T, path?: string, value?: any) => void

功能说明:
设置对象属性值，支持多级路径设置

参数:

示例:

// 设置对象属性值
const obj = {};
writeObject(obj, 'a.b.c', 1);
console.log(obj); // { a: { b: { c: 1 } } }

forceJsTransform - 强制使用JS动画

函数签名:

forceJsTransform() => void

示例:

// 强制使用JS transform
forceJsTransform();

cancelForceJsTransform - 取消强制使用JS动画

函数签名:

cancelForceJsTransform() => void

示例:

// 取消强制JS transform
cancelForceJsTransform();

supportTransform - 检测transform支持情况

函数签名:

supportTransform() => boolean

功能说明:
是否支持transform

示例:

// 检测transform支持
if (supportTransform()) {
  console.log('支持transform');
}

supportCss - 检测CSS属性支持情况

函数签名:

supportCss(prop: keyof CSSStyleDeclaration) => boolean

功能说明:
判断是否支持某css属性

参数:

示例:

// 检测CSS属性支持
if (supportCss('transform')) {
  console.log('支持transform');
}

typeIs - 类型判断

函数签名:

typeIs(type: TType, obj: any) => boolean

功能说明:
判断obj是否是给定类型

参数:

示例:

// 类型判断
console.log(typeIs('Array', [1, 2, 3])); // true
console.log(typeIs('Number', 123)); // true
console.log(typeIs('String', 'test')); // true
console.log(typeIs('Object', {})); // true

uniqueBy - 获取唯一键值

函数签名:

uniqueBy(string: string = window.location.href, rest: string = '') => string

功能说明:
获取唯一键值

参数:

示例:

// 获取唯一键值
const key1 = uniqueBy(); // 基于当前URL
const key2 = uniqueBy('http://example.com', 'extra');
console.log(key1, key2);

valid - 参数是否有效

函数签名:

valid(arg: any) => boolean

功能说明:
参数是否有效(非undefined, null, NaN)

参数:

示例:

// 判断参数是否有效
console.log(valid(123)); // true
console.log(valid('test')); // true
console.log(valid(null)); // false
console.log(valid(undefined)); // false
console.log(valid(NaN)); // false

类型定义参考

Ajax

interface Ajax {
  /** 请求方法 */ type?: 'GET' | 'POST';
  /** 请求地址 */ url: string;
  /** 请求参数是否为json字符串 */ json?: boolean;
  /** 请求是否开启gzip */ gzip?: boolean;
  /** 请求头参数 */ headers?: { [key: string]: string };
  /** 请求参数 */ params?: Object;
  /** 超时ms */ timeout?: number;
  /** 延迟响应结果ms */ delay?: number;
  /** 是否采用同步请求 */ sync?: boolean;
  /** 发生异常时的重试次数 */ retry?: number;
  /** 成功回调 */ success?: (data: string) => void;
  /** 异常回调 */ error?: (err: ProgressEvent<EventTarget> | string) => void;
}

BannerConfig

interface BannerConfig<T> {
  /** 起始索引 */ index?: number;
  /** 静态轮播 */ static?: boolean;
  /** 切换时间 */ interval?: number;
  /** 初始化时是否立即执行change方法 */ immediate?: boolean;
  /**
   * 切换监听
   * @param item 当前轮播数据
   * @param index 当前索引
   * @param prev 前一个索引
   */
  change?(item: T, index: number, prev: number): void;
}

CountDown

interface CountDown {
  /** 结束倒计时 */ stop(): void;
}

CropText

interface CropText {
  /** 是否超出指定长度 */
  over: boolean;
  /** 原始字符串 */
  origin: string;
  /** 处理后的字符串 */
  value: string;
}

ExtendHTMLElement

type Content = string | string[] | ExtendHTMLElement | (() => string | string[] | ExtendHTMLElement);
interface ExtendHTMLElement extends HTMLElement {
  /**
   * 添加事件监听
   * @param type 事件名
   * @param listener 监听函数
   * @param option 监听配置
   */
  addEvent<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
  addEvent(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
  /**
   * 移除事件监听
   * @param type 事件名
   * @param listener 监听函数
   */
  removeEvent<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
  removeEvent(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
  /**
   * 显示dom
   */
  block(): this;
  /**
   * 隐藏dom
   */
  none(): this;
  /**
   * 显示dom
   */
  visible(): this;
  /**
   * 隐藏dom
   */
  unvisible(): this;
  /**
   * dom是否可见
   */
  active(): boolean;
  /**
   * 设置不透明度
   * @param {number} opacity 不透明度 0-1
   */
  setOpacity(opacity: number): this;
  /**
   * 淡入动画
   * @param {number} duration 动画时间ms
   * @param {() => void} complete 动画结束回调
   * @default 1000
   */
  fadeIn(duration?: number, complete?: () => void): this;
  /**
   * 淡出动画
   * @param {number} duration 动画时间ms
   * @param {() => void} complete 动画结束回调
   * @default 1000
   */
  fadeOut(duration?: number, complete?: () => void): this;
  /**
   * 图片加载淡入淡出动画
   * @param {string} src 图片加载路径
   * @param {number} duration 动画时间ms
   * @param {boolean} immediate 首次加载时是否需要动画
   * @param {() => void} complete 动画结束回调
   */
  fadeImg(src: string, duration?: number, immediate?: boolean, complete?: () => void): this;
  /**
   * 获取当前淡入的图片路径
   */
  getFadeImg(): string;
  /**
   * 结尾追加html
   * @param html html字符串或dom
   */
  appendHtml(html: Content): this;
  /**
   * 开头追加html
   * @param html html字符串或dom
   */
  prependHtml(html: Content): this;
  /**
   * 挂载数据
   * @param {string} key 键
   * @param {string} val 值
   * @example
   * const dom = SEpg.Util.$('area0_list_0');
   * dom.data('name', 'value');// 内存中设置name="value"
   * dom.data('name');// 获取name的值
   */
  data<T>(key: string, val?: T): T | null;
  /**
   * 设置或获取data属性值
   * @param {string} key 键
   * @param {string} val 值
   * @example
   * const dom = SEpg.Util.$('area0_list_0');
   * dom.pack('name', 'value');// 设置data-name="value"
   * dom.pack('name');// 获取data-name的值
   */
  pack(key: string, val?: string | number): string | null;
  /**
   * 设置或获取dom属性值
   * @param {string} key 键
   * @param {string} val 值
   * @example
   * const dom = SEpg.Util.$('area0_list_0');
   * dom.attr('style', 'left:12px;top:20px');// 设置style样式
   * dom.attr('name');// 获取name属性的值
   */
  attr(key: string, val?: string): string | this;
  /**
   * 设置默认滑动速度
   * @param speed 速度
   */
  defaultSpeed(speed: number): this;
  /**
   * 宽度伸缩动画
   * @param {number} width 目标宽度
   * @param {number} [speed] 速度
   * @param {TTimeFunction} [time_function='ease'] 滑动的速度曲线 
   */
  widthChange(width: number, speed?: number, complete?: () => void, time_function?: TTimeFunction): this;
  /** 滑动开始回调 */
  slideStart?: (() => void) | null;
  /** 滑动结束回调 */
  slideEnd?: (() => void) | null;
  /**
   * 设置dom元素滑动
   * @param {number} distance 滑动距离
   * @param {'h'|'v'} [slideDir] 横向还是纵向(h开头为横向，v开头为纵向，默认v)
   * @param {number} [speed] 速度
   * @param {number} [delay=0] 延迟
   * @param {any} [keepVal] 不动轴的值 传非数值时自动获取
   * @param {TTimeFunction} [time_function='ease'] 滑动的速度曲线
   * @example
   * const dom = SEpg.Util.$('area0_list_0');
   * // dom在竖直方向上按'ease'时间曲线函数移动到translateY=100处，过度时间200ms。
   * dom.slide(100, 'v', 200, 0, false, 'ease');
   */
  slide(distance: number, slideDir?: TScrollDir, speed?: number, delay?: number, keepVal?: any, time_function?: TTimeFunction): this;
  /**
   * 设置dom元素滑动(双轴同时滑动)
   * @param {number} x 横轴距离
   * @param {number} y 纵轴距离
   * @param {number} [speed] 速度
   * @param {number} [delay=0] 延迟
   * @param {TTimeFunction} [time_function='ease'] 滑动的速度曲线
   * @example
   * const dom = SEpg.Util.$('area0_list_0');
   * // dom按'ease'时间曲线函数移动到translateX=100、translateY=100处，过度时间200ms。
   * dom.slide(100, 100, 200, 0, 'ease');
   */
  freeSlide(x: number, y: number, speed?: number, delay?: number, time_function?: TTimeFunction): this;
  /**
   * 轮播图式滑动切换
   * @param {string | ExtendHTMLElement} slideContainer 滑动元素的类名或滑动元素
   * @param {number} [timeout=5000] 滑动间隔(最低1000)
   * @param {number} [speed=500] 滑动速度
   * @example
   * const dom = SEpg.Util.$('text');
   * const banner = dom.bannerSlide('scroll');
   * banner.move();// 开始滚动
   * banner.stop();// 停止滚动
   */
  bannerSlide(slideContainer: string | ExtendHTMLElement, timeout?: number, speed?: number): {
  /** 启用滚动 */ move(): void; /** 停止滚动 */ stop(): void
  };
  /**
   * 获取transform对应坐标轴的translate值（前提使用translate3d）
   * @param {TTranslateDir} [translateDir='x'] 获取的坐标轴
   * @example
   * const dom = SEpg.Util.$('area0_list_0');
   * let translateX = dom.getTranslateVal();// 获取translateX值
   * let translateY = dom.getTranslateVal('y');// 获取translateY值
   * let translateZ = dom.getTranslateVal('z');// 获取translateZ值
   */
  getTranslateVal(translateDir?: TTranslateDir): number;
  /**
   * 获取style某属性值
   * @param {keyof CSSStyleDeclaration} prop 属性
   */
  getStyle(prop: keyof CSSStyleDeclaration): string;
  /** 强制js实现标识 */
  forceJs: boolean;
  /** 焦点元素定位索引 */
  index: number;
  /** 从属的区域控制器实例 */
  area: any;
  /** SafeDOMRect数据 */
  rect: SafeDOMRect | null;
  /** 已扩展标识 */
  _extend_: boolean;
  /** 复制元素标识 */
  _copy_: boolean;
  /** 当前元素所在屏幕序号, 用于处理多屏元素的焦点计算 */
  screen: number;
  /** 定制dom焦点样式 */
  focusClass: string;
  /** 定制dom失焦样式 */
  blurClass: string;
  /** 定制dom驻留样式 */
  selectClass: string;
  /**
   * 强制js实现
   */
  doForceJs(): this;
  /**
   * 取消强制js实现
   */
  undoForceJs(): this;
  /**
   * getBoundingClientRect方法兼容(结果会自动四舍五入)
   */
  getBoundingClientRectSafe(): SafeDOMRect;
  /**
   * 检测当前元素是否在指定视口内(需要完全进入视口)
   * @param {ExtendHTMLElement} viewPoint 视口元素
   */
  enterView(viewPoint?: ExtendHTMLElement): boolean;
  /**
   * 检测当前元素是否进入指定视口(与视口有重叠即可)
   * @param {ExtendHTMLElement} viewPoint 视口元素
   * @param {number} [offset=0] 视口偏移值(在实际的尺寸下的偏移量, 用于做预加载判断)
   * @param {'v' | 'h'} [origin='v'] 重叠方向(一般同页面滑动方向)
   */
  contactView(viewPoint?: ExtendHTMLElement, offset?: number, origin?: 'v' | 'h'): boolean;
  /** 内容置空 */
  empty(): this;
  /** 内容是否为空 */
  isEmpty(): boolean;
  /**
   * 填充元素html内容
   * @param {Content} html 字符串或html元素
   */
  html(html?: Content): string;
  /**
   * 设置动画
   * @param options 动画配置
   * @param time_function 时间函数
   */
  motion(options: AnimateOptions & { zoom?: number }, time_function?: TTimeFunction): this;
  [key: string]: any;
}

TTimeFunction

/** transform时间函数 */
type TTimeFunction = '' | 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out';

SafeDOMRect

interface SafeDOMRect {
  bottom: number;
  height: number;
  left: number;
  right: number;
  top: number;
  width: number;
  x: number;
  y: number;
}

AnimateOptions

type PCSS = Partial<Pick<
  CSSStyleDeclaration,
  'left' | 'top' | 'right' | 'bottom' | 'width' | 'height' | 'opacity'
>>;
type A<T> = {
  [P in keyof T]: number;
};
/** 动画配置参数接口 */
type AnimateOptions = {
  duration?: number;
  complete?(): void;
} & A<PCSS>;

IDate

/** 时间数据 */
interface IDate {
  /** 格式化时间 */ time: string;
  /** 今天、昨天、日期等 */ dateStr: string;
}

TType

/** 数据类型 */
type TType = 'Undefined' | 'Null' | 'RegExp' | 'Error' | 'Promise' | 'Set' | 'Function' | 'Object' | 'Symbol' | 'Number' | 'String' | 'Boolean' | 'Array';

TScrollDir

/** 横纵方向 */
type TScrollDir = 'h' | 'v';

TTranslateDir

/** translate方向 */
type TTranslateDir = 'x' | 'y' | 'z';