qy-better-lib 0.0.1

package/src/document/hooks.md

@@ -0,0 +1,632 @@
+# QY Better Lib Hooks - 使用文档
+
+本文档详细介绍了 QY Better Lib Hooks 包中的各种hooks，包括功能描述、参数说明、返回类型和使用示例。
+
+## hooks函数列表
+
+### 1. use-print - 打印功能
+
+#### 功能描述
+适用于需要在前端实现打印功能的场景，支持打印HTML内容和DOM元素，包括打印预览功能。
+
+#### 方法列表
+
+##### print_html
+- **功能**: 打印指定DOM选择器的内容
+- **参数**:
+  - `dom_selector: string` - DOM节点选择器
+  - `options?: PrintOptions` - 打印选项
+- **返回类型**: `Promise<void>`
+- **示例**:
+  ```typescript
+  import { use_print } from '@qy_better_lib/hooks';
+  
+  const { print_html } = use_print();
+  
+  // 打印ID为content的元素
+  await print_html('#content');
+  
+  // 打印并预览
+  await print_html('#content', { preview: true });
+  ```
+
+##### print_html_element
+- **功能**: 打印多个DOM元素
+- **参数**:
+  - `element_array: Element[]` - DOM元素数组
+  - `options?: PrintOptions` - 打印选项
+- **返回类型**: `Promise<void>`
+- **示例**:
+  ```typescript
+  import { use_print } from '@qy_better_lib/hooks';
+  
+  const { print_html_element } = use_print();
+  
+  // 获取多个元素并打印
+  const elements = document.querySelectorAll('.printable');
+  await print_html_element(Array.from(elements));
+  ```
+
+##### preview_html
+- **功能**: 预览指定DOM选择器的内容
+- **参数**:
+  - `dom_selector: string` - DOM节点选择器
+  - `options?: PrintOptions` - 打印选项
+- **返回类型**: `void`
+- **示例**:
+  ```typescript
+  import { use_print } from '@qy_better_lib/hooks';
+  
+  const { preview_html } = use_print();
+  
+  // 预览ID为content的元素
+  preview_html('#content');
+  ```
+
+##### preview_html_element
+- **功能**: 预览多个DOM元素
+- **参数**:
+  - `element_array: Element[]` - DOM元素数组
+  - `options?: PrintOptions` - 打印选项
+- **返回类型**: `void`
+- **示例**:
+  ```typescript
+  import { use_print } from '@qy_better_lib/hooks';
+  
+  const { preview_html_element } = use_print();
+  
+  // 获取多个元素并预览
+  const elements = document.querySelectorAll('.printable');
+  preview_html_element(Array.from(elements));
+  ```
+
+##### close_preview
+- **功能**: 关闭预览
+- **返回类型**: `void`
+- **示例**:
+  ```typescript
+  import { use_print } from '@qy_better_lib/hooks';
+  
+  const { close_preview } = use_print();
+  
+  // 关闭预览
+  close_preview();
+  ```
+
+### 2. use-fullscreen - 全屏功能
+
+#### 功能描述
+适用于需要在前端实现全屏功能的场景，支持切换、进入和退出全屏。
+
+#### 参数
+- `selector: string` - 目标元素选择器
+
+#### 返回值
+- **full**: `Ref<boolean>` - 是否全屏
+- **container**: `ShallowRef<Element | null>` - 目标元素
+- **toggle_fullscreen**: `() => void` - 切换全屏状态
+- **enter_fullscreen**: `() => void` - 进入全屏
+- **exit_fullscreen**: `() => void` - 退出全屏
+
+#### 示例
+```typescript
+import { use_fullscreen } from '@qy_better_lib/hooks';
+
+const { full, toggle_fullscreen, enter_fullscreen, exit_fullscreen } = use_fullscreen('#container');
+
+// 切换全屏状态
+toggle_fullscreen();
+
+// 进入全屏
+enter_fullscreen();
+
+// 退出全屏
+exit_fullscreen();
+
+// 监听全屏状态变化
+console.log(full.value); // 是否全屏
+```
+
+### 3. use-watermark - 水印功能
+
+#### 功能描述
+适用于需要在前端添加水印的场景，支持创建、移除、更新水印，包括响应式水印。
+
+#### 方法列表
+
+##### create_water_mark
+- **功能**: 创建水印
+- **参数**:
+  - `options: WaterMarkOptions` - 水印配置选项
+- **返回类型**: `void`
+- **示例**:
+  ```typescript
+  import { use_water_mark } from '@qy_better_lib/hooks';
+  
+  const { create_water_mark } = use_water_mark();
+  
+  // 创建水印
+  create_water_mark({
+    text1: '测试水印',
+    text2: '2024-01-01',
+    font_size: 16,
+    font_family: 'Arial',
+    rotate: -15,
+    text_color: '#999',
+    opacity: 0.1,
+    responsive: true
+  });
+  ```
+
+##### remove_water_mark
+- **功能**: 移除水印
+- **返回类型**: `void`
+- **示例**:
+  ```typescript
+  import { use_water_mark } from '@qy_better_lib/hooks';
+  
+  const { remove_water_mark } = use_water_mark();
+  
+  // 移除水印
+  remove_water_mark();
+  ```
+
+##### update_water_mark
+- **功能**: 更新水印
+- **参数**:
+  - `options: Partial<WaterMarkOptions>` - 水印配置选项
+- **返回类型**: `void`
+- **示例**:
+  ```typescript
+  import { use_water_mark } from '@qy_better_lib/hooks';
+  
+  const { update_water_mark } = use_water_mark();
+  
+  // 更新水印
+  update_water_mark({
+    text1: '更新后的水印',
+    opacity: 0.15
+  });
+  ```
+
+##### has_water_mark
+- **功能**: 检查水印是否存在
+- **返回类型**: `boolean` - 是否存在水印
+- **示例**:
+  ```typescript
+  import { use_water_mark } from '@qy_better_lib/hooks';
+  
+  const { has_water_mark } = use_water_mark();
+  
+  // 检查水印是否存在
+  const exists = has_water_mark();
+  console.log(exists);
+  ```
+
+### 4. use-websocket - WebSocket功能
+
+#### 功能描述
+适用于需要在前端实现WebSocket通信的场景，支持自动重连、心跳检测、消息队列等功能。
+
+#### 参数
+- `options: WebSocketOptions` - WebSocket配置选项
+
+#### 返回值
+- **ws**: `WebSocket | undefined` - WebSocket实例
+- **create**: `() => void` - 创建连接
+- **close**: `() => void` - 关闭连接
+- **send_message**: `(msg: any) => boolean` - 发送消息
+- **get_status**: `() => WebSocketStatus` - 获取连接状态
+- **reconnect**: `() => void` - 重连
+- **start_heartbeat**: `() => void` - 启动心跳检测
+- **stop_heartbeat**: `() => void` - 停止心跳检测
+
+#### 示例
+```typescript
+import { use_web_socket } from '@qy_better_lib/hooks';
+
+const { create, close, send_message, get_status } = use_web_socket({
+  server: 'ws://localhost:8080',
+  receive: (event) => {
+    console.log('收到消息:', event.data);
+  },
+  on_open: () => {
+    console.log('连接成功');
+  },
+  on_error: (error) => {
+    console.error('连接错误:', error);
+  },
+  on_close: () => {
+    console.log('连接关闭');
+  },
+  auto_reconnect: true,
+  heartbeat_interval: 30000
+});
+
+// 发送消息
+send_message('Hello WebSocket');
+
+// 获取连接状态
+const status = get_status();
+console.log(status);
+
+// 关闭连接
+close();
+```
+
+### 5. use-mqtt - MQTT功能
+
+> 注意：MQTT功能现在是可选依赖，需要单独导入
+
+#### 功能描述
+适用于需要MQTT通信的场景，支持连接管理、消息订阅和发布。
+
+#### 参数
+- `url: string` - MQTT broker地址
+- `options: any` - MQTT连接选项
+
+#### 返回值
+- **status**: `MqttConnectionStatus` - 连接状态
+- **connect**: `({ success, error, receive }: MqttConnectOptions) => void` - 连接MQTT
+- **close**: `(callback?: MqttCloseCallback) => void` - 关闭MQTT连接
+- **subscribe**: `(topic: string | string[], options?: any, callback?: MqttSubscribeCallback) => void` - 订阅主题
+- **unsubscribe**: `(topic: string | string[], callback?: MqttUnsubscribeCallback) => void` - 取消订阅
+- **publish**: `(topic: string, message: string | Buffer, options?: any, callback?: MqttPublishCallback) => void` - 发布消息
+
+#### 示例
+```typescript
+import { use_mqtt } from '@qy_better_lib/hooks/use-mqtt';
+
+const { connect, close, subscribe, publish } = use_mqtt('mqtt://localhost:1883', {
+  clientId: 'test-client',
+  reconnectPeriod: 5000
+});
+
+// 连接MQTT
+connect({
+  success: () => {
+    console.log('MQTT连接成功');
+    // 订阅主题
+    subscribe('test/topic', {}, (err, granted) => {
+      if (!err) {
+        console.log('订阅成功:', granted);
+        // 发布消息
+        publish('test/topic', 'Hello MQTT');
+      }
+    });
+  },
+  error: (err) => {
+    console.error('MQTT连接错误:', err);
+  },
+  receive: (topic, message) => {
+    console.log('收到消息:', topic, message.toString());
+  }
+});
+
+// 关闭连接
+close(() => {
+  console.log('MQTT连接已关闭');
+});
+```
+
+### 6. use-image - 图片处理功能
+
+#### 功能描述
+适用于需要在前端处理图片的场景，支持图片压缩、转换、下载等功能。
+
+#### 方法列表
+
+##### compress
+- **功能**: 压缩File（Blob）对象
+- **参数**:
+  - `file: File | Blob` - 一个File（Blob）对象
+  - `config?: ICompressConfig` - 压缩配置
+- **返回类型**: `Promise<Blob>` - 压缩后的Blob对象
+- **示例**:
+  ```typescript
+  import { use_image } from '@qy_better_lib/hooks';
+  
+  const { compress } = use_image();
+  
+  // 压缩图片
+  const compressedFile = await compress(file, {
+    quality: 0.8,
+    width: 800,
+    height: 600
+  });
+  ```
+
+##### compress_accurately
+- **功能**: 根据体积压缩File（Blob）对象
+- **参数**:
+  - `file: File | Blob` - 一个File（Blob）对象
+  - `config?: CompressAccuratelyConfig` - 压缩配置
+- **返回类型**: `Promise<Blob>` - 压缩后的Blob对象
+- **示例**:
+  ```typescript
+  import { use_image } from '@qy_better_lib/hooks';
+  
+  const { compress_accurately } = use_image();
+  
+  // 压缩图片到指定大小（100KB）
+  const compressedFile = await compress_accurately(file, {
+    size: 100, // 目标大小，单位KB
+    accuracy: 0.9 // 精度
+  });
+  ```
+
+##### compress_image
+- **功能**: 使用core中的图片压缩功能
+- **参数**:
+  - `file: File` - 图片文件
+  - `max_width: number` - 最大宽度，默认 800
+  - `max_height: number` - 最大高度，默认 800
+  - `quality: number` - 压缩质量，默认 0.8
+- **返回类型**: `Promise<File | undefined>` - 压缩后的文件
+- **示例**:
+  ```typescript
+  import { use_image } from '@qy_better_lib/hooks';
+  
+  const { compress_image } = use_image();
+  
+  // 压缩图片
+  const compressedFile = await compress_image(file, 1024, 768, 0.7);
+  ```
+
+##### download_file
+- **功能**: 下载文件
+- **参数**:
+  - `blob: Blob` - Blob对象
+  - `file_name: string` - 文件名，默认 'download'
+- **返回类型**: `void`
+- **示例**:
+  ```typescript
+  import { use_image } from '@qy_better_lib/hooks';
+  
+  const { download_file } = use_image();
+  
+  // 下载图片
+  download_file(blob, 'image.jpg');
+  ```
+
+### 7. use-chart - 图表管理
+
+> 注意：图表管理功能现在是可选依赖，需要单独导入
+
+#### 功能描述
+适用于需要在前端使用ECharts的场景，支持图表渲染、主题切换、响应式设计等功能。
+
+#### 参数
+- `options?: UseChartOptions` - 全局配置选项
+
+#### 方法列表
+
+##### render_chart
+- **功能**: 渲染图表
+- **参数**:
+  - `option: Record<string, any>` - 图表配置
+  - `dom_id: string` - DOM元素选择器
+  - `render_options?: Partial<UseChartOptions>` - 渲染选项
+- **返回类型**: `Promise<any>` - 图表实例
+- **示例**:
+  ```typescript
+  import { use_chart } from '@qy_better_lib/hooks/use-chart';
+  
+  const { render_chart } = use_chart();
+  
+  // 渲染图表
+  const chart = await render_chart({
+    title: {
+      text: '测试图表'
+    },
+    xAxis: {
+      type: 'category',
+      data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
+    },
+    yAxis: {
+      type: 'value'
+    },
+    series: [{
+      data: [120, 200, 150, 80, 70, 110, 130],
+      type: 'bar'
+    }]
+  }, '#chart-container');
+  ```
+
+##### update_chart
+- **功能**: 更新图表配置
+- **参数**:
+  - `dom_id: string` - DOM元素选择器
+  - `option: Record<string, any>` - 图表配置
+- **返回类型**: `boolean` - 是否更新成功
+- **示例**:
+  ```typescript
+  import { use_chart } from '@qy_better_lib/hooks/use-chart';
+  
+  const { update_chart } = use_chart();
+  
+  // 更新图表
+  update_chart('#chart-container', {
+    series: [{
+      data: [200, 300, 250, 180, 170, 210, 230],
+      type: 'bar'
+    }]
+  });
+  ```
+
+##### remove_chart
+- **功能**: 删除图表
+- **参数**:
+  - `dom_id: string` - DOM元素选择器
+- **返回类型**: `boolean` - 是否删除成功
+- **示例**:
+  ```typescript
+  import { use_chart } from '@qy_better_lib/hooks/use-chart';
+  
+  const { remove_chart } = use_chart();
+  
+  // 删除图表
+  remove_chart('#chart-container');
+  ```
+
+##### export_chart_image
+- **功能**: 导出图表为图片
+- **参数**:
+  - `dom_id: string` - DOM元素选择器
+  - `options?: any` - 导出选项
+- **返回类型**: `string | null` - 图片URL
+- **示例**:
+  ```typescript
+  import { use_chart } from '@qy_better_lib/hooks/use-chart';
+  
+  const { export_chart_image } = use_chart();
+  
+  // 导出图表为图片
+  const imageUrl = export_chart_image('#chart-container');
+  ```
+
+### 8. use-layout-flow - 流程图布局
+
+> 注意：流程图布局功能现在是可选依赖，需要单独导入
+
+#### 功能描述
+适用于需要自动布局的流程图场景，支持多种布局方向和自定义元素。
+
+#### 参数
+- `options: LayoutFlow` - 布局配置选项
+
+#### 方法列表
+
+##### init
+- **功能**: 初始化画布
+- **参数**:
+  - `container: HTMLElement` - 容器元素
+- **返回类型**: `Promise<boolean>` - 是否初始化成功
+- **示例**:
+  ```typescript
+  import { use_layout_flow } from '@qy_better_lib/hooks/use-layout-flow';
+  
+  const { init } = use_layout_flow({});
+  
+  // 初始化画布
+  const container = document.getElementById('flow-container');
+  await init(container);
+  ```
+
+##### layout
+- **功能**: 自动布局
+- **参数**:
+  - `cfg: LayoutFlowNodeOption` - 布局配置
+  - `dir: LayoutDirection` - 布局方向，默认为 'LR'（从左到右）
+- **返回类型**: `Promise<boolean>` - 是否布局成功
+- **示例**:
+  ```typescript
+  import { use_layout_flow } from '@qy_better_lib/hooks/use-layout-flow';
+  
+  const { layout } = use_layout_flow({});
+  
+  // 执行布局
+  await layout({
+    node_w: 120,
+    node_h: 60,
+    nodesep: 50,
+    ranksep: 50
+  }, 'LR');
+  ```
+
+##### create_nodes
+- **功能**: 创建节点
+- **参数**:
+  - `node_options: any[]` - 节点配置数组
+- **返回类型**: `any[]` - 创建的节点数组
+- **示例**:
+  ```typescript
+  import { use_layout_flow } from '@qy_better_lib/hooks/use-layout-flow';
+  
+  const { create_nodes } = use_layout_flow({});
+  
+  // 创建节点
+  const nodes = create_nodes([
+    {
+      id: 'node1',
+      x: 100,
+      y: 100,
+      width: 120,
+      height: 60,
+      label: '节点1'
+    },
+    {
+      id: 'node2',
+      x: 300,
+      y: 100,
+      width: 120,
+      height: 60,
+      label: '节点2'
+    }
+  ]);
+  ```
+
+##### create_edges
+- **功能**: 创建连线
+- **参数**:
+  - `edge_options: any[]` - 边配置数组
+- **返回类型**: `any[]` - 创建的边数组
+- **示例**:
+  ```typescript
+  import { use_layout_flow } from '@qy_better_lib/hooks/use-layout-flow';
+  
+  const { create_edges } = use_layout_flow({});
+  
+  // 创建连线
+  const edges = create_edges([
+    {
+      source_id: 'node1',
+      target_id: 'node2',
+      shape: 'edge'
+    }
+  ]);
+  ```
+
+### 9. use-emit - 事件总线(异步支持)
+
+#### 功能描述
+适用于需要在前端使用事件发射的场景，基于mitt库实现，支持异步事件和自动清理监听器。
+
+#### 参数
+- `event_list?: Array<EventItem>` - 事件列表
+
+#### 返回值
+- **emitter**: `ExtendEmitter` - 事件发射器
+
+#### 示例
+```typescript
+import { use_emit } from '@qy_better_lib/hooks';
+
+const { emitter } = use_emit([
+  {
+    key: 'test',
+    value: (data) => {
+      console.log('收到test事件:', data);
+    }
+  }
+]);
+
+// 发射事件
+emitter.emit('test', { message: 'Hello' });
+
+// 监听事件
+emitter.on('test', (data) => {
+  console.log('监听test事件:', data);
+});
+
+// 移除监听
+emitter.off('test', listener);
+```
+
+## 注意事项
+
+1. **use-chart** 现在是可选依赖，需要单独导入：`import { use_chart } from '@qy_better_lib/hooks/use-chart'`，并需要安装 ECharts 依赖：`npm install echarts`
+2. **use-layout-flow** 现在是可选依赖，需要单独导入：`import { use_layout_flow } from '@qy_better_lib/hooks/use-layout-flow'`，并需要安装 @antv/x6 和 dagre 依赖：`npm install @antv/x6 dagre`
+3. **use-mqtt** 现在是可选依赖，需要单独导入：`import { use_mqtt } from '@qy_better_lib/hooks/use-mqtt'`，并需要安装 mqtt 依赖：`npm install mqtt`
+4. **use-websocket** 需要确保服务器端支持 WebSocket 协议
+5. **use-print** 在某些浏览器中可能存在兼容性问题，建议在现代浏览器中使用