z-util-page 说明文档

简介

z-util-page 是一个基于JavaScript的工具包，包含了一些常用的工具函数，如防抖、节流、深拷贝等。

安装

1. 全局引入

拷贝包目录下dist文件夹内 [ zutilpage.min.js ] 文件到自己的项目里，在HTML里添加如下引用：

1<script src="zutilpage.min.js"></script>

这会添加一个全局变量 [ Utils ] 到window对象;

1Utils.debounce(function(){
2    console.log('身体和心灵，总有一个在路上。');
3}, 200);

2. 按需引入

运行以下命令将工具包安装到本地

1npm i z-util-page --save

根据需要自行引入

1import { debounce, throttle, deepClone } from 'z-util-page';

说明

Cookie操作辅助类

CookieHelper

clear()

1function clear(): void

清空cookie

Example

1clear();

Returns

void

---

exist()

1function exist(key: string): boolean

根据key值判断Cookie中是否存在键值对

Example

1exist('test');

Parameters

Parameter	Type	Description
key	string	key值

Returns

boolean

---

getItem()

1function getItem(key: string): string

根据key值获取cookie数据

Example

1getItem('test');

Parameters

Parameter	Type	Description
key	string	key值

Returns

string

Cookie中key值为key的值

---

getItemOnce()

1function getItemOnce(key: string): string

根据key值获取cookie数据后删除Cookie中该键值对

Example

1getItemOnce('test');

Parameters

Parameter	Type	Description
key	string	key值

Returns

string

Cookie中键值为key的值

---

removeItem()

1function removeItem(key: string): void

根据key值删除Cookie中键值对

Example

1removeItem('test');

Parameters

Parameter	Type	Description
key	string	key值

Returns

void

---

setItem()

1function setItem(key: string, val: string): boolean

设置cookie的键值对

Example

1setItem('test', '你好, 世界!');

Parameters

Parameter	Type	Description
key	string	键
val	string	值

Returns

boolean

DOM操作辅助类

DomHelper

draggable()

1function draggable(dom: HTMLElement): false | {
2  close: void;
3  open: void;
4  wrap: void;
5}

将一个元素处理为可拖动元素

Example

1const handle = draggable(dom: HTMLElement);
2// 关闭拖动功能
3handle.close();
4// 开启拖动功能
5handle.open();
6// 指定一个子元素，当该鼠标按下该元素时，关闭拖动功能，鼠标抬起后恢复拖动功能
7handle.wrap(dom: HTMLElement);

Parameters

Parameter	Type	Description
dom	HTMLElement	要处理的元素

Returns

false | { close: void; open: void; wrap: void; }

---

scrollToBottom()

1function scrollToBottom(scroll: HTMLElement): void

将可滚动元素滚动到底部

Example

1scrollToBottom(dom: HTMLElement);

Parameters

Parameter	Type	Description
scroll	HTMLElement	要滚动的元素

Returns

void

---

scrollToLeft()

1function scrollToLeft(scroll: HTMLElement): void

将可滚动元素滚动到最左侧

Example

1scrollToLeft(dom: HTMLElement);

Parameters

Parameter	Type	Description
scroll	HTMLElement	要滚动的元素

Returns

void

---

scrollToRight()

1function scrollToRight(scroll: HTMLElement): void

将可滚动元素滚动到最右侧

Example

1scrollToRight(dom: HTMLElement);

Parameters

Parameter	Type	Description
scroll	HTMLElement	要滚动的元素

Returns

void

---

scrollToTop()

1function scrollToTop(scroll: HTMLElement): void

将可滚动元素滚动到顶部

Example

1scrollToTop(dom: HTMLElement);

Parameters

Parameter	Type	Description
scroll	HTMLElement	要滚动的元素

Returns

void

HTTTP请求操作辅助类

Http

Constructors

new Http()

1new Http(options: CustomHttpOptions): Http

构造函数

Example

