@qy_better_lib/hooks 0.1.9 → 0.2.0

package/USAGE.md

@@ -0,0 +1,444 @@
+# QY Better Lib Hooks - 使用文档
+
+本文档详细介绍了 QY Better Lib Hooks 包中的各种钩子函数，包括功能描述、参数说明、返回类型和使用示例。
+
+## Hooks 分类
+
+### 1. 事件管理钩子 (use-emit)
+
+#### use_emit
+- **功能**: 创建全局事件发射器，支持事件的注册和监听
+- **参数**: `event_list?: Array<EventItem>` - 事件监听器数组
+- **返回类型**: `UseEmits` - 包含事件发射器的对象
+- **示例**:
+  ```typescript
+  import { use_emit } from '@qy_better_lib/hooks';
+  
+  const { emitter } = use_emit([
+    {
+      key: 'test-event',
+      value: (data) => {
+        console.log('收到事件:', data);
+      }
+    }
+  ]);
+  
+  // 发送事件
+  emitter.emit('test-event', { message: 'Hello' });
+  
+  // 异步发送事件
+  await emitter.emitAsync('test-event', { message: 'Async Hello' });
+  ```
+
+### 2. 打印功能钩子 (use-print)
+
+#### use_print
+- **功能**: 提供打印页面元素的功能，支持打印HTML内容和DOM元素
+- **参数**: 无
+- **返回类型**: `UsePrintReturn` - 包含打印操作方法的对象
+- **示例**:
+  ```typescript
+  import { use_print } from '@qy_better_lib/hooks';
+  
+  const { print_html, preview_html } = use_print();
+  
+  // 打印指定DOM元素
+  print_html('#content', {
+    page_size: 'A4',
+    page_orientation: 'portrait',
+    print_background: true,
+    on_complete: () => {
+      console.log('打印完成');
+    }
+  });
+  
+  // 预览打印内容
+  preview_html('#content', {
+    preview: true
+  });
+  ```
+
+### 3. 水印功能钩子 (use-watermark)
+
+#### use_water_mark
+- **功能**: 在页面上添加水印，支持自定义水印内容、样式和位置
+- **参数**: 无
+- **返回类型**: `UseWaterMark` - 包含水印操作方法的对象
+- **示例**:
+  ```typescript
+  import { use_water_mark } from '@qy_better_lib/hooks';
+  
+  const { create_water_mark, remove_water_mark, update_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,
+    z_index: 100000,
+    responsive: true
+  });
+  
+  // 更新水印
+  update_water_mark({
+    text1: '更新后的水印'
+  });
+  
+  // 移除水印
+  remove_water_mark();
+  ```
+
+### 4. WebSocket 钩子 (use-websocket)
+
+#### use_web_socket
+- **功能**: 提供 WebSocket 通信功能，支持自动重连、心跳检测和消息队列
+- **参数**: `options: WebSocketOptions` - WebSocket 配置选项
+- **返回类型**: `UseWebSocketReturn` - 包含 WebSocket 操作方法和状态的对象
+- **示例**:
+  ```typescript
+  import { use_web_socket } from '@qy_better_lib/hooks';
+  
+  const { ws, send_message, get_status, close } = use_web_socket({
+    server: 'ws://localhost:8080',
+    receive: (event) => {
+      console.log('收到消息:', event.data);
+    },
+    max_reconnect_attempts: 5,
+    reconnect_interval: 5000,
+    heartbeat_interval: 30000,
+    heartbeat_message: 'ping',
+    on_open: () => {
+      console.log('WebSocket连接成功');
+    },
+    on_error: (error) => {
+      console.error('WebSocket错误:', error);
+    },
+    on_close: () => {
+      console.log('WebSocket连接关闭');
+    }
+  });
+  
+  // 发送消息
+  send_message({ type: 'chat', content: 'Hello WebSocket' });
+  
+  // 获取连接状态
+  console.log('连接状态:', get_status());
+  
+  // 关闭连接
+  close();
+  ```
+
+### 5. 图片处理钩子 (use-image)
+
+#### use_image
+- **功能**: 提供图片处理功能，包括压缩、转换和下载
+- **参数**: 无
+- **返回类型**: 包含图片处理方法的对象
+- **示例**:
+  ```typescript
+  import { use_image, EImageType } from '@qy_better_lib/hooks';
+  
+  const { compress, compress_accurately, download_file } = use_image();
+  
+  // 压缩图片
+  async function handleImageCompress(file) {
+    const compressedFile = await compress(file, {
+      quality: 0.8,
+      type: EImageType.JPEG
+    });
+    console.log('压缩后的文件大小:', compressedFile.size);
+    return compressedFile;
+  }
+  
+  // 精确压缩图片到指定大小
+  async function handleImageCompressAccurately(file) {
+    const compressedFile = await compress_accurately(file, {
+      size: 100, // 100KB
+      accuracy: 0.95,
+      type: EImageType.JPEG
+    });
+    console.log('精确压缩后的文件大小:', compressedFile.size);
+    return compressedFile;
+  }
+  
+  // 下载图片
+  function handleDownloadImage(blob) {
+    download_file(blob, 'compressed-image.jpg');
+  }
+  ```
+
+### 6. 全屏功能钩子 (use-fullscreen)
+
+#### use_fullscreen
+- **功能**: 提供全屏功能，支持切换、进入和退出全屏
+- **参数**: `selector: string` - 目标元素选择器
+- **返回类型**: `UseFullScreenReturn` - 包含全屏操作方法和状态的对象
+- **示例**:
+  ```typescript
+  import { use_fullscreen } from '@qy_better_lib/hooks';
+  
+  const { full, toggle_fullscreen, enter_fullscreen, exit_fullscreen } = use_fullscreen('#app');
+  
+  // 切换全屏状态
+  toggle_fullscreen();
+  
+  // 进入全屏
+  enter_fullscreen();
+  
+  // 退出全屏
+  exit_fullscreen();
+  
+  // 监听全屏状态变化
+  console.log('当前全屏状态:', full.value);
+  ```
+
+### 7. 图表管理钩子 (use-chart)
+
+#### use_chart
+- **功能**: 提供 ECharts 图表管理功能，支持渲染、更新和销毁图表
+- **参数**: `options: UseChartOptions` - 图表配置选项
+- **返回类型**: `UseChartReturn` - 包含图表管理方法的对象
+- **示例**:
+  ```typescript
+  import { use_chart } from '@qy_better_lib/hooks';
+  
+  const { render_chart, update_chart, remove_chart } = use_chart({
+    default_theme: 'light',
+    default_renderer: 'canvas',
+    auto_responsive: true
+  });
+  
+  // 渲染图表
+  async function renderMyChart() {
+    const chartOption = {
+      title: {
+        text: '示例图表'
+      },
+      tooltip: {},
+      xAxis: {
+        data: ['周一', '周二', '周三', '周四', '周五', '周六', '周日']
+      },
+      yAxis: {},
+      series: [{
+        name: '销量',
+        type: 'bar',
+        data: [120, 200, 150, 80, 70, 110, 130]
+      }]
+    };
+    
+    const chart = await render_chart(chartOption, '#chart-container');
+    console.log('图表渲染成功:', chart);
+  }
+  
+  // 更新图表
+  function updateMyChart() {
+    const newOption = {
+      series: [{
+        name: '销量',
+        type: 'bar',
+        data: [150, 250, 200, 100, 90, 130, 160]
+      }]
+    };
+    
+    update_chart('#chart-container', newOption);
+  }
+  
+  // 移除图表
+  function removeMyChart() {
+    remove_chart('#chart-container');
+  }
+  ```
+
+### 8. 流程图布局钩子 (use-layout-flow)
+
+#### use_layout_flow
+- **功能**: 提供流程图自动布局功能，支持多种布局方向和自定义元素
+- **参数**: `options: LayoutFlow` - 布局配置选项
+- **返回类型**: 包含流程图布局方法的对象
+- **示例**:
+  ```typescript
+  import { use_layout_flow } from '@qy_better_lib/hooks';
+  
+  const { init, add_graph_elements, layout, center_content } = use_layout_flow({
+    option: {
+      panning: true,
+      interacting: false,
+      mousewheel: {
+        enabled: true
+      },
+      scaling: { min: 0.1, max: 10 }
+    }
+  });
+  
+  // 初始化画布
+  async function initFlowChart() {
+    const container = document.getElementById('flow-container');
+    const success = await init(container);
+    
+    if (success) {
+      // 添加节点和边
+      const elements = [
+        {
+          id: 'node1',
+          shape: 'rect',
+          x: 100,
+          y: 100,
+          width: 80,
+          height: 40,
+          label: '节点1'
+        },
+        {
+          id: 'node2',
+          shape: 'rect',
+          x: 300,
+          y: 100,
+          width: 80,
+          height: 40,
+          label: '节点2'
+        },
+        {
+          id: 'edge1',
+          shape: 'edge',
+          source: 'node1',
+          target: 'node2'
+        }
+      ];
+      
+      add_graph_elements(elements);
+      
+      // 自动布局
+      await layout({
+        node_w: 100,
+        node_h: 50,
+        nodesep: 50,
+        ranksep: 80
+      }, 'LR');
+      
+      // 内容居中
+      center_content(50);
+    }
+  }
+  ```
+
+### 9. MQTT 通信钩子 (use-mqtt)
+
+#### use_mqtt
+- **功能**: 提供 MQTT 通信功能，支持连接管理、消息订阅和发布
+- **参数**: 
+  - `url: string` - MQTT broker 地址
+  - `options: any` - MQTT 连接选项
+- **返回类型**: `UseMqttReturn` - 包含 MQTT 操作方法和状态的对象
+- **示例**:
+  ```typescript
+  import { use_mqtt } from '@qy_better_lib/hooks';
+  
+  const { connect, subscribe, publish, close, status } = use_mqtt('mqtt://localhost:1883', {
+    clientId: 'test-client',
+    clean: true,
+    reconnectPeriod: 5000
+  });
+  
+  // 连接 MQTT
+  async function connectMqtt() {
+    connect({
+      success: () => {
+        console.log('MQTT 连接成功');
+        // 订阅主题
+        subscribe('test/topic', {}, (err, granted) => {
+          if (!err) {
+            console.log('订阅成功:', granted);
+          }
+        });
+      },
+      error: (err) => {
+        console.error('MQTT 连接错误:', err);
+      },
+      receive: (topic, message) => {
+        console.log('收到消息:', topic, message.toString());
+      }
+    });
+  }
+  
+  // 发布消息
+  function publishMessage() {
+    publish('test/topic', 'Hello MQTT', {}, (error) => {
+      if (!error) {
+        console.log('消息发布成功');
+      }
+    });
+  }
+  
+  // 关闭连接
+  function closeMqtt() {
+    close(() => {
+      console.log('MQTT 连接已关闭');
+    });
+  }
+  
+  // 监听连接状态
+  console.log('当前连接状态:', status);
+  ```
+
+## 安装和使用
+
+### 安装
+
+```bash
+# 使用 npm
+npm install @qy_better_lib/hooks
+
+# 使用 yarn
+yarn add @qy_better_lib/hooks
+```
+
+### 全局引入
+
+```typescript
+import { createApp } from 'vue';
+import App from './App.vue';
+import * as QyHooks from '@qy_better_lib/hooks';
+
+const app = createApp(App);
+
+// 全局注册所有钩子
+app.config.globalProperties.$hooks = QyHooks;
+
+app.mount('#app');
+```
+
+### 按需引入
+
+```typescript
+// 按需引入所需的钩子
+import { use_print, use_water_mark } from '@qy_better_lib/hooks';
+```
+
+## 版本历史
+
+- **v1.0.0** - 初始版本，包含所有钩子函数
+
+## 贡献指南
+
+1. Fork 仓库
+2. 创建功能分支
+3. 提交代码
+4. 发起 Pull Request
+
+## 许可证
+
+MIT License
+
+## 注意事项
+
+- 使用 `use-chart` 钩子时，需要确保已安装 `echarts` 依赖
+- 使用 `use-layout-flow` 钩子时，需要确保已安装 `@antv/x6` 和 `dagre` 依赖
+- 使用 `use-mqtt` 钩子时，需要确保已安装 `mqtt` 依赖
+- 所有钩子函数都使用 TypeScript 编写，提供了完整的类型定义
+
+## 总结
+
+QY Better Lib Hooks 提供了一系列实用的 Vue 3 Composition API 钩子函数，涵盖了事件管理、打印功能、水印功能、WebSocket 通信、图片处理、全屏功能、图表管理、流程图布局和 MQTT 通信等多种场景。这些钩子函数设计简洁，使用方便，可以帮助开发者更高效地构建 Vue 应用。