gzkx-package 0.1.48 → 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 类型导出
 
@@ -155,6 +158,10 @@ import type {
   AddItemConfig,       // 新增/编辑表单配置类型
   ValidateConfig,      // 验证配置类型
   CommonPageHandle,    // CommonPage Ref 类型
+  CustomTableHandle,   // CustomTable Ref 类型
+  CustomColumnType,    // 自定义表格列类型
+  CustomColumnsType,   // 自定义表格列数组类型
+  HotkeyConfig,        // 组合键配置类型
 } from 'gzkx-package';
 ```
 
@@ -162,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 组件概述
 
@@ -252,6 +395,10 @@ interface CommonPageHandle {
   reload: () => void;                               // 重新加载列表
   getSearchFieldsValue: () => any;                  // 获取搜索表单值
   setSearchFieldsValue: (values: any) => void;      // 设置搜索表单值
+  /** 打开表格配置弹窗 */
+  openSettingModal: () => void;                     // 打开表格配置弹窗
+  /** 关闭表格配置弹窗 */
+  closeSettingModal: () => void;                    // 关闭表格配置弹窗
 }
 ```
 
@@ -399,7 +546,7 @@ export default DemoPage;
 
 ---
 
-## 2. CustomTable 自定义表格组件
+## 4. CustomTable 自定义表格组件
 
 ### 2.1 组件概述
 
@@ -428,7 +575,45 @@ export default DemoPage;
 3. **树形数据支持**：支持展开/收起树形数据。
 4. **Tooltip 支持**：单元格内容过长时自动显示 Tooltip。
 
-### 2.4 使用示例
+### 2.4 Ref 暴露的方法
+
+使用 `ref` 可以调用组件内部方法：
+
+```typescript
+interface CustomTableHandle {
+  openSettingModal: () => void;   // 打开表格配置弹窗
+  closeSettingModal: () => void;  // 关闭表格配置弹窗
+}
+```
+
+**使用示例：**
+
+```tsx
+import { useRef } from 'react';
+import CustomTable, { CustomTableHandle } from '@/components/customComponents/CustomTable';
+
+const Demo = () => {
+  const tableRef = useRef<CustomTableHandle>(null);
+
+  const handleOpenConfig = () => {
+    tableRef.current?.openSettingModal();
+  };
+
+  return (
+    <>
+      <Button onClick={handleOpenConfig}>打开表格配置</Button>
+      <CustomTable
+        ref={tableRef}
+        columns={columns}
+        dataSource={dataSource}
+        tableId="my-table"
+      />
+    </>
+  );
+};
+```
+
+### 2.5 使用示例
 
 ```tsx
 import CustomTable from '@/components/customComponents/CustomTable';
@@ -483,7 +668,7 @@ const DemoTable = () => {
 };
 ```
 
-### 2.5 列配置弹窗说明
+### 2.6 列配置弹窗说明
 
 当 `showTableConfig={true}` 时，序号列旁边会显示设置图标，点击后打开配置弹窗，可以配置：
 
@@ -498,7 +683,7 @@ const DemoTable = () => {
 
 ---
 
-## 3. CustomForm 自定义表单组件
+## 5. CustomForm 自定义表单组件
 
 ### 3.1 组件概述
 
@@ -642,7 +827,7 @@ const DemoForm = () => {
 
 ---
 
-## 4. CustomAdd 新增/编辑弹窗组件
+## 6. CustomAdd 新增/编辑弹窗组件
 
 ### 4.1 组件概述
 
@@ -948,7 +1133,7 @@ const validateConfig: ValidateConfig = {
 
 ---
 
-## 5. 常见使用场景
+## 7. 常见使用场景
 
 ### 5.1 完整的 CRUD 页面
 
@@ -1075,7 +1260,7 @@ const UserManagePage = () => {
 
 ---
 
-## 6. 注意事项
+## 8. 注意事项
 
 ### 6.1 表单字段命名
 
@@ -1102,7 +1287,7 @@ const UserManagePage = () => {
 
 ---
 
-## 7. 常见问题
+## 9. 常见问题
 
 ### Q1: 如何在表单提交前进行自定义验证？
 
@@ -1156,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 组件创建

package/dist/components/customComponents/CustomTable.d.ts

@@ -11,6 +11,12 @@ interface CustomColumnType<T = any> extends ColumnType<T> {
     contentAlignment?: 'left' | 'center' | 'right';
 }
 type CustomColumnsType<T = any> = CustomColumnType<T>[];
+export interface CustomTableHandle {
+    /** 打开表格配置弹窗 */
+    openSettingModal: () => void;
+    /** 关闭表格配置弹窗 */
+    closeSettingModal: () => void;
+}
 interface CustomTableProps {
     columns: CustomColumnsType;
     dataSource: any[];
@@ -24,6 +30,6 @@ interface CustomTableProps {
     showTableConfig?: boolean;
     [key: string]: any;
 }
-declare const CustomTable: React.FC<CustomTableProps>;
+declare const CustomTable: React.ForwardRefExoticComponent<Omit<CustomTableProps, "ref"> & React.RefAttributes<CustomTableHandle>>;
 export default CustomTable;
 export type { CustomColumnType, CustomColumnsType };

package/dist/components/customComponents/commonPage/index.d.ts

@@ -9,6 +9,10 @@ export interface CommonPageHandle {
     reload: () => void;
     getSearchFieldsValue: () => any;
     setSearchFieldsValue: (values: any) => void;
+    /** 打开表格配置弹窗 */
+    openSettingModal: () => void;
+    /** 关闭表格配置弹窗 */
+    closeSettingModal: () => void;
 }
 interface CommonPageProps {
     onSearchFormChange?: (name: string, value: any) => void;