@qy_better_lib/core 0.2.5 → 0.2.7

package/DOCUMENTATION.md

@@ -1,4 +1,4 @@
-# QY Better Lib Core - 工具函数文档
+# QY Better Lib Core - 工具函数文档
 
 本文档详细介绍了 QY Better Lib Core 包中的工具函数，包括功能描述、参数说明、返回类型和使用示例。
 
@@ -547,6 +547,8 @@
 
 ### 3. 日期时间工具 (date.ts)
 
+> 注意：日期时间工具现在是可选依赖，需要单独导入
+
 #### format_date
 - **功能**: 格式化日期时间
 - **参数**:
@@ -555,7 +557,7 @@
 - **返回类型**: `string` - 格式化后的日期时间字符串
 - **示例**:
   ```typescript
-  import { format_date } from '@qy_better_lib/core';
+  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
@@ -571,7 +573,7 @@
 - **返回类型**: `[string, string]` - [开始日期时间, 截止日期时间]
 - **示例**:
   ```typescript
-  import { get_date_time_range } from '@qy_better_lib/core';
+  import { get_date_time_range } from '@qy_better_lib/core/date';
   
   // 获取昨天的时间范围
   const [start, end] = get_date_time_range('d', -1);
@@ -587,7 +589,7 @@
 - **返回类型**: `number` - 时间差
 - **示例**:
   ```typescript
-  import { get_date_diff } from '@qy_better_lib/core';
+  import { get_date_diff } from '@qy_better_lib/core/date';
   
   const date1 = '2023-12-31';
   const date2 = '2023-12-25';
@@ -604,7 +606,7 @@
 - **返回类型**: `Date | string` - 增加后的日期或格式化后的字符串
 - **示例**:
   ```typescript
-  import { add_date } from '@qy_better_lib/core';
+  import { add_date } from '@qy_better_lib/core/date';
   
   // 添加7天
   add_date(new Date(), 7, 'day'); // 7天后的日期对象
@@ -621,7 +623,7 @@
 - **返回类型**: `Date | string` - 减少后的日期或格式化后的字符串
 - **示例**:
   ```typescript
-  import { subtract_date } from '@qy_better_lib/core';
+  import { subtract_date } from '@qy_better_lib/core/date';
   
   // 减去7天
   subtract_date(new Date(), 7, 'day'); // 7天前的日期对象
@@ -634,7 +636,7 @@
 - **返回类型**: `boolean` - 是否为工作日
 - **示例**:
   ```typescript
-  import { is_weekday } from '@qy_better_lib/core';
+  import { is_weekday } from '@qy_better_lib/core/date';
   
   is_weekday('2023-12-31'); // true (周日)
   is_weekday('2024-01-01'); // false (周一)
@@ -646,7 +648,7 @@
 - **返回类型**: `boolean` - 是否为周末
 - **示例**:
   ```typescript
-  import { is_weekend } from '@qy_better_lib/core';
+  import { is_weekend } from '@qy_better_lib/core/date';
   
   is_weekend('2023-12-30'); // true (周六)
   is_weekend('2023-12-29'); // false (周五)
@@ -658,7 +660,7 @@
 - **返回类型**: `string` - 相对时间描述
 - **示例**:
   ```typescript
-  import { get_relative_time } from '@qy_better_lib/core';
+  import { get_relative_time } from '@qy_better_lib/core/date';
   
   // 假设当前时间是2023-12-31
   get_relative_time('2023-12-31 23:50:00'); // 刚刚
@@ -673,7 +675,7 @@
 - **返回类型**: `string` - 格式化后的时间差字符串
 - **示例**:
   ```typescript
-  import { format_timestamp_diff } from '@qy_better_lib/core';
+  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;
@@ -1693,223 +1695,22 @@
   });
   ```
 
