桌面 Hooks

桌面应用专属 Hooks，包括全局快捷键、文件拖放、通知、窗口状态和脏状态检测

useGlobalShortcut

注册全局键盘快捷键，组件卸载时自动清理。

import { useGlobalShortcut } from '@linch-tech/desktop-core';

function App() {
  useGlobalShortcut('CommandOrControl+K', () => {
    openSearchDialog();
  });
}

签名

function useGlobalShortcut(
  shortcut: string,
  handler: () => void,
  enabled?: boolean
): void

参数

参数	类型	默认值	说明
`shortcut`	`string`	-	快捷键组合，如 `"CommandOrControl+K"`
`handler`	`() => void`	-	触发时的回调函数
`enabled`	`boolean`	`true`	是否启用

需要安装 @tauri-apps/plugin-global-shortcut（可选 peerDependency）

useFileDrop

监听文件拖放事件，获取拖入窗口的文件路径列表。

import { useFileDrop } from '@linch-tech/desktop-core';

function DropZone() {
  const ref = useFileDrop<HTMLDivElement>((paths) => {
    console.log('拖入的文件:', paths);
  });

  return <div ref={ref} className="drop-zone">将文件拖到这里</div>;
}

签名

function useFileDrop<T extends HTMLElement = HTMLElement>(
  handler: (paths: string[]) => void,
  enabled?: boolean
): RefObject<T | null>

参数

参数	类型	默认值	说明
`handler`	`(paths: string[]) => void`	-	收到文件时的回调
`enabled`	`boolean`	`true`	是否启用

useNotification

桌面原生通知，包含权限管理。

import { useNotification } from '@linch-tech/desktop-core';

function NotifyButton() {
  const { notify, isPermissionGranted, requestPermission } = useNotification();

  const handleClick = async () => {
    if (!isPermissionGranted) {
      await requestPermission();
    }
    await notify('任务完成', '数据处理已完成');
  };

  return <button onClick={handleClick}>发送通知</button>;
}

签名

function useNotification(): {
  notify: (title: string, body?: string, icon?: string) => Promise<void>;
  isPermissionGranted: boolean;
  requestPermission: () => Promise<boolean>;
}

需要安装 @tauri-apps/plugin-notification（可选 peerDependency）

useWindowState

持久化窗口位置和大小，重启后自动恢复。

import { useWindowState } from '@linch-tech/desktop-core';

function App() {
  const { position, size, isMaximized } = useWindowState();

  // 窗口位置/大小会自动保存到 localStorage
  // 下次启动时自动恢复
}

签名

function useWindowState(key?: string): {
  position: { x: number; y: number } | null;
  size: { width: number; height: number } | null;
  isMaximized: boolean;
  saveState: () => Promise<void>;
  restoreState: () => Promise<void>;
}

参数

参数	类型	默认值	说明
`key`	`string`	`"window-state"`	localStorage 存储键名

useDirtyState

追踪状态是否被修改（脏状态检测），用于退出前提示保存。

import { useDirtyState } from '@linch-tech/desktop-core';

function Editor() {
  const { value, setValue, isDirty, reset } = useDirtyState({ title: '', content: '' });

  const handleSave = async () => {
    await saveToDatabase(value);
    reset(); // 保存后重置为"干净"状态
  };

  return (
    <div>
      <input value={value.title} onChange={(e) => setValue({ ...value, title: e.target.value })} />
      {isDirty && <span>* 未保存</span>}
      <button onClick={handleSave} disabled={!isDirty}>保存</button>
    </div>
  );
}

签名

function useDirtyState<T>(initialValue: T): {
  value: T;
  setValue: (value: T) => void;
  isDirty: boolean;
  reset: () => void;
  original: T;
}

返回值

字段	类型	说明
`value`	`T`	当前值
`setValue`	`(value: T) => void`	更新值
`isDirty`	`boolean`	是否与初始值不同（深度比较）
`reset`	`() => void`	重置为初始值
`original`	`T`	初始值引用

桌面 Hooks

目录