1const http = new Http({
2 //超时等待时间(ms)
3 timeout: 10000,
4 //基地址
5 baseUrl: 'http://localhost:3000',
6 //请求体数据格式
7 contentType: 'application/json',
8 //响应数据格式
9 responseType: 'json'
10});

Parameters

Parameter	Type	Description
options	CustomHttpOptions	默认参数

Returns

Http

Properties

Property	Modifier	Type	Description
Interceptor	public	Interceptor	拦截器
options	public	HttpOptions	默认参数

Methods

ajax()

1ajax(param: Param): PromiseHandle

XMLHttpRequest异步请求

Example

1const http = new Http();

2// 拦截器
3http.Interceptor.request((param) => {
4 // 请求参数
5 console.log(param);
6 param.url = 'http://localhost:3000' + param.url;
7})
8http.Interceptor.response((res) => {
9 // 请求结果
10 console.log(res);
11 res.data = res.data + '拦截器修改';
12 return res;
13})
14
15// 请求
16const req = http.ajax({
17 // 请求地址
18 baseUrl: 'http://localhost:3000',
19 url: '/api/user',
20 // 请求方法
21 method: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE',
22 // 响应数据格式
23 type: "arraybuffer" | "blob" | "document" | "json" | "text",
24 // 请求头
25 headers: {
26  'Content-Type': 'application/json',
27   'Authorization': 'Bearer ' + token
28 }
29 // 请求体
30 data: {
31  name: 'jack'
32 }
33 // 请求参数
34 params: {
35  name: 'jack'
36 }
37 // 请求超时时间
38 timeout: 10000
39 // 请求体数据格式
40 contentType: 'application/json',
41 // 响应数据类型
42 responseType: 'json',
43 // 上传文件
44 file: {
45   file: new Blob([JSON.stringify({a: '身体和心灵，总有一个在路上。'}, null, 2)], {type : 'application/json'})
46 }
47}).then((res) => {
48  // 请求成功
49}).catch((err) => {
50 // 请求失败
51}).finally(() => {
52 // 请求完成
53}).progress(() => {
54 // 请求进度
55});
56
57// 取消请求
58req.abort();

Parameters

Parameter	Type	Description
param	Param	请求参数

Returns

PromiseHandle

ajaxAsync()

1ajaxAsync(param: Param): any

XMLHttpRequest同步请求，绝大多数情况下只能在work进程内使用。

Example

1const http = new Http();
2// 请求
3const req = http.ajax({
4 // 请求地址

5 baseUrl: 'http://localhost:3000',

6 url: '/api/user',
7 // 请求方法

8 method: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE',
9 // 响应数据格式

10 type: "arraybuffer" | "blob" | "document" | "json" | "text",
11 // 请求头

12 headers: {
13  'Content-Type': 'application/json',
14   'Authorization': 'Bearer ' + token
15 }
16 // 请求体

17 data: {

18  name: 'jack'
19 }
20 // 请求参数

21 params: {

22  name: 'jack'
23 }
24 // 请求超时时间

25 timeout: 10000
26 // 请求体数据格式

27 contentType: 'application/json',
28 // 响应数据类型

29 responseType: 'json',
30 // 上传文件

31 file: {

32   file: new Blob([JSON.stringify({a: '身体和心灵，总有一个在路上。'}, null, 2)], {type : 'application/json'})
33 }
34})
35// 请求成功
36console.log(res);

Parameters

Parameter	Type	Description
param	Param	请求参数

Returns

any

indexedDB操作辅助类

IDBHelper

Constructors

new IDBHelper()

1new IDBHelper(name: string): IDBHelper

构造函数

Parameters

Parameter	Type	Description
name	string	数据库名称

Returns

IDBHelper

IDBHelper实例

---

Throws

Error 数据库名称不能为空

Methods

close()

1close(): Promise<undefined | false>

关闭数据库

Example

1const db = new IDBHelper('test');
2await db.close();

Returns

Promise<undefined | false>

---

createTable()

1createTable(tableNameList: string | string[], keyPath?: string): Promise<boolean>