-#### get_attribute
-- **功能**: 获取元素属性
-- **参数**:
-  - `element: Element | null` - DOM元素
-  - `attribute: string` - 属性名
-- **返回类型**: `string` - 属性值
-- **示例**:
-  ```typescript
-  import { get_attribute } from '@qy_better_lib/core';
-  
-  const element = document.getElementById('link');
-  const href = get_attribute(element, 'href');
-  console.log(href);
-  ```
-
-#### set_attribute
-- **功能**: 设置元素属性
-- **参数**:
-  - `element: Element | null` - DOM元素
-  - `attribute: string` - 属性名
-  - `value: string` - 属性值
-- **示例**:
-  ```typescript
-  import { set_attribute } from '@qy_better_lib/core';
-  
-  const element = document.getElementById('link');
-  set_attribute(element, 'href', 'https://example.com');
-  ```
-
-#### remove_attribute
-- **功能**: 移除元素属性
-- **参数**:
-  - `element: Element | null` - DOM元素
-  - `attribute: string` - 属性名
-- **示例**:
-  ```typescript
-  import { remove_attribute } from '@qy_better_lib/core';
-  
-  const element = document.getElementById('link');
-  remove_attribute(element, 'href');
-  ```
-
-#### on
-- **功能**: 绑定事件
-- **参数**:
-  - `element: Element | Window | Document | null` - DOM元素、窗口或文档
-  - `event: string` - 事件名
-  - `handler: EventListener` - 事件处理函数
-  - `options: AddEventListenerOptions` - 事件选项
-- **示例**:
-  ```typescript
-  import { on } from '@qy_better_lib/core';
-  
-  const button = document.getElementById('button');
-  on(button, 'click', () => {
-    console.log('Button clicked');
-  });
-  ```
-
-#### off
-- **功能**: 解绑事件
-- **参数**:
-  - `element: Element | Window | Document | null` - DOM元素、窗口或文档
-  - `event: string` - 事件名
-  - `handler: EventListener` - 事件处理函数
-  - `options: EventListenerOptions` - 事件选项
-- **示例**:
-  ```typescript
-  import { off } from '@qy_better_lib/core';
-  
-  const button = document.getElementById('button');
-  const handleClick = () => {
-    console.log('Button clicked');
-  };
-  
-  on(button, 'click', handleClick);
-  // 解绑事件
-  off(button, 'click', handleClick);
-  ```
-
-#### create_element
-- **功能**: 创建元素
-- **参数**:
-  - `tag_name: string` - 标签名
-  - `options: object` - 元素选项
-- **返回类型**: `Element` - 创建的DOM元素
-- **示例**:
-  ```typescript
-  import { create_element } from '@qy_better_lib/core';
-  
-  // 创建带有类名和样式的元素
-  const element = create_element('div', {
-    class_name: 'container',
-    style: {
-      color: 'red',
-      fontSize: '16px'
-    },
-    attributes: {
-      'data-id': '123'
-    },
-    text: 'Hello World'
-  });
-  
-  document.body.appendChild(element);
-  ```
-
-#### get_element_rect
-- **功能**: 获取元素位置和尺寸
-- **参数**: `element: Element | null` - DOM元素
-- **返回类型**: `DOMRect | null` - 元素位置和尺寸信息
-- **示例**:
-  ```typescript
-  import { get_element_rect } from '@qy_better_lib/core';
-  
-  const element = document.getElementById('container');
-  const rect = get_element_rect(element);
-  if (rect) {
-    console.log(rect.width, rect.height, rect.top, rect.left);
-  }
-  ```
-
-#### get_element_position
-- **功能**: 获取元素相对于文档的位置
-- **参数**: `element: Element | null` - DOM元素
-- **返回类型**: `{ top: number; left: number } | null` - 元素位置信息
-- **示例**:
-  ```typescript
-  import { get_element_position } from '@qy_better_lib/core';
-  
-  const element = document.getElementById('container');
-  const position = get_element_position(element);
-  if (position) {
-    console.log(position.top, position.left);
-  }
-  ```
-
-#### get_element_size
-- **功能**: 获取元素尺寸
-- **参数**: `element: Element | null` - DOM元素
-- **返回类型**: `{ width: number; height: number } | null` - 元素尺寸信息
-- **示例**:
-  ```typescript
-  import { get_element_size } from '@qy_better_lib/core';
-  
-  const element = document.getElementById('container');
-  const size = get_element_size(element);
-  if (size) {
-    console.log(size.width, size.height);
-  }
-  ```
-
-#### scroll_to_element
-- **功能**: 滚动到指定元素
+#### auto_size
+- **功能**: 根据屏幕宽度自动调整尺寸
 - **参数**:
-  - `element: Element | null` - DOM元素
-  - `options: object` - 滚动选项
-- **示例**:
-  ```typescript
-  import { scroll_to_element } from '@qy_better_lib/core';
-  
-  const targetElement = document.getElementById('target');
-  // 滚动到指定元素
-  scroll_to_element(targetElement, {
-    behavior: 'smooth',
-    offsetTop: 100 // 顶部偏移量
-  });
-  ```
-
-#### is_in_viewport
-- **功能**: 检查元素是否在视口中
-- **参数**: `element: Element | null` - DOM元素
-- **返回类型**: `boolean` - 是否在视口中
-- **示例**:
-  ```typescript
-  import { is_in_viewport } from '@qy_better_lib/core';
-  
-  const element = document.getElementById('container');
-  const inViewport = is_in_viewport(element);
-  console.log(inViewport);
-  ```
-
-#### is_completely_in_viewport
-- **功能**: 检查元素是否完全在视口中
-- **参数**: `element: Element | null` - DOM元素
-- **返回类型**: `boolean` - 是否完全在视口中
-- **示例**:
-  ```typescript
-  import { is_completely_in_viewport } from '@qy_better_lib/core';
-  
-  const element = document.getElementById('container');
-  const completelyInViewport = is_completely_in_viewport(element);
-  console.log(completelyInViewport);
-  ```
-
-#### get_window_size
-- **功能**: 获取窗口尺寸
-- **返回类型**: `{ width: number; height: number }` - 窗口尺寸信息
-- **示例**:
-  ```typescript
-  import { get_window_size } from '@qy_better_lib/core';
-  
-  const windowSize = get_window_size();
-  console.log(windowSize.width, windowSize.height);
-  ```
-
-#### get_document_size
-- **功能**: 获取文档尺寸
-- **返回类型**: `{ width: number; height: number }` - 文档尺寸信息
+  - `size: number` - 原始尺寸值
+  - `deflate_width: number` - 基准宽度，默认 1920
+- **返回类型**: `number` - 调整后的尺寸值
 - **示例**:
   ```typescript
-  import { get_document_size } from '@qy_better_lib/core';
+  import { auto_size } from '@qy_better_lib/core';
   
-  const documentSize = get_document_size();
-  console.log(documentSize.width, documentSize.height);
+  // 根据屏幕宽度自动调整字体大小
+  const fontSize = auto_size(16);
+  console.log(fontSize); // 根据当前屏幕宽度计算的值
   ```
 
-### 9. 颜色处理工具 (color.ts)
+### 9. 颜色工具 (color.ts)
 
 #### mix
 - **功能**: 过渡颜色生成
