@qy_better_lib/core 0.2.6 → 0.2.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/DOCUMENTATION.md CHANGED
@@ -1,4 +1,4 @@
1
- # QY Better Lib Core - 工具函数文档
1
+ # QY Better Lib Core - 工具函数文档
2
2
 
3
3
  本文档详细介绍了 QY Better Lib Core 包中的工具函数,包括功能描述、参数说明、返回类型和使用示例。
4
4
 
@@ -1695,223 +1695,22 @@
1695
1695
  });
1696
1696
  ```
1697
1697
 
1698
- #### get_attribute
1699
- - **功能**: 获取元素属性
1700
- - **参数**:
1701
- - `element: Element | null` - DOM元素
1702
- - `attribute: string` - 属性名
1703
- - **返回类型**: `string` - 属性值
1704
- - **示例**:
1705
- ```typescript
1706
- import { get_attribute } from '@qy_better_lib/core';
1707
-
1708
- const element = document.getElementById('link');
1709
- const href = get_attribute(element, 'href');
1710
- console.log(href);
1711
- ```
1712
-
1713
- #### set_attribute
1714
- - **功能**: 设置元素属性
1715
- - **参数**:
1716
- - `element: Element | null` - DOM元素
1717
- - `attribute: string` - 属性名
1718
- - `value: string` - 属性值
1719
- - **示例**:
1720
- ```typescript
1721
- import { set_attribute } from '@qy_better_lib/core';
1722
-
1723
- const element = document.getElementById('link');
1724
- set_attribute(element, 'href', 'https://example.com');
1725
- ```
1726
-
1727
- #### remove_attribute
1728
- - **功能**: 移除元素属性
1729
- - **参数**:
1730
- - `element: Element | null` - DOM元素
1731
- - `attribute: string` - 属性名
1732
- - **示例**:
1733
- ```typescript
1734
- import { remove_attribute } from '@qy_better_lib/core';
1735
-
1736
- const element = document.getElementById('link');
1737
- remove_attribute(element, 'href');
1738
- ```
1739
-
1740
- #### on
1741
- - **功能**: 绑定事件
1742
- - **参数**:
1743
- - `element: Element | Window | Document | null` - DOM元素、窗口或文档
1744
- - `event: string` - 事件名
1745
- - `handler: EventListener` - 事件处理函数
1746
- - `options: AddEventListenerOptions` - 事件选项
1747
- - **示例**:
1748
- ```typescript
1749
- import { on } from '@qy_better_lib/core';
1750
-
1751
- const button = document.getElementById('button');
1752
- on(button, 'click', () => {
1753
- console.log('Button clicked');
1754
- });
1755
- ```
1756
-
1757
- #### off
1758
- - **功能**: 解绑事件
1759
- - **参数**:
1760
- - `element: Element | Window | Document | null` - DOM元素、窗口或文档
1761
- - `event: string` - 事件名
1762
- - `handler: EventListener` - 事件处理函数
1763
- - `options: EventListenerOptions` - 事件选项
1764
- - **示例**:
1765
- ```typescript
1766
- import { off } from '@qy_better_lib/core';
1767
-
1768
- const button = document.getElementById('button');
1769
- const handleClick = () => {
1770
- console.log('Button clicked');
1771
- };
1772
-
1773
- on(button, 'click', handleClick);
1774
- // 解绑事件
1775
- off(button, 'click', handleClick);
1776
- ```
1777
-
1778
- #### create_element
1779
- - **功能**: 创建元素
1780
- - **参数**:
1781
- - `tag_name: string` - 标签名
1782
- - `options: object` - 元素选项
1783
- - **返回类型**: `Element` - 创建的DOM元素
1784
- - **示例**:
1785
- ```typescript
1786
- import { create_element } from '@qy_better_lib/core';
1787
-
1788
- // 创建带有类名和样式的元素
1789
- const element = create_element('div', {
1790
- class_name: 'container',
1791
- style: {
1792
- color: 'red',
1793
- fontSize: '16px'
1794
- },
1795
- attributes: {
1796
- 'data-id': '123'
1797
- },
1798
- text: 'Hello World'
1799
- });
1800
-
1801
- document.body.appendChild(element);
1802
- ```
1803
-
1804
- #### get_element_rect
1805
- - **功能**: 获取元素位置和尺寸
1806
- - **参数**: `element: Element | null` - DOM元素
1807
- - **返回类型**: `DOMRect | null` - 元素位置和尺寸信息
1808
- - **示例**:
1809
- ```typescript
1810
- import { get_element_rect } from '@qy_better_lib/core';
1811
-
1812
- const element = document.getElementById('container');
1813
- const rect = get_element_rect(element);
1814
- if (rect) {
1815
- console.log(rect.width, rect.height, rect.top, rect.left);
1816
- }
1817
- ```
1818
-
1819
- #### get_element_position
1820
- - **功能**: 获取元素相对于文档的位置
1821
- - **参数**: `element: Element | null` - DOM元素
1822
- - **返回类型**: `{ top: number; left: number } | null` - 元素位置信息
1823
- - **示例**:
1824
- ```typescript
1825
- import { get_element_position } from '@qy_better_lib/core';
1826
-
1827
- const element = document.getElementById('container');
1828
- const position = get_element_position(element);
1829
- if (position) {
1830
- console.log(position.top, position.left);
1831
- }
1832
- ```
1833
-
1834
- #### get_element_size
1835
- - **功能**: 获取元素尺寸
1836
- - **参数**: `element: Element | null` - DOM元素
1837
- - **返回类型**: `{ width: number; height: number } | null` - 元素尺寸信息
1838
- - **示例**:
1839
- ```typescript
1840
- import { get_element_size } from '@qy_better_lib/core';
1841
-
1842
- const element = document.getElementById('container');
1843
- const size = get_element_size(element);
1844
- if (size) {
1845
- console.log(size.width, size.height);
1846
- }
1847
- ```
1848
-
1849
- #### scroll_to_element
1850
- - **功能**: 滚动到指定元素
1698
+ #### auto_size
1699
+ - **功能**: 根据屏幕宽度自动调整尺寸
1851
1700
  - **参数**:
1852
- - `element: Element | null` - DOM元素
1853
- - `options: object` - 滚动选项
1854
- - **示例**:
1855
- ```typescript
1856
- import { scroll_to_element } from '@qy_better_lib/core';
1857
-
1858
- const targetElement = document.getElementById('target');
1859
- // 滚动到指定元素
1860
- scroll_to_element(targetElement, {
1861
- behavior: 'smooth',
1862
- offsetTop: 100 // 顶部偏移量
1863
- });
1864
- ```
1865
-
1866
- #### is_in_viewport
1867
- - **功能**: 检查元素是否在视口中
1868
- - **参数**: `element: Element | null` - DOM元素
1869
- - **返回类型**: `boolean` - 是否在视口中
1870
- - **示例**:
1871
- ```typescript
1872
- import { is_in_viewport } from '@qy_better_lib/core';
1873
-
1874
- const element = document.getElementById('container');
1875
- const inViewport = is_in_viewport(element);
1876
- console.log(inViewport);
1877
- ```
1878
-
1879
- #### is_completely_in_viewport
1880
- - **功能**: 检查元素是否完全在视口中
1881
- - **参数**: `element: Element | null` - DOM元素
1882
- - **返回类型**: `boolean` - 是否完全在视口中
1883
- - **示例**:
1884
- ```typescript
1885
- import { is_completely_in_viewport } from '@qy_better_lib/core';
1886
-
1887
- const element = document.getElementById('container');
1888
- const completelyInViewport = is_completely_in_viewport(element);
1889
- console.log(completelyInViewport);
1890
- ```
1891
-
1892
- #### get_window_size
1893
- - **功能**: 获取窗口尺寸
1894
- - **返回类型**: `{ width: number; height: number }` - 窗口尺寸信息
1895
- - **示例**:
1896
- ```typescript
1897
- import { get_window_size } from '@qy_better_lib/core';
1898
-
1899
- const windowSize = get_window_size();
1900
- console.log(windowSize.width, windowSize.height);
1901
- ```
1902
-
1903
- #### get_document_size
1904
- - **功能**: 获取文档尺寸
1905
- - **返回类型**: `{ width: number; height: number }` - 文档尺寸信息
1701
+ - `size: number` - 原始尺寸值
1702
+ - `deflate_width: number` - 基准宽度,默认 1920
1703
+ - **返回类型**: `number` - 调整后的尺寸值
1906
1704
  - **示例**:
1907
1705
  ```typescript