创建表

Example

1const db = new IDBHelper('test');
2await db.createTable('tn');

Parameters

Parameter	Type	Description
tableNameList	string | string[]	表名列表
keyPath?	string	主键

Returns

Promise<boolean>

---

deleteAllTable()

1deleteAllTable(): Promise<boolean>

删除所有表

Example

1const db = new IDBHelper('test');
2await db.deleteAllTable();

Returns

Promise<boolean>

---

deleteTable()

1deleteTable(tableNameList: string | string[]): Promise<boolean>

删除表

Example

1const db = new IDBHelper('test');
2await db.deleteTable('tn');

Parameters

Parameter	Type	Description
tableNameList	string | string[]	表名列表

Returns

Promise<boolean>

---

deleteTableRow()

1deleteTableRow(tableName: string, key: string): Promise<undefined | false>

删除表中某行数据

Example

1const db = new IDBHelper('test');
2await db.deleteTableRow('tn', 'key');

Parameters

Parameter	Type	Description
tableName	string	表名
key	string	键

Returns

Promise<undefined | false>

---

getAllTableName()

1getAllTableName(): Promise<false | DOMStringList>

获取所有表名

Example

1const db = new IDBHelper('test');
2await db.getAllTableName();

Returns

Promise<false | DOMStringList>

false 或 string[]

---

getAllTableRow()

1getAllTableRow(tableName: string, range?: IDBKeyRange): Promise<unknown>

获取表中所有数据

Example

1const db = new IDBHelper('test');
2await db.getAllTableRow('tn');

Parameters

Parameter	Type	Description
tableName	string	表名
range?	IDBKeyRange	范围

Returns

Promise<unknown>

---

getTableRow()

1getTableRow(tableName: string, key: string): Promise<unknown>

获取表中某行数据

Example

1const db = new IDBHelper('test');
2await db.getTableRow('tn', 'key');

Parameters

Parameter	Type	Description
tableName	string	表名
key	string	键

Returns

Promise<unknown>

---

getTableRowCount()

1getTableRowCount(tableName: string, range?: IDBKeyRange): Promise<unknown>

获取表数据条数

Example

1const db = new IDBHelper('test');
2await db.getTableRowCount('tn');

Parameters

Parameter	Type	Description
tableName	string	表名
range?	IDBKeyRange	范围

Returns

Promise<unknown>

---

reSet()

1reSet(): Promise<false | Boolean>

重置数据库

Example

1const db = new IDBHelper('test');
2await db.reSet();

Returns

Promise<false | Boolean>

---

setTableRow()

1setTableRow(tableName: string, data: any): Promise<undefined | false>

增加/修改表中某行数据

Example

1const db = new IDBHelper('test');
2await db.setTableRow('tn', '你好！');

Parameters

Parameter	Type	Description
tableName	string	表名
data	any	数据

Returns

Promise<undefined | false>

---

事件总线

EventBus

Example

1// 总线
2let count = 0;
3EventBus.on('test', function (num, num1) {
4  count = num + num1;
5})
6EventBus.emit('test', 1, 2);
7expect(count).toBe(3);
8
9// 分线
10let count = 0;
11const bus = new EventBus();
12bus.on('test', function (num, num1) {
13  count = num + num1;
14})
15bus.emit('test', 3, 4);
16expect(count).toBe(7);

Constructors

new EventBus()

1new EventBus(config?: EventBusConfig): EventBus

Parameters

Parameter	Type
config?	EventBusConfig

Returns

EventBus

Properties

Property	Modifier	Type
emit	public	(key: string, ...rest: any[]) => void
on	public	(key: string, func: (...rest: any[]) => void) => void

Methods

emit()

1static emit(key: string, ...rest: any[]): void

触发事件

Parameters

Parameter	Type	Description
key	string	事件名
...rest	any[]	传给回调函数的参数

Returns

void

on()

1static on(key: string, func: (...rest: any[]) => void): void

监听事件

Parameters