@@ -1922,8 +1723,9 @@
   ```typescript
   import { mix } from '@qy_better_lib/core';
   
+  // 混合红色和蓝色，权重0.5
   const mixedColor = mix('#ff0000', '#0000ff', 0.5);
-  console.log(mixedColor); // 混合后的紫色
+  console.log(mixedColor); // #800080
   ```
 
 #### get_rgb
@@ -1934,14 +1736,14 @@
   ```typescript
   import { get_rgb } from '@qy_better_lib/core';
   
-  const rgbString = get_rgb('#ff0000');
-  console.log(rgbString); // "255,0,0"
+  const rgb = get_rgb('#ff0000');
+  console.log(rgb); // "255,0,0"
   ```
 
 #### hex_to_rgb
 - **功能**: HEX转成RGB对象
 - **参数**: `hex: string` - HEX颜色值
-- **返回类型**: `{ r: number; g: number; b: number } | null` - RGB对象
+- **返回类型**: `{r, g, b} | null` - RGB对象或null
 - **示例**:
   ```typescript
   import { hex_to_rgb } from '@qy_better_lib/core';
@@ -1991,8 +1793,8 @@
   ```typescript
   import { lighten } from '@qy_better_lib/core';
   
-  const lightColor = lighten('#ff0000', 0.2);
-  console.log(lightColor); // 变亮后的红色
+  const lightColor = lighten('#ff0000', 0.5);
+  console.log(lightColor); // #ffffff
   ```
 
 #### darken
@@ -2005,8 +1807,8 @@
   ```typescript
   import { darken } from '@qy_better_lib/core';
   
-  const darkColor = darken('#ff0000', 0.2);
-  console.log(darkColor); // 变暗后的红色
+  const darkColor = darken('#ff0000', 0.5);
+  console.log(darkColor); // #800000
   ```
 
 #### is_light
@@ -2042,26 +1844,13 @@
   import { get_contrast_color } from '@qy_better_lib/core';
   
   const contrastColor = get_contrast_color('#ff0000');
-  console.log(contrastColor); // #000000
+  console.log(contrastColor); // #FFFFFF
   ```
 
-### 10. ECharts 图表工具 (echarts.ts)
-
-#### auto_size
-- **功能**: ECharts图表字体、间距自适应
-- **参数**:
-  - `size: number` - 原始尺寸
-  - `deflate_width: number` - 基准宽度，默认 1920
-- **返回类型**: `number` - 自适应后的尺寸
-- **示例**:
-  ```typescript
-  import { auto_size } from '@qy_better_lib/core';
-  
-  const fontSize = auto_size(14); // 根据屏幕宽度自适应的字体大小
-  ```
+### 10. ECharts 工具 (echarts.ts)
 
 #### get_chart_gradient_color
-- **功能**: ECharts线性渐变颜色
+- **功能**: Echarts线性渐变颜色
 - **参数**:
   - `type: 'v' | 'h'` - 渐变类型，'v'为垂直渐变，'h'为水平渐变
   - `start_color: string` - 起始颜色
@@ -2072,49 +1861,33 @@
   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图表
+- **功能**: 初始化Echarts图表
 - **参数**:
   - `container: HTMLElement | string` - 容器元素或容器ID
-  - `options: object` - 图表配置项
+  - `options?: EChartsOption` - 图表配置项
   - `renderer: 'canvas' | 'svg'` - 渲染方式，默认 'canvas'
-  - `theme: string` - 图表主题，默认 undefined
-- **返回类型**: `Promise<object>` - ECharts实例
+  - `theme?: string` - 主题
+- **返回类型**: `Promise<any>` - Echarts实例
 - **示例**:
   ```typescript
   import { init_chart } from '@qy_better_lib/core';
   
-  async function example() {
-    // 使用默认主题
-    const chart1 = await init_chart('chart-container1', {
-      title: {
-        text: '示例图表'
-      },
-      series: [{
-        type: 'bar',
-        data: [1, 2, 3, 4, 5]
-      }]
+  async function init() {
+    const chart = await init_chart('chart-container', {
+      title: { text: '示例图表' },
+      series: [{ type: 'bar', data: [1, 2, 3] }]
     });
-    
-    // 使用暗色主题
-    const chart2 = await init_chart('chart-container2', {
-      title: {
-        text: '示例图表'
-      },
-      series: [{
-        type: 'bar',
-        data: [1, 2, 3, 4, 5]
-      }]
-    }, 'canvas', 'dark');
+    return chart;
   }
   ```
 
 #### destroy_chart
-- **功能**: 销毁ECharts图表
-- **参数**: `chart: object` - ECharts实例
-- **返回类型**: `void`
+- **功能**: 销毁Echarts图表
+- **参数**: `chart: any` - Echarts实例
 - **示例**:
   ```typescript
   import { destroy_chart } from '@qy_better_lib/core';
@@ -2123,26 +1896,22 @@
   ```
 
 #### update_chart
-- **功能**: 更新ECharts图表配置
+- **功能**: 更新Echarts图表配置
 - **参数**:
-  - `chart: object` - ECharts实例
-  - `options: object` - 图表配置项
-- **返回类型**: `void`
+  - `chart: any` - Echarts实例
+  - `options: EChartsOption` - 图表配置项
 - **示例**:
   ```typescript
   import { update_chart } from '@qy_better_lib/core';
   
   update_chart(chart, {
-    series: [{
-      data: [6, 7, 8, 9, 10]
-    }]
+    series: [{ type: 'bar', data: [4, 5, 6] }]
   });
   ```
 
 #### resize_chart