1908
- import { get_document_size } from '@qy_better_lib/core';
1706
+ import { auto_size } from '@qy_better_lib/core';
1909
1707
 
1910
- const documentSize = get_document_size();
1911
- console.log(documentSize.width, documentSize.height);
1708
+ // 根据屏幕宽度自动调整字体大小
1709
+ const fontSize = auto_size(16);
1710
+ console.log(fontSize); // 根据当前屏幕宽度计算的值
1912
1711
  ```
1913
1712
 
1914
- ### 9. 颜色处理工具 (color.ts)
1713
+ ### 9. 颜色工具 (color.ts)
1915
1714
 
1916
1715
  #### mix
1917
1716
  - **功能**: 过渡颜色生成
@@ -1924,8 +1723,9 @@
1924
1723
  ```typescript
1925
1724
  import { mix } from '@qy_better_lib/core';
1926
1725
 
1726
+ // 混合红色和蓝色,权重0.5
1927
1727
  const mixedColor = mix('#ff0000', '#0000ff', 0.5);
1928
- console.log(mixedColor); // 混合后的紫色
1728
+ console.log(mixedColor); // #800080
1929
1729
  ```
1930
1730
 
1931
1731
  #### get_rgb
@@ -1936,14 +1736,14 @@
1936
1736
  ```typescript
1937
1737
  import { get_rgb } from '@qy_better_lib/core';
1938
1738
 
1939
- const rgbString = get_rgb('#ff0000');
1940
- console.log(rgbString); // "255,0,0"
1739
+ const rgb = get_rgb('#ff0000');
1740
+ console.log(rgb); // "255,0,0"
1941
1741
  ```
1942
1742
 
1943
1743
  #### hex_to_rgb
1944
1744
  - **功能**: HEX转成RGB对象
1945
1745
  - **参数**: `hex: string` - HEX颜色值
1946
- - **返回类型**: `{ r: number; g: number; b: number } | null` - RGB对象
1746
+ - **返回类型**: `{r, g, b} | null` - RGB对象或null
1947
1747
  - **示例**:
1948
1748
  ```typescript
1949
1749
  import { hex_to_rgb } from '@qy_better_lib/core';
@@ -1993,8 +1793,8 @@
1993
1793
  ```typescript
1994
1794
  import { lighten } from '@qy_better_lib/core';
1995
1795
 
1996
- const lightColor = lighten('#ff0000', 0.2);
1997
- console.log(lightColor); // 变亮后的红色
1796
+ const lightColor = lighten('#ff0000', 0.5);
1797
+ console.log(lightColor); // #ffffff
1998
1798
  ```
1999
1799
 
2000
1800
  #### darken
@@ -2007,8 +1807,8 @@
2007
1807
  ```typescript
2008
1808
  import { darken } from '@qy_better_lib/core';
2009
1809
 
2010
- const darkColor = darken('#ff0000', 0.2);
2011
- console.log(darkColor); // 变暗后的红色
1810
+ const darkColor = darken('#ff0000', 0.5);
1811
+ console.log(darkColor); // #800000
2012
1812
  ```
2013
1813
 
2014
1814
  #### is_light
@@ -2044,26 +1844,13 @@
2044
1844
  import { get_contrast_color } from '@qy_better_lib/core';
2045
1845
 
2046
1846
  const contrastColor = get_contrast_color('#ff0000');
2047
- console.log(contrastColor); // #000000
1847
+ console.log(contrastColor); // #FFFFFF
2048
1848
  ```
2049
1849
 
2050
- ### 10. ECharts 图表工具 (echarts.ts)
2051
-
2052
- #### auto_size
2053
- - **功能**: ECharts图表字体、间距自适应
2054
- - **参数**:
2055
- - `size: number` - 原始尺寸
2056
- - `deflate_width: number` - 基准宽度,默认 1920
2057
- - **返回类型**: `number` - 自适应后的尺寸
2058
- - **示例**:
2059
- ```typescript
2060
- import { auto_size } from '@qy_better_lib/core/echarts';
2061
-
2062
- const fontSize = auto_size(14); // 根据屏幕宽度自适应的字体大小
2063
- ```
1850
+ ### 10. ECharts 工具 (echarts.ts)
2064
1851
 
2065
1852
  #### get_chart_gradient_color
2066
- - **功能**: ECharts线性渐变颜色
1853
+ - **功能**: Echarts线性渐变颜色
2067
1854
  - **参数**:
2068
1855
  - `type: 'v' | 'h'` - 渐变类型,'v'为垂直渐变,'h'为水平渐变
2069
1856
  - `start_color: string` - 起始颜色
@@ -2071,96 +1858,76 @@
2071
1858
  - **返回类型**: `object` - 渐变配置对象
2072
1859
  - **示例**:
2073
1860
  ```typescript
2074
- import { get_chart_gradient_color } from '@qy_better_lib/core/echarts';
1861
+ import { get_chart_gradient_color } from '@qy_better_lib/core';
2075
1862
 
2076
1863
  const gradient = get_chart_gradient_color('v', '#ff0000', '#0000ff');
1864
+ console.log(gradient);
2077
1865
  ```
2078
1866
 
2079
1867
  #### init_chart
2080
- - **功能**: 初始化ECharts图表
1868
+ - **功能**: 初始化Echarts图表
2081
1869
  - **参数**:
2082
1870
  - `container: HTMLElement | string` - 容器元素或容器ID
2083
- - `options: object` - 图表配置项
1871
+ - `options?: EChartsOption` - 图表配置项
2084
1872
  - `renderer: 'canvas' | 'svg'` - 渲染方式,默认 'canvas'
2085
- - `theme: string` - 图表主题,默认 undefined
2086
- - **返回类型**: `Promise<object>` - ECharts实例
1873
+ - `theme?: string` - 主题
1874
+ - **返回类型**: `Promise<any>` - Echarts实例
2087
1875
  - **示例**:
2088
1876
  ```typescript
2089
- import { init_chart } from '@qy_better_lib/core/echarts';
1877
+ import { init_chart } from '@qy_better_lib/core';
2090
1878
 