Parameter	Type	Description
key	string	事件名
func	(...rest: any[]) => void	回调函数

Returns

void

响应式数据API

Reactive

computed()

1function computed<T>(getter: () => {
2  value: T;
3 }): {
4  get value: any;
5}

获取计算属性

Example

1const count = ref(0);
2const double = computed(() => count.value * 2);
3console.log(double.value); //0
4count.value = 1;
5console.log(double.value); //2

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
getter	() => { value: T; }

Returns

1{
2  get value: any;
3}

computed

Name	Type
get value	any

---

effect()

1function effect(func: Function, options: EffectOptions): Effect

创建副作用函数

Example

1const count = ref(0);
2effect(() => {
3 console.log(count.value);
4})
5count.value = 1;
6// 打印1

Parameters

Parameter	Type	Description
func	Function	函数
options	EffectOptions	配置

Returns

Effect

effectFunc

---

reactive()

1function reactive<T>(
2   value: T, 
3   isShadow: boolean, 
4   isReadonly: boolean): T

代理对象值，返回响应式数据

Example

1const obj = reactive({name:'张三'});
2obj.name = '李四';
3console.log(obj.name); //李四

Type Parameters

Type Parameter
T extends object

Parameters

Parameter	Type	Default value	Description
value	T	undefined	对象值
isShadow	boolean	false	true为深代理，false为浅代理
isReadonly	boolean	false	是否只读

Returns

T

---

ref()

1function ref<T>(value: T, isReadonly: boolean): Ref<T>

代理基本类型值，返回响应式数据

1const obj = ref(3);
2obj.value = 4;
3console.log(obj.value); //4

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Default value	Description
value	T	undefined	基本类型值
isReadonly	boolean	false	是否只读

Returns

Ref<T>

---

toRaw()

1function toRaw<T>(proxy: T): T

获取原始对象

Example

1const count = reactive({ a: 1 });
2console.log(toRaw(count)); //{ a: 1 }

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
proxy	T	响应式对象

Returns

T

原始对象

---

toRef()

1function toRef(val: any, key: string | symbol): {
2  get set value: any;
3}

将响应式对象的某键值转为ref

Example

1const obj = reactive({ a: 1 });
2const a = toRef(obj, 'a');
3a.value = 2;
4console.log(obj.a); //2

Parameters

Parameter	Type	Description
val	any	响应式对象
key	string | symbol	键值

Returns

1{
2  get set value: any;
3}

Ref

Name	Type
get value	any
set value	void

---

toRefs()

1function toRefs(obj: any): {}

将响应式对象的键值全部转换为Ref, 可解构使用

Example

1const obj = reactive({ a: 1, b: 2 });
2const { a, b } = toRefs(obj);
3a.value = 2;
4console.log(obj.a); //2

Parameters

Parameter	Type	Description
obj	any	响应式对象

Returns

1{}

Refs

---

watch()

1function watch(
2   source: object | Function, 
3   cb: Function, 
4   options: EffectOptions): void

监听响应式数据

Example

1const count = ref(0);
2watch(count, (newVal, oldVal) => {
3 console.log(newVal, oldVal);
4})
5count.value = 1;
6// 打印1 0

Parameters

Parameter	Type	Description
source	object | Function	副作用函数或者响应式对象
cb	Function	数据变化后回调函数
options	EffectOptions	配置

Returns

void

文件操作辅助类

FileHelper

choose()

1function choose(options: {
2  accept: string[];
3  capture:   | "user"
4     | "environment"
5     | "camera"
6     | "camcorder"
7     | "microphone";
8  multiple: boolean;
9}): Promise<FileList>

文件选择

Example

1choose({
2 accept: [".doc",".docx","application/msword"],
3 capture: "user",
4 multiple: true
5}).then(files => {
6    console.log(files);
7  })
8  .catch(err => {
9    console.error(err);
10  });

Parameters

