gzkx-package 0.1.49 → 0.1.51

package/README.md

@@ -1,6 +1,6 @@
 # 自定义组件使用文档
 
-本文档详细介绍了项目中四个核心自定义组件的使用方法和参数说明。
+本文档详细介绍了项目中核心自定义组件和工具 Hooks 的使用方法和参数说明。
 
 ---
 
@@ -9,10 +9,19 @@
 - [安装](#安装)
 - [快速开始](#快速开始)
 - [组件列表](#组件列表)
-  1. [CommonPage 通用页面组件](#1-commonpage-通用页面组件)
-  2. [CustomTable 自定义表格组件](#2-customtable-自定义表格组件)
-  3. [CustomForm 自定义表单组件](#3-customform-自定义表单组件)
-  4. [CustomAdd 新增/编辑弹窗组件](#4-customadd-新增编辑弹窗组件)
+  1. [工具 Hooks](#1-工具-hooks)
+     - [useHotkeyListener 组合键监听](#11-usehotkeylistener---组合键监听-hook)
+     - [useTakeShotHotkey 截图专用组合键](#12-usetakeshothotkey---截图专用组合键-hook)
+     - [takeShot 截图接口](#13-takeshot---截图接口)
+  2. [CommonPage 通用页面组件](#2-commonpage-通用页面组件)
+  3. [CustomTable 自定义表格组件](#3-customtable-自定义表格组件)
+  4. [CustomForm 自定义表单组件](#4-customform-自定义表单组件)
+  5. [CustomAdd 新增/编辑弹窗组件](#5-customadd-新增编辑弹窗组件)
+  6. [常见使用场景](#6-常见使用场景)
+  7. [注意事项](#7-注意事项)
+  8. [常见问题](#8-常见问题)
+  9. [更新日志](#9-更新日志)
+  10. [技术支持](#10-技术支持)
 
 ---
 
@@ -146,6 +155,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 +170,7 @@ import type {
   CustomTableHandle,   // CustomTable Ref 类型
   CustomColumnType,    // 自定义表格列类型
   CustomColumnsType,   // 自定义表格列数组类型
+  HotkeyConfig,        // 组合键配置类型
 } from 'gzkx-package';
 ```
 
@@ -165,13 +178,149 @@ import type {
 
 ## 组件列表
 
-## 1. CommonPage 通用页面组件
+## 1. 工具 Hooks
 
-### 1.1 组件概述
+### 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);
+  }
+};
+```
+
+---
+
+## 3. CommonPage 通用页面组件
+
+### 3.1 组件概述
 
 `CommonPage` 是一个集成了搜索表单、数据表格、新增/编辑弹窗的通用页面组件，适用于大部分 CRUD 操作场景。
 
-### 1.2 Props 参数
+### 3.2 Props 参数
 
 | 参数名 | 类型 | 必填 | 默认值 | 说明 |
 |--------|------|------|--------|------|
@@ -207,7 +356,7 @@ import type {
 | `validateConfig` | `ValidateConfig` | 否 | - | 表单验证配置 |
 | `tableConfig` | `any` | 否 | - | 表格额外配置 |
 
-#### 1.2.1 详细参数说明
+#### 3.2.1 详细参数说明
 
 **postParams 对象结构：**
 
@@ -243,7 +392,7 @@ import type {
 }
 ```
 
-### 1.3 Ref 暴露的方法
+### 3.3 Ref 暴露的方法
 
 使用 `ref` 可以调用组件内部方法：
 
@@ -262,7 +411,7 @@ interface CommonPageHandle {
 }
 ```
 
-### 1.4 使用示例
+### 3.4 使用示例
 
 ```tsx
 import { useRef } from 'react';
@@ -406,13 +555,13 @@ export default DemoPage;
 
 ---
 
-## 2. CustomTable 自定义表格组件
+## 4. CustomTable 自定义表格组件
 
-### 2.1 组件概述
+### 4.1 组件概述
 
 `CustomTable` 是对 Ant Design Table 组件的增强封装，支持用户自定义表格列配置、保存配置到后端、序号列、树形数据等功能。
 
-### 2.2 Props 参数
+### 4.2 Props 参数
 
 | 参数名 | 类型 | 必填 | 默认值 | 说明 |
 |--------|------|------|--------|------|
@@ -428,14 +577,14 @@ export default DemoPage;
 | `showTableConfig` | `boolean` | 否 | `true` | 是否显示表格配置按钮和序号列 |
 | `...rest` | `any` | 否 | - | 其他 Ant Design Table 原生属性 |
 
-### 2.3 特色功能
+### 4.3 特色功能
 
 1. **表格配置功能**：用户可以自定义列的显示、宽度、对齐方式、排序等，配置会保存到后端。
 2. **自动序号列**：自动添加序号列（可通过 `showTableConfig` 控制）。
 3. **树形数据支持**：支持展开/收起树形数据。
 4. **Tooltip 支持**：单元格内容过长时自动显示 Tooltip。
 
-### 2.4 Ref 暴露的方法
+### 4.4 Ref 暴露的方法
 
 使用 `ref` 可以调用组件内部方法：
 
@@ -528,7 +677,7 @@ const DemoTable = () => {
 };
 ```
 
-### 2.6 列配置弹窗说明
+### 4.6 列配置弹窗说明
 
 当 `showTableConfig={true}` 时，序号列旁边会显示设置图标，点击后打开配置弹窗，可以配置：
 
@@ -543,13 +692,13 @@ const DemoTable = () => {
 
 ---
 
-## 3. CustomForm 自定义表单组件
+## 5. CustomForm 自定义表单组件
 
-### 3.1 组件概述
+### 5.1 组件概述
 
 `CustomForm` 是一个基于配置的表单组件，通过传入配置数组即可快速生成表单，支持多种表单项类型。
 
-### 3.2 Props 参数
+### 5.2 Props 参数
 
 | 参数名 | 类型 | 必填 | 默认值 | 说明 |
 |--------|------|------|--------|------|
@@ -568,7 +717,7 @@ const DemoTable = () => {
 | `onSearchFormChange` | `Function` | 否 | - | 表单值变化回调 |
 | `...restFormProps` | `any` | 否 | - | 其他 Ant Design Form 原生属性 |
 
-### 3.3 FormItemConfig 配置项
+### 5.3 FormItemConfig 配置项
 
 ```typescript
 interface FormItemConfig {
@@ -593,7 +742,7 @@ interface FormItemOption {
 }
 ```
 
-### 3.4 支持的表单类型
+### 5.4 支持的表单类型
 
 | type 值 | 说明 | 额外属性 |
 |---------|------|---------|
@@ -607,7 +756,7 @@ interface FormItemOption {
 | `deptSelect` | 科室选择（自动加载数据） | - |
 | `orgSelect` | 机构选择（自动加载数据） | - |
 
-### 3.5 Ref 暴露的方法
+### 5.5 Ref 暴露的方法
 
 ```typescript
 interface CustomFormHandle {
@@ -616,7 +765,7 @@ interface CustomFormHandle {
 }
 ```
 
-### 3.6 使用示例
+### 5.6 使用示例
 
 ```tsx
 import { useRef } from 'react';
@@ -687,13 +836,13 @@ const DemoForm = () => {
 
 ---
 
-## 4. CustomAdd 新增/编辑弹窗组件
+## 6. CustomAdd 新增/编辑弹窗组件
 
-### 4.1 组件概述
+### 6.1 组件概述
 
 `CustomAdd` 是一个功能强大的弹窗表单组件，支持新增、编辑、查看三种模式，支持多种表单项类型、表单验证、Tab 分组等。
 
-### 4.2 Props 参数
+### 6.2 Props 参数
 
 | 参数名 | 类型 | 必填 | 默认值 | 说明 |
 |--------|------|------|--------|------|
@@ -711,7 +860,7 @@ const DemoForm = () => {
 | `CustomModalFooter` | `Function` | 否 | - | 自定义底部按钮 |
 | `validateConfig` | `ValidateConfig` | 否 | - | 验证配置 |
 
-### 4.3 AddItemConfig 配置项
+### 6.3 AddItemConfig 配置项
 
 ```typescript
 interface AddItemConfig {
@@ -740,7 +889,7 @@ interface AddItemConfig {
 }
 ```
 
-### 4.4 支持的表单类型
+### 6.4 支持的表单类型
 
 | type 值 | 说明 | 额外配置 |
 |---------|------|---------|
@@ -764,7 +913,7 @@ interface AddItemConfig {
 | `inputnumberoption` | 数字输入框+下拉框组合 | `optionname`, `options` |
 | `doubleValue` | 双输入框（如范围） | `firstLabel`, `secondLabel`, `separator` |
 
-### 4.5 ValidateConfig 验证配置
+### 6.5 ValidateConfig 验证配置
 
 ```typescript
 interface ValidateConfig {
@@ -780,7 +929,7 @@ interface ValidateConfig {
 }
 ```
 
-### 4.6 Ref 暴露的方法
+### 6.6 Ref 暴露的方法
 
 ```typescript
 interface CustomAddHandle {
@@ -789,9 +938,9 @@ interface CustomAddHandle {
 }
 ```
 
-### 4.7 使用示例
+### 6.7 使用示例
 
-#### 4.7.1 基础使用
+#### 6.7.1 基础使用
 
 ```tsx
 import { useState, useRef } from 'react';
@@ -928,7 +1077,7 @@ const tabFormConfig = [
 />
 ```
 
-#### 4.7.3 带验证配置
+#### 6.7.3 带验证配置
 
 ```tsx
 const validateConfig: ValidateConfig = {
@@ -951,7 +1100,7 @@ const validateConfig: ValidateConfig = {
 />
 ```
 
-#### 4.7.4 特殊类型示例
+#### 6.7.4 特殊类型示例
 
 ```tsx
 // 双输入框（范围）
@@ -993,9 +1142,9 @@ const validateConfig: ValidateConfig = {
 
 ---
 
-## 5. 常见使用场景
+## 7. 常见使用场景
 
-### 5.1 完整的 CRUD 页面
+### 7.1 完整的 CRUD 页面
 
 ```tsx
 import { useRef } from 'react';
@@ -1084,7 +1233,7 @@ const UserManagePage = () => {
 };
 ```
 
-### 5.2 自定义操作列
+### 7.2 自定义操作列
 
 ```tsx
 <CommonPage
@@ -1101,7 +1250,7 @@ const UserManagePage = () => {
 />
 ```
 
-### 5.3 带权限控制
+### 7.3 带权限控制
 
 ```tsx
 <CommonPage
@@ -1120,25 +1269,25 @@ const UserManagePage = () => {
 
 ---
 
-## 6. 注意事项
+## 8. 注意事项
 
-### 6.1 表单字段命名
+### 8.1 表单字段命名
 
 1. **日期范围字段**：使用 `/` 分隔，如 `startDate/endDate`，组件会自动拆分为两个字段。
 2. **输入框+下拉框组合**：使用 `name` 和 `optionname` 分别定义两个字段。
 3. **双输入框**：使用 `firstLabel` 和 `secondLabel` 定义两个字段名。
 
-### 6.2 数据格式
+### 8.2 数据格式
 
 1. **日期数据**：后端返回的日期字符串会自动转换为 dayjs 对象，提交时根据 `dateFormat` 格式化。
 2. **树形选择多选**：多选时，后端返回逗号分隔的字符串（如 "1,2,3"），组件会自动转换为数组。
 
-### 6.3 性能优化
+### 8.3 性能优化
 
 1. **tableId**：为表格设置唯一 ID，用户的列配置会保存到后端，避免每次都重新配置。
 2. **防抖**：组件内部已对列表刷新、实时验证等操作做了防抖处理。
 
-### 6.4 样式定制
+### 8.4 样式定制
 
 组件使用了 CSS Modules，如需定制样式，可以：
 1. 通过 `className` 传入自定义类名
@@ -1147,7 +1296,7 @@ const UserManagePage = () => {
 
 ---
 
-## 7. 常见问题
+## 9. 常见问题
 
 ### Q1: 如何在表单提交前进行自定义验证？
 
@@ -1201,14 +1350,15 @@ 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 组件创建
 
 ---
 
-## 9. 技术支持
+## 11. 技术支持
 
 如有问题，请联系开发团队或查看源代码注释。