2091
- async function example() {
2092
- // 使用默认主题
2093
- const chart1 = await init_chart('chart-container1', {
2094
- title: {
2095
- text: '示例图表'
2096
- },
2097
- series: [{
2098
- type: 'bar',
2099
- data: [1, 2, 3, 4, 5]
2100
- }]
1879
+ async function init() {
1880
+ const chart = await init_chart('chart-container', {
1881
+ title: { text: '示例图表' },
1882
+ series: [{ type: 'bar', data: [1, 2, 3] }]
2101
1883
  });
2102
-
2103
- // 使用暗色主题
2104
- const chart2 = await init_chart('chart-container2', {
2105
- title: {
2106
- text: '示例图表'
2107
- },
2108
- series: [{
2109
- type: 'bar',
2110
- data: [1, 2, 3, 4, 5]
2111
- }]
2112
- }, 'canvas', 'dark');
1884
+ return chart;
2113
1885
  }
2114
1886
  ```
2115
1887
 
2116
1888
  #### destroy_chart
2117
- - **功能**: 销毁ECharts图表
2118
- - **参数**: `chart: object` - ECharts实例
2119
- - **返回类型**: `void`
1889
+ - **功能**: 销毁Echarts图表
1890
+ - **参数**: `chart: any` - Echarts实例
2120
1891
  - **示例**:
2121
1892
  ```typescript
2122
- import { destroy_chart } from '@qy_better_lib/core/echarts';
1893
+ import { destroy_chart } from '@qy_better_lib/core';
2123
1894
 
2124
1895
  destroy_chart(chart);
2125
1896
  ```
2126
1897
 
2127
1898
  #### update_chart
2128
- - **功能**: 更新ECharts图表配置
1899
+ - **功能**: 更新Echarts图表配置
2129
1900
  - **参数**:
2130
- - `chart: object` - ECharts实例
2131
- - `options: object` - 图表配置项
2132
- - **返回类型**: `void`
1901
+ - `chart: any` - Echarts实例
1902
+ - `options: EChartsOption` - 图表配置项
2133
1903
  - **示例**:
2134
1904
  ```typescript
2135
- import { update_chart } from '@qy_better_lib/core/echarts';
1905
+ import { update_chart } from '@qy_better_lib/core';
2136
1906
 
2137
1907
  update_chart(chart, {
2138
- series: [{
2139
- data: [6, 7, 8, 9, 10]
2140
- }]
1908
+ series: [{ type: 'bar', data: [4, 5, 6] }]
2141
1909
  });
2142
1910
  ```
2143
1911
 
2144
1912
  #### resize_chart
2145
- - **功能**: 调整ECharts图表大小
2146
- - **参数**: `chart: object` - ECharts实例
2147
- - **返回类型**: `void`
1913
+ - **功能**: 调整Echarts图表大小
1914
+ - **参数**: `chart: any` - Echarts实例
2148
1915
  - **示例**:
2149
1916
  ```typescript
2150
- import { resize_chart } from '@qy_better_lib/core/echarts';
1917
+ import { resize_chart } from '@qy_better_lib/core';
2151
1918
 
2152
1919
  resize_chart(chart);
2153
1920
  ```
2154
1921
 
2155
1922
  #### make_chart_responsive
2156
- - **功能**: 为ECharts图表添加响应式处理
1923
+ - **功能**: 为Echarts图表添加响应式处理
2157
1924
  - **参数**:
2158
- - `chart: object` - ECharts实例
2159
- - `debounce_time: number` - 防抖时间,默认 200ms
1925
+ - `chart: any` - Echarts实例
1926
+ - `debounce_time: number` - 防抖时间,默认200ms
2160
1927
  - **返回类型**: `Function` - 清理函数
2161
1928
  - **示例**:
2162
1929
  ```typescript
2163
- import { make_chart_responsive } from '@qy_better_lib/core/echarts';
1930
+ import { make_chart_responsive } from '@qy_better_lib/core';
2164
1931
 
2165
1932
  const cleanup = make_chart_responsive(chart);
2166
1933
  // 当需要清理时调用
@@ -2168,106 +1935,110 @@
2168
1935
  ```
2169
1936
 
2170
1937
  #### generate_chart_colors
2171
- - **功能**: 生成ECharts颜色数组
1938
+ - **功能**: 生成Echarts颜色数组
2172
1939
  - **参数**:
2173
1940
  - `count: number` - 颜色数量
2174
- - `base_colors: string[]` - 基础颜色数组,默认使用ECharts默认颜色
1941
+ - `base_colors?: string[]` - 基础颜色数组,默认使用ECharts默认颜色
2175
1942
  - **返回类型**: `string[]` - 颜色数组
2176
1943
  - **示例**:
2177
1944
  ```typescript
2178
- import { generate_chart_colors } from '@qy_better_lib/core/echarts';
1945
+ import { generate_chart_colors } from '@qy_better_lib/core';
2179
1946
 
2180
1947
  const colors = generate_chart_colors(5);
1948
+ console.log(colors);
2181
1949
  ```
2182
1950
 
2183
1951
  #### format_chart_label
2184
- - **功能**: 格式化ECharts数据标签
1952
+ - **功能**: 格式化Echarts数据标签
2185
1953
  - **参数**:
2186
1954
  - `value: any` - 数值
2187
- - `formatter: Function | string` - 格式化函数或格式化模板
1955
+ - `formatter?: ((value: any) => string) | string` - 格式化函数或格式化模板
2188
1956
  - **返回类型**: `string` - 格式化后的值
2189
1957
  - **示例**:
2190
1958
  ```typescript
2191
- import { format_chart_label } from '@qy_better_lib/core/echarts';
1959
+ import { format_chart_label } from '@qy_better_lib/core';
2192
1960
 
2193
- const label = format_chart_label(100, '{value}'); // 100元
1961
+ const label = format_chart_label(123, '{value}');
1962
+ console.log(label); // 123件
2194
1963
  ```
2195
1964
 
2196
1965
  #### merge_chart_options
2197
- - **功能**: 合并ECharts配置项
1966
+ - **功能**: 合并Echarts配置项
2198
1967
  - **参数**:
2199
- - `defaultOption: object` - 默认配置项
2200
- - `customOption: object` - 自定义配置项
2201
- - **返回类型**: `object` - 合并后的配置项
1968
+ - `defaultOption: EChartsOption` - 默认配置项
1969
+ - `customOption: EChartsOption` - 自定义配置项
1970
+ - **返回类型**: `EChartsOption` - 合并后的配置项
2202
1971
  - **示例**:
2203
1972
  ```typescript
2204
1973
  import { merge_chart_options } from '@qy_better_lib/core';
2205
1974
 
2206
- const options = merge_chart_options(defaultOptions, customOptions);
1975
+ const options = merge_chart_options(
1976
+ { title: { text: '默认标题' } },
1977
+ { title: { text: '自定义标题' } }
1978
+ );
2207
1979
  ```
2208
1980
 
2209
1981
  #### add_chart_listener
2210
- - **功能**: 为ECharts图表添加事件监听器
1982
+ - **功能**: 为Echarts图表添加事件监听器
2211
1983
  - **参数**:
2212
- - `chart: object` - ECharts实例
1984
+ - `chart: any` - Echarts实例
2213
1985
  - `eventName: string` - 事件名称
2214
- - `handler: Function` - 事件处理函数
2215
- - **返回类型**: `void`
1986
+ - `handler: (...args: any[]) => void` - 事件处理函数
2216
1987
  - **示例**:
2217
1988
  ```typescript
2218
1989
  import { add_chart_listener } from '@qy_better_lib/core';
2219
1990
 
2220
1991
  add_chart_listener(chart, 'click', (params) => {
2221
- console.log('图表点击:', params);
1992
+ console.log('点击事件:', params);
2222
1993
  });
2223
1994
  ```
2224
1995
 
2225
1996
  #### remove_chart_listener
2226
- - **功能**: 移除ECharts图表事件监听器
1997
+ - **功能**: 移除Echarts图表事件监听器
2227
1998
  - **参数**:
2228
- - `chart: object` - ECharts实例
1999
+ - `chart: any` - Echarts实例
2229
2000
  - `eventName: string` - 事件名称
2230
- - `handler: Function` - 事件处理函数
2231
- - **返回类型**: `void`
2001
+ - `handler: (...args: any[]) => void` - 事件处理函数
2232
2002
  - **示例**:
2233
2003
  ```typescript
2234
2004
  import { remove_chart_listener } from '@qy_better_lib/core';
2235
2005
 
2006
+ const handler = (params) => console.log('点击事件:', params);
2007
+ add_chart_listener(chart, 'click', handler);
2008
+ // 稍后移除
2236
2009
  remove_chart_listener(chart, 'click', handler);
2237
2010
  ```
2238
2011
 
2239
2012
  #### export_chart_image
2240
- - **功能**: 导出ECharts图表为图片
2013
+ - **功能**: 导出Echarts图表为图片
2241
2014
  - **参数**:
2242
- - `chart: object` - ECharts实例
2243
- - `options: object` - 导出选项
2244
- - **返回类型**: `string` - 图片URL
2015
+ - `chart: any` - Echarts实例
2016
+ - `options?: object` - 导出选项
2017
+ - **返回类型**: `string | null` - 图片URL
2245
2018
  - **示例**:
2246
2019
  ```typescript
2247
2020
  import { export_chart_image } from '@qy_better_lib/core';
2248
2021
 
2249
2022
  const imageUrl = export_chart_image(chart, {
2250
2023
  type: 'png',
2251
- file_name: 'chart'
2024
+ file_name: 'chart-image'
2252
2025
  });
2253
2026
  ```
2254
2027
 
2255
2028
  #### is_echarts_loaded
2256
- - **功能**: 检查ECharts是否已加载
2029
+ - **功能**: 检查Echarts是否已加载
2257
2030
  - **返回类型**: `boolean` - 是否已加载
2258
2031
  - **示例**:
2259
2032
  ```typescript
2260
2033
  import { is_echarts_loaded } from '@qy_better_lib/core';
2261
2034
 
2262
- if (is_echarts_loaded()) {
2263
- // ECharts已加载
2264
- }
2035
+ const loaded = is_echarts_loaded();
2036
+ console.log(loaded);
2265
2037
  ```
2266
2038
 
2267
2039
  #### resize_charts
2268
- - **功能**: 批量调整ECharts图表大小
2269
- - **参数**: `charts: object[]` - 图表实例数组
2270
- - **返回类型**: `void`
2040
+ - **功能**: 批量调整Echarts图表大小
2041
+ - **参数**: `charts: any[]` - 图表实例数组
2271
2042
  - **示例**:
2272
2043
  ```typescript
2273
2044
  import { resize_charts } from '@qy_better_lib/core';
@@ -2276,9 +2047,8 @@
2276
2047
  ```
2277
2048
 
2278
2049
  #### destroy_charts
2279
- - **功能**: 批量销毁ECharts图表
2280
- - **参数**: `charts: object[]` - 图表实例数组
2281
- - **返回类型**: `void`
2050
+ - **功能**: 批量销毁Echarts图表
2051
+ - **参数**: `charts: any[]` - 图表实例数组
2282
2052
  - **示例**:
2283
2053
  ```typescript
2284
2054
  import { destroy_charts } from '@qy_better_lib/core';
@@ -2291,13 +2061,14 @@
2291
2061
  - **参数**:
2292
2062
  - `data: any[]` - 原始数据数组
2293
2063
  - `sort_key: string` - 排序字段名
2294
- - `order: 'asc' | 'desc'` - 排序顺序,默认 'asc'
2064
+ - `order: 'asc' | 'desc'` - 排序顺序,默认'asc'
2295
2065
  - **返回类型**: `any[]` - 排序后的数据数组
2296
2066
  - **示例**:
2297
2067
  ```typescript
2298
2068
  import { sort_chart_data } from '@qy_better_lib/core';
2299
2069
 
2300
- const sortedData = sort_chart_data(data, 'value', 'desc');
2070
+ const sortedData = sort_chart_data([{ value: 3 }, { value: 1 }, { value: 2 }], 'value');
2071
+ console.log(sortedData);
2301
2072
  ```
2302
2073
 
2303
2074
  #### group_chart_data
@@ -2310,7 +2081,12 @@
2310
2081
  ```typescript
2311
2082
  import { group_chart_data } from '@qy_better_lib/core';
2312
2083
 
2313
- const groupedData = group_chart_data(data, 'category');
2084
+ const groupedData = group_chart_data([
2085
+ { category: 'A', value: 1 },
2086
+ { category: 'B', value: 2 },
2087
+ { category: 'A', value: 3 }
2088
+ ], 'category');
2089
+ console.log(groupedData);
2314
2090
  ```
2315
2091
 
2316
2092
  #### aggregate_chart_data
@@ -2319,16 +2095,21 @@
2319
2095
  - `data: any[]` - 原始数据数组
2320
2096
  - `group_key: string` - 分组字段名
2321
2097
  - `value_key: string` - 数值字段名
2322
- - `aggregator: Function` - 聚合函数,默认求和
2098
+ - `aggregator: (values: number[]) => number` - 聚合函数,默认求和
2323
2099
  - **返回类型**: `any[]` - 聚合后的数据数组
2324
2100
  - **示例**:
2325
2101
  ```typescript
2326
2102
  import { aggregate_chart_data } from '@qy_better_lib/core';
2327
2103
 
2328
- const aggregatedData = aggregate_chart_data(data, 'category', 'value');
2104
+ const aggregatedData = aggregate_chart_data([
2105
+ { category: 'A', value: 1 },
2106
+ { category: 'A', value: 3 },
2107
+ { category: 'B', value: 2 }
2108
+ ], 'category', 'value');
2109
+ console.log(aggregatedData);
2329
2110
  ```
2330
2111
 
2331
- ### 11. 文件操作工具 (file.ts)
2112
+ ### 11. 文件工具 (file.ts)
2332
2113
 
2333
2114
  #### download_file
2334
2115
  - **功能**: 下载文件
@@ -2339,18 +2120,16 @@
2339
2120
  ```typescript
2340
2121
  import { download_file } from '@qy_better_lib/core';
2341
2122
 
2342
- // 下载文件
2343
- download_file({ path: 'https://example.com/file.pdf', name: 'document.pdf' });
2123
+ download_file({ path: 'https://example.com/file.pdf', name: 'example.pdf' });
2344
2124
  ```
2345
2125
 
2346
2126
  #### download_files
2347
2127
  - **功能**: 批量下载文件
2348
- - **参数**: `file_list: any[]` - 文件列表,每个元素包含url和name属性
2128
+ - **参数**: `file_list: any[]` - 文件列表
2349
2129
  - **示例**:
2350
2130
  ```typescript
2351
2131
  import { download_files } from '@qy_better_lib/core';
2352
2132
 
2353
- // 批量下载文件
2354
2133
  download_files([
2355
2134
  { url: 'https://example.com/file1.pdf', name: 'file1.pdf' },
2356
2135
  { url: 'https://example.com/file2.pdf', name: 'file2.pdf' }
@@ -2365,10 +2144,12 @@
2365
2144
  ```typescript
2366
2145
  import { to_base64 } from '@qy_better_lib/core';
2367
2146
 
2368
- async function example() {
2369
- const file = document.querySelector('input[type="file"]').files[0];
2370
- const base64 = await to_base64(file);
2371
- console.log(base64);
2147
+ async function convert() {
2148
+ const input = document.querySelector('input[type="file"]');
2149
+ if (input.files[0]) {
2150
+ const base64 = await to_base64(input.files[0]);
2151
+ console.log(base64);
2152
+ }
2372
2153
  }
2373
2154
  ```
2374
2155
 
@@ -2382,10 +2163,12 @@
2382
2163
  ```typescript
2383
2164
  import { read_file } from '@qy_better_lib/core';
2384
2165
 
2385
- async function example() {
2386
- const file = document.querySelector('input[type="file"]').files[0];
2387
- const content = await read_file(file);
2388
- console.log(content);
2166
+ async function read() {
2167
+ const input = document.querySelector('input[type="file"]');
2168
+ if (input.files[0]) {
2169
+ const content = await read_file(input.files[0]);
2170
+ console.log(content);
2171
+ }
2389
2172
  }
2390
2173
  ```
2391
2174
 
@@ -2397,7 +2180,8 @@
2397
2180
  ```typescript
2398
2181
  import { get_file_extension } from '@qy_better_lib/core';
2399
2182
 
2400
- const ext = get_file_extension('example.jpg'); // 'jpg'
2183
+ const extension = get_file_extension('example.pdf');
2184
+ console.log(extension); // pdf
2401
2185
  ```
2402
2186
 
2403
2187
  #### get_file_name_without_extension
@@ -2408,7 +2192,8 @@
2408
2192
  ```typescript
2409
2193
  import { get_file_name_without_extension } from '@qy_better_lib/core';
2410
2194
 
2411
- const name = get_file_name_without_extension('example.jpg'); // 'example'
2195
+ const name = get_file_name_without_extension('example.pdf');
2196
+ console.log(name); // example
2412
2197
  ```
2413
2198
 
2414
2199
  #### validate_file_size
@@ -2421,9 +2206,11 @@
2421
2206
  ```typescript
2422
2207
  import { validate_file_size } from '@qy_better_lib/core';
2423
2208
 
2424
- const file = document.querySelector('input[type="file"]').files[0];
2425
- const isValid = validate_file_size(file, 1024 * 1024); // 1MB
2426
- console.log(isValid);
2209
+ const input = document.querySelector('input[type="file"]');
2210
+ if (input.files[0]) {
2211
+ const isValid = validate_file_size(input.files[0], 1024 * 1024); // 1MB
2212
+ console.log(isValid);
2213
+ }
2427
2214
  ```
2428
2215
 
2429
2216
  #### validate_file_type
@@ -2436,9 +2223,11 @@
2436
2223
  ```typescript
2437
2224
  import { validate_file_type } from '@qy_better_lib/core';
2438
2225
 
2439
- const file = document.querySelector('input[type="file"]').files[0];
2440
- const isValid = validate_file_type(file, ['jpg', 'png', 'gif']);
2441
- console.log(isValid);
2226
+ const input = document.querySelector('input[type="file"]');
2227
+ if (input.files[0]) {
2228
+ const isValid = validate_file_type(input.files[0], ['pdf', 'doc', 'docx']);
2229
+ console.log(isValid);
2230
+ }
2442
2231
  ```
2443
2232
 
2444
2233
  #### create_file_from_blob
@@ -2452,8 +2241,9 @@
2452
2241
  ```typescript
2453
2242
  import { create_file_from_blob } from '@qy_better_lib/core';
2454
2243
 
2455
- const blob = new Blob(['Hello'], { type: 'text/plain' });
2244
+ const blob = new Blob(['Hello World'], { type: 'text/plain' });
2456
2245
  const file = create_file_from_blob(blob, 'example.txt', 'text/plain');
2246
+ console.log(file);
2457
2247
  ```
2458
2248
 
2459
2249
  #### download_text_file
@@ -2466,7 +2256,6 @@
2466
2256
  ```typescript
2467
2257
  import { download_text_file } from '@qy_better_lib/core';
2468
2258
 
2469
- // 下载文本文件
2470
2259
  download_text_file('Hello World', 'example.txt');
2471
2260
  ```
2472
2261
 
@@ -2482,10 +2271,12 @@
2482
2271
  ```typescript
2483
2272
  import { compress_image } from '@qy_better_lib/core';
2484
2273
 
2485
- async function example() {
2486
- const file = document.querySelector('input[type="file"]').files[0];
2487
- const compressedFile = await compress_image(file, 1024, 1024, 0.7);
2488
- console.log(compressedFile);
2274
+ async function compress() {
2275
+ const input = document.querySelector('input[type="file"]');
2276
+ if (input.files[0]) {
2277
+ const compressedFile = await compress_image(input.files[0]);
2278
+ console.log(compressedFile);
2279
+ }
2489
2280
  }
2490
2281
  ```
2491
2282
 
@@ -2497,9 +2288,11 @@
2497
2288
  ```typescript
2498
2289
  import { get_file_info } from '@qy_better_lib/core';
2499
2290
 
2500
- const file = document.querySelector('input[type="file"]').files[0];
2501
- const info = get_file_info(file);
2502
- console.log(info);
2291
+ const input = document.querySelector('input[type="file"]');
2292
+ if (input.files[0]) {
2293
+ const info = get_file_info(input.files[0]);
2294
+ console.log(info);
2295
+ }
2503
2296
  ```
2504
2297
 
2505
2298
  #### generate_unique_file_name
@@ -2510,7 +2303,7 @@
2510
2303
  ```typescript
2511
2304
  import { generate_unique_file_name } from '@qy_better_lib/core';
2512
2305
 
2513
- const uniqueName = generate_unique_file_name('example.jpg');
2306
+ const uniqueName = generate_unique_file_name('example.pdf');
2514
2307
  console.log(uniqueName);
2515
2308
  ```
2516
2309
 
@@ -2519,188 +2312,202 @@
2519
2312
  #### tree_flat
2520
2313
  - **功能**: 树形数据扁平化处理
2521
2314
  - **参数**:
2522
- - `data: TreeNode[]` - 树形数据数组
2315
+ - `data: TreeNode<T>[]` - 树形数据数组
2523
2316
  - `key: string` - key属性,默认"key"
2524
2317
  - `children: string` - children属性,默认"children"
2525
- - **返回类型**: `Record<string, TreeNode>` - 扁平化的树形数据映射
2318
+ - **返回类型**: `FlatTreeMap<T>` - 扁平化的树形数据映射
2526
2319
  - **示例**:
2527
2320
  ```typescript
2528
2321
  import { tree_flat } from '@qy_better_lib/core';
2529
2322
 
2530
- const tree = [
2531
- {
2532
- key: '1',
2533
- name: '节点1',
2534
- children: [
2535
- { key: '1-1', name: '节点1-1' }
2536
- ]
2537
- }
2323
+ const treeData = [
2324
+ { key: '1', name: '节点1', children: [{ key: '1-1', name: '节点1-1' }] }
2538
2325
  ];
2539
- const flattened = tree_flat(tree);
2540
- console.log(flattened); // { '1': { ... }, '1-1': { ... } }
2326
+ const flatMap = tree_flat(treeData);
2327
+ console.log(flatMap);
2541
2328
  ```
2542
2329
 
2543
2330
  #### build_tree
2544
2331
  - **功能**: 从扁平化数据构建树形结构
2545
2332
  - **参数**:
2546
- - `data: TreeNode[]` - 扁平化数据数组
2333
+ - `data: TreeNode<T>[]` - 扁平化数据数组
2547
2334
  - `key: string` - key属性,默认"key"
2548
2335
  - `parent_key: string` - 父节点key属性,默认"parentId"
2549
2336
  - `children: string` - children属性,默认"children"
2550
- - **返回类型**: `TreeNode[]` - 树形数据
2337
+ - **返回类型**: `TreeNode<T>[]` - 树形数据数组
2551
2338
  - **示例**:
2552
2339
  ```typescript
2553
2340
  import { build_tree } from '@qy_better_lib/core';
2554
2341
 
2555
- const data = [
2556
- { key: '1', name: '节点1', parentId: null },
2342
+ const flatData = [
2343
+ { key: '1', name: '节点1' },
2557
2344
  { key: '1-1', name: '节点1-1', parentId: '1' }
2558
2345
  ];
2559
- const tree = build_tree(data);
2560
- console.log(tree);
2346
+ const treeData = build_tree(flatData);
2347
+ console.log(treeData);
2561
2348
  ```
2562
2349
 
2563
2350
  #### traverse_tree_depth_first
2564
2351
  - **功能**: 深度优先遍历树形数据
2565
2352
  - **参数**:
2566
- - `tree: TreeNode | TreeNode[]` - 树形数据
2567
- - `callback: (node: TreeNode, depth: number) => boolean | void` - 回调函数,返回false可中断遍历
2353
+ - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
2354
+ - `callback: (node: TreeNode<T>, depth: number) => boolean | void` - 回调函数,返回false可中断遍历
2568
2355
  - `children: string` - children属性,默认"children"
2569
2356
  - **返回类型**: `boolean` - 是否提前中断了遍历
2570
2357
  - **示例**:
2571
2358
  ```typescript
2572
2359
  import { traverse_tree_depth_first } from '@qy_better_lib/core';
2573
2360
 
2574
- traverse_tree_depth_first(tree, (node, depth) => {
2575
- console.log('深度:', depth, '节点:', node.name);
2576
- // 返回 false 可中断遍历
2361
+ const treeData = [
2362
+ { key: '1', name: '节点1', children: [{ key: '1-1', name: '节点1-1' }] }
2363
+ ];
2364
+ traverse_tree_depth_first(treeData, (node, depth) => {
2365
+ console.log(`${' '.repeat(depth)}${node.name}`);
2577
2366
  });
2578
2367
  ```
2579
2368
 
2580
2369
  #### traverse_tree_breadth_first
2581
2370
  - **功能**: 广度优先遍历树形数据
2582
2371
  - **参数**:
2583
- - `tree: TreeNode | TreeNode[]` - 树形数据
2584
- - `callback: (node: TreeNode, depth: number) => boolean | void` - 回调函数,返回false可中断遍历
2372
+ - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
2373
+ - `callback: (node: TreeNode<T>, depth: number) => boolean | void` - 回调函数,返回false可中断遍历
2585
2374
  - `children: string` - children属性,默认"children"
2586
2375
  - **返回类型**: `boolean` - 是否提前中断了遍历
2587
2376
  - **示例**:
2588
2377
  ```typescript
2589
2378
  import { traverse_tree_breadth_first } from '@qy_better_lib/core';
2590
2379
 
2591
- traverse_tree_breadth_first(tree, (node, depth) => {
2592
- console.log('深度:', depth, '节点:', node.name);
2380
+ const treeData = [
2381
+ { key: '1', name: '节点1', children: [{ key: '1-1', name: '节点1-1' }] }
2382
+ ];
2383
+ traverse_tree_breadth_first(treeData, (node, depth) => {
2384
+ console.log(`${' '.repeat(depth)}${node.name}`);
2593
2385
  });
2594
2386
  ```
2595
2387
 
2596
2388
  #### find_tree_node
2597
2389
  - **功能**: 根据条件查找树形节点
2598
2390
  - **参数**:
2599
- - `tree: TreeNode | TreeNode[]` - 树形数据
2600
- - `predicate: (node: TreeNode) => boolean` - 条件函数
2391
+ - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
2392
+ - `predicate: (node: TreeNode<T>) => boolean` - 条件函数
2601
2393
  - `children: string` - children属性,默认"children"
2602
- - **返回类型**: `TreeNode | null` - 找到的节点或null
2394
+ - **返回类型**: `TreeNode<T> | null` - 找到的节点或null
2603
2395
  - **示例**:
2604
2396
  ```typescript
2605
2397
  import { find_tree_node } from '@qy_better_lib/core';
2606
2398
 
2607
- const node = find_tree_node(tree, (node) => node.name === '节点1-1');
2399
+ const treeData = [
2400
+ { key: '1', name: '节点1', children: [{ key: '1-1', name: '节点1-1' }] }
2401
+ ];
2402
+ const node = find_tree_node(treeData, node => node.key === '1-1');
2608
2403
  console.log(node);
2609
2404
  ```
2610
2405
 
2611
2406
  #### find_tree_node_by_key
2612
2407
  - **功能**: 根据key查找树形节点
2613
2408
  - **参数**:
2614
- - `tree: TreeNode | TreeNode[]` - 树形数据
2409
+ - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
2615
2410
  - `key_value: any` - key值
2616
2411
  - `key: string` - key属性,默认"key"
2617
2412
  - `children: string` - children属性,默认"children"
2618
- - **返回类型**: `TreeNode | null` - 找到的节点或null
2413
+ - **返回类型**: `TreeNode<T> | null` - 找到的节点或null
2619
2414
  - **示例**:
2620
2415
  ```typescript
2621
2416
  import { find_tree_node_by_key } from '@qy_better_lib/core';
2622
2417
 
2623
- const node = find_tree_node_by_key(tree, '1-1', 'key');
2418
+ const treeData = [
2419
+ { key: '1', name: '节点1', children: [{ key: '1-1', name: '节点1-1' }] }
2420
+ ];
2421
+ const node = find_tree_node_by_key(treeData, '1-1');
2624
2422
  console.log(node);
2625
2423
  ```
2626
2424
 
2627
2425
  #### filter_tree
2628
2426
  - **功能**: 过滤树形数据
2629
2427
  - **参数**:
2630
- - `tree: TreeNode | TreeNode[]` - 树形数据
2631
- - `predicate: (node: TreeNode) => boolean` - 过滤条件
2428
+ - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
2429
+ - `predicate: (node: TreeNode<T>) => boolean` - 条件函数
2632
2430
  - `children: string` - children属性,默认"children"
2633
- - **返回类型**: `TreeNode[]` - 过滤后的树形数据
2431
+ - **返回类型**: `TreeNode<T>[]` - 过滤后的树形数据
2634
2432
  - **示例**:
2635
2433
  ```typescript
2636
2434
  import { filter_tree } from '@qy_better_lib/core';
2637
2435
 
2638
- const filtered = filter_tree(tree, (node) => node.name.includes('1'));
2639
- console.log(filtered);
2436
+ const treeData = [
2437
+ { key: '1', name: '节点1', value: 10 },
2438
+ { key: '2', name: '节点2', value: 20 }
2439
+ ];
2440
+ const filteredData = filter_tree(treeData, node => node.value > 15);
2441
+ console.log(filteredData);
2640
2442
  ```
2641
2443
 
2642
2444
  #### transform_tree
2643
2445
  - **功能**: 转换树形数据结构
2644
2446
  - **参数**:
2645
- - `tree: TreeNode | TreeNode[]` - 树形数据
2646
- - `transform: (node: TreeNode) => TreeNode` - 转换函数
2447
+ - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
2448
+ - `transform: (node: TreeNode<T>) => TreeNode<T>` - 转换函数
2647
2449
  - `children: string` - children属性,默认"children"
2648
- - **返回类型**: `TreeNode[]` - 转换后的树形数据
2450
+ - **返回类型**: `TreeNode<T>[]` - 转换后的树形数据
2649
2451
  - **示例**:
2650
2452
  ```typescript
2651
2453
  import { transform_tree } from '@qy_better_lib/core';
2652
2454
 
2653
- const transformed = transform_tree(tree, (node) => ({
2455
+ const treeData = [
2456
+ { key: '1', name: '节点1' }
2457
+ ];
2458
+ const transformedData = transform_tree(treeData, node => ({
2654
2459
  ...node,
2655
- label: node.name,
2656
- value: node.key
2460
+ newProperty: 'value'
2657
2461
  }));
2658
- console.log(transformed);
2462
+ console.log(transformedData);
2659
2463
  ```
2660
2464
 
2661
2465
  #### add_tree_node_path
2662
2466
  - **功能**: 为树形节点添加路径信息
2663
2467
  - **参数**:
2664
- - `tree: TreeNode | TreeNode[]` - 树形数据
2468
+ - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
2665
2469
  - `key: string` - key属性,默认"key"
2666
2470
  - `path: string` - path属性,默认"path"
2667
2471
  - `children: string` - children属性,默认"children"
2668
- - **返回类型**: `TreeNode[]` - 添加了路径信息的树形数据
2472
+ - **返回类型**: `TreeNode<T>[]` - 添加了路径信息的树形数据
2669
2473
  - **示例**:
2670
2474
  ```typescript
2671
2475
  import { add_tree_node_path } from '@qy_better_lib/core';
2672
2476
 
2673
- const treeWithPath = add_tree_node_path(tree);
2674
- console.log(treeWithPath[0].path); // 路径信息,如 "1"
2477
+ const treeData = [
2478
+ { key: '1', name: '节点1', children: [{ key: '1-1', name: '节点1-1' }] }
2479
+ ];
2480
+ const dataWithPath = add_tree_node_path(treeData);
2481
+ console.log(dataWithPath);
2675
2482
  ```
2676
2483
 
2677
2484
  #### get_tree_node_descendants
2678
2485
  - **功能**: 获取树形节点的所有后代
2679
2486
  - **参数**:
2680
- - `node: TreeNode` - 树形节点
2487
+ - `node: TreeNode<T>` - 树形节点
2681
2488
  - `children: string` - children属性,默认"children"
2682
- - **返回类型**: `TreeNode[]` - 所有后代节点数组
2489
+ - **返回类型**: `TreeNode<T>[]` - 所有后代节点数组
2683
2490
  - **示例**:
2684
2491
  ```typescript
2685
2492
  import { get_tree_node_descendants } from '@qy_better_lib/core';
2686
2493
 
2687
- const rootNode = tree[0];
2688
- const descendants = get_tree_node_descendants(rootNode);
2494
+ const node = { key: '1', name: '节点1', children: [{ key: '1-1', name: '节点1-1' }] };
2495
+ const descendants = get_tree_node_descendants(node);
2689
2496
  console.log(descendants);
2690
2497
  ```
2691
2498
 
2692
2499
  #### get_tree_node_ancestors
2693
2500
  - **功能**: 获取树形节点的所有祖先
2694
2501
  - **参数**:
2695
- - `node: TreeNode` - 树形节点
2502
+ - `node: TreeNode<T>` - 树形节点
2696
2503
  - `parent: string` - parent属性,默认"parent"
2697
- - **返回类型**: `TreeNode[]` - 所有祖先节点数组
2504
+ - **返回类型**: `TreeNode<T>[]` - 所有祖先节点数组
2698
2505
  - **示例**:
2699
2506
  ```typescript
2700
2507
  import { get_tree_node_ancestors } from '@qy_better_lib/core';
2701
2508
 
2702
- // 假设节点有parent属性指向父节点
2703
- const childNode = tree[0].children[0];
2509
+ const parentNode = { key: '1', name: '节点1' };
2510
+ const childNode = { key: '1-1', name: '节点1-1', parent: parentNode };
2704
2511
  const ancestors = get_tree_node_ancestors(childNode);
2705
2512
  console.log(ancestors);
2706
2513
  ```
@@ -2708,253 +2515,167 @@
2708
2515
  #### get_tree_depth
2709
2516
  - **功能**: 计算树形数据的深度
2710
2517
  - **参数**:
2711
- - `tree: TreeNode | TreeNode[]` - 树形数据
2518
+ - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
2712
2519
  - `children: string` - children属性,默认"children"
2713
2520
  - **返回类型**: `number` - 树形数据的深度
2714
2521
  - **示例**:
2715
2522
  ```typescript
2716
2523
  import { get_tree_depth } from '@qy_better_lib/core';
2717
2524
 
2718
- const depth = get_tree_depth(tree);
2719
- console.log(depth);
2525
+ const treeData = [
2526
+ { key: '1', name: '节点1', children: [{ key: '1-1', name: '节点1-1' }] }
2527
+ ];
2528
+ const depth = get_tree_depth(treeData);
2529
+ console.log(depth); // 2
2720
2530
  ```
2721
2531
 
2722
2532
  #### flatten_tree_to_array
2723
2533
  - **功能**: 扁平化树形数据为数组
2724
2534
  - **参数**:
2725
- - `tree: TreeNode | TreeNode[]` - 树形数据
2535
+ - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
2726
2536
  - `children: string` - children属性,默认"children"
2727
- - **返回类型**: `TreeNode[]` - 扁平化的节点数组
2537
+ - **返回类型**: `TreeNode<T>[]` - 扁平化的节点数组
2728
2538
  - **示例**:
2729
2539
  ```typescript
2730
2540
  import { flatten_tree_to_array } from '@qy_better_lib/core';
2731
2541
 
2732
- const array = flatten_tree_to_array(tree);
2733
- console.log(array);
2542
+ const treeData = [
2543
+ { key: '1', name: '节点1', children: [{ key: '1-1', name: '节点1-1' }] }
2544
+ ];
2545
+ const flatArray = flatten_tree_to_array(treeData);
2546
+ console.log(flatArray);
2734
2547
  ```
2735
2548
 
2736
2549
  #### add_tree_node
2737
2550
  - **功能**: 向树形结构添加节点
2738
2551
  - **参数**:
2739
- - `tree: TreeNode | TreeNode[]` - 树形数据
2552
+ - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
2740
2553
  - `parent_key: any` - 父节点key值
2741
- - `new_node: TreeNode` - 新节点
2554
+ - `new_node: TreeNode<T>` - 新节点
2742
2555
  - `key: string` - key属性,默认"key"
2743
2556
  - `children: string` - children属性,默认"children"
2744
- - **返回类型**: `TreeNode[]` - 更新后的树形数据
2557
+ - **返回类型**: `TreeNode<T>[]` - 更新后的树形数据
2745
2558
  - **示例**:
2746
2559
  ```typescript
2747
2560
  import { add_tree_node } from '@qy_better_lib/core';
2748
2561
 
2749
- const newNode = { key: '1-2', name: '节点1-2' };
2750
- const newTree = add_tree_node(tree, '1', newNode);
2751
- console.log(newTree);
2562
+ const treeData = [
2563
+ { key: '1', name: '节点1' }
2564
+ ];
2565
+ const newTreeData = add_tree_node(treeData, '1', { key: '1-1', name: '节点1-1' });
2566
+ console.log(newTreeData);
2752
2567
  ```
2753
2568
 
2754
2569
  #### remove_tree_node
2755
2570
  - **功能**: 从树形结构移除节点
2756
2571
  - **参数**:
2757
- - `tree: TreeNode | TreeNode[]` - 树形数据
2572
+ - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
2758
2573
  - `node_key: any` - 要移除的节点key值
2759
2574
  - `key: string` - key属性,默认"key"
2760
2575
  - `children: string` - children属性,默认"children"
2761
- - **返回类型**: `TreeNode[]` - 更新后的树形数据
2576
+ - **返回类型**: `TreeNode<T>[]` - 更新后的树形数据
2762
2577
  - **示例**:
2763
2578
  ```typescript
2764
2579
  import { remove_tree_node } from '@qy_better_lib/core';
2765
2580
 
2766
- const newTree = remove_tree_node(tree, '1-1');
2767
- console.log(newTree);
2581
+ const treeData = [
2582
+ { key: '1', name: '节点1', children: [{ key: '1-1', name: '节点1-1' }] }
2583
+ ];
2584
+ const newTreeData = remove_tree_node(treeData, '1-1');
2585
+ console.log(newTreeData);
2768
2586
  ```
2769
2587
 
2770
2588
  #### update_tree_node
2771
2589
  - **功能**: 更新树形结构中的节点
2772
2590
  - **参数**:
2773
- - `tree: TreeNode | TreeNode[]` - 树形数据
2591
+ - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
2774
2592
  - `node_key: any` - 要更新的节点key值
2775
- - `updates: Partial<TreeNode>` - 要更新的属性
2593
+ - `updates: Partial<TreeNode<T>>` - 更新内容
2776
2594
  - `key: string` - key属性,默认"key"
2777
2595
  - `children: string` - children属性,默认"children"
2778
- - **返回类型**: `TreeNode[]` - 更新后的树形数据
2596
+ - **返回类型**: `TreeNode<T>[]` - 更新后的树形数据
2779
2597
  - **示例**:
2780
2598
  ```typescript
2781
2599
  import { update_tree_node } from '@qy_better_lib/core';
2782
2600
 
2783
- const newTree = update_tree_node(tree, '1', { name: '更新的节点1' });
2784
- console.log(newTree);
2601
+ const treeData = [
2602
+ { key: '1', name: '节点1' }
2603
+ ];
2604
+ const newTreeData = update_tree_node(treeData, '1', { name: '更新后的节点1' });
2605
+ console.log(newTreeData);
2785
2606
  ```
2786
2607
 
2787
2608
  #### sort_tree
2788
2609
  - **功能**: 对树形结构进行排序
2789
2610
  - **参数**:
2790
- - `tree: TreeNode | TreeNode[]` - 树形数据
2791
- - `compare_fn: ((a: TreeNode, b: TreeNode) => number) | string` - 比较函数或属性名
2611
+ - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
2612
+ - `compare_fn: ((a: TreeNode<T>, b: TreeNode<T>) => number) | string` - 比较函数或属性名
2792
2613
  - `recursive: boolean` - 是否递归排序所有层级,默认true
2793
2614
  - `children: string` - children属性,默认"children"
2794
- - **返回类型**: `TreeNode[]` - 排序后的树形数据
2615
+ - **返回类型**: `TreeNode<T>[]` - 排序后的树形数据
2795
2616
  - **示例**:
2796
2617
  ```typescript
2797
2618
  import { sort_tree } from '@qy_better_lib/core';
2798
2619
 
2799
- // 使用比较函数排序
2800
- const sortedTree = sort_tree(tree, (a, b) => a.name.localeCompare(b.name));
2801
-
2802
- // 使用属性名排序
2803
- const sortedTree2 = sort_tree(tree, 'name');
2804
- console.log(sortedTree);
2620
+ const treeData = [
2621
+ { key: '2', name: '节点2' },
2622
+ { key: '1', name: '节点1' }
2623
+ ];
2624
+ const sortedData = sort_tree(treeData, 'key');
2625
+ console.log(sortedData);
2805
2626
  ```
2806
2627
 
2807
2628
  #### clone_tree
2808
2629
  - **功能**: 克隆树形结构
2809
2630
  - **参数**:
2810
- - `tree: TreeNode | TreeNode[]` - 树形数据
2631
+ - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
2811
2632
  - `children: string` - children属性,默认"children"
2812
- - **返回类型**: `TreeNode[]` - 克隆后的树形数据
2633
+ - **返回类型**: `TreeNode<T>[]` - 克隆后的树形数据
2813
2634
  - **示例**:
2814
2635
  ```typescript
2815
2636
  import { clone_tree } from '@qy_better_lib/core';
2816
2637
 
2817
- const clonedTree = clone_tree(tree);
2818
- console.log(clonedTree);
2638
+ const treeData = [
2639
+ { key: '1', name: '节点1' }
2640
+ ];
2641
+ const clonedData = clone_tree(treeData);
2642
+ console.log(clonedData);
2819
2643
  ```
2820
2644
 
2821
2645
  #### validate_tree
2822
2646
  - **功能**: 验证树形结构的有效性
2823
2647
  - **参数**:
2824
- - `tree: TreeNode | TreeNode[]` - 树形数据
2648
+ - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
2825
2649
  - `key: string` - key属性,默认"key"
2826
2650
  - `children: string` - children属性,默认"children"
2827
- - **返回类型**: `{ valid: boolean; errors: string[] }` - 验证结果,包含是否有效和错误信息
2651
+ - **返回类型**: `{ valid: boolean; errors: string[] }` - 验证结果
2828
2652
  - **示例**:
2829
2653
  ```typescript
2830
2654
  import { validate_tree } from '@qy_better_lib/core';
2831
2655
 
2832
- const result = validate_tree(tree);
2833
- console.log(result.valid); // 是否有效
2834
- console.log(result.errors); // 错误信息
2656
+ const treeData = [
2657
+ { key: '1', name: '节点1' }
2658
+ ];
2659
+ const result = validate_tree(treeData);
2660
+ console.log(result);
2835
2661
  ```
2836
2662
 
2837
2663
  #### search_tree
2838
2664
  - **功能**: 在树形结构中搜索节点
2839
2665
  - **参数**:
2840
- - `tree: TreeNode | TreeNode[]` - 树形数据
2841
- - `predicate: ((node: TreeNode) => boolean) | Record<string, any>` - 搜索条件函数或属性值对
2666
+ - `tree: TreeNode<T> | TreeNode<T>[]` - 树形数据
2667
+ - `predicate: ((node: TreeNode<T>) => boolean) | Record<string, any>` - 搜索条件函数或属性值对
2842
2668
  - `children: string` - children属性,默认"children"
2843
- - **返回类型**: `TreeNode[]` - 所有匹配的节点数组
2669
+ - **返回类型**: `TreeNode<T>[]` - 所有匹配的节点数组
2844
2670
  - **示例**:
2845
2671
  ```typescript
2846
2672
  import { search_tree } from '@qy_better_lib/core';
2847
2673
 
2848
- // 使用函数搜索
2849
- const results = search_tree(tree, (node) => node.name.includes('1'));
2850
-
2851
- // 使用对象搜索
2852
- const results2 = search_tree(tree, { name: '节点1' });
2674
+ const treeData = [
2675
+ { key: '1', name: '节点1', value: 10 },
2676
+ { key: '2', name: '节点2', value: 20 }
2677
+ ];
2678
+ const results = search_tree(treeData, { value: 10 });
2853
2679
  console.log(results);
2854
2680
  ```
2855
-
2856
- ## 指令功能 (directives)
2857
-
2858
- ### 1. 点击外部区域指令 (click_outside.ts)
2859
-
2860
- #### 功能描述
2861
- 当点击元素外部区域时触发绑定的回调函数,可用于实现下拉菜单、弹窗等组件的关闭功能。
2862
-
2863
- #### 指令参数
2864
- - **value**: `Function` - 点击外部区域时触发的回调函数
2865
- - **arg**: `HTMLElement | HTMLElement[]` - 可选,需要排除的元素或元素数组
2866
-
2867
- #### 使用示例
2868
-
2869
- **基本用法**
2870
- ```vue
2871
- <template>
2872
- <div v-click-outside="handleClickOutside">
2873
- 点击外部区域会触发回调
2874
- </div>
2875
- </template>
2876
-
2877
- <script setup lang="ts">
2878
- import { ref } from 'vue';
2879
-
2880
- const handleClickOutside = () => {
2881
- console.log('点击了外部区域');
2882
- };
2883
- </script>
2884
- ```
2885
-
2886
- **带排除元素**
2887
- ```vue
2888
- <template>
2889
- <div>
2890
- <div ref="excludeElement">
2891
- 点击此区域不会触发外部点击回调
2892
- </div>
2893
- <div v-click-outside:[excludeElement]="handleClickOutside">
2894
- 点击外部区域会触发回调,但点击上方排除元素不会
2895
- </div>
2896
- </div>
2897
- </template>
2898
-
2899
- <script setup lang="ts">
2900
- import { ref } from 'vue';
2901
-
2902
- const excludeElement = ref<HTMLElement | null>(null);
2903
-
2904
- const handleClickOutside = () => {
2905
- console.log('点击了外部区域');
2906
- };
2907
- </script>
2908
- ```
2909
-
2910
- **带多个排除元素**
2911
- ```vue
2912
- <template>
2913
- <div>
2914
- <div ref="excludeElement1">
2915
- 排除元素 1
2916
- </div>
2917
- <div ref="excludeElement2">
2918
- 排除元素 2
2919
- </div>
2920
- <div v-click-outside:[excludeElements]="handleClickOutside">
2921
- 点击外部区域会触发回调,但点击排除元素不会
2922
- </div>
2923
- </div>
2924
- </template>
2925
-
2926
- <script setup lang="ts">
2927
- import { ref, computed } from 'vue';
2928
-
2929
- const excludeElement1 = ref<HTMLElement | null>(null);
2930
- const excludeElement2 = ref<HTMLElement | null>(null);
2931
-
2932
- const excludeElements = computed(() => [
2933
- excludeElement1.value,
2934
- excludeElement2.value
2935
- ]);
2936
-
2937
- const handleClickOutside = () => {
2938
- console.log('点击了外部区域');
2939
- };
2940
- </script>
2941
- ```
2942
-
2943
- #### 注册指令
2944
-
2945
- 在 Vue 应用中注册指令:
2946
-
2947
- ```typescript
2948
- import { createApp } from 'vue';
2949
- import App from './App.vue';
2950
- import { setupDirectives } from '@qy_better_lib/core';
2951
-
2952
- const app = createApp(App);
2953
-
2954
- // 注册所有指令
2955
- setupDirectives(app);
2956
-
2957
- app.mount('#app');
2958
- ```
2959
-
2960
-
2681
+