qy-better-lib 0.0.1

package/packages/core/DOCUMENTATION.md

@@ -0,0 +1,2681 @@
+# QY Better Lib Core - 工具函数文档
+
+本文档详细介绍了 QY Better Lib Core 包中的工具函数，包括功能描述、参数说明、返回类型和使用示例。
+
+## 工具函数分类
+
+### 1. 类型检查工具 (is.ts)
+
+#### is_array
+- **功能**: 检查值是否为数组
+- **参数**: `val: any` - 要检查的值
+- **返回类型**: `boolean` - 是否为数组
+- **示例**:
+  ```typescript
+  import { is_array } from '@qy_better_lib/core';
+  
+  is_array([]); // true
+  is_array({}); // false
+  ```
+
+#### is_object
+- **功能**: 检查值是否为对象
+- **参数**: `val: any` - 要检查的值
+- **返回类型**: `boolean` - 是否为对象
+- **示例**:
+  ```typescript
+  import { is_object } from '@qy_better_lib/core';
+  
+  is_object({}); // true
+  is_object([]); // false
+  ```
+
+#### is_string
+- **功能**: 检查值是否为字符串
+- **参数**: `val: any` - 要检查的值
+- **返回类型**: `boolean` - 是否为字符串
+- **示例**:
+  ```typescript
+  import { is_string } from '@qy_better_lib/core';
+  
+  is_string('hello'); // true
+  is_string(123); // false
+  ```
+
+#### is_number
+- **功能**: 检查值是否为数字
+- **参数**: `val: any` - 要检查的值
+- **返回类型**: `boolean` - 是否为数字
+- **示例**:
+  ```typescript
+  import { is_number } from '@qy_better_lib/core';
+  
+  is_number(123); // true
+  is_number('123'); // false
+  ```
+
+#### is_function
+- **功能**: 检查值是否为函数
+- **参数**: `val: any` - 要检查的值
+- **返回类型**: `boolean` - 是否为函数
+- **示例**:
+  ```typescript
+  import { is_function } from '@qy_better_lib/core';
+  
+  is_function(() => {}); // true
+  is_function({}); // false
+  ```
+
+#### is_boolean
+- **功能**: 检查值是否为布尔值
+- **参数**: `val: any` - 要检查的值
+- **返回类型**: `boolean` - 是否为布尔值
+- **示例**:
+  ```typescript
+  import { is_boolean } from '@qy_better_lib/core';
+  
+  is_boolean(true); // true
+  is_boolean('true'); // false
+  ```
+
+#### is_null
+- **功能**: 检查值是否为 null
+- **参数**: `val: any` - 要检查的值
+- **返回类型**: `boolean` - 是否为 null
+- **示例**:
+  ```typescript
+  import { is_null } from '@qy_better_lib/core';
+  
+  is_null(null); // true
+  is_null(undefined); // false
+  ```
+
+#### is_undefined
+- **功能**: 检查值是否为 undefined
+- **参数**: `val: any` - 要检查的值
+- **返回类型**: `boolean` - 是否为 undefined
+- **示例**:
+  ```typescript
+  import { is_undefined } from '@qy_better_lib/core';
+  
+  is_undefined(undefined); // true
+  is_undefined(null); // false
+  ```
+
+#### is_empty
+- **功能**: 检查值是否为空
+- **参数**: `val: any` - 要检查的值
+- **返回类型**: `boolean` - 是否为空
+- **示例**:
+  ```typescript
+  import { is_empty } from '@qy_better_lib/core';
+  
+  is_empty([]); // true
+  is_empty(''); // true
+  is_empty({}); // true
+  is_empty(null); // true
+  is_empty(undefined); // true
+  is_empty(0); // false
+  ```
+
+#### is_date
+- **功能**: 检查值是否为日期对象
+- **参数**: `val: any` - 要检查的值
+- **返回类型**: `boolean` - 是否为日期对象
+- **示例**:
+  ```typescript
+  import { is_date } from '@qy_better_lib/core';
+  
+  is_date(new Date()); // true
+  is_date('2023-01-01'); // false
+  ```
+
+#### is_reg_exp
+- **功能**: 检查值是否为正则表达式
+- **参数**: `val: any` - 要检查的值
+- **返回类型**: `boolean` - 是否为正则表达式
+- **示例**:
+  ```typescript
+  import { is_reg_exp } from '@qy_better_lib/core';
+  
+  is_reg_exp(/test/); // true
+  is_reg_exp('test'); // false
+  ```
+
+#### is_error
+- **功能**: 检查值是否为错误对象
+- **参数**: `val: any` - 要检查的值
+- **返回类型**: `boolean` - 是否为错误对象
+- **示例**:
+  ```typescript
+  import { is_error } from '@qy_better_lib/core';
+  
+  is_error(new Error('error')); // true
+  is_error('error'); // false
+  ```
+
+#### is_promise
+- **功能**: 检查值是否为 Promise 对象
+- **参数**: `val: any` - 要检查的值
+- **返回类型**: `boolean` - 是否为 Promise 对象
+- **示例**:
+  ```typescript
+  import { is_promise } from '@qy_better_lib/core';
+  
+  is_promise(new Promise(() => {})); // true
+  is_promise({}); // false
+  ```
+
+#### is_element
+- **功能**: 检查值是否为 DOM 元素
+- **参数**: `val: any` - 要检查的值
+- **返回类型**: `boolean` - 是否为 DOM 元素
+- **示例**:
+  ```typescript
+  import { is_element } from '@qy_better_lib/core';
+  
+  is_element(document.createElement('div')); // true
+  is_element({}); // false
+  ```
+
+#### is_plain_object
+- **功能**: 是否为纯粹的对象（排除数组、null等）
+- **参数**: `val: any` - 要检查的值
+- **返回类型**: `boolean` - 是否为纯粹的对象
+- **示例**:
+  ```typescript
+  import { is_plain_object } from '@qy_better_lib/core';
+  
+  is_plain_object({}); // true
+  is_plain_object([]); // false
+  is_plain_object(null); // false
+  ```
+
+#### is_valid_date
+- **功能**: 是否为有效的日期
+- **参数**: `val: any` - 要检查的值
+- **返回类型**: `boolean` - 是否为有效的日期
+- **示例**:
+  ```typescript
+  import { is_valid_date } from '@qy_better_lib/core';
+  
+  is_valid_date(new Date()); // true
+  is_valid_date(new Date('invalid')); // false
+  ```
+
+#### is_truthy
+- **功能**: 是否为真值
+- **参数**: `val: any` - 要检查的值
+- **返回类型**: `boolean` - 是否为真值
+- **示例**:
+  ```typescript
+  import { is_truthy } from '@qy_better_lib/core';
+  
+  is_truthy(1); // true
+  is_truthy('hello'); // true
+  is_truthy(false); // false
+  ```
+
+#### is_falsy
+- **功能**: 是否为假值
+- **参数**: `val: any` - 要检查的值
+- **返回类型**: `boolean` - 是否为假值
+- **示例**:
+  ```typescript
+  import { is_falsy } from '@qy_better_lib/core';
+  
+  is_falsy(false); // true
+  is_falsy(0); // true
+  is_falsy(''); // true
+  is_falsy('hello'); // false
+  ```
+
+#### is_string_number
+- **功能**: 是否为字符串数值
+- **参数**: `val: any` - 要检查的值
+- **返回类型**: `boolean` - 是否为字符串数值
+- **示例**:
+  ```typescript
+  import { is_string_number } from '@qy_better_lib/core';
+  
+  is_string_number('123'); // true
+  is_string_number('abc'); // false
+  ```
+
+#### is_mobile
+- **功能**: 是否为手机号（国内手机号）
+- **参数**: `str: string` - 要检查的字符串
+- **返回类型**: `boolean` - 是否为手机号
+- **示例**:
+  ```typescript
+  import { is_mobile } from '@qy_better_lib/core';
+  
+  is_mobile('13800138000'); // true
+  is_mobile('12345678901'); // false
+  ```
+
+#### is_email
+- **功能**: 是否为邮箱地址
+- **参数**: `str: string` - 要检查的字符串
+- **返回类型**: `boolean` - 是否为邮箱地址
+- **示例**:
+  ```typescript
+  import { is_email } from '@qy_better_lib/core';
+  
+  is_email('test@example.com'); // true
+  is_email('invalid'); // false
+  ```
+
+#### is_url
+- **功能**: 是否为URL地址
+- **参数**: `str: string` - 要检查的字符串
+- **返回类型**: `boolean` - 是否为URL地址
+- **示例**:
+  ```typescript
+  import { is_url } from '@qy_better_lib/core';
+  
+  is_url('https://example.com'); // true
+  is_url('invalid'); // false
+  ```
+
+#### is_hex_color
+- **功能**: 是否为十六进制颜色值
+- **参数**: `str: string` - 要检查的字符串
+- **返回类型**: `boolean` - 是否为十六进制颜色值
+- **示例**:
+  ```typescript
+  import { is_hex_color } from '@qy_better_lib/core';
+  
+  is_hex_color('#ff0000'); // true
+  is_hex_color('#fff'); // true
+  is_hex_color('red'); // false
+  ```
+
+#### is_ip
+- **功能**: 是否为有效IP地址
+- **参数**: `val: string` - 要检查的字符串
+- **返回类型**: `boolean` - 是否为有效IP地址
+- **示例**:
+  ```typescript
+  import { is_ip } from '@qy_better_lib/core';
+  
+  is_ip('192.168.1.1'); // true
+  is_ip('256.0.0.1'); // false
+  ```
+
+#### is_port
+- **功能**: 是否为有效端口
+- **参数**: `val: string` - 要检查的字符串
+- **返回类型**: `boolean` - 是否为有效端口
+- **示例**:
+  ```typescript
+  import { is_port } from '@qy_better_lib/core';
+  
+  is_port('8080'); // true
+  is_port('65536'); // false
+  ```
+
+#### is_client
+- **功能**: 检查是否在客户端环境
+- **返回类型**: `boolean` - 是否在客户端环境
+- **示例**:
+  ```typescript
+  import { is_client } from '@qy_better_lib/core';
+  
+  if (is_client) {
+    // 客户端环境代码
+  }
+  ```
+
+#### is_server
+- **功能**: 检查是否在服务端环境
+- **返回类型**: `boolean` - 是否在服务端环境
+- **示例**:
+  ```typescript
+  import { is_server } from '@qy_better_lib/core';
+  
+  if (is_server) {
+    // 服务端环境代码
+  }
+  ```
+
+### 2. 数字处理工具 (number.ts)
+
+#### format_currency
+- **功能**: 格式化货币
+- **参数**:
+  - `value: number` - 要格式化的数值
+  - `currency: string` - 货币符号，默认 '¥'
+  - `decimals: number` - 小数位数，默认 2
+  - `decimalSeparator: string` - 小数分隔符，默认 '.'
+  - `thousandSeparator: string` - 千位分隔符，默认 ','
+- **返回类型**: `string` - 格式化后的货币字符串
+- **示例**:
+  ```typescript
+  import { format_currency } from '@qy_better_lib/core';
+  
+  format_currency(1234.56); // ¥1,234.56
+  format_currency(1234.56, '$'); // $1,234.56
+  ```
+
+#### format_number
+- **功能**: 格式化数字
+- **参数**:
+  - `value: number` - 要格式化的数值
+  - `decimals: number` - 小数位数，默认 0
+  - `decimalSeparator: string` - 小数分隔符，默认 '.'
+  - `thousandSeparator: string` - 千位分隔符，默认 ','
+- **返回类型**: `string` - 格式化后的数字字符串
+- **示例**:
+  ```typescript
+  import { format_number } from '@qy_better_lib/core';
+  
+  format_number(1234.56, 2); // 1,234.56
+  format_number(1234, 0); // 1,234
+  ```
+
+#### to_percentage
+- **功能**: 将数字转换为百分比
+- **参数**:
+  - `value: number` - 要转换的数值
+  - `decimals: number` - 小数位数，默认 2
+  - `multiply: boolean` - 是否乘以 100，默认 true
+- **返回类型**: `string` - 格式化后的百分比字符串
+- **示例**:
+  ```typescript
+  import { to_percentage } from '@qy_better_lib/core';
+  
+  to_percentage(0.1234); // 12.34%
+  to_percentage(12.34, 1, false); // 12.3%
+  ```
+
+#### clamp
+- **功能**: 限制数字在指定范围内
+- **参数**:
+  - `value: number` - 要限制的值
+  - `min: number` - 最小值
+  - `max: number` - 最大值
+- **返回类型**: `number` - 限制后的值
+- **示例**:
+  ```typescript
+  import { clamp } from '@qy_better_lib/core';
+  
+  clamp(5, 0, 10); // 5
+  clamp(-5, 0, 10); // 0
+  clamp(15, 0, 10); // 10
+  ```
+
+#### is_even
+- **功能**: 检查数字是否为偶数
+- **参数**: `value: number` - 要检查的数字
+- **返回类型**: `boolean` - 是否为偶数
+- **示例**:
+  ```typescript
+  import { is_even } from '@qy_better_lib/core';
+  
+  is_even(2); // true
+  is_even(3); // false
+  ```
+
+#### is_odd
+- **功能**: 检查数字是否为奇数
+- **参数**: `value: number` - 要检查的数字
+- **返回类型**: `boolean` - 是否为奇数
+- **示例**:
+  ```typescript
+  import { is_odd } from '@qy_better_lib/core';
+  
+  is_odd(3); // true
+  is_odd(2); // false
+  ```
+
+#### get_integer_part
+- **功能**: 获取数字的整数部分
+- **参数**: `value: number` - 要处理的数字
+- **返回类型**: `number` - 整数部分
+- **示例**:
+  ```typescript
+  import { get_integer_part } from '@qy_better_lib/core';
+  
+  get_integer_part(123.45); // 123
+  get_integer_part(-123.45); // -123
+  ```
+
+#### get_decimal_part
+- **功能**: 获取数字的小数部分
+- **参数**: `value: number` - 要处理的数字
+- **返回类型**: `number` - 小数部分
+- **示例**:
+  ```typescript
+  import { get_decimal_part } from '@qy_better_lib/core';
+  
+  get_decimal_part(123.45); // 0.45
+  get_decimal_part(-123.45); // 0.45
+  ```
+
+#### round
+- **功能**: 四舍五入数字
+- **参数**:
+  - `value: number` - 要四舍五入的数字
+  - `decimals: number` - 小数位数，默认 0
+- **返回类型**: `number` - 四舍五入后的数字
+- **示例**:
+  ```typescript
+  import { round } from '@qy_better_lib/core';
+  
+  round(123.45); // 123
+  round(123.45, 1); // 123.5
+  ```
+
+#### ceil
+- **功能**: 向上取整数字
+- **参数**: `value: number` - 要向上取整的数字
+- **返回类型**: `number` - 向上取整后的数字
+- **示例**:
+  ```typescript
+  import { ceil } from '@qy_better_lib/core';
+  
+  ceil(123.1); // 124
+  ceil(-123.9); // -123
+  ```
+
+#### floor
+- **功能**: 向下取整数字
+- **参数**: `value: number` - 要向下取整的数字
+- **返回类型**: `number` - 向下取整后的数字
+- **示例**:
+  ```typescript
+  import { floor } from '@qy_better_lib/core';
+  
+  floor(123.9); // 123
+  floor(-123.1); // -124
+  ```
+
+#### thousand_separator
+- **功能**: 数字转成千分位
+- **参数**: `num: any` - 数字或数字字符串
+- **返回类型**: `string` - 千分位格式的字符串
+- **示例**:
+  ```typescript
+  import { thousand_separator } from '@qy_better_lib/core';
+  
+  thousand_separator(1234567); // "1,234,567"
+  thousand_separator('1234567'); // "1,234,567"
+  ```
+
+#### to_number
+- **功能**: 转换成数值
+- **参数**: `num: any` - 源
+- **返回类型**: `number` - 转换后的数值
+- **示例**:
+  ```typescript
+  import { to_number } from '@qy_better_lib/core';
+  
+  to_number(123); // 123
+  to_number('123'); // 123
+  to_number('invalid'); // NaN
+  ```
+
+#### to_fixed
+- **功能**: 保留小数点
+- **参数**:
+  - `num: any` - 数字或数字字符串
+  - `fixed: number` - 小数位数
+- **返回类型**: `number` - 保留小数点后的数值
+- **示例**:
+  ```typescript
+  import { to_fixed } from '@qy_better_lib/core';
+  
+  to_fixed(123.456, 2); // 123.46
+  to_fixed('123.456', 1); // 123.5
+  ```
+
+#### calculate_percentage
+- **功能**: 计算百分比
+- **参数**:
+  - `current: number` - 当前值
+  - `total: number` - 总值
+  - `fixed: number` - 小数位数，默认 2
+- **返回类型**: `number` - 百分比值
+- **示例**:
+  ```typescript
+  import { calculate_percentage } from '@qy_better_lib/core';
+  
+  calculate_percentage(50, 200); // 25
+  calculate_percentage(25, 100, 1); // 25
+  ```
+
+### 3. 日期时间工具 (date.ts)
+
+> 注意：日期时间工具现在是可选依赖，需要单独导入
+
+#### format_date
+- **功能**: 格式化日期时间
+- **参数**:
+  - `date: Date | string | number` - 日期时间对象或字符串
+  - `format: string` - 格式化模板，默认 "YYYY-MM-DD HH:mm:ss"
+- **返回类型**: `string` - 格式化后的日期时间字符串
+- **示例**:
+  ```typescript
+  import { format_date } from '@qy_better_lib/core/date';
+  
+  format_date(new Date()); // 2023-12-31 23:59:59
+  format_date(new Date(), 'YYYY-MM-DD'); // 2023-12-31
+  ```
+
+#### get_date_time_range
+- **功能**: 根据当前时间获取指定类型的时间范围
+- **参数**:
+  - `type: DateRangeType` - 范围类型 ('d' | 'w' | 'M' | 'Q' | 'y' | 'h' | 'm' | 's')
+  - `increment: number` - 增量，默认 -1
+  - `format: string` - 日期时间显示格式，默认 "YYYY-MM-DD HH:mm:ss"
+  - `span: boolean` - 是否跨越范围类型，默认 false
+- **返回类型**: `[string, string]` - [开始日期时间, 截止日期时间]
+- **示例**:
+  ```typescript
+  import { get_date_time_range } from '@qy_better_lib/core/date';
+  
+  // 获取昨天的时间范围
+  const [start, end] = get_date_time_range('d', -1);
+  console.log(start, end); // 2023-12-30 00:00:00 2023-12-31 23:59:59
+  ```
+
+#### get_date_diff
+- **功能**: 计算两个日期之间的时间差
+- **参数**:
+  - `date1: Date | string | number` - 第一个日期
+  - `date2: Date | string | number` - 第二个日期
+  - `unit: string` - 时间单位，默认 "day"
+- **返回类型**: `number` - 时间差
+- **示例**:
+  ```typescript
+  import { get_date_diff } from '@qy_better_lib/core/date';
+  
+  const date1 = '2023-12-31';
+  const date2 = '2023-12-25';
+  get_date_diff(date1, date2); // 6
+  ```
+
+#### add_date
+- **功能**: 添加时间
+- **参数**:
+  - `date: Date | string | number` - 基础日期
+  - `value: number` - 增加的值
+  - `unit: string` - 时间单位
+  - `format: string` - 格式化模板，默认不格式化
+- **返回类型**: `Date | string` - 增加后的日期或格式化后的字符串
+- **示例**:
+  ```typescript
+  import { add_date } from '@qy_better_lib/core/date';
+  
+  // 添加7天
+  add_date(new Date(), 7, 'day'); // 7天后的日期对象
+  add_date(new Date(), 7, 'day', 'YYYY-MM-DD'); // 格式化后的日期字符串
+  ```
+
+#### subtract_date
+- **功能**: 减去时间
+- **参数**:
+  - `date: Date | string | number` - 基础日期
+  - `value: number` - 减少的值
+  - `unit: string` - 时间单位
+  - `format: string` - 格式化模板，默认不格式化
+- **返回类型**: `Date | string` - 减少后的日期或格式化后的字符串
+- **示例**:
+  ```typescript
+  import { subtract_date } from '@qy_better_lib/core/date';
+  
+  // 减去7天
+  subtract_date(new Date(), 7, 'day'); // 7天前的日期对象
+  subtract_date(new Date(), 7, 'day', 'YYYY-MM-DD'); // 格式化后的日期字符串
+  ```
+
+#### is_weekday
+- **功能**: 判断是否为工作日
+- **参数**: `date: Date | string | number` - 日期
+- **返回类型**: `boolean` - 是否为工作日
+- **示例**:
+  ```typescript
+  import { is_weekday } from '@qy_better_lib/core/date';
+  
+  is_weekday('2023-12-31'); // true (周日)
+  is_weekday('2024-01-01'); // false (周一)
+  ```
+
+#### is_weekend
+- **功能**: 判断是否为周末
+- **参数**: `date: Date | string | number` - 日期
+- **返回类型**: `boolean` - 是否为周末
+- **示例**:
+  ```typescript
+  import { is_weekend } from '@qy_better_lib/core/date';
+  
+  is_weekend('2023-12-30'); // true (周六)
+  is_weekend('2023-12-29'); // false (周五)
+  ```
+
+#### get_relative_time
+- **功能**: 获取相对时间描述
+- **参数**: `date: Date | string | number` - 日期
+- **返回类型**: `string` - 相对时间描述
+- **示例**:
+  ```typescript
+  import { get_relative_time } from '@qy_better_lib/core/date';
+  
+  // 假设当前时间是2023-12-31
+  get_relative_time('2023-12-31 23:50:00'); // 刚刚
+  get_relative_time('2023-12-31 22:00:00'); // 1小时前
+  ```
+
+#### format_timestamp_diff
+- **功能**: 将时间戳差值转换成可读格式
+- **参数**:
+  - `timestamp_diff: number` - 时间戳差值（毫秒）
+  - `format: TimeDiffFormatType` - 格式类型，默认 'zh'
+- **返回类型**: `string` - 格式化后的时间差字符串
+- **示例**:
+  ```typescript
+  import { format_timestamp_diff } from '@qy_better_lib/core/date';
+  
+  // 1天2小时3分钟4秒
+  const diff = 1 * 24 * 60 * 60 * 1000 + 2 * 60 * 60 * 1000 + 3 * 60 * 1000 + 4 * 1000;
+  format_timestamp_diff(diff); // 1天2时3分4秒
+  format_timestamp_diff(diff, 'en'); // 1D2H3M4S
+  ```
+
+### 4. 对象操作工具 (object.ts)
+
+#### deep_clone
+- **功能**: 深拷贝对象
+- **参数**: `obj: any` - 要拷贝的对象
+- **返回类型**: `any` - 拷贝后的新对象
+- **示例**:
+  ```typescript
+  import { deep_clone } from '@qy_better_lib/core';
+  
+  const obj = { a: 1, b: { c: 2 } };
+  const cloned = deep_clone(obj);
+  cloned.b.c = 3;
+  console.log(obj.b.c); // 2
+  ```
+
+#### deep_assign
+- **功能**: 深度合并多个对象
+- **参数**: `...args: any[]` - 要合并的对象列表
+- **返回类型**: `any` - 合并后的对象
+- **示例**:
+  ```typescript
+  import { deep_assign } from '@qy_better_lib/core';
+  
+  const obj1 = { a: 1, b: { c: 2 } };
+  const obj2 = { b: { d: 3 }, e: 4 };
+  const merged = deep_assign(obj1, obj2);
+  console.log(merged); // { a: 1, b: { c: 2, d: 3 }, e: 4 }
+  ```
+
+#### deep_equal
+- **功能**: 深度比较两个对象值是否一致
+- **参数**:
+  - `a: any` - 第一个对象
+  - `b: any` - 第二个对象
+- **返回类型**: `boolean` - 是否相等
+- **示例**:
+  ```typescript
+  import { deep_equal } from '@qy_better_lib/core';
+  
+  const obj1 = { a: 1, b: { c: 2 } };
+  const obj2 = { a: 1, b: { c: 2 } };
+  const obj3 = { a: 1, b: { c: 3 } };
+  
+  deep_equal(obj1, obj2); // true
+  deep_equal(obj1, obj3); // false
+  ```
+
+#### is_empty_object
+- **功能**: 检查对象是否为空
+- **参数**: `obj: any` - 要检查的对象
+- **返回类型**: `boolean` - 是否为空对象
+- **示例**:
+  ```typescript
+  import { is_empty_object } from '@qy_better_lib/core';
+  
+  is_empty_object({}); // true
+  is_empty_object({ a: 1 }); // false
+  ```
+
+#### pick
+- **功能**: 从对象中提取指定属性
+- **参数**:
+  - `obj: any` - 源对象
+  - `keys: string[]` - 要提取的属性名数组
+- **返回类型**: `Record<string, any>` - 提取后的新对象
+- **示例**:
+  ```typescript
+  import { pick } from '@qy_better_lib/core';
+  
+  const obj = { a: 1, b: 2, c: 3 };
+  const picked = pick(obj, ['a', 'c']);
+  console.log(picked); // { a: 1, c: 3 }
+  ```
+
+#### omit
+- **功能**: 从对象中排除指定属性
+- **参数**:
+  - `obj: any` - 源对象
+  - `keys: string[]` - 要排除的属性名数组
+- **返回类型**: `Record<string, any>` - 排除后的新对象
+- **示例**:
+  ```typescript
+  import { omit } from '@qy_better_lib/core';
+  
+  const obj = { a: 1, b: 2, c: 3 };
+  const omitted = omit(obj, ['b']);
+  console.log(omitted); // { a: 1, c: 3 }
+  ```
+
+#### flatten_object
+- **功能**: 将嵌套对象扁平化为一维对象
+- **参数**:
+  - `obj: any` - 源对象
+  - `prefix: string` - 前缀，默认 ''
+- **返回类型**: `Record<string, any>` - 扁平化后的对象
+- **示例**:
+  ```typescript
+  import { flatten_object } from '@qy_better_lib/core';
+  
+  const obj = { a: 1, b: { c: 2, d: { e: 3 } } };
+  const flattened = flatten_object(obj);
+  console.log(flattened); // { a: 1, 'b.c': 2, 'b.d.e': 3 }
+  ```
+
+#### unflatten_object
+- **功能**: 将扁平对象转换为嵌套对象
+- **参数**: `obj: any` - 扁平对象
+- **返回类型**: `Record<string, any>` - 嵌套对象
+- **示例**:
+  ```typescript
+  import { unflatten_object } from '@qy_better_lib/core';
+  
+  const obj = { a: 1, 'b.c': 2, 'b.d.e': 3 };
+  const unflattened = unflatten_object(obj);
+  console.log(unflattened); // { a: 1, b: { c: 2, d: { e: 3 } } }
+  ```
+
+#### get_object_value
+- **功能**: 根据路径获取对象值
+- **参数**:
+  - `obj: any` - 源对象
+  - `path: string` - 路径字符串，如 "a.b.c"
+  - `defaultValue: any` - 默认值，默认 undefined
+- **返回类型**: `any` - 获取的值或默认值
+- **示例**:
+  ```typescript
+  import { get_object_value } from '@qy_better_lib/core';
+  
+  const obj = { a: 1, b: { c: 2, d: { e: 3 } } };
+  get_object_value(obj, 'a'); // 1
+  get_object_value(obj, 'b.c'); // 2
+  get_object_value(obj, 'b.d.e'); // 3
+  get_object_value(obj, 'b.f', 'default'); // 'default'
+  ```
+
+#### set_object_value
+- **功能**: 根据路径设置对象值
+- **参数**:
+  - `obj: any` - 源对象
+  - `path: string` - 路径字符串，如 "a.b.c"
+  - `value: any` - 要设置的值
+- **返回类型**: `Record<string, any>` - 修改后的对象
+- **示例**:
+  ```typescript
+  import { set_object_value } from '@qy_better_lib/core';
+  
+  const obj = { a: 1, b: { c: 2 } };
+  set_object_value(obj, 'b.d.e', 3);
+  console.log(obj); // { a: 1, b: { c: 2, d: { e: 3 } } }
+  ```
+
+#### merge_objects
+- **功能**: 浅合并多个对象
+- **参数**: `...args: any[]` - 要合并的对象列表
+- **返回类型**: `Record<string, any>` - 合并后的对象
+- **示例**:
+  ```typescript
+  import { merge_objects } from '@qy_better_lib/core';
+  
+  const obj1 = { a: 1, b: 2 };
+  const obj2 = { b: 3, c: 4 };
+  const merged = merge_objects(obj1, obj2);
+  console.log(merged); // { a: 1, b: 3, c: 4 }
+  ```
+
+#### diff_objects
+- **功能**: 比较两个对象的差异
+- **参数**:
+  - `obj1: any` - 第一个对象
+  - `obj2: any` - 第二个对象
+- **返回类型**: `Record<string, any>` - 差异对象
+- **示例**:
+  ```typescript
+  import { diff_objects } from '@qy_better_lib/core';
+  
+  const obj1 = { a: 1, b: 2, c: 3 };
+  const obj2 = { a: 1, b: 4, d: 5 };
+  const diff = diff_objects(obj1, obj2);
+  console.log(diff); // { b: { oldValue: 2, newValue: 4 }, c: { oldValue: 3, newValue: undefined }, d: { oldValue: undefined, newValue: 5 } }
+  ```
+
+### 5. 随机值生成工具 (random.ts)
+
+#### random_id
+- **功能**: 生成[0-10000]的随机数,针对数据小量使用
+- **返回类型**: `number` - 随机数
+- **示例**:
+  ```typescript
+  import { random_id } from '@qy_better_lib/core';
+  
+  random_id(); // 生成0-10000之间的随机数
+  ```
+
+#### random_int
+- **功能**: 生成[0-max]的随机数
+- **参数**: `max: number` - 最大值
+- **返回类型**: `number` - 随机数
+- **示例**:
+  ```typescript
+  import { random_int } from '@qy_better_lib/core';
+  
+  random_int(10); // 生成0-10之间的随机整数
+  ```
+
+#### random_int_range
+- **功能**: 生成指定范围的随机整数
+- **参数**:
+  - `min: number` - 最小值
+  - `max: number` - 最大值
+- **返回类型**: `number` - 随机整数
+- **示例**:
+  ```typescript
+  import { random_int_range } from '@qy_better_lib/core';
+  
+  random_int_range(1, 10); // 生成1-10之间的随机整数
+  ```
+
+#### random_float
+- **功能**: 生成随机浮点数
+- **参数**:
+  - `min: number` - 最小值
+  - `max: number` - 最大值
+  - `decimalPlaces: number` - 小数位数，默认 2
+- **返回类型**: `number` - 随机浮点数
+- **示例**:
+  ```typescript
+  import { random_float } from '@qy_better_lib/core';
+  
+  random_float(1, 10, 2); // 生成1-10之间的随机小数，保留2位小数
+  ```
+
+#### guid
+- **功能**: 生成GUID/UUID
+- **返回类型**: `string` - GUID/UUID字符串
+- **示例**:
+  ```typescript
+  import { guid } from '@qy_better_lib/core';
+  
+  guid(); // 生成一个随机GUID/UUID
+  ```
+
+#### random_string
+- **功能**: 生成随机字符串
+- **返回类型**: `string` - 随机字符串
+- **示例**:
+  ```typescript
+  import { random_string } from '@qy_better_lib/core';
+  
+  random_string(); // 生成一个随机字符串
+  ```
+
+#### random_len_string
+- **功能**: 生成指定长度的随机字符串
+- **参数**:
+  - `length: number` - 字符串长度
+  - `chars: string` - 可选字符集，默认包含大小写字母和数字
+- **返回类型**: `string` - 随机字符串
+- **示例**:
+  ```typescript
+  import { random_len_string } from '@qy_better_lib/core';
+  
+  random_len_string(10); // 生成10位随机字符串
+  random_len_string(8, 'ABCDEFG'); // 生成8位只包含指定字符的随机字符串
+  ```
+
+#### random_boolean
+- **功能**: 生成随机布尔值
+- **返回类型**: `boolean` - 随机布尔值
+- **示例**:
+  ```typescript
+  import { random_boolean } from '@qy_better_lib/core';
+  
+  random_boolean(); // 50%概率为true
+  ```
+
+#### random_element
+- **功能**: 从数组中随机选择一个元素
+- **参数**: `array: T[]` - 源数组
+- **返回类型**: `T | undefined` - 随机选中的元素
+- **示例**:
+  ```typescript
+  import { random_element } from '@qy_better_lib/core';
+  
+  const array = ['a', 'b', 'c', 'd'];
+  random_element(array); // 随机返回数组中的一个元素
+  ```
+
+#### random_elements
+- **功能**: 从数组中随机选择多个元素
+- **参数**:
+  - `array: T[]` - 源数组
+  - `count: number` - 选择数量
+- **返回类型**: `T[]` - 随机选中的元素数组
+- **示例**:
+  ```typescript
+  import { random_elements } from '@qy_better_lib/core';
+  
+  const array = ['a', 'b', 'c', 'd'];
+  random_elements(array, 2); // 随机返回数组中的2个元素
+  ```
+
+#### random_color
+- **功能**: 生成随机颜色
+- **返回类型**: `string` - 随机颜色的十六进制值
+- **示例**:
+  ```typescript
+  import { random_color } from '@qy_better_lib/core';
+  
+  random_color(); // 生成一个随机十六进制颜色
+  ```
+
+#### random_number_string
+- **功能**: 生成指定长度的随机数字字符串
+- **参数**: `length: number` - 字符串长度
+- **返回类型**: `string` - 随机数字字符串
+- **示例**:
+  ```typescript
+  import { random_number_string } from '@qy_better_lib/core';
+  
+  random_number_string(6); // 生成6位随机数字字符串
+  ```
+
+#### random_password
+- **功能**: 生成随机密码
+- **参数**: `length: number` - 密码长度，默认 8
+- **返回类型**: `string` - 随机密码
+- **示例**:
+  ```typescript
+  import { random_password } from '@qy_better_lib/core';
+  
+  random_password(); // 生成8位随机密码
+  random_password(12); // 生成12位随机密码
+  ```
+
+#### random_phone
+- **功能**: 生成随机手机号
+- **返回类型**: `string` - 随机手机号
+- **示例**:
+  ```typescript
+  import { random_phone } from '@qy_better_lib/core';
+  
+  random_phone(); // 生成一个随机手机号
+  ```
+
+#### random_email
+- **功能**: 生成随机邮箱
+- **返回类型**: `string` - 随机邮箱
+- **示例**:
+  ```typescript
+  import { random_email } from '@qy_better_lib/core';
+  
+  random_email(); // 生成一个随机邮箱
+  ```
+
+#### random_url
+- **功能**: 生成随机URL
+- **返回类型**: `string` - 随机URL
+- **示例**:
+  ```typescript
+  import { random_url } from '@qy_better_lib/core';
+  
+  random_url(); // 生成一个随机URL
+  ```
+
+#### shuffle_array
+- **功能**: 打乱数组顺序
+- **参数**: `array: T[]` - 源数组
+- **返回类型**: `T[]` - 打乱后的新数组
+- **示例**:
+  ```typescript
+  import { shuffle_array } from '@qy_better_lib/core';
+  
+  const array = [1, 2, 3, 4, 5];
+  const shuffled = shuffle_array(array); // 打乱数组顺序
+  ```
+
+### 6. 函数工具 (share.ts)
+
+#### debounce
+- **功能**: 防抖函数
+- **参数**:
+  - `fn: Function` - 要执行的函数
+  - `delay: number` - 延迟时间，默认 200ms
+  - `immediate: boolean` - 是否立即执行，默认 false
+- **返回类型**: `Function` - 防抖处理后的函数
+- **示例**:
+  ```typescript
+  import { debounce } from '@qy_better_lib/core';
+  
+  // 防抖处理的搜索函数
+  const debouncedSearch = debounce((keyword) => {
+    console.log('搜索:', keyword);
+  }, 300);
+  
+  // 频繁调用时，只会在最后一次调用后300ms执行
+  debouncedSearch('关键词1');
+  debouncedSearch('关键词2');
+  debouncedSearch('关键词3'); // 只有这次会执行
+  ```
+
+#### throttle
+- **功能**: 节流函数
+- **参数**:
+  - `fn: Function` - 要执行的函数
+  - `interval: number` - 时间间隔，默认 200ms
+  - `options: object` - 配置选项
+- **返回类型**: `Function` - 节流处理后的函数
+- **示例**:
+  ```typescript
+  import { throttle } from '@qy_better_lib/core';
+  
+  // 节流处理的滚动函数
+  const throttledScroll = throttle(() => {
+    console.log('滚动事件');
+  }, 100);
+  
+  // 滚动时，每100ms执行一次
+  window.addEventListener('scroll', throttledScroll);
+  ```
+
+#### curry
+- **功能**: 柯里化函数
+- **参数**: `fn: Function` - 要柯里化的函数
+- **返回类型**: `Function` - 柯里化后的函数
+- **示例**:
+  ```typescript
+  import { curry } from '@qy_better_lib/core';
+  
+  const add = (a, b, c) => a + b + c;
+  const curriedAdd = curry(add);
+  
+  curriedAdd(1)(2)(3); // 6
+  curriedAdd(1, 2)(3); // 6
+  curriedAdd(1)(2, 3); // 6
+  ```
+
+#### compose
+- **功能**: 函数组合
+- **参数**: `...fns: Function[]` - 要组合的函数列表
+- **返回类型**: `Function` - 组合后的函数
+- **示例**:
+  ```typescript
+  import { compose } from '@qy_better_lib/core';
+  
+  const add1 = x => x + 1;
+  const multiply2 = x => x * 2;
+  const subtract3 = x => x - 3;
+  
+  const composed = compose(subtract3, multiply2, add1);
+  composed(5); // ((5 + 1) * 2) - 3 = 9
+  ```
+
+#### pipe
+- **功能**: 管道函数
+- **参数**: `...fns: Function[]` - 要管道的函数列表
+- **返回类型**: `Function` - 管道后的函数
+- **示例**:
+  ```typescript
+  import { pipe } from '@qy_better_lib/core';
+  
+  const add1 = x => x + 1;
+  const multiply2 = x => x * 2;
+  const subtract3 = x => x - 3;
+  
+  const piped = pipe(add1, multiply2, subtract3);
+  piped(5); // ((5 + 1) * 2) - 3 = 9
+  ```
+
+#### delay_execution
+- **功能**: 延迟执行函数
+- **参数**:
+  - `fn: Function` - 要执行的函数
+  - `delay: number` - 延迟时间，默认 1000ms
+- **返回类型**: `Promise<any>` - 执行结果的Promise
+- **示例**:
+  ```typescript
+  import { delay_execution } from '@qy_better_lib/core';
+  
+  async function example() {
+    console.log('开始');
+    await delay_execution(() => {
+      console.log('延迟执行');
+    }, 2000);
+    console.log('结束');
+  }
+  
+  example(); // 开始 -> 2秒后 -> 延迟执行 -> 结束
+  ```
+
+#### retry
+- **功能**: 重试函数
+- **参数**:
+  - `fn: Function` - 要执行的函数
+  - `options: object` - 配置选项
+- **返回类型**: `Promise<any>` - 执行结果的Promise
+- **示例**:
+  ```typescript
+  import { retry } from '@qy_better_lib/core';
+  
+  async function example() {
+    const result = await retry(async () => {
+      // 可能会失败的操作
+      if (Math.random() > 0.5) {
+        throw new Error('失败');
+      }
+      return '成功';
+    }, {
+      maxAttempts: 3,
+      delay: 1000
+    });
+    console.log(result);
+  }
+  
+  example();
+  ```
+
+#### once
+- **功能**: 一次性函数
+- **参数**: `fn: Function` - 要执行的函数
+- **返回类型**: `Function` - 一次性函数
+- **示例**:
+  ```typescript
+  import { once } from '@qy_better_lib/core';
+  
+  const initialize = once(() => {
+    console.log('初始化');
+    return '初始化完成';
+  });
+  
+  initialize(); // 初始化
+  initialize(); // 无输出
+  initialize(); // 无输出
+  ```
+
+#### memoize
+- **功能**: 记忆化函数
+- **参数**:
+  - `fn: Function` - 要记忆化的函数
+  - `keyGenerator: Function` - 缓存键生成函数
+- **返回类型**: `Function` - 记忆化后的函数
+- **示例**:
+  ```typescript
+  import { memoize } from '@qy_better_lib/core';
+  
+  // 记忆化的计算函数
+  const memoizedCalculate = memoize((a, b) => {
+    console.log('计算中...');
+    return a + b;
+  });
+  
+  console.log(memoizedCalculate(1, 2)); // 计算中... 3
+  console.log(memoizedCalculate(1, 2)); // 直接返回缓存结果 3
+  console.log(memoizedCalculate(2, 3)); // 计算中... 5
+  ```
+
+#### batch_execution
+- **功能**: 批量执行函数
+- **参数**:
+  - `fns: Function[]` - 要执行的函数数组
+  - `parallel: boolean` - 是否并行执行，默认 true
+- **返回类型**: `Promise<any[]>` - 执行结果的Promise数组
+- **示例**:
+  ```typescript
+  import { batch_execution } from '@qy_better_lib/core';
+  
+  async function example() {
+    const fns = [
+      () => Promise.resolve(1),
+      () => Promise.resolve(2),
+      () => Promise.resolve(3)
+    ];
+    
+    const results = await batch_execution(fns);
+    console.log(results); // [1, 2, 3]
+  }
+  
+  example();
+  ```
+
+#### timeout
+- **功能**: 超时控制函数
+- **参数**:
+  - `fn: Function` - 要执行的函数
+  - `timeout: number` - 超时时间，默认 3000ms
+  - `message: string` - 超时消息，默认 '操作超时'
+- **返回类型**: `Promise<any>` - 执行结果的Promise
+- **示例**:
+  ```typescript
+  import { timeout } from '@qy_better_lib/core';
+  
+  async function example() {
+    try {
+      const result = await timeout(async () => {
+        // 模拟长时间操作
+        await new Promise(resolve => setTimeout(resolve, 5000));
+        return '成功';
+      }, 3000);
+      console.log(result);
+    } catch (error) {
+      console.log(error.message); // 操作超时
+    }
+  }
+  
+  example();
+  ```
+
+### 7. 存储工具 (storage.ts)
+
+#### get_token
+- **功能**: 获取用户token,包含过期时间判断
+- **返回类型**: `any | null` - token值或null
+- **示例**:
+  ```typescript
+  import { get_token } from '@qy_better_lib/core';
+  
+  const token = get_token();
+  console.log(token);
+  ```
+
+#### set_token
+- **功能**: 设置用户token,有效期默认七天
+- **参数**:
+  - `value: any` - token值
+  - `expires: number` - 过期时间（秒），默认7天
+- **示例**:
+  ```typescript
+  import { set_token } from '@qy_better_lib/core';
+  
+  set_token('abc123'); // 默认7天过期
+  set_token('abc123', 3600); // 1小时过期
+  ```
+
+#### remove_token
+- **功能**: 移除token
+- **示例**:
+  ```typescript
+  import { remove_token } from '@qy_better_lib/core';
+  
+  remove_token();
+  ```
+
+#### set_storage
+- **功能**: 设置缓存
+- **参数**:
+  - `key: string` - 缓存键
+  - `value: any` - 缓存值
+  - `type: 'local' | 'session'` - 存储类型，默认'local'
+- **示例**:
+  ```typescript
+  import { set_storage } from '@qy_better_lib/core';
+  
+  // 设置localStorage
+  set_storage('user', { name: '张三', age: 20 });
+  
+  // 设置sessionStorage
+  set_storage('token', 'abc123', 'session');
+  ```
+
+#### get_storage
+- **功能**: 获取缓存
+- **参数**:
+  - `key: string` - 缓存键
+  - `type: 'local' | 'session'` - 存储类型，默认'local'
+- **返回类型**: `any` - 缓存值或null
+- **示例**:
+  ```typescript
+  import { get_storage } from '@qy_better_lib/core';
+  
+  // 获取localStorage
+  const user = get_storage('user');
+  console.log(user); // { name: '张三', age: 20 }
+  
+  // 获取sessionStorage
+  const token = get_storage('token', 'session');
+  console.log(token); // 'abc123'
+  ```
+
+#### remove_storage
+- **功能**: 删除指定key的缓存
+- **参数**:
+  - `key: string` - 缓存键
+  - `type: 'local' | 'session'` - 存储类型，默认'local'
+- **示例**:
+  ```typescript
+  import { remove_storage } from '@qy_better_lib/core';
+  
+  // 移除localStorage
+  remove_storage('user');
+  
+  // 移除sessionStorage
+  remove_storage('token', 'session');
+  ```
+
+#### clear_storage
+- **功能**: 清除所有缓存
+- **参数**: `type: 'local' | 'session'` - 存储类型，默认'local'
+- **示例**:
+  ```typescript
+  import { clear_storage } from '@qy_better_lib/core';
+  
+  // 清空localStorage
+  clear_storage();
+  
+  // 清空sessionStorage
+  clear_storage('session');
+  ```
+
+#### set_storage_with_expiry
+- **功能**: 设置带过期时间的缓存
+- **参数**:
+  - `key: string` - 缓存键
+  - `value: any` - 缓存值
+  - `expiry: number` - 过期时间（秒）
+  - `type: 'local' | 'session'` - 存储类型，默认'local'
+- **示例**:
+  ```typescript
+  import { set_storage_with_expiry } from '@qy_better_lib/core';
+  
+  // 设置1小时过期的缓存
+  set_storage_with_expiry('user', { name: '张三', age: 20 }, 3600);
+  ```
+
+#### get_storage_with_expiry
+- **功能**: 获取带过期时间的缓存
+- **参数**:
+  - `key: string` - 缓存键
+  - `type: 'local' | 'session'` - 存储类型，默认'local'
+- **返回类型**: `any` - 缓存值或null
+- **示例**:
+  ```typescript
+  import { get_storage_with_expiry } from '@qy_better_lib/core';
+  
+  const user = get_storage_with_expiry('user');
+  console.log(user);
+  ```
+
+#### has_storage
+- **功能**: 检查缓存是否存在
+- **参数**:
+  - `key: string` - 缓存键
+  - `type: 'local' | 'session'` - 存储类型，默认'local'
+- **返回类型**: `boolean` - 是否存在
+- **示例**:
+  ```typescript
+  import { has_storage } from '@qy_better_lib/core';
+  
+  const hasUser = has_storage('user');
+  console.log(hasUser);
+  ```
+
+#### get_all_storage_keys
+- **功能**: 获取所有缓存键
+- **参数**: `type: 'local' | 'session'` - 存储类型，默认'local'
+- **返回类型**: `string[]` - 缓存键数组
+- **示例**:
+  ```typescript
+  import { get_all_storage_keys } from '@qy_better_lib/core';
+  
+  const keys = get_all_storage_keys();
+  console.log(keys);
+  ```
+
+#### clear_expired_storage
+- **功能**: 清除过期的缓存
+- **参数**: `type: 'local' | 'session'` - 存储类型，默认'local'
+- **返回类型**: `number` - 清除的缓存数量
+- **示例**:
+  ```typescript
+  import { clear_expired_storage } from '@qy_better_lib/core';
+  
+  const count = clear_expired_storage();
+  console.log(`清除了${count}个过期缓存`);
+  ```
+
+#### encrypt_storage
+- **功能**: 加密存储敏感数据
+- **参数**:
+  - `key: string` - 缓存键
+  - `value: any` - 缓存值
+  - `type: 'local' | 'session'` - 存储类型，默认'local'
+- **示例**:
+  ```typescript
+  import { encrypt_storage } from '@qy_better_lib/core';
+  
+  // 加密存储用户信息
+  encrypt_storage('user', { name: '张三', age: 20 });
+  ```
+
+#### decrypt_storage
+- **功能**: 解密获取敏感数据
+- **参数**:
+  - `key: string` - 缓存键
+  - `type: 'local' | 'session'` - 存储类型，默认'local'
+- **返回类型**: `any` - 解密后的数据或null
+- **示例**:
+  ```typescript
+  import { decrypt_storage } from '@qy_better_lib/core';
+  
+  // 解密获取用户信息
+  const user = decrypt_storage('user');
+  console.log(user); // { name: '张三', age: 20 }
+  ```
+
+#### set_batch_storage
+- **功能**: 批量设置缓存
+- **参数**:
+  - `items: Array<{ key: string; value: any }>` - 缓存项数组
+  - `type: 'local' | 'session'` - 存储类型，默认'local'
+- **示例**:
+  ```typescript
+  import { set_batch_storage } from '@qy_better_lib/core';
+  
+  set_batch_storage([
+    { key: 'user', value: { name: '张三', age: 20 } },
+    { key: 'token', value: 'abc123' }
+  ]);
+  ```
+
+#### get_batch_storage
+- **功能**: 批量获取缓存
+- **参数**:
+  - `keys: string[]` - 缓存键数组
+  - `type: 'local' | 'session'` - 存储类型，默认'local'
+- **返回类型**: `Record<string, any>` - 缓存值对象
+- **示例**:
+  ```typescript
+  import { get_batch_storage } from '@qy_better_lib/core';
+  
+  const data = get_batch_storage(['user', 'token']);
+  console.log(data.user);
+  console.log(data.token);
+  ```
+
+#### remove_batch_storage
+- **功能**: 批量删除缓存
+- **参数**:
+  - `keys: string[]` - 缓存键数组
+  - `type: 'local' | 'session'` - 存储类型，默认'local'
+- **示例**:
+  ```typescript
+  import { remove_batch_storage } from '@qy_better_lib/core';
+  
+  remove_batch_storage(['user', 'token']);
+  ```
+
+### 8. DOM 操作工具 (dom.ts)
+
+#### get_parent_by_class
+- **功能**: 根据类名获取父元素
+- **参数**:
+  - `dom: Element | null` - DOM元素
+  - `class_name: string` - CSS类名
+- **返回类型**: `Element | null` - DOM元素或null
+- **示例**:
+  ```typescript
+  import { get_parent_by_class } from '@qy_better_lib/core';
+  
+  const childElement = document.getElementById('child');
+  const parentElement = get_parent_by_class(childElement, 'parent-class');
+  console.log(parentElement);
+  ```
+
+#### scroll_footer
+- **功能**: 滚动到底部
+- **参数**:
+  - `dom_id: string` - 元素ID
+  - `behavior: boolean` - 开启滚动动画，默认true
+- **示例**:
+  ```typescript
+  import { scroll_footer } from '@qy_better_lib/core';
+  
+  // 滚动到ID为container的元素底部
+  scroll_footer('container');
+  ```
+
+#### get_element
+- **功能**: 根据选择器获取元素
+- **参数**:
+  - `selector: string` - 选择器
+  - `context: Element | Document` - 上下文元素，默认为document
+- **返回类型**: `Element | null` - DOM元素或null
+- **示例**:
+  ```typescript
+  import { get_element } from '@qy_better_lib/core';
+  
+  // 通过选择器获取元素
+  const element = get_element('#container');
+  
+  // 在指定上下文中获取元素
+  const parentElement = get_element('.parent');
+  const childElement = get_element('.child', parentElement);
+  ```
+
+#### get_elements
+- **功能**: 根据选择器获取多个元素
+- **参数**:
+  - `selector: string` - 选择器
+  - `context: Element | Document` - 上下文元素，默认为document
+- **返回类型**: `Element[]` - DOM元素数组
+- **示例**:
+  ```typescript
+  import { get_elements } from '@qy_better_lib/core';
+  
+  // 获取所有段落元素
+  const paragraphs = get_elements('p');
+  console.log(paragraphs.length);
+  ```
+
+#### add_class
+- **功能**: 添加类名
+- **参数**:
+  - `element: Element | null` - DOM元素
+  - `class_name: string` - 类名
+- **示例**:
+  ```typescript
+  import { add_class } from '@qy_better_lib/core';
+  
+  const element = document.getElementById('container');
+  add_class(element, 'active');
+  ```
+
+#### remove_class
+- **功能**: 移除类名
+- **参数**:
+  - `element: Element | null` - DOM元素
+  - `class_name: string` - 类名
+- **示例**:
+  ```typescript
+  import { remove_class } from '@qy_better_lib/core';
+  
+  const element = document.getElementById('container');
+  remove_class(element, 'active');
+  ```
+
+#### toggle_class
+- **功能**: 切换类名
+- **参数**:
+  - `element: Element | null` - DOM元素
+  - `class_name: string` - 类名
+- **返回类型**: `boolean` - 是否添加了类名
+- **示例**:
+  ```typescript
+  import { toggle_class } from '@qy_better_lib/core';
+  
+  const element = document.getElementById('container');
+  const isActive = toggle_class(element, 'active');
+  console.log(isActive); // 切换后的状态
+  ```
+
+#### has_class
+- **功能**: 检查是否包含类名
+- **参数**:
+  - `element: Element | null` - DOM元素
+  - `class_name: string` - 类名
+- **返回类型**: `boolean` - 是否包含类名
+- **示例**:
+  ```typescript
+  import { has_class } from '@qy_better_lib/core';
+  
+  const element = document.getElementById('container');
+  const hasActive = has_class(element, 'active');
+  console.log(hasActive);
+  ```
+
+#### get_style
+- **功能**: 获取元素样式
+- **参数**:
+  - `element: Element | null` - DOM元素
+  - `property: string` - CSS属性名
+- **返回类型**: `string` - CSS属性值
+- **示例**:
+  ```typescript
+  import { get_style } from '@qy_better_lib/core';
+  
+  const element = document.getElementById('container');
+  const color = get_style(element, 'color');
+  console.log(color);
+  ```
+
+#### set_style
+- **功能**: 设置元素样式
+- **参数**:
+  - `element: Element | null` - DOM元素
+  - `property: string` - CSS属性名
+  - `value: string` - CSS属性值
+- **示例**:
+  ```typescript
+  import { set_style } from '@qy_better_lib/core';
+  
+  const element = document.getElementById('container');
+  set_style(element, 'color', 'red');
+  set_style(element, 'fontSize', '16px');
+  ```
+
+#### set_styles
+- **功能**: 设置元素多个样式
+- **参数**:
+  - `element: Element | null` - DOM元素
+  - `styles: Record<string, string>` - 样式对象
+- **示例**:
+  ```typescript
+  import { set_styles } from '@qy_better_lib/core';
+  
+  const element = document.getElementById('container');
+  set_styles(element, {
+    color: 'red',
+    fontSize: '16px',
+    backgroundColor: '#f0f0f0'
+  });
+  ```
+
+#### auto_size
+- **功能**: 根据屏幕宽度自动调整尺寸
+- **参数**:
+  - `size: number` - 原始尺寸值
+  - `deflate_width: number` - 基准宽度，默认 1920
+- **返回类型**: `number` - 调整后的尺寸值
+- **示例**:
+  ```typescript
+  import { auto_size } from '@qy_better_lib/core';
+  
+  // 根据屏幕宽度自动调整字体大小
+  const fontSize = auto_size(16);
+  console.log(fontSize); // 根据当前屏幕宽度计算的值
+  ```
+
+### 9. 颜色工具 (color.ts)
+
+#### mix
+- **功能**: 过渡颜色生成
+- **参数**:
+  - `color1: string` - 第一个颜色
+  - `color2: string` - 第二个颜色
+  - `weight: number` - 混合权重 (0-1)
+- **返回类型**: `string` - 混合后的颜色
+- **示例**:
+  ```typescript
+  import { mix } from '@qy_better_lib/core';
+  
+  // 混合红色和蓝色，权重0.5
+  const mixedColor = mix('#ff0000', '#0000ff', 0.5);
+  console.log(mixedColor); // #800080
+  ```
+
+#### get_rgb
+- **功能**: HEX转成RGB字符串
+- **参数**: `color: string` - HEX颜色值
+- **返回类型**: `string` - RGB字符串 "r,g,b"
+- **示例**:
+  ```typescript
+  import { get_rgb } from '@qy_better_lib/core';
+  
+  const rgb = get_rgb('#ff0000');
+  console.log(rgb); // "255,0,0"
+  ```
+
+#### hex_to_rgb
+- **功能**: HEX转成RGB对象
+- **参数**: `hex: string` - HEX颜色值
+- **返回类型**: `{r, g, b} | null` - RGB对象或null
+- **示例**:
+  ```typescript
+  import { hex_to_rgb } from '@qy_better_lib/core';
+  
+  const rgb = hex_to_rgb('#ff0000');
+  console.log(rgb); // { r: 255, g: 0, b: 0 }
+  ```
+
+#### rgb_to_hex
+- **功能**: RGB转成HEX
+- **参数**:
+  - `r: number` - 红色通道值 (0-255)
+  - `g: number` - 绿色通道值 (0-255)
+  - `b: number` - 蓝色通道值 (0-255)
+- **返回类型**: `string` - HEX颜色值
+- **示例**:
+  ```typescript
+  import { rgb_to_hex } from '@qy_better_lib/core';
+  
+  const hex = rgb_to_hex(255, 0, 0);
+  console.log(hex); // #ff0000
+  ```
+
+#### rgba_to_hex
+- **功能**: RGBA转成HEX
+- **参数**:
+  - `r: number` - 红色通道值 (0-255)
+  - `g: number` - 绿色通道值 (0-255)
+  - `b: number` - 蓝色通道值 (0-255)
+  - `a: number` - 透明度值 (0-1)
+- **返回类型**: `string` - HEX颜色值
+- **示例**:
+  ```typescript
+  import { rgba_to_hex } from '@qy_better_lib/core';
+  
+  const hex = rgba_to_hex(255, 0, 0, 0.5);
+  console.log(hex); // #ff0000
+  ```
+
+#### lighten
+- **功能**: 使颜色变亮
+- **参数**:
+  - `color: string` - HEX颜色值
+  - `amount: number` - 变亮程度 (0-1)
+- **返回类型**: `string` - 变亮后的HEX颜色值
+- **示例**:
+  ```typescript
+  import { lighten } from '@qy_better_lib/core';
+  
+  const lightColor = lighten('#ff0000', 0.5);
+  console.log(lightColor); // #ffffff
+  ```
+
+#### darken
+- **功能**: 使颜色变暗
+- **参数**:
+  - `color: string` - HEX颜色值
+  - `amount: number` - 变暗程度 (0-1)
+- **返回类型**: `string` - 变暗后的HEX颜色值
+- **示例**:
+  ```typescript
+  import { darken } from '@qy_better_lib/core';
+  
+  const darkColor = darken('#ff0000', 0.5);
+  console.log(darkColor); // #800000
+  ```
+
+#### is_light
+- **功能**: 判断颜色是否为亮色
+- **参数**: `color: string` - HEX颜色值
+- **返回类型**: `boolean` - 是否为亮色
+- **示例**:
+  ```typescript
+  import { is_light } from '@qy_better_lib/core';
+  
+  const isLight = is_light('#ffffff');
+  console.log(isLight); // true
+  ```
+
+#### is_dark
+- **功能**: 判断颜色是否为暗色
+- **参数**: `color: string` - HEX颜色值
+- **返回类型**: `boolean` - 是否为暗色
+- **示例**:
+  ```typescript
+  import { is_dark } from '@qy_better_lib/core';
+  
+  const isDark = is_dark('#000000');
+  console.log(isDark); // true
+  ```
+
+#### get_contrast_color
+- **功能**: 获取与给定颜色对比度高的颜色（黑或白）
+- **参数**: `color: string` - HEX颜色值
+- **返回类型**: `string` - 对比度高的颜色 (#000000 或 #FFFFFF)
+- **示例**:
+  ```typescript
+  import { get_contrast_color } from '@qy_better_lib/core';
+  
+  const contrastColor = get_contrast_color('#ff0000');
+  console.log(contrastColor); // #FFFFFF
+  ```
+
+### 10. ECharts 工具 (echarts.ts)
+
+#### get_chart_gradient_color
+- **功能**: Echarts线性渐变颜色
+- **参数**:
+  - `type: 'v' | 'h'` - 渐变类型，'v'为垂直渐变，'h'为水平渐变
+  - `start_color: string` - 起始颜色
+  - `end_color: string` - 结束颜色
+- **返回类型**: `object` - 渐变配置对象
+- **示例**:
+  ```typescript
+  import { get_chart_gradient_color } from '@qy_better_lib/core';
+  
+  const gradient = get_chart_gradient_color('v', '#ff0000', '#0000ff');
+  console.log(gradient);
+  ```
+
+#### init_chart
+- **功能**: 初始化Echarts图表
+- **参数**:
+  - `container: HTMLElement | string` - 容器元素或容器ID
+  - `options?: EChartsOption` - 图表配置项
+  - `renderer: 'canvas' | 'svg'` - 渲染方式，默认 'canvas'
+  - `theme?: string` - 主题
+- **返回类型**: `Promise<any>` - Echarts实例
+- **示例**:
+  ```typescript
+  import { init_chart } from '@qy_better_lib/core';
+  
+  async function init() {
+    const chart = await init_chart('chart-container', {
+      title: { text: '示例图表' },
+      series: [{ type: 'bar', data: [1, 2, 3] }]
+    });
+    return chart;
+  }
+  ```
+
+#### destroy_chart
+- **功能**: 销毁Echarts图表
+- **参数**: `chart: any` - Echarts实例
+- **示例**:
+  ```typescript
+  import { destroy_chart } from '@qy_better_lib/core';
+  
+  destroy_chart(chart);
+  ```
+
+#### update_chart
+- **功能**: 更新Echarts图表配置
+- **参数**:
+  - `chart: any` - Echarts实例
+  - `options: EChartsOption` - 图表配置项
+- **示例**:
+  ```typescript
+  import { update_chart } from '@qy_better_lib/core';
+  
+  update_chart(chart, {
+    series: [{ type: 'bar', data: [4, 5, 6] }]
+  });
+  ```
+
+#### resize_chart
+- **功能**: 调整Echarts图表大小
+- **参数**: `chart: any` - Echarts实例
+- **示例**:
+  ```typescript
+  import { resize_chart } from '@qy_better_lib/core';
+  
+  resize_chart(chart);
+  ```
+
+#### make_chart_responsive
+- **功能**: 为Echarts图表添加响应式处理
+- **参数**:
+  - `chart: any` - Echarts实例
+  - `debounce_time: number` - 防抖时间，默认200ms
+- **返回类型**: `Function` - 清理函数
+- **示例**:
+  ```typescript
+  import { make_chart_responsive } from '@qy_better_lib/core';
+  
+  const cleanup = make_chart_responsive(chart);
+  // 当需要清理时调用
+  // cleanup();
+  ```
+
+#### generate_chart_colors
+- **功能**: 生成Echarts颜色数组
+- **参数**:
+  - `count: number` - 颜色数量
+  - `base_colors?: string[]` - 基础颜色数组，默认使用ECharts默认颜色
+- **返回类型**: `string[]` - 颜色数组
+- **示例**:
+  ```typescript
+  import { generate_chart_colors } from '@qy_better_lib/core';
+  
+  const colors = generate_chart_colors(5);
+  console.log(colors);
+  ```
+
+#### format_chart_label
+- **功能**: 格式化Echarts数据标签
+- **参数**:
+  - `value: any` - 数值
+  - `formatter?: ((value: any) => string) | string` - 格式化函数或格式化模板
+- **返回类型**: `string` - 格式化后的值
+- **示例**:
+  ```typescript
+  import { format_chart_label } from '@qy_better_lib/core';
+  
+  const label = format_chart_label(123, '{value}件');
+  console.log(label); // 123件
+  ```
+
+#### merge_chart_options
+- **功能**: 合并Echarts配置项
+- **参数**:
+  - `defaultOption: EChartsOption` - 默认配置项
+  - `customOption: EChartsOption` - 自定义配置项
+- **返回类型**: `EChartsOption` - 合并后的配置项
+- **示例**:
+  ```typescript
+  import { merge_chart_options } from '@qy_better_lib/core';
+  
+  const options = merge_chart_options(
+    { title: { text: '默认标题' } },
+    { title: { text: '自定义标题' } }
+  );
+  ```
+
+#### add_chart_listener
+- **功能**: 为Echarts图表添加事件监听器
+- **参数**:
+  - `chart: any` - Echarts实例
+  - `eventName: string` - 事件名称
+  - `handler: (...args: any[]) => void` - 事件处理函数
+- **示例**:
+  ```typescript
+  import { add_chart_listener } from '@qy_better_lib/core';
+  
+  add_chart_listener(chart, 'click', (params) => {
+    console.log('点击事件:', params);
+  });
+  ```
+
+#### remove_chart_listener
+- **功能**: 移除Echarts图表事件监听器
+- **参数**:
+  - `chart: any` - Echarts实例
+  - `eventName: string` - 事件名称
+  - `handler: (...args: any[]) => void` - 事件处理函数
+- **示例**:
+  ```typescript
+  import { remove_chart_listener } from '@qy_better_lib/core';
+  
+  const handler = (params) => console.log('点击事件:', params);
+  add_chart_listener(chart, 'click', handler);
+  // 稍后移除
+  remove_chart_listener(chart, 'click', handler);
+  ```
+
+#### export_chart_image
+- **功能**: 导出Echarts图表为图片
+- **参数**:
+  - `chart: any` - Echarts实例
+  - `options?: object` - 导出选项
+- **返回类型**: `string | null` - 图片URL
+- **示例**:
+  ```typescript
+  import { export_chart_image } from '@qy_better_lib/core';
+  
+  const imageUrl = export_chart_image(chart, {
+    type: 'png',
+    file_name: 'chart-image'
+  });
+  ```
+
+#### is_echarts_loaded
+- **功能**: 检查Echarts是否已加载
+- **返回类型**: `boolean` - 是否已加载
+- **示例**:
+  ```typescript
+  import { is_echarts_loaded } from '@qy_better_lib/core';
+  
+  const loaded = is_echarts_loaded();
+  console.log(loaded);
+  ```
+
+#### resize_charts
+- **功能**: 批量调整Echarts图表大小
+- **参数**: `charts: any[]` - 图表实例数组
+- **示例**:
+  ```typescript
+  import { resize_charts } from '@qy_better_lib/core';
+  
+  resize_charts([chart1, chart2]);
+  ```
+
+#### destroy_charts
+- **功能**: 批量销毁Echarts图表
+- **参数**: `charts: any[]` - 图表实例数组
+- **示例**:
+  ```typescript
+  import { destroy_charts } from '@qy_better_lib/core';
+  
+  destroy_charts([chart1, chart2]);
+  ```
+
+#### sort_chart_data
+- **功能**: 数据排序函数
+- **参数**:
+  - `data: any[]` - 原始数据数组
+  - `sort_key: string` - 排序字段名
+  - `order: 'asc' | 'desc'` - 排序顺序，默认'asc'
+- **返回类型**: `any[]` - 排序后的数据数组
+- **示例**:
+  ```typescript
+  import { sort_chart_data } from '@qy_better_lib/core';
+  
+  const sortedData = sort_chart_data([{ value: 3 }, { value: 1 }, { value: 2 }], 'value');
+  console.log(sortedData);
+  ```
+
+#### group_chart_data
+- **功能**: 数据分组函数
+- **参数**:
+  - `data: any[]` - 原始数据数组
+  - `group_key: string` - 分组字段名
+- **返回类型**: `Record<string, any[]>` - 分组后的数据对象
+- **示例**:
+  ```typescript
+  import { group_chart_data } from '@qy_better_lib/core';
+  
+  const groupedData = group_chart_data([
+    { category: 'A', value: 1 },
+    { category: 'B', value: 2 },
+    { category: 'A', value: 3 }
+  ], 'category');
+  console.log(groupedData);
+  ```
+
+#### aggregate_chart_data
+- **功能**: 数据聚合函数
+- **参数**:
+  - `data: any[]` - 原始数据数组
+  - `group_key: string` - 分组字段名
+  - `value_key: string` - 数值字段名
+  - `aggregator: (values: number[]) => number` - 聚合函数，默认求和
+- **返回类型**: `any[]` - 聚合后的数据数组
+- **示例**:
+  ```typescript
+  import { aggregate_chart_data } from '@qy_better_lib/core';
+  
+  const aggregatedData = aggregate_chart_data([
+    { category: 'A', value: 1 },
+    { category: 'A', value: 3 },
+    { category: 'B', value: 2 }
+  ], 'category', 'value');
+  console.log(aggregatedData);
+  ```
+
+### 11. 文件工具 (file.ts)
+
+#### download_file
+- **功能**: 下载文件
+- **参数**:
+  - `path: string` - 文件路径
+  - `name?: string` - 文件名
+- **示例**:
+  ```typescript
+  import { download_file } from '@qy_better_lib/core';
+  
+  download_file({ path: 'https://example.com/file.pdf', name: 'example.pdf' });
+  ```
+
+#### download_files
+- **功能**: 批量下载文件
+- **参数**: `file_list: any[]` - 文件列表
+- **示例**:
+  ```typescript
+  import { download_files } from '@qy_better_lib/core';
+  
+  download_files([
+    { url: 'https://example.com/file1.pdf', name: 'file1.pdf' },
+    { url: 'https://example.com/file2.pdf', name: 'file2.pdf' }
+  ]);
+  ```
+
+#### to_base64
+- **功能**: 将file转换成base64
+- **参数**: `file: Blob` - 文件对象
+- **返回类型**: `Promise<string | undefined>` - base64字符串
+- **示例**:
+  ```typescript
+  import { to_base64 } from '@qy_better_lib/core';
+  
+  async function convert() {
+    const input = document.querySelector('input[type="file"]');
+    if (input.files[0]) {
+      const base64 = await to_base64(input.files[0]);
+      console.log(base64);
+    }
+  }
+  ```
+
+#### read_file
+- **功能**: 读取文件内容
+- **参数**:
+  - `file: Blob` - 文件对象
+  - `encoding: string` - 编码方式，默认为 UTF-8
+- **返回类型**: `Promise<string | undefined>` - 文件内容
+- **示例**:
+  ```typescript
+  import { read_file } from '@qy_better_lib/core';
+  
+  async function read() {
+    const input = document.querySelector('input[type="file"]');
+    if (input.files[0]) {
+      const content = await read_file(input.files[0]);
+      console.log(content);
+    }
+  }
+  ```
+
+#### get_file_extension
+- **功能**: 获取文件扩展名
+- **参数**: `file_name: string` - 文件名
+- **返回类型**: `string` - 文件扩展名
+- **示例**:
+  ```typescript
+  import { get_file_extension } from '@qy_better_lib/core';
+  
+  const extension = get_file_extension('example.pdf');
+  console.log(extension); // pdf
+  ```
+
+#### get_file_name_without_extension
+- **功能**: 获取不带扩展名的文件名
+- **参数**: `file_name: string` - 文件名
+- **返回类型**: `string` - 不带扩展名的文件名
+- **示例**:
+  ```typescript
+  import { get_file_name_without_extension } from '@qy_better_lib/core';
+  
+  const name = get_file_name_without_extension('example.pdf');
+  console.log(name); // example
+  ```
+
+#### validate_file_size
+- **功能**: 验证文件大小
+- **参数**:
+  - `file: File` - 文件对象
+  - `max_size: number` - 最大文件大小（字节）
+- **返回类型**: `boolean` - 是否符合大小要求
+- **示例**:
+  ```typescript
+  import { validate_file_size } from '@qy_better_lib/core';
+  
+  const input = document.querySelector('input[type="file"]');
+  if (input.files[0]) {
+    const isValid = validate_file_size(input.files[0], 1024 * 1024); // 1MB
+    console.log(isValid);
+  }
+  ```
+
+#### validate_file_type
+- **功能**: 验证文件类型
+- **参数**:
+  - `file: File` - 文件对象
+  - `allowed_types: string[]` - 允许的文件类型数组
+- **返回类型**: `boolean` - 是否符合类型要求
+- **示例**:
+  ```typescript
+  import { validate_file_type } from '@qy_better_lib/core';
+  
+  const input = document.querySelector('input[type="file"]');
+  if (input.files[0]) {
+    const isValid = validate_file_type(input.files[0], ['pdf', 'doc', 'docx']);
+    console.log(isValid);
+  }
+  ```
+
+#### create_file_from_blob
+- **功能**: 从 Blob 创建文件
+- **参数**:
+  - `blob: Blob` - Blob 对象
+  - `file_name: string` - 文件名
+  - `mime_type: string` - MIME 类型
+- **返回类型**: `File` - 文件对象
+- **示例**:
+  ```typescript
+  import { create_file_from_blob } from '@qy_better_lib/core';
+  
+  const blob = new Blob(['Hello World'], { type: 'text/plain' });
+  const file = create_file_from_blob(blob, 'example.txt', 'text/plain');
+  console.log(file);
+  ```
+
+#### download_text_file
+- **功能**: 下载文本文件
+- **参数**:
+  - `content: string` - 文件内容
+  - `file_name: string` - 文件名
+  - `mime_type: string` - MIME 类型，默认为 text/plain
+- **示例**:
+  ```typescript
+  import { download_text_file } from '@qy_better_lib/core';
+  
+  download_text_file('Hello World', 'example.txt');
+  ```
+
+#### compress_image
+- **功能**: 压缩图片文件
+- **参数**:
+  - `file: File` - 图片文件
+  - `max_width: number` - 最大宽度，默认 800
+  - `max_height: number` - 最大高度，默认 800
+  - `quality: number` - 压缩质量，0-1之间，默认 0.8
+- **返回类型**: `Promise<File | undefined>` - 压缩后的文件
+- **示例**:
+  ```typescript
+  import { compress_image } from '@qy_better_lib/core';
+  
+  async function compress() {
+    const input = document.querySelector('input[type="file"]');
+    if (input.files[0]) {
+      const compressedFile = await compress_image(input.files[0]);
+      console.log(compressedFile);
+    }
+  }
+  ```
+
+#### get_file_info
+- **功能**: 获取文件信息
+- **参数**: `file: File` - 文件对象
+- **返回类型**: `object` - 文件信息对象
+- **示例**:
+  ```typescript
+  import { get_file_info } from '@qy_better_lib/core';
+  
+  const input = document.querySelector('input[type="file"]');
+  if (input.files[0]) {
+    const info = get_file_info(input.files[0]);
+    console.log(info);
+  }
+  ```
+
+#### generate_unique_file_name
+- **功能**: 生成唯一的文件名
+- **参数**: `original_name: string` - 原始文件名
+- **返回类型**: `string` - 唯一的文件名
+- **示例**:
+  ```typescript
+  import { generate_unique_file_name } from '@qy_better_lib/core';
+  
+  const uniqueName = generate_unique_file_name('example.pdf');
+  console.log(uniqueName);
+  ```
+
+### 12. 树形数据工具 (tree.ts)
+
+#### tree_flat
+- **功能**: 树形数据扁平化处理
+- **参数**:
+  - `data: TreeNode<T>[]` - 树形数据数组
+  - `key: string` - key属性，默认"key"
+  - `children: string` - children属性，默认"children"
+- **返回类型**: `FlatTreeMap<T>` - 扁平化的树形数据映射
+- **示例**:
+  ```typescript
+  import { tree_flat } from '@qy_better_lib/core';
+  
+  const treeData = [
+    { key: '1', name: '节点1', children: [{ key: '1-1', name: '节点1-1' }] }
+  ];
+  const flatMap = tree_flat(treeData);
+  console.log(flatMap);
+  ```
+
+#### build_tree
+- **功能**: 从扁平化数据构建树形结构
+- **参数**:
+  - `data: TreeNode<T>[]` - 扁平化数据数组
+  - `key: string` - key属性，默认"key"
+  - `parent_key: string` - 父节点key属性，默认"parentId"
+  - `children: string` - children属性，默认"children"
+- **返回类型**: `TreeNode<T>[]` - 树形数据数组
+- **示例**:
+  ```typescript
+  import { build_tree } from '@qy_better_lib/core';
+  
+  const flatData = [
+    { key: '1', name: '节点1' },
+    { key: '1-1', name: '节点1-1', parentId: '1' }
+  ];
+  const treeData = build_tree(flatData);
+  console.log(treeData);
+  ```
+
+#### traverse_tree_depth_first
+- **功能**: 深度优先遍历树形数据
+- **参数**:
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
+  - `callback: (node: TreeNode<T>, depth: number) => boolean | void` - 回调函数，返回false可中断遍历
+  - `children: string` - children属性，默认"children"
+- **返回类型**: `boolean` - 是否提前中断了遍历
+- **示例**:
+  ```typescript
+  import { traverse_tree_depth_first } from '@qy_better_lib/core';
+  
+  const treeData = [
+    { key: '1', name: '节点1', children: [{ key: '1-1', name: '节点1-1' }] }
+  ];
+  traverse_tree_depth_first(treeData, (node, depth) => {
+    console.log(`${'  '.repeat(depth)}${node.name}`);
+  });
+  ```
+
+#### traverse_tree_breadth_first
+- **功能**: 广度优先遍历树形数据
+- **参数**:
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
+  - `callback: (node: TreeNode<T>, depth: number) => boolean | void` - 回调函数，返回false可中断遍历
+  - `children: string` - children属性，默认"children"
+- **返回类型**: `boolean` - 是否提前中断了遍历
+- **示例**:
+  ```typescript
+  import { traverse_tree_breadth_first } from '@qy_better_lib/core';
+  
+  const treeData = [
+    { key: '1', name: '节点1', children: [{ key: '1-1', name: '节点1-1' }] }
+  ];
+  traverse_tree_breadth_first(treeData, (node, depth) => {
+    console.log(`${'  '.repeat(depth)}${node.name}`);
+  });
+  ```
+
+#### find_tree_node
+- **功能**: 根据条件查找树形节点
+- **参数**:
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
+  - `predicate: (node: TreeNode<T>) => boolean` - 条件函数
+  - `children: string` - children属性，默认"children"
+- **返回类型**: `TreeNode<T> | null` - 找到的节点或null
+- **示例**:
+  ```typescript
+  import { find_tree_node } from '@qy_better_lib/core';
+  
+  const treeData = [
+    { key: '1', name: '节点1', children: [{ key: '1-1', name: '节点1-1' }] }
+  ];
+  const node = find_tree_node(treeData, node => node.key === '1-1');
+  console.log(node);
+  ```
+
+#### find_tree_node_by_key
+- **功能**: 根据key查找树形节点
+- **参数**:
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
+  - `key_value: any` - key值
+  - `key: string` - key属性，默认"key"
+  - `children: string` - children属性，默认"children"
+- **返回类型**: `TreeNode<T> | null` - 找到的节点或null
+- **示例**:
+  ```typescript
+  import { find_tree_node_by_key } from '@qy_better_lib/core';
+  
+  const treeData = [
+    { key: '1', name: '节点1', children: [{ key: '1-1', name: '节点1-1' }] }
+  ];
+  const node = find_tree_node_by_key(treeData, '1-1');
+  console.log(node);
+  ```
+
+#### filter_tree
+- **功能**: 过滤树形数据
+- **参数**:
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
+  - `predicate: (node: TreeNode<T>) => boolean` - 条件函数
+  - `children: string` - children属性，默认"children"
+- **返回类型**: `TreeNode<T>[]` - 过滤后的树形数据
+- **示例**:
+  ```typescript
+  import { filter_tree } from '@qy_better_lib/core';
+  
+  const treeData = [
+    { key: '1', name: '节点1', value: 10 },
+    { key: '2', name: '节点2', value: 20 }
+  ];
+  const filteredData = filter_tree(treeData, node => node.value > 15);
+  console.log(filteredData);
+  ```
+
+#### transform_tree
+- **功能**: 转换树形数据结构
+- **参数**:
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
+  - `transform: (node: TreeNode<T>) => TreeNode<T>` - 转换函数
+  - `children: string` - children属性，默认"children"
+- **返回类型**: `TreeNode<T>[]` - 转换后的树形数据
+- **示例**:
+  ```typescript
+  import { transform_tree } from '@qy_better_lib/core';
+  
+  const treeData = [
+    { key: '1', name: '节点1' }
+  ];
+  const transformedData = transform_tree(treeData, node => ({
+    ...node,
+    newProperty: 'value'
+  }));
+  console.log(transformedData);
+  ```
+
+#### add_tree_node_path
+- **功能**: 为树形节点添加路径信息
+- **参数**:
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
+  - `key: string` - key属性，默认"key"
+  - `path: string` - path属性，默认"path"
+  - `children: string` - children属性，默认"children"
+- **返回类型**: `TreeNode<T>[]` - 添加了路径信息的树形数据
+- **示例**:
+  ```typescript
+  import { add_tree_node_path } from '@qy_better_lib/core';
+  
+  const treeData = [
+    { key: '1', name: '节点1', children: [{ key: '1-1', name: '节点1-1' }] }
+  ];
+  const dataWithPath = add_tree_node_path(treeData);
+  console.log(dataWithPath);
+  ```
+
+#### get_tree_node_descendants
+- **功能**: 获取树形节点的所有后代
+- **参数**:
+  - `node: TreeNode<T>` - 树形节点
+  - `children: string` - children属性，默认"children"
+- **返回类型**: `TreeNode<T>[]` - 所有后代节点数组
+- **示例**:
+  ```typescript
+  import { get_tree_node_descendants } from '@qy_better_lib/core';
+  
+  const node = { key: '1', name: '节点1', children: [{ key: '1-1', name: '节点1-1' }] };
+  const descendants = get_tree_node_descendants(node);
+  console.log(descendants);
+  ```
+
+#### get_tree_node_ancestors
+- **功能**: 获取树形节点的所有祖先
+- **参数**:
+  - `node: TreeNode<T>` - 树形节点
+  - `parent: string` - parent属性，默认"parent"
+- **返回类型**: `TreeNode<T>[]` - 所有祖先节点数组
+- **示例**:
+  ```typescript
+  import { get_tree_node_ancestors } from '@qy_better_lib/core';
+  
+  const parentNode = { key: '1', name: '节点1' };
+  const childNode = { key: '1-1', name: '节点1-1', parent: parentNode };
+  const ancestors = get_tree_node_ancestors(childNode);
+  console.log(ancestors);
+  ```
+
+#### get_tree_depth
+- **功能**: 计算树形数据的深度
+- **参数**:
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
+  - `children: string` - children属性，默认"children"
+- **返回类型**: `number` - 树形数据的深度
+- **示例**:
+  ```typescript
+  import { get_tree_depth } from '@qy_better_lib/core';
+  
+  const treeData = [
+    { key: '1', name: '节点1', children: [{ key: '1-1', name: '节点1-1' }] }
+  ];
+  const depth = get_tree_depth(treeData);
+  console.log(depth); // 2
+  ```
+
+#### flatten_tree_to_array
+- **功能**: 扁平化树形数据为数组
+- **参数**:
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
+  - `children: string` - children属性，默认"children"
+- **返回类型**: `TreeNode<T>[]` - 扁平化的节点数组
+- **示例**:
+  ```typescript
+  import { flatten_tree_to_array } from '@qy_better_lib/core';
+  
+  const treeData = [
+    { key: '1', name: '节点1', children: [{ key: '1-1', name: '节点1-1' }] }
+  ];
+  const flatArray = flatten_tree_to_array(treeData);
+  console.log(flatArray);
+  ```
+
+#### add_tree_node
+- **功能**: 向树形结构添加节点
+- **参数**:
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
+  - `parent_key: any` - 父节点key值
+  - `new_node: TreeNode<T>` - 新节点
+  - `key: string` - key属性，默认"key"
+  - `children: string` - children属性，默认"children"
+- **返回类型**: `TreeNode<T>[]` - 更新后的树形数据
+- **示例**:
+  ```typescript
+  import { add_tree_node } from '@qy_better_lib/core';
+  
+  const treeData = [
+    { key: '1', name: '节点1' }
+  ];
+  const newTreeData = add_tree_node(treeData, '1', { key: '1-1', name: '节点1-1' });
+  console.log(newTreeData);
+  ```
+
+#### remove_tree_node
+- **功能**: 从树形结构移除节点
+- **参数**:
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
+  - `node_key: any` - 要移除的节点key值
+  - `key: string` - key属性，默认"key"
+  - `children: string` - children属性，默认"children"
+- **返回类型**: `TreeNode<T>[]` - 更新后的树形数据
+- **示例**:
+  ```typescript
+  import { remove_tree_node } from '@qy_better_lib/core';
+  
+  const treeData = [
+    { key: '1', name: '节点1', children: [{ key: '1-1', name: '节点1-1' }] }
+  ];
+  const newTreeData = remove_tree_node(treeData, '1-1');
+  console.log(newTreeData);
+  ```
+
+#### update_tree_node
+- **功能**: 更新树形结构中的节点
+- **参数**:
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
+  - `node_key: any` - 要更新的节点key值
+  - `updates: Partial<TreeNode<T>>` - 更新内容
+  - `key: string` - key属性，默认"key"
+  - `children: string` - children属性，默认"children"
+- **返回类型**: `TreeNode<T>[]` - 更新后的树形数据
+- **示例**:
+  ```typescript
+  import { update_tree_node } from '@qy_better_lib/core';
+  
+  const treeData = [
+    { key: '1', name: '节点1' }
+  ];
+  const newTreeData = update_tree_node(treeData, '1', { name: '更新后的节点1' });
+  console.log(newTreeData);
+  ```
+
+#### sort_tree
+- **功能**: 对树形结构进行排序
+- **参数**:
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
+  - `compare_fn: ((a: TreeNode<T>, b: TreeNode<T>) => number) | string` - 比较函数或属性名
+  - `recursive: boolean` - 是否递归排序所有层级，默认true
+  - `children: string` - children属性，默认"children"
+- **返回类型**: `TreeNode<T>[]` - 排序后的树形数据
+- **示例**:
+  ```typescript
+  import { sort_tree } from '@qy_better_lib/core';
+  
+  const treeData = [
+    { key: '2', name: '节点2' },
+    { key: '1', name: '节点1' }
+  ];
+  const sortedData = sort_tree(treeData, 'key');
+  console.log(sortedData);
+  ```
+
+#### clone_tree
+- **功能**: 克隆树形结构
+- **参数**:
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
+  - `children: string` - children属性，默认"children"
+- **返回类型**: `TreeNode<T>[]` - 克隆后的树形数据
+- **示例**:
+  ```typescript
+  import { clone_tree } from '@qy_better_lib/core';
+  
+  const treeData = [
+    { key: '1', name: '节点1' }
+  ];
+  const clonedData = clone_tree(treeData);
+  console.log(clonedData);
+  ```
+
+#### validate_tree
+- **功能**: 验证树形结构的有效性
+- **参数**:
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
+  - `key: string` - key属性，默认"key"
+  - `children: string` - children属性，默认"children"
+- **返回类型**: `{ valid: boolean; errors: string[] }` - 验证结果
+- **示例**:
+  ```typescript
+  import { validate_tree } from '@qy_better_lib/core';
+  
+  const treeData = [
+    { key: '1', name: '节点1' }
+  ];
+  const result = validate_tree(treeData);
+  console.log(result);
+  ```
+
+#### search_tree
+- **功能**: 在树形结构中搜索节点
+- **参数**:
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
+  - `predicate: ((node: TreeNode<T>) => boolean) | Record<string, any>` - 搜索条件函数或属性值对
+  - `children: string` - children属性，默认"children"
+- **返回类型**: `TreeNode<T>[]` - 所有匹配的节点数组
+- **示例**:
+  ```typescript
+  import { search_tree } from '@qy_better_lib/core';
+  
+  const treeData = [
+    { key: '1', name: '节点1', value: 10 },
+    { key: '2', name: '节点2', value: 20 }
+  ];
+  const results = search_tree(treeData, { value: 10 });
+  console.log(results);
+  ```
+