Parameter	Type	Description
options	object	文件选择配置
options.accept?	string[]	以逗号为分隔的[唯一文件类型说明符]列表
options.capture?	| "user" | "environment" | "camera" | "camcorder" | "microphone"	尝试请求使用设备的媒体捕获设备（如：摄像机），而不是请求一个文件输入。camera–照相机；camcorder–摄像机；microphone–录音
options.multiple?	boolean	是否允许多选

Returns

Promise<FileList>

---

pickDir()

1function pickDir(dirKey: string, force: boolean): Promise<{
2  data: FileSystemDirectoryHandle | null;
3  message: string;
4  success: boolean;
5}>

选择文件夹(与saveFileToDir共用缓存)

Example

1//选择文件夹，将其与key绑定
2pickDir('key');
3//强制重新选择
4pickDir('key', true);

Parameters

Parameter	Type	Default value	Description
dirKey	string	undefined	文件夹唯一标识，自行定义string，用于后续向同一文件夹写入文件
force	boolean	false	是否强制重新选择

Returns

Promise<{ data: FileSystemDirectoryHandle | null; message: string; success: boolean; }>

Name	Type
data	FileSystemDirectoryHandle | null
message	string
success	boolean

---

read()

1function read(file: Blob | File): FileReaderDecorate

文件读取

Example

1const reader = read(file)
2 .loadend((res) => {
3   console.log(res);
4 })
5 //start方法参数类型："ArrayBuffer" | "BinaryString" | "DataURL" | "Text"
6 .start("ArrayBuffer");
7
8//读取操作发生中断时触发
9reader.abort((abo) => {
10  console.log(abo);
11})
12
13//读取操作发生错误时触发
14reader.error((err) => {
15  console.log(err);
16})
17
18//读取操作完成时触发
19reader.load((res) => {
20  console.log(res);
21})
22
23//读取操作开始时触发
24reader.loadstart((res) => {
25  console.log(res);
26})
27
28//读取操作结束时（要么成功，要么失败）触发
29reader.loadstart((res) => {
30  console.log(res);
31})
32
33//获取读取结果的promise
34const promise = reader.loadendPromise();
35
36//在读取Blob时触发。
37reader.progress((res) => {
38  console.log(res);
39})
40
41//获取状态
42const status = reader.getStatus();
43
44//获取结果
45const result = reader.getResult();
46
47//中断读取
48reader.stop();

Parameters

Parameter	Type	Description
file	Blob | File	File对象或Blob对象

Returns

FileReaderDecorate

---

save()

1function save(file: string | Blob, saveFileName: string): void

H5文件下载方法

Example

1save(new Blob(['你好世界'], { type: 'text/plain' }), 'test.txt');
2save('https://www.baidu.com/img/flexible/logo/pc/result@2.png', 'baidu.png');

Parameters

Parameter	Type	Default value	Description
file	string | Blob	undefined	资源链接或者blob对象
saveFileName	string	''	保存文件名

Returns

void

---

saveFileToDir()

1function saveFileToDir(
2   dirKey: string, 
3   fileName: string, 
4   fileContent: (FileContent | Promise<FileContent>)[], 
5   overwrite: boolean): Promise<{
6  message: string;
7  success: boolean;
8}>

将文件写入目标文件夹

Example

1//需要先调用pickDir选择文件夹
2saveFileToDir('key', 'file.txt', ['string', new Blob(['你好世界'], { type: 'text/plain' })]);

Parameters

Parameter	Type	Default value	Description
dirKey	string	undefined	文件夹唯一标识，自行定义string，用于后续向同一文件夹写入文件
fileName	string	undefined	文件名
fileContent	(FileContent | Promise<FileContent>)[]	undefined	二进制文件流或字符串数组
overwrite	boolean	true	是否覆盖同名文件

Returns

Promise<{ message: string; success: boolean; }>

Name	Type
message	string
success	boolean

辅助函数

debounce()

1function debounce(
2   func: Function, 
3   wait: number, 
4   immediatel?: boolean): (this: any, ...args: any[]) => any

将函数处理为防抖函数

Example

1let debounced = debounce(function () {
2  console.log('身体和心灵，总有一个在路上。');
3  return '身体和心灵，总有一个在路上。';
4}, 1000, true);
5debounced.then(function (res) {
6  console.log(res);
7});
8debounced();
9debounced.cancel();

Parameters

Parameter	Type	Description
func	Function	待处理函数
wait	number	函数执行延迟时间
immediatel?	boolean	是否立刻执行

Returns

Function

处理好的防抖函数

Parameters

Parameter	Type	Description
this	any	执行上下文继承自传入函数
...args	any[]	参数继承自传入函数

Returns

any

Name	Type	Description
cancel	void	取消防抖函数执行
then	{ (this: any, ...args: any[]): any; cancel(): void; then(callback: Function): ...; }	注册防抖函数执行后的回调

---

deepClone()

1function deepClone(value: any): any

深拷贝

Example

1let newValue = deepClone({
2  a: '身体和心灵，总有一个在路上。',
3  b: {
4    c: new Date(),
5    d: [1, 3, 4],
6    e: Symbol(),
7    a: null,
8    b: undefined,
9    f: {
10      a: 1,
11      b: true,
12    }
13  },
14  c: document.createElement('div'),
15  d: new RegExp(/\d+/ig),
16  e: new Error('错误'),
17  f: function () {
18    console.log('身体和心灵，总有一个在路上。');
19  }

Parameters

Parameter	Type	Description
value	any	待克隆值

Returns

any

克隆值

---

generateUUID()

1function generateUUID(length?: number, radix?: number): string

生成UUID4

Example

1generateUUID();
2generateUUID(12, 32);

Parameters

Parameter	Type	Description
length?	number	生成uuid的总长度，不传递则按照rfc4122标准生成uuid
radix?	number	uuid每个字符的基数 1-62

Returns

string

uuid字符串

---

getType()

1function getType(value: any): string

获取数据类型

Example

1const type = getType('你好');
2type === 'String';

Parameters

Parameter	Type	Description
value	any	任意值

Returns

string

类型字符串, 如'String'、'Map'等

---

mergeObject()

1function mergeObject<T>(
2   origin: T, 
3   ob: undefined | StandardObject, ...
4   more: StandardObject[]): T

深度合并n个对象值

Example

1const a = { a: 1, b: { c: 2 } };
2const b = { b: { d: 3 } };
3const c = { c: 4 };
4mergeObject(a, b, c);

Type Parameters

Type Parameter
T extends StandardObject

Parameters

Parameter	Type	Description
origin	T	将多个对象深度合并到该对象
ob	undefined | StandardObject	被合并对象
...more	StandardObject[]	其余被合并对象

Returns

T

---

parseUrl()

1function parseUrl(url: string): URLWithParam | null

解析URL

Example

1const url = 'https://www.baidu.com/s?wd=hello#world'
2const result = parseUrl(url)

Parameters

Parameter	Type	Description
url	string	统一资源定位符

Returns

URLWithParam | null

---

throttle()

1function throttle(
2   func: Function, 
3   wait: number, 
4   option?: throttleOptions): (this: any, ...argList: any[]) => any

函数节流

Example

1interface throttleOptions {
2  // 首次是否执行
3  leading: boolean,
4  // 结束是否执行
5  trailing: boolean
6}
7let throttle = throttle(function(){
8  console.log('身体和心灵，总有一个在路上。');
9  return '身体和心灵，总有一个在路上。';
10}, 1000, {
11  leading: true, 
12  trailing: true
13});
14throttle();
15throttle.cancel();

Parameters

Parameter	Type	Description
func	Function	待处理函数
wait	number	函数执行最短间隔时间
option?	throttleOptions	函数执行配置

Returns

Function

处理好的节流函数

Parameters

Parameter	Type	Description
this	any	执行上下文继承自传入函数
...argList	any[]	参数继承自传入函数

Returns

any

Name	Type	Description
cancel	void	取消节流函数执行