gzkx-package 0.1.49 → 0.1.50

package/README.md

@@ -146,6 +146,9 @@ export default MyPage;
 | `CustomTable` | 自定义表格组件 | `import { CustomTable } from 'gzkx-package'` |
 | `CustomForm` | 自定义表单组件 | `import { CustomForm } from 'gzkx-package'` |
 | `CustomAdd` | 新增/编辑弹窗组件 | `import { CustomAdd } from 'gzkx-package'` |
+| `useHotkeyListener` | 组合键监听 Hook | `import { useHotkeyListener } from 'gzkx-package'` |
+| `useTakeShotHotkey` | 截图专用组合键 Hook | `import { useTakeShotHotkey } from 'gzkx-package'` |
+| `takeShot` | 截图接口 | `import { takeShot } from 'gzkx-package'` |
 
 ### 5. TypeScript 类型导出
 
@@ -158,6 +161,7 @@ import type {
   CustomTableHandle,   // CustomTable Ref 类型
   CustomColumnType,    // 自定义表格列类型
   CustomColumnsType,   // 自定义表格列数组类型
+  HotkeyConfig,        // 组合键配置类型
 } from 'gzkx-package';
 ```
 
@@ -165,7 +169,143 @@ import type {
 
 ## 组件列表
 
-## 1. CommonPage 通用页面组件
+## 1. 工具 Hooks
+
+### 1.1 useHotkeyListener - 组合键监听 Hook
+
+用于监听键盘组合键（如 `Ctrl+S`、`Alt+F2`、`Ctrl+Shift+A` 等）。
+
+#### 参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| `hotkeys` | `HotkeyConfig[]` | 是 | - | 监听的组合键配置数组 |
+| `onTrigger` | `(hotkey: HotkeyConfig, event: KeyboardEvent) => void` | 是 | - | 组合键触发回调 |
+| `preventDefault` | `boolean` | 否 | `false` | 是否阻止默认行为 |
+| `stopPropagation` | `boolean` | 否 | `false` | 是否阻止事件冒泡 |
+
+#### HotkeyConfig 配置
+
+```typescript
+interface HotkeyConfig {
+  key: string;      // 主键，如 'F2', 's', 'Enter'
+  ctrl?: boolean;   // 是否按住 Ctrl
+  alt?: boolean;    // 是否按住 Alt
+  shift?: boolean;  // 是否按住 Shift
+  meta?: boolean;   // 是否按住 Meta (Mac Command/Windows Win)
+}
+```
+
+#### 使用示例
+
+```tsx
+import { useHotkeyListener } from 'gzkx-package';
+
+const MyComponent = () => {
+  // 监听多个组合键
+  useHotkeyListener({
+    hotkeys: [
+      { key: 'F2' },                           // 单独 F2
+      { key: 'F2', ctrl: true },               // Ctrl+F2
+      { key: 's', ctrl: true, shift: true },   // Ctrl+Shift+S
+      { key: 'a', alt: true },                 // Alt+A
+    ],
+    onTrigger: (hotkey, event) => {
+      console.log('组合键触发:', hotkey);
+      // 根据触发的组合键执行不同操作
+    },
+    preventDefault: true,  // 阻止默认行为（如 Ctrl+S 保存页面）
+  });
+
+  return <div>按 F2 或 Ctrl+F2 触发</div>;
+};
+```
+
+### 1.2 useTakeShotHotkey - 截图专用组合键 Hook
+
+专门用于截图功能的组合键监听 Hook，是 `useHotkeyListener` 的简化封装。
+
+#### 参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| `onTakeShot` | `() => void` | 是 | - | 截图触发回调 |
+| `hotkeys` | `HotkeyConfig[]` | 否 | `[{ key: 'F2' }]` | 监听的组合键配置 |
+
+#### 使用示例
+
+```tsx
+import { useTakeShotHotkey, takeShot } from 'gzkx-package';
+import { message } from 'antd';
+
+const UltrasoundWorkstation = () => {
+  // 使用默认 F2 键截图
+  useTakeShotHotkey(async () => {
+    const result = await takeShot();
+    if (result.code === 200) {
+      message.success('截图成功');
+      console.log('截图数据:', result.data?.imageBase64);
+    } else {
+      message.error(`截图失败: ${result.msg}`);
+    }
+  });
+
+  // 或者自定义组合键
+  useTakeShotHotkey(
+    async () => {
+      const result = await takeShot();
+      // 处理截图结果...
+    },
+    [
+      { key: 'F9' },                    // F9 截图
+      { key: 'p', ctrl: true },         // Ctrl+P 截图
+      { key: 's', ctrl: true, shift: true }, // Ctrl+Shift+S 截图
+    ]
+  );
+
+  return <div>超声工作站 - 按 F9 或 Ctrl+P 截图</div>;
+};
+```
+
+### 1.3 takeShot - 截图接口
+
+调用本地截图服务进行截图。
+
+#### 配置方法
+
+```tsx
+import { setTakeShotConfig, takeShot } from 'gzkx-package';
+
+// 配置截图服务（通常在应用初始化时）
+setTakeShotConfig({
+  host: 'localhost',    // 截图服务主机
+  port: 28081,          // 截图服务端口
+  timeout: 10000,       // 请求超时时间(ms)
+});
+```
+
+#### 使用示例
+
+```tsx
+const handleCapture = async () => {
+  const result = await takeShot({
+    format: 'png',      // 图片格式
+    quality: 100,       // 图片质量
+  });
+
+  if (result.code === 200) {
+    // result.data.imageBase64 - Base64 图片数据
+    // result.data.imagePath - 图片保存路径
+    console.log('截图成功:', result.data);
+  } else {
+    console.error('截图失败:', result.msg);
+  }
+};
+```
+
+---
+
+## 2. CommonPage 通用页面组件
 
 ### 1.1 组件概述
 
@@ -406,7 +546,7 @@ export default DemoPage;
 
 ---
 
-## 2. CustomTable 自定义表格组件
+## 4. CustomTable 自定义表格组件
 
 ### 2.1 组件概述
 
@@ -543,7 +683,7 @@ const DemoTable = () => {
 
 ---
 
-## 3. CustomForm 自定义表单组件
+## 5. CustomForm 自定义表单组件
 
 ### 3.1 组件概述
 
@@ -687,7 +827,7 @@ const DemoForm = () => {
 
 ---
 
-## 4. CustomAdd 新增/编辑弹窗组件
+## 6. CustomAdd 新增/编辑弹窗组件
 
 ### 4.1 组件概述
 
@@ -993,7 +1133,7 @@ const validateConfig: ValidateConfig = {
 
 ---
 
-## 5. 常见使用场景
+## 7. 常见使用场景
 
 ### 5.1 完整的 CRUD 页面
 
@@ -1120,7 +1260,7 @@ const UserManagePage = () => {
 
 ---
 
-## 6. 注意事项
+## 8. 注意事项
 
 ### 6.1 表单字段命名
 
@@ -1147,7 +1287,7 @@ const UserManagePage = () => {
 
 ---
 
-## 7. 常见问题
+## 9. 常见问题
 
 ### Q1: 如何在表单提交前进行自定义验证？
 
@@ -1201,8 +1341,9 @@ formRef.current?.setFieldsValue({ name: '张三' });
 
 ---
 
-## 8. 更新日志
+## 10. 更新日志
 
+- **2026-04-14**: 新增组合键监听 Hooks (`useHotkeyListener`, `useTakeShotHotkey`) 和截图接口 (`takeShot`)
 - **2025-11-24**: CustomTable 添加了表格配置保存功能
 - **2025-04-27**: CommonPage 组件创建
 - **2025-04-23**: CustomTable 组件创建