-- **功能**: 调整ECharts图表大小
-- **参数**: `chart: object` - ECharts实例
-- **返回类型**: `void`
+- **功能**: 调整Echarts图表大小
+- **参数**: `chart: any` - Echarts实例
 - **示例**:
   ```typescript
   import { resize_chart } from '@qy_better_lib/core';
@@ -2151,10 +1920,10 @@
   ```
 
 #### make_chart_responsive
-- **功能**: 为ECharts图表添加响应式处理
+- **功能**: 为Echarts图表添加响应式处理
 - **参数**:
-  - `chart: object` - ECharts实例
-  - `debounce_time: number` - 防抖时间，默认 200ms
+  - `chart: any` - Echarts实例
+  - `debounce_time: number` - 防抖时间，默认200ms
 - **返回类型**: `Function` - 清理函数
 - **示例**:
   ```typescript
@@ -2166,106 +1935,110 @@
   ```
 
 #### generate_chart_colors
-- **功能**: 生成ECharts颜色数组
+- **功能**: 生成Echarts颜色数组
 - **参数**:
   - `count: number` - 颜色数量
-  - `base_colors: string[]` - 基础颜色数组，默认使用ECharts默认颜色
+  - `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数据标签
+- **功能**: 格式化Echarts数据标签
 - **参数**:
   - `value: any` - 数值
-  - `formatter: Function | string` - 格式化函数或格式化模板
+  - `formatter?: ((value: any) => string) | string` - 格式化函数或格式化模板
 - **返回类型**: `string` - 格式化后的值
 - **示例**:
   ```typescript
   import { format_chart_label } from '@qy_better_lib/core';
   
-  const label = format_chart_label(100, '{value}元'); // 100元
+  const label = format_chart_label(123, '{value}件');
+  console.log(label); // 123件
   ```
 
 #### merge_chart_options
-- **功能**: 合并ECharts配置项
+- **功能**: 合并Echarts配置项
 - **参数**:
-  - `defaultOption: object` - 默认配置项
-  - `customOption: object` - 自定义配置项
-- **返回类型**: `object` - 合并后的配置项
+  - `defaultOption: EChartsOption` - 默认配置项
+  - `customOption: EChartsOption` - 自定义配置项
+- **返回类型**: `EChartsOption` - 合并后的配置项
 - **示例**:
   ```typescript
   import { merge_chart_options } from '@qy_better_lib/core';
   
-  const options = merge_chart_options(defaultOptions, customOptions);
+  const options = merge_chart_options(
+    { title: { text: '默认标题' } },
+    { title: { text: '自定义标题' } }
+  );
   ```
 
 #### add_chart_listener
-- **功能**: 为ECharts图表添加事件监听器
+- **功能**: 为Echarts图表添加事件监听器
 - **参数**:
-  - `chart: object` - ECharts实例
+  - `chart: any` - Echarts实例
   - `eventName: string` - 事件名称
-  - `handler: Function` - 事件处理函数
-- **返回类型**: `void`
+  - `handler: (...args: any[]) => void` - 事件处理函数
 - **示例**:
   ```typescript
   import { add_chart_listener } from '@qy_better_lib/core';
   
   add_chart_listener(chart, 'click', (params) => {
-    console.log('图表点击:', params);
+    console.log('点击事件:', params);
   });
   ```
 
 #### remove_chart_listener
-- **功能**: 移除ECharts图表事件监听器
+- **功能**: 移除Echarts图表事件监听器
 - **参数**:
-  - `chart: object` - ECharts实例
+  - `chart: any` - Echarts实例
   - `eventName: string` - 事件名称
-  - `handler: Function` - 事件处理函数
-- **返回类型**: `void`
+  - `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图表为图片
+- **功能**: 导出Echarts图表为图片
 - **参数**:
-  - `chart: object` - ECharts实例
-  - `options: object` - 导出选项
-- **返回类型**: `string` - 图片URL
+  - `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'
+    file_name: 'chart-image'
   });
   ```
 
 #### is_echarts_loaded
-- **功能**: 检查ECharts是否已加载
+- **功能**: 检查Echarts是否已加载
 - **返回类型**: `boolean` - 是否已加载
 - **示例**:
   ```typescript
   import { is_echarts_loaded } from '@qy_better_lib/core';
   
-  if (is_echarts_loaded()) {
-    // ECharts已加载
-  }
+  const loaded = is_echarts_loaded();
+  console.log(loaded);
   ```
 
 #### resize_charts
-- **功能**: 批量调整ECharts图表大小
-- **参数**: `charts: object[]` - 图表实例数组
-- **返回类型**: `void`
+- **功能**: 批量调整Echarts图表大小
+- **参数**: `charts: any[]` - 图表实例数组
 - **示例**:
   ```typescript
   import { resize_charts } from '@qy_better_lib/core';
@@ -2274,9 +2047,8 @@
   ```
 
 #### destroy_charts
-- **功能**: 批量销毁ECharts图表
-- **参数**: `charts: object[]` - 图表实例数组
-- **返回类型**: `void`
+- **功能**: 批量销毁Echarts图表
+- **参数**: `charts: any[]` - 图表实例数组
 - **示例**:
   ```typescript
   import { destroy_charts } from '@qy_better_lib/core';
@@ -2289,13 +2061,14 @@
 - **参数**:
   - `data: any[]` - 原始数据数组
   - `sort_key: string` - 排序字段名
-  - `order: 'asc' | 'desc'` - 排序顺序，默认 'asc'
+  - `order: 'asc' | 'desc'` - 排序顺序，默认'asc'
 - **返回类型**: `any[]` - 排序后的数据数组
 - **示例**:
   ```typescript
   import { sort_chart_data } from '@qy_better_lib/core';
   
-  const sortedData = sort_chart_data(data, 'value', 'desc');
+  const sortedData = sort_chart_data([{ value: 3 }, { value: 1 }, { value: 2 }], 'value');
+  console.log(sortedData);
   ```
 
 #### group_chart_data
@@ -2308,7 +2081,12 @@
   ```typescript
   import { group_chart_data } from '@qy_better_lib/core';
   
-  const groupedData = group_chart_data(data, 'category');
+  const groupedData = group_chart_data([
+    { category: 'A', value: 1 },
+    { category: 'B', value: 2 },
+    { category: 'A', value: 3 }
+  ], 'category');
+  console.log(groupedData);
   ```
 
 #### aggregate_chart_data
@@ -2317,16 +2095,21 @@
   - `data: any[]` - 原始数据数组
   - `group_key: string` - 分组字段名
   - `value_key: string` - 数值字段名
-  - `aggregator: Function` - 聚合函数，默认求和
+  - `aggregator: (values: number[]) => number` - 聚合函数，默认求和
 - **返回类型**: `any[]` - 聚合后的数据数组
 - **示例**:
   ```typescript
   import { aggregate_chart_data } from '@qy_better_lib/core';
   
-  const aggregatedData = aggregate_chart_data(data, 'category', 'value');
+  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)
+### 11. 文件工具 (file.ts)
 
 #### download_file
 - **功能**: 下载文件
@@ -2337,18 +2120,16 @@
   ```typescript
   import { download_file } from '@qy_better_lib/core';
   
-  // 下载文件
-  download_file({ path: 'https://example.com/file.pdf', name: 'document.pdf' });
+  download_file({ path: 'https://example.com/file.pdf', name: 'example.pdf' });
   ```
 
 #### download_files
 - **功能**: 批量下载文件
-- **参数**: `file_list: any[]` - 文件列表，每个元素包含url和name属性
+- **参数**: `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' }
@@ -2363,10 +2144,12 @@
   ```typescript
   import { to_base64 } from '@qy_better_lib/core';
   
-  async function example() {
-    const file = document.querySelector('input[type="file"]').files[0];
-    const base64 = await to_base64(file);
-    console.log(base64);
+  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);
+    }
   }
   ```
 
@@ -2380,10 +2163,12 @@
   ```typescript
   import { read_file } from '@qy_better_lib/core';
   
-  async function example() {
-    const file = document.querySelector('input[type="file"]').files[0];
-    const content = await read_file(file);
-    console.log(content);
+  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);
+    }
   }
   ```
 
@@ -2395,7 +2180,8 @@
   ```typescript
   import { get_file_extension } from '@qy_better_lib/core';
   
-  const ext = get_file_extension('example.jpg'); // 'jpg'
+  const extension = get_file_extension('example.pdf');
+  console.log(extension); // pdf
   ```
 
 #### get_file_name_without_extension
@@ -2406,7 +2192,8 @@
   ```typescript
   import { get_file_name_without_extension } from '@qy_better_lib/core';
   
-  const name = get_file_name_without_extension('example.jpg'); // 'example'
+  const name = get_file_name_without_extension('example.pdf');
+  console.log(name); // example
   ```
 
 #### validate_file_size
@@ -2419,9 +2206,11 @@
   ```typescript
   import { validate_file_size } from '@qy_better_lib/core';
   
-  const file = document.querySelector('input[type="file"]').files[0];
-  const isValid = validate_file_size(file, 1024 * 1024); // 1MB
-  console.log(isValid);
+  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
@@ -2434,9 +2223,11 @@
   ```typescript
   import { validate_file_type } from '@qy_better_lib/core';
   
-  const file = document.querySelector('input[type="file"]').files[0];
-  const isValid = validate_file_type(file, ['jpg', 'png', 'gif']);
-  console.log(isValid);
+  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
@@ -2450,8 +2241,9 @@
   ```typescript
   import { create_file_from_blob } from '@qy_better_lib/core';
   
-  const blob = new Blob(['Hello'], { type: 'text/plain' });
+  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
@@ -2464,7 +2256,6 @@
   ```typescript
   import { download_text_file } from '@qy_better_lib/core';
   
-  // 下载文本文件
   download_text_file('Hello World', 'example.txt');
   ```
 
@@ -2480,10 +2271,12 @@
   ```typescript
   import { compress_image } from '@qy_better_lib/core';
   
-  async function example() {
-    const file = document.querySelector('input[type="file"]').files[0];
-    const compressedFile = await compress_image(file, 1024, 1024, 0.7);
-    console.log(compressedFile);
+  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);
+    }
   }
   ```
 
@@ -2495,9 +2288,11 @@
   ```typescript
   import { get_file_info } from '@qy_better_lib/core';
   
-  const file = document.querySelector('input[type="file"]').files[0];
-  const info = get_file_info(file);
-  console.log(info);
+  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
@@ -2508,7 +2303,7 @@
   ```typescript
   import { generate_unique_file_name } from '@qy_better_lib/core';
   
-  const uniqueName = generate_unique_file_name('example.jpg');
+  const uniqueName = generate_unique_file_name('example.pdf');
   console.log(uniqueName);
   ```
 
@@ -2517,188 +2312,202 @@
 #### tree_flat
 - **功能**: 树形数据扁平化处理
 - **参数**:
-  - `data: TreeNode[]` - 树形数据数组
+  - `data: TreeNode<T>[]` - 树形数据数组
   - `key: string` - key属性，默认"key"
   - `children: string` - children属性，默认"children"
-- **返回类型**: `Record<string, TreeNode>` - 扁平化的树形数据映射
+- **返回类型**: `FlatTreeMap<T>` - 扁平化的树形数据映射
 - **示例**:
   ```typescript
   import { tree_flat } from '@qy_better_lib/core';
   
-  const tree = [
-    {
-      key: '1',
-      name: '节点1',
-      children: [
-        { key: '1-1', name: '节点1-1' }
-      ]
-    }
+  const treeData = [
+    { key: '1', name: '节点1', children: [{ key: '1-1', name: '节点1-1' }] }
   ];
-  const flattened = tree_flat(tree);
-  console.log(flattened); // { '1': { ... }, '1-1': { ... } }
+  const flatMap = tree_flat(treeData);
+  console.log(flatMap);
   ```
 
 #### build_tree
 - **功能**: 从扁平化数据构建树形结构
 - **参数**:
-  - `data: TreeNode[]` - 扁平化数据数组
+  - `data: TreeNode<T>[]` - 扁平化数据数组
   - `key: string` - key属性，默认"key"
   - `parent_key: string` - 父节点key属性，默认"parentId"
   - `children: string` - children属性，默认"children"
-- **返回类型**: `TreeNode[]` - 树形数据
+- **返回类型**: `TreeNode<T>[]` - 树形数据数组
 - **示例**:
   ```typescript
   import { build_tree } from '@qy_better_lib/core';
   
-  const data = [
-    { key: '1', name: '节点1', parentId: null },
+  const flatData = [
+    { key: '1', name: '节点1' },
     { key: '1-1', name: '节点1-1', parentId: '1' }
   ];
-  const tree = build_tree(data);
-  console.log(tree);
+  const treeData = build_tree(flatData);
+  console.log(treeData);
   ```
 
 #### traverse_tree_depth_first
 - **功能**: 深度优先遍历树形数据
 - **参数**:
-  - `tree: TreeNode | TreeNode[]` - 树形数据
-  - `callback: (node: TreeNode, depth: number) => boolean | void` - 回调函数，返回false可中断遍历
+  - `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';
   
-  traverse_tree_depth_first(tree, (node, depth) => {
-    console.log('深度:', depth, '节点:', node.name);
-    // 返回 false 可中断遍历
+  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 | TreeNode[]` - 树形数据
-  - `callback: (node: TreeNode, depth: number) => boolean | void` - 回调函数，返回false可中断遍历
+  - `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';
   
-  traverse_tree_breadth_first(tree, (node, depth) => {
-    console.log('深度:', depth, '节点:', node.name);
+  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 | TreeNode[]` - 树形数据
-  - `predicate: (node: TreeNode) => boolean` - 条件函数
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
+  - `predicate: (node: TreeNode<T>) => boolean` - 条件函数
   - `children: string` - children属性，默认"children"
-- **返回类型**: `TreeNode | null` - 找到的节点或null
+- **返回类型**: `TreeNode<T> | null` - 找到的节点或null
 - **示例**:
   ```typescript
   import { find_tree_node } from '@qy_better_lib/core';
   
-  const node = find_tree_node(tree, (node) => node.name === '节点1-1');
+  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 | TreeNode[]` - 树形数据
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
   - `key_value: any` - key值
   - `key: string` - key属性，默认"key"
   - `children: string` - children属性，默认"children"
-- **返回类型**: `TreeNode | null` - 找到的节点或null
+- **返回类型**: `TreeNode<T> | null` - 找到的节点或null
 - **示例**:
   ```typescript
   import { find_tree_node_by_key } from '@qy_better_lib/core';
   
-  const node = find_tree_node_by_key(tree, '1-1', 'key');
+  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 | TreeNode[]` - 树形数据
-  - `predicate: (node: TreeNode) => boolean` - 过滤条件
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
+  - `predicate: (node: TreeNode<T>) => boolean` - 条件函数
   - `children: string` - children属性，默认"children"
-- **返回类型**: `TreeNode[]` - 过滤后的树形数据
+- **返回类型**: `TreeNode<T>[]` - 过滤后的树形数据
 - **示例**:
   ```typescript
   import { filter_tree } from '@qy_better_lib/core';
   
-  const filtered = filter_tree(tree, (node) => node.name.includes('1'));
-  console.log(filtered);
+  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 | TreeNode[]` - 树形数据
-  - `transform: (node: TreeNode) => TreeNode` - 转换函数
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
+  - `transform: (node: TreeNode<T>) => TreeNode<T>` - 转换函数
   - `children: string` - children属性，默认"children"
-- **返回类型**: `TreeNode[]` - 转换后的树形数据
+- **返回类型**: `TreeNode<T>[]` - 转换后的树形数据
 - **示例**:
   ```typescript
   import { transform_tree } from '@qy_better_lib/core';
   
-  const transformed = transform_tree(tree, (node) => ({
+  const treeData = [
+    { key: '1', name: '节点1' }
+  ];
+  const transformedData = transform_tree(treeData, node => ({
     ...node,
-    label: node.name,
-    value: node.key
+    newProperty: 'value'
   }));
-  console.log(transformed);
+  console.log(transformedData);
   ```
 
 #### add_tree_node_path
 - **功能**: 为树形节点添加路径信息
 - **参数**:
-  - `tree: TreeNode | TreeNode[]` - 树形数据
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
   - `key: string` - key属性，默认"key"
   - `path: string` - path属性，默认"path"
   - `children: string` - children属性，默认"children"
-- **返回类型**: `TreeNode[]` - 添加了路径信息的树形数据
+- **返回类型**: `TreeNode<T>[]` - 添加了路径信息的树形数据
 - **示例**:
   ```typescript
   import { add_tree_node_path } from '@qy_better_lib/core';
   
-  const treeWithPath = add_tree_node_path(tree);
-  console.log(treeWithPath[0].path); // 路径信息，如 "1"
+  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` - 树形节点
+  - `node: TreeNode<T>` - 树形节点
   - `children: string` - children属性，默认"children"
-- **返回类型**: `TreeNode[]` - 所有后代节点数组
+- **返回类型**: `TreeNode<T>[]` - 所有后代节点数组
 - **示例**:
   ```typescript
   import { get_tree_node_descendants } from '@qy_better_lib/core';
   
-  const rootNode = tree[0];
-  const descendants = get_tree_node_descendants(rootNode);
+  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` - 树形节点
+  - `node: TreeNode<T>` - 树形节点
   - `parent: string` - parent属性，默认"parent"
-- **返回类型**: `TreeNode[]` - 所有祖先节点数组
+- **返回类型**: `TreeNode<T>[]` - 所有祖先节点数组
 - **示例**:
   ```typescript
   import { get_tree_node_ancestors } from '@qy_better_lib/core';
   
-  // 假设节点有parent属性指向父节点
-  const childNode = tree[0].children[0];
+  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);
   ```
@@ -2706,253 +2515,167 @@
 #### get_tree_depth
 - **功能**: 计算树形数据的深度
 - **参数**:
-  - `tree: TreeNode | TreeNode[]` - 树形数据
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
   - `children: string` - children属性，默认"children"
 - **返回类型**: `number` - 树形数据的深度
 - **示例**:
   ```typescript
   import { get_tree_depth } from '@qy_better_lib/core';
   
-  const depth = get_tree_depth(tree);
-  console.log(depth);
+  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 | TreeNode[]` - 树形数据
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
   - `children: string` - children属性，默认"children"
-- **返回类型**: `TreeNode[]` - 扁平化的节点数组
+- **返回类型**: `TreeNode<T>[]` - 扁平化的节点数组
 - **示例**:
   ```typescript
   import { flatten_tree_to_array } from '@qy_better_lib/core';
   
-  const array = flatten_tree_to_array(tree);
-  console.log(array);
+  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 | TreeNode[]` - 树形数据
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
   - `parent_key: any` - 父节点key值
-  - `new_node: TreeNode` - 新节点
+  - `new_node: TreeNode<T>` - 新节点
   - `key: string` - key属性，默认"key"
   - `children: string` - children属性，默认"children"
-- **返回类型**: `TreeNode[]` - 更新后的树形数据
+- **返回类型**: `TreeNode<T>[]` - 更新后的树形数据
 - **示例**:
   ```typescript
   import { add_tree_node } from '@qy_better_lib/core';
   
-  const newNode = { key: '1-2', name: '节点1-2' };
-  const newTree = add_tree_node(tree, '1', newNode);
-  console.log(newTree);
+  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 | TreeNode[]` - 树形数据
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
   - `node_key: any` - 要移除的节点key值
   - `key: string` - key属性，默认"key"
   - `children: string` - children属性，默认"children"
-- **返回类型**: `TreeNode[]` - 更新后的树形数据
+- **返回类型**: `TreeNode<T>[]` - 更新后的树形数据
 - **示例**:
   ```typescript
   import { remove_tree_node } from '@qy_better_lib/core';
   
-  const newTree = remove_tree_node(tree, '1-1');
-  console.log(newTree);
+  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 | TreeNode[]` - 树形数据
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
   - `node_key: any` - 要更新的节点key值
-  - `updates: Partial<TreeNode>` - 要更新的属性
+  - `updates: Partial<TreeNode<T>>` - 更新内容
   - `key: string` - key属性，默认"key"
   - `children: string` - children属性，默认"children"
-- **返回类型**: `TreeNode[]` - 更新后的树形数据
+- **返回类型**: `TreeNode<T>[]` - 更新后的树形数据
 - **示例**:
   ```typescript
   import { update_tree_node } from '@qy_better_lib/core';
   
-  const newTree = update_tree_node(tree, '1', { name: '更新的节点1' });
-  console.log(newTree);
+  const treeData = [
+    { key: '1', name: '节点1' }
+  ];
+  const newTreeData = update_tree_node(treeData, '1', { name: '更新后的节点1' });
+  console.log(newTreeData);
   ```
 
 #### sort_tree
 - **功能**: 对树形结构进行排序
 - **参数**:
-  - `tree: TreeNode | TreeNode[]` - 树形数据
-  - `compare_fn: ((a: TreeNode, b: TreeNode) => number) | string` - 比较函数或属性名
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
+  - `compare_fn: ((a: TreeNode<T>, b: TreeNode<T>) => number) | string` - 比较函数或属性名
   - `recursive: boolean` - 是否递归排序所有层级，默认true
   - `children: string` - children属性，默认"children"
-- **返回类型**: `TreeNode[]` - 排序后的树形数据
+- **返回类型**: `TreeNode<T>[]` - 排序后的树形数据
 - **示例**:
   ```typescript
   import { sort_tree } from '@qy_better_lib/core';
   
-  // 使用比较函数排序
-  const sortedTree = sort_tree(tree, (a, b) => a.name.localeCompare(b.name));
-  
-  // 使用属性名排序
-  const sortedTree2 = sort_tree(tree, 'name');
-  console.log(sortedTree);
+  const treeData = [
+    { key: '2', name: '节点2' },
+    { key: '1', name: '节点1' }
+  ];
+  const sortedData = sort_tree(treeData, 'key');
+  console.log(sortedData);
   ```
 
 #### clone_tree
 - **功能**: 克隆树形结构
 - **参数**:
-  - `tree: TreeNode | TreeNode[]` - 树形数据
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
   - `children: string` - children属性，默认"children"
-- **返回类型**: `TreeNode[]` - 克隆后的树形数据
+- **返回类型**: `TreeNode<T>[]` - 克隆后的树形数据
 - **示例**:
   ```typescript
   import { clone_tree } from '@qy_better_lib/core';
   
-  const clonedTree = clone_tree(tree);
-  console.log(clonedTree);
+  const treeData = [
+    { key: '1', name: '节点1' }
+  ];
+  const clonedData = clone_tree(treeData);
+  console.log(clonedData);
   ```
 
 #### validate_tree
 - **功能**: 验证树形结构的有效性
 - **参数**:
-  - `tree: TreeNode | TreeNode[]` - 树形数据
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
   - `key: string` - key属性，默认"key"
   - `children: string` - children属性，默认"children"
-- **返回类型**: `{ valid: boolean; errors: string[] }` - 验证结果，包含是否有效和错误信息
+- **返回类型**: `{ valid: boolean; errors: string[] }` - 验证结果
 - **示例**:
   ```typescript
   import { validate_tree } from '@qy_better_lib/core';
   
-  const result = validate_tree(tree);
-  console.log(result.valid); // 是否有效
-  console.log(result.errors); // 错误信息
+  const treeData = [
+    { key: '1', name: '节点1' }
+  ];
+  const result = validate_tree(treeData);
+  console.log(result);
   ```
 
 #### search_tree
 - **功能**: 在树形结构中搜索节点
 - **参数**:
-  - `tree: TreeNode | TreeNode[]` - 树形数据
-  - `predicate: ((node: TreeNode) => boolean) | Record<string, any>` - 搜索条件函数或属性值对
+  - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
+  - `predicate: ((node: TreeNode<T>) => boolean) | Record<string, any>` - 搜索条件函数或属性值对
   - `children: string` - children属性，默认"children"
-- **返回类型**: `TreeNode[]` - 所有匹配的节点数组
+- **返回类型**: `TreeNode<T>[]` - 所有匹配的节点数组
 - **示例**:
   ```typescript
   import { search_tree } from '@qy_better_lib/core';
   
-  // 使用函数搜索
-  const results = search_tree(tree, (node) => node.name.includes('1'));
-  
-  // 使用对象搜索
-  const results2 = search_tree(tree, { name: '节点1' });
+  const treeData = [
+    { key: '1', name: '节点1', value: 10 },
+    { key: '2', name: '节点2', value: 20 }
+  ];
+  const results = search_tree(treeData, { value: 10 });
   console.log(results);
   ```
-
-## 指令功能 (directives)
-
-### 1. 点击外部区域指令 (click_outside.ts)
-
-#### 功能描述
-当点击元素外部区域时触发绑定的回调函数，可用于实现下拉菜单、弹窗等组件的关闭功能。
-
-#### 指令参数
-- **value**: `Function` - 点击外部区域时触发的回调函数
-- **arg**: `HTMLElement | HTMLElement[]` - 可选，需要排除的元素或元素数组
-
-#### 使用示例
-
-**基本用法**
-```vue
-<template>
-  <div v-click-outside="handleClickOutside">
-    点击外部区域会触发回调
-  </div>
-</template>
-
-<script setup lang="ts">
-import { ref } from 'vue';
-
-const handleClickOutside = () => {
-  console.log('点击了外部区域');
-};
-</script>
-```
-
-**带排除元素**
-```vue
-<template>
-  <div>
-    <div ref="excludeElement">
-      点击此区域不会触发外部点击回调
-    </div>
-    <div v-click-outside:[excludeElement]="handleClickOutside">
-      点击外部区域会触发回调，但点击上方排除元素不会
-    </div>
-  </div>
-</template>
-
-<script setup lang="ts">
-import { ref } from 'vue';
-
-const excludeElement = ref<HTMLElement | null>(null);
-
-const handleClickOutside = () => {
-  console.log('点击了外部区域');
-};
-</script>
-```
-
-**带多个排除元素**
-```vue
-<template>
-  <div>
-    <div ref="excludeElement1">
-      排除元素 1
-    </div>
-    <div ref="excludeElement2">
-      排除元素 2
-    </div>
-    <div v-click-outside:[excludeElements]="handleClickOutside">
-      点击外部区域会触发回调，但点击排除元素不会
-    </div>
-  </div>
-</template>
-
-<script setup lang="ts">
-import { ref, computed } from 'vue';
-
-const excludeElement1 = ref<HTMLElement | null>(null);
-const excludeElement2 = ref<HTMLElement | null>(null);
-
-const excludeElements = computed(() => [
-  excludeElement1.value,
-  excludeElement2.value
-]);
-
-const handleClickOutside = () => {
-  console.log('点击了外部区域');
-};
-</script>
-```
-
-#### 注册指令
-
-在 Vue 应用中注册指令：
-
-```typescript
-import { createApp } from 'vue';
-import App from './App.vue';
-import { setupDirectives } from '@qy_better_lib/core';
-
-const app = createApp(App);
-
-// 注册所有指令
-setupDirectives(app);
-
-app.mount('#app');
-```
-
-
+