Skip to content

Commit da2291c

Browse files
OFreshmanOFreshman
committed
✨ feat: 更新文档
1 parent e1cddf6 commit da2291c

File tree

3 files changed

+129
-86
lines changed

3 files changed

+129
-86
lines changed

‎README.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -250,8 +250,7 @@ console.log(desensitize('110105199001011234', 'idcard')); // 输出：110105****
250250
</template>
251251
252252
<script setup lang="ts">
253-
import { ref } from 'vue'
254-
import Mutex from '@/utils/Mutex' // 假设 Mutex 存放在 utils 目录
253+
import Mutex from 'ui-utils-kit' // 假设 Mutex 存放在 utils 目录
255254
256255
// 状态变量，无需在 setup 中 return，自动暴露给模板使用
257256
const isSubmitting = ref(false)

‎packages/core/README.md‎

Lines changed: 64 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,12 @@ ui-utils-kit 是一个高效的偏业务前端工具函数库。
1111
[![License](https://img.shields.io/github/license/OFreshman/ui-utils-kit.svg?style=flat&colorA=080f12&colorB=1fa669)](https://github.com/OFreshman/ui-utils-kit/blob/main/LICENSE)
1212

1313
---
14+
## 📖changlogs
15+
- 2023-10-01
16+
- 新增 `tree` 模块，提供树形数据操作的工具函数。
17+
- 新增 `business` 模块，提供 DOM 转图片的工具函数。
18+
- 新增 `common` 模块，提供一些常用的业务工具函数。
19+
- 完善文档说明。
1420

1521
## 📌 简介
1622

@@ -22,6 +28,8 @@ ui-utils-kit 是一个高效的偏业务前端工具函数库。
2228
- **海报制作**
2329
将 DOM 元素转换为图片（canvas），支持自动下载或返回 Blob 格式数据。
2430
> 针对跨域图片问题，内置 `html2canvas` proxy 解决方案。
31+
- **业务工具类函数**
32+
提供一些常用的业务工具函数，如 JSON 安全解析、敏感信息脱敏等。
2533

2634
---
2735

@@ -45,12 +53,14 @@ ui-utils-kit 的工具函数分为三大类：`tree`、`business`、`common`，
4553
**方式一：**
4654
```javascript
4755
import { tree } from "ui-utils-kit";
56+
4857
const result = tree.buildTree(nodes);
4958
```
5059

5160
**方式二：**
5261
```javascript
5362
import { buildTree } from "ui-utils-kit";
63+
5464
const result = buildTree(nodes);
5565
```
5666

@@ -83,6 +93,9 @@ const result = buildTree(nodes);
8393

8494
**`tree.treeToArr`** 将树形数据转换为扁平化数组，便于遍历与处理。
8595

96+
- **参数：**
97+
- `tree` (`TreeNode`)：包含 `id` 与 `name`、`children`的树形结构数据。
98+
- `node` (`TreeNode`)：包含 `id` 与 `pid` 的节点数据。
8699
- **示例：**
87100
```typescript
88101
import { treeToArr } from 'ui-utils-kit';
@@ -96,6 +109,8 @@ const result = buildTree(nodes);
96109

97110
**`tree.updateTreeCheckStatus`** 更新树中节点的选中状态（含子节点与父节点联动）。
98111

112+
- **参数：**
113+
- `tree` (`TreeNode`)：包含 `id` 与 `name`、`children`的树形结构数据。
99114
- **示例：**
100115
```typescript
101116
import { updateTreeCheckStatus } from 'ui-utils-kit';
@@ -174,20 +189,8 @@ const result = buildTree(nodes);
174189
175190
### 1. safeJsonParse<T>(jsonString: string, defaultValue: T): [Error \| null, T]
176191
177-
**功能描述：**
178-
安全地解析 JSON 字符串，如果解析出错则返回默认值和错误对象。
192+
**功能描述：** 安全地解析 JSON 字符串，如果解析出错则返回默认值和错误对象。
179193
180-
```typescript
181-
export function safeJsonParse<T>(jsonString: string, defaultValue: T): [Error | null, T] {
182-
try {
183-
const parsed = JSON.parse(jsonString) as T;
184-
return [null, parsed];
185-
} catch (error) {
186-
console.error("JSON 解析错误:", error);
187-
return [error instanceof Error ? error : new Error(String(error)), defaultValue];
188-
}
189-
}
190-
```
191194
**参数**
192195
- `jsonString: string` — 要解析的 JSON 格式字符串。
193196
@@ -198,6 +201,8 @@ export function safeJsonParse<T>(jsonString: string, defaultValue: T): [Error |
198201
199202
- 示例
200203
```typescript
204+
import { safeJsonParse } from 'ui-utils-kit';
205+
201206
const [err, data] = safeJsonParse('{"foo": 42}', { foo: 0 });
202207
if (err) {
203208
// 处理解析错误
@@ -206,54 +211,71 @@ if (err) {
206211
}
207212
```
208213
### 2. desensitize(value: string, type: "mobile" | "idcard"): string
209-
功能描述：对敏感信息（手机号或身份证号）进行脱敏处理，隐藏中间部分。
214+
**功能描述**：对敏感信息（手机号或身份证号）进行脱敏处理，隐藏中间部分。
210215
211216
**参数**
212217
- `value: string` — 原始字符串，如手机号或身份证号。
213-
214218
- `type: "mobile" \| "idcard"` — 数据类型，"mobile" 脱敏手机号，"idcard" 脱敏身份证号。
215219
216220
**返回值**
217221
string — 脱敏后字符串，如果输入非字符串则返回空字符串。
222+
218223
- 示例
219224
```typescript
225+
import { desensitize } from 'ui-utils-kit';
226+
220227
console.log(desensitize('13812345678', 'mobile')); // 输出：138****5678
221228
console.log(desensitize('110105199001011234', 'idcard')); // 输出：110105********1234
222229
```
223230
224231
### 3. Mutex 类
225232
功能描述：模拟互斥锁机制，用于控制异步操作对共享资源的访问，确保同一时刻只有一个操作进入临界区。
226-
- 示例
227-
228-
```typescript
229-
import Mutex from './Mutex';
230-
231-
const mutex = new Mutex();
232-
233-
// 初始状态
234-
console.log('初始状态', mutex.isLocked(), mutex.queueLength()); // 初始状态 false 0
233+
> ##### 以下是一些应用场景
234+
> - 防止按钮重复点击：避免用户多次点击同一按钮导致重复网络请求或状态混乱
235+
> - 强制 API 调用顺序：确保一组异步接口按预期顺序依次执行，防止乱序带来的逻辑错误
236+
> - 多标签页 localStorage 访问：在多个浏览器标签或窗口同时操作同一 localStorage 时，避免数据竞争和丢失
237+
> - 分片上传（Chunked Upload）：在大文件上传时，按顺序上传每个分片，确保断点续传或失败重试时不会错乱
238+
> - Web Worker 任务同步：在主线程与 Worker 线程之间同步访问共享内存（如 SharedArrayBuffer ）时，保证原子性
235239
236-
// 获取锁
237-
await mutex.lock();
238-
console.log('获取锁后', mutex.isLocked(), mutex.queueLength()); // 获取锁后 true 0
239240
240-
// 第二次请求锁，不会立即获取，加入队列
241-
const pending = mutex.lock().then(() => {
242-
console.log('第二次获取锁', mutex.isLocked(), mutex.queueLength());
243-
});
244-
console.log('请求队列长度', mutex.queueLength()); // 请求队列长度 1
245-
246-
// 执行临界区代码
247-
// ...
241+
- 示例
248242
249-
// 释放锁，自动唤醒队列中的下一个请求
250-
mutex.unlock();
251-
console.log('释放锁后', mutex.isLocked(), mutex.queueLength()); // 释放锁后 true 0
243+
```typescript
244+
<template>
245+
<view>
246+
<button @click="onSubmit" :disabled="isSubmitting">
247+
{{ isSubmitting ? '提交中...' : '提交' }}
248+
</button>
249+
</view>
250+
</template>
251+
252+
<script setup lang="ts">
253+
import Mutex from 'ui-utils-kit' // 假设 Mutex 存放在 utils 目录
254+
255+
// 状态变量，无需在 setup 中 return，自动暴露给模板使用
256+
const isSubmitting = ref(false)
257+
// 创建一个互斥锁实例
258+
const submitMutex = new Mutex()
259+
260+
// 点击处理函数
261+
const onSubmit = async () => {
262+
// 获取锁：若已有操作在进行，则挂起后续调用
263+
await submitMutex.lock()
264+
try {
265+
isSubmitting.value = true
266+
// 模拟网络请求
267+
await new Promise<void>(resolve => setTimeout(resolve, 1500))
268+
uni.showToast({ title: '提交成功' })
269+
} catch (err: any) {
270+
uni.showModal({ title: '错误', content: err.message })
271+
} finally {
272+
isSubmitting.value = false
273+
// 释放锁，允许下一次点击
274+
submitMutex.unlock()
275+
}
276+
}
277+
</script>
252278
253-
await pending; // 等待第二个请求获取锁
254-
// 最后释放锁
255-
mutex.unlock();
256-
console.log('全部完成', mutex.isLocked(), mutex.queueLength()); // 全部完成 false 0
257279
```
258280
259281
---

‎playground/README.md‎

Lines changed: 64 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,12 @@ ui-utils-kit 是一个高效的偏业务前端工具函数库。
1111
[![License](https://img.shields.io/github/license/OFreshman/ui-utils-kit.svg?style=flat&colorA=080f12&colorB=1fa669)](https://github.com/OFreshman/ui-utils-kit/blob/main/LICENSE)
1212

1313
---
14+
## 📖changlogs
15+
- 2023-10-01
16+
- 新增 `tree` 模块，提供树形数据操作的工具函数。
17+
- 新增 `business` 模块，提供 DOM 转图片的工具函数。
18+
- 新增 `common` 模块，提供一些常用的业务工具函数。
19+
- 完善文档说明。
1420

1521
## 📌 简介
1622

@@ -22,6 +28,8 @@ ui-utils-kit 是一个高效的偏业务前端工具函数库。
2228
- **海报制作**
2329
将 DOM 元素转换为图片（canvas），支持自动下载或返回 Blob 格式数据。
2430
> 针对跨域图片问题，内置 `html2canvas` proxy 解决方案。
31+
- **业务工具类函数**
32+
提供一些常用的业务工具函数，如 JSON 安全解析、敏感信息脱敏等。
2533

2634
---
2735

@@ -45,12 +53,14 @@ ui-utils-kit 的工具函数分为三大类：`tree`、`business`、`common`，
4553
**方式一：**
4654
```javascript
4755
import { tree } from "ui-utils-kit";
56+
4857
const result = tree.buildTree(nodes);
4958
```
5059

5160
**方式二：**
5261
```javascript
5362
import { buildTree } from "ui-utils-kit";
63+
5464
const result = buildTree(nodes);
5565
```
5666

@@ -83,6 +93,9 @@ const result = buildTree(nodes);
8393

8494
**`tree.treeToArr`** 将树形数据转换为扁平化数组，便于遍历与处理。
8595

96+
- **参数：**
97+
- `tree` (`TreeNode`)：包含 `id` 与 `name`、`children`的树形结构数据。
98+
- `node` (`TreeNode`)：包含 `id` 与 `pid` 的节点数据。
8699
- **示例：**
87100
```typescript
88101
import { treeToArr } from 'ui-utils-kit';
@@ -96,6 +109,8 @@ const result = buildTree(nodes);
96109

97110
**`tree.updateTreeCheckStatus`** 更新树中节点的选中状态（含子节点与父节点联动）。
98111

112+
- **参数：**
113+
- `tree` (`TreeNode`)：包含 `id` 与 `name`、`children`的树形结构数据。
99114
- **示例：**
100115
```typescript
101116
import { updateTreeCheckStatus } from 'ui-utils-kit';
@@ -174,20 +189,8 @@ const result = buildTree(nodes);
174189
175190
### 1. safeJsonParse<T>(jsonString: string, defaultValue: T): [Error \| null, T]
176191
177-
**功能描述：**
178-
安全地解析 JSON 字符串，如果解析出错则返回默认值和错误对象。
192+
**功能描述：** 安全地解析 JSON 字符串，如果解析出错则返回默认值和错误对象。
179193
180-
```typescript
181-
export function safeJsonParse<T>(jsonString: string, defaultValue: T): [Error | null, T] {
182-
try {
183-
const parsed = JSON.parse(jsonString) as T;
184-
return [null, parsed];
185-
} catch (error) {
186-
console.error("JSON 解析错误:", error);
187-
return [error instanceof Error ? error : new Error(String(error)), defaultValue];
188-
}
189-
}
190-
```
191194
**参数**
192195
- `jsonString: string` — 要解析的 JSON 格式字符串。
193196
@@ -198,6 +201,8 @@ export function safeJsonParse<T>(jsonString: string, defaultValue: T): [Error |
198201
199202
- 示例
200203
```typescript
204+
import { safeJsonParse } from 'ui-utils-kit';
205+
201206
const [err, data] = safeJsonParse('{"foo": 42}', { foo: 0 });
202207
if (err) {
203208
// 处理解析错误
@@ -206,54 +211,71 @@ if (err) {
206211
}
207212
```
208213
### 2. desensitize(value: string, type: "mobile" | "idcard"): string
209-
功能描述：对敏感信息（手机号或身份证号）进行脱敏处理，隐藏中间部分。
214+
**功能描述**：对敏感信息（手机号或身份证号）进行脱敏处理，隐藏中间部分。
210215
211216
**参数**
212217
- `value: string` — 原始字符串，如手机号或身份证号。
213-
214218
- `type: "mobile" \| "idcard"` — 数据类型，"mobile" 脱敏手机号，"idcard" 脱敏身份证号。
215219
216220
**返回值**
217221
string — 脱敏后字符串，如果输入非字符串则返回空字符串。
222+
218223
- 示例
219224
```typescript
225+
import { desensitize } from 'ui-utils-kit';
226+
220227
console.log(desensitize('13812345678', 'mobile')); // 输出：138****5678
221228
console.log(desensitize('110105199001011234', 'idcard')); // 输出：110105********1234
222229
```
223230
224231
### 3. Mutex 类
225232
功能描述：模拟互斥锁机制，用于控制异步操作对共享资源的访问，确保同一时刻只有一个操作进入临界区。
226-
- 示例
227-
228-
```typescript
229-
import Mutex from './Mutex';
230-
231-
const mutex = new Mutex();
232-
233-
// 初始状态
234-
console.log('初始状态', mutex.isLocked(), mutex.queueLength()); // 初始状态 false 0
233+
> ##### 以下是一些应用场景
234+
> - 防止按钮重复点击：避免用户多次点击同一按钮导致重复网络请求或状态混乱
235+
> - 强制 API 调用顺序：确保一组异步接口按预期顺序依次执行，防止乱序带来的逻辑错误
236+
> - 多标签页 localStorage 访问：在多个浏览器标签或窗口同时操作同一 localStorage 时，避免数据竞争和丢失
237+
> - 分片上传（Chunked Upload）：在大文件上传时，按顺序上传每个分片，确保断点续传或失败重试时不会错乱
238+
> - Web Worker 任务同步：在主线程与 Worker 线程之间同步访问共享内存（如 SharedArrayBuffer ）时，保证原子性
235239
236-
// 获取锁
237-
await mutex.lock();
238-
console.log('获取锁后', mutex.isLocked(), mutex.queueLength()); // 获取锁后 true 0
239240
240-
// 第二次请求锁，不会立即获取，加入队列
241-
const pending = mutex.lock().then(() => {
242-
console.log('第二次获取锁', mutex.isLocked(), mutex.queueLength());
243-
});
244-
console.log('请求队列长度', mutex.queueLength()); // 请求队列长度 1
245-
246-
// 执行临界区代码
247-
// ...
241+
- 示例
248242
249-
// 释放锁，自动唤醒队列中的下一个请求
250-
mutex.unlock();
251-
console.log('释放锁后', mutex.isLocked(), mutex.queueLength()); // 释放锁后 true 0
243+
```typescript
244+
<template>
245+
<view>
246+
<button @click="onSubmit" :disabled="isSubmitting">
247+
{{ isSubmitting ? '提交中...' : '提交' }}
248+
</button>
249+
</view>
250+
</template>
251+
252+
<script setup lang="ts">
253+
import Mutex from 'ui-utils-kit' // 假设 Mutex 存放在 utils 目录
254+
255+
// 状态变量，无需在 setup 中 return，自动暴露给模板使用
256+
const isSubmitting = ref(false)
257+
// 创建一个互斥锁实例
258+
const submitMutex = new Mutex()
259+
260+
// 点击处理函数
261+
const onSubmit = async () => {
262+
// 获取锁：若已有操作在进行，则挂起后续调用
263+
await submitMutex.lock()
264+
try {
265+
isSubmitting.value = true
266+
// 模拟网络请求
267+
await new Promise<void>(resolve => setTimeout(resolve, 1500))
268+
uni.showToast({ title: '提交成功' })
269+
} catch (err: any) {
270+
uni.showModal({ title: '错误', content: err.message })
271+
} finally {
272+
isSubmitting.value = false
273+
// 释放锁，允许下一次点击
274+
submitMutex.unlock()
275+
}
276+
}
277+
</script>
252278
253-
await pending; // 等待第二个请求获取锁
254-
// 最后释放锁
255-
mutex.unlock();
256-
console.log('全部完成', mutex.isLocked(), mutex.queueLength()); // 全部完成 false 0
257279
```
258280
259281
---

0 commit comments

Comments
 (0)