@cloudeasy/spider-react-hooks

基于最佳实践的 React Hooks 核心库

📦 安装

npm install @cloudeasy/spider-react-hooks
# 或
yarn add @cloudeasy/spider-react-hooks
# 或
pnpm add @cloudeasy/spider-react-hooks

✨ 特性

• 🚀 高性能: 基于最佳实践优化的 React Hooks
• 📝 TypeScript: 完整的 TypeScript 类型支持
• 🧪 测试覆盖: 完整的单元测试覆盖
• 📚 文档完善: 详细的使用文档和示例
• 🔧 开箱即用: 零配置，直接使用
• 🌳 Tree Shaking: 支持按需导入，减小包体积

🎯 Hooks 列表

异步处理

• useAsync - 异步操作状态管理
• useRequest - HTTP 请求管理
• useDebounce - 防抖处理
• useThrottle - 节流处理

状态管理

• useDisclosure - 开关状态管理
• useListState - 列表状态管理
• useUncontrolled - 受控/非受控状态
• usePrevious - 获取前一个值
• useForceUpdate - 强制更新组件

存储相关

• useLocalStorage - localStorage 管理
• useSessionStorage - sessionStorage 管理
• useClipboard - 剪贴板操作

用户交互

• useHotkeys - 快捷键处理
• useTextSelection - 文本选择
• usePageEnter - 页面进入检测
• usePageLeave - 页面离开检测

设备检测

• useMediaQuery - 媒体查询
• useReducedMotion - 减少动画偏好检测
• useIntersectionObserver - 元素可见性检测

工具类

• useDidUpdate - 组件更新检测
• useIsomorphicEffect - 同构副作用
• useWindowEvent - 窗口事件监听
• useLogger - 日志记录
• usePerformanceMonitor - 性能监控
• usePagination - 分页管理
• useQueue - 队列管理
• useScrollIntoView - 滚动到视图

🚀 快速开始

import React from 'react';
import { useAsync, useClipboard, useLocalStorage } from '@cloudeasy/spider-react-hooks';

function App() {
  // 异步操作
  const { execute, loading, error, data } = useAsync(async () => {
    const response = await fetch('/api/data');
    return response.json();
  });

  // 剪贴板操作
  const { copy, copied } = useClipboard();

  // 本地存储
  const [theme, setTheme] = useLocalStorage('theme', 'light');

  return (
    <div>
      <button onClick={execute} disabled={loading}>
        {loading ? '加载中...' : '获取数据'}
      </button>

      <button onClick={() => copy('Hello World!')}>{copied ? '已复制!' : '复制文本'}</button>

      <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
        当前主题: {theme}
      </button>

      {error && <div>错误: {error.message}</div>}
      {data && <pre>{JSON.stringify(data, null, 2)}</pre>}
    </div>
  );
}

📖 API 文档

useAsync

异步操作状态管理 Hook。

const { execute, loading, error, data, reset } = useAsync(asyncFunction, options);

参数:

• asyncFunction: 异步函数
• options: 配置选项
  • immediate?: boolean - 是否立即执行，默认 false
  • onSuccess?: (data: T) => void - 成功回调
  • onError?: (error: Error) => void - 错误回调

返回值:

• execute: 执行函数
• loading: 加载状态
• error: 错误信息
• data: 返回数据
• reset: 重置状态

useClipboard

剪贴板操作 Hook。

const { copy, copied, error, reset } = useClipboard(options);

参数:

• options: 配置选项
  • timeout?: number - 复制状态持续时间，默认 2000ms

返回值:

• copy: 复制函数
• copied: 是否已复制
• error: 错误信息
• reset: 重置状态

useLocalStorage / useSessionStorage

本地存储 Hook。

const [value, setValue, removeValue] = useLocalStorage(key, defaultValue);

参数:

• key: 存储键名
• defaultValue: 默认值

返回值:

• value: 当前值
• setValue: 设置值函数
• removeValue: 删除值函数

useDebounce

防抖 Hook。

const debouncedValue = useDebounce(value, delay);
const debouncedFn = useDebounceFn(fn, delay);
useDebounceEffect(effect, deps, delay);

useMediaQuery

媒体查询 Hook。

const matches = useMediaQuery('(min-width: 768px)');

useHotkeys

快捷键 Hook。

useHotkeys('ctrl+s', () => {
  console.log('保存');
});

🛠️ 工具函数

除了 Hooks，我们还提供了一些实用的工具函数：

import { clamp, randomId, shallowEqual } from '@cloudeasy/spider-react-hooks';

// 数值限制
const value = clamp(15, 0, 10); // 10

// 生成随机ID
const id = randomId(); // "mantine-r4nd0m1d"

// 浅比较
const isEqual = shallowEqual({ a: 1 }, { a: 1 }); // true

🔧 开发

# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建
pnpm build

# 测试
pnpm test

# 类型检查
pnpm type-check

# 代码检查
pnpm lint

📦 发布

本项目使用 Changeset 进行版本管理和发布。

快速发布

# 1. 创建 changeset（描述你的更改）
pnpm changeset

# 2. 提交更改
git add . && git commit -m "add changeset"

# 3. 运行发布脚本
# 交互式发布（推荐）
pnpm publish:interactive

# 快速发布（构建+测试+发布）
pnpm publish:quick

如果你确信代码已经准备好发布，可以使用快速发布命令：

pnpm publish:quick

这个命令会跳过一些交互式确认，直接进行发布。

注意： 发布脚本已优化为只发布 core 包，无需担心影响其他包。

发布工具命令

• pnpm publish:check - 检查待发布的更改
• pnpm publish:dry-run - 详细查看发布计划
• pnpm publish:interactive - 交互式发布流程
• pnpm publish:quick - 快速发布（跳过交互）

手动发布

# 查看待发布的更改
pnpm changeset status

# 更新版本号
pnpm version-packages

# 发布到 npm
pnpm release