component-library-for-react 1.0.0

package/dist/es/hooks/index.js

@@ -0,0 +1 @@
+import e from"./useDebounce.js";import t from"./useThrottle.js";import n from"./useClickOutside.js";export{n as useClickOutside,e as useDebounce,t as useThrottle};

package/dist/es/hooks/useClickOutside.js

@@ -0,0 +1 @@
+import{useEffect as e,useRef as t}from"react";var n=(n,r)=>{let i=t(r);e(()=>{i.current=r},[r]),e(()=>{let e=e=>{let t=n.current;!t||t.contains(e.target)||i.current(e)};return document.addEventListener(`click`,e),document.addEventListener(`touchstart`,e),()=>{document.removeEventListener(`click`,e),document.removeEventListener(`touchstart`,e)}},[n])};export{n as default};

package/dist/es/hooks/useDebounce.js

@@ -0,0 +1 @@
+import{useCallback as e,useEffect as t,useRef as n}from"react";var r=(r,i,a=!1)=>{let o=n(null),s=e(()=>{o.current&&=(clearTimeout(o.current),null)},[]),c=e((...e)=>{if(o.current&&clearTimeout(o.current),a){let t=!o.current;o.current=setTimeout(()=>{o.current=null},i),t&&r(...e)}else o.current=setTimeout(()=>{r(...e),o.current=null},i)},[r,i,a]);return t(()=>s,[s]),{run:c,cancel:s}};export{r as default};

package/dist/es/hooks/useThrottle.js

@@ -0,0 +1 @@
+import{useCallback as e,useEffect as t,useRef as n}from"react";function r(r,i=300,a=!1){let o=n(r),s=n(null),c=n(0);t(()=>{o.current=r},[r]);let l=e(()=>{s.current&&=(clearTimeout(s.current),null),c.current=0},[]),u=e((...e)=>{let t=Date.now();if(c.current===0){if(a){o.current(...e),c.current=t;return}c.current=t}let n=i-(t-c.current);n<=0?(s.current&&=(clearTimeout(s.current),null),o.current(...e),c.current=t):s.current||=setTimeout(()=>{o.current(...e),c.current=Date.now(),s.current=null},n)},[i,a]);return t(()=>l,[l]),{run:u,cancel:l}}export{r as default};

package/dist/es/index.js

@@ -0,0 +1 @@
+import e from"./hooks/useDebounce.js";import t from"./hooks/useThrottle.js";import n from"./hooks/useClickOutside.js";import"./hooks/index.js";import r from"./packages/LazyLoadImage/index.js";import i from"./packages/VirtualList/index.js";import a from"./packages/Upload/index.js";import"./packages/index.js";export{r as LazyLoadImage,a as Upload,i as VirtualList,n as useClickOutside,e as useDebounce,t as useThrottle};

package/dist/es/packages/LazyLoadImage/index.js

@@ -0,0 +1 @@
+import{useEffect as e,useRef as t,useState as n}from"react";import{Fragment as r,jsx as i}from"@emotion/react/jsx-runtime";var a=({src:a,placeholder:o,alt:s,className:c=``,style:l={}})=>{let[u,d]=n(o),[f,p]=n(!1),m=t(null);return e(()=>{if(!m.current)return;let e=new IntersectionObserver(([t])=>{t.isIntersecting&&(d(a),m.current&&e.unobserve(m.current))});return e.observe(m.current),()=>{e.disconnect()}},[a]),i(r,{children:i(`img`,{src:u,alt:s,ref:m,className:c,style:{objectFit:`cover`,transition:`opacity 0.3s ease-in-out`,opacity:f?1:.5,width:`200px`,...l},onLoad:()=>{p(!0)}})})};export{a as default};

package/dist/es/packages/Upload/index.js

@@ -0,0 +1,5 @@
+import{useRef as e,useState as t}from"react";import{jsx as n,jsxs as r}from"@emotion/react/jsx-runtime";import{css as i}from"@emotion/react";var a=({accept:a,action:o,multiple:s=!1,maxCount:c,onChange:l})=>{let u=e(null),[d,f]=t([]),[p,m]=t(!1),h=()=>{u.current&&u.current.click()},g=async e=>{let t=e.target.files?Array.from(e.target.files):[];if(t.length===0)return;let n=[...d,...t];c&&n.length>c&&(n=n.slice(0,c),alert(`最多只能上传${c}个文件`)),f(n),l?.(n);try{await _(n)}catch(e){console.log(e)}finally{u.current&&(u.current.value=``)}},_=async e=>{m(!0);let t=new FormData;s?e.forEach(e=>{t.append(`files`,e)}):t.append(`file`,e[0]);try{return(await fetch(o,{method:`POST`,body:t})).ok?!0:Error(`上传失败`)}catch{return Error(`上传失败`)}finally{m(!1)}},v=e=>{let t=d.filter((t,n)=>n!==e);f(t),l?.(t)},y=i`cursor:pointer;padding:8px 16px;`,b=i`display:none;`,x=i`margin-top:15px;list-style:none;padding-left:0px;
+    li {
+    margin-bottom:8px;
+    }
+    `;return r(`div`,{children:[n(`input`,{type:`file`,ref:u,accept:a,multiple:s,onChange:g,css:b}),n(`button`,{onClick:h,disabled:p,css:y,children:p?`上传中...`:`请选择上传的文件`}),n(`ul`,{css:x,children:d.map((e,t)=>r(`li`,{children:[n(`span`,{style:{marginRight:`10px`},children:e.name}),r(`span`,{style:{color:`#888`,fontSize:`12px`,marginRight:`15px`},children:[`(`,(e.size/1024).toFixed(2),` KB)`]}),n(`button`,{onClick:()=>v(t),style:{color:`red`,border:`none`,background:`none`,cursor:`pointer`},children:`删除`})]},e.name))})]})};export{a as default};

package/dist/es/packages/VirtualList/index.js

@@ -0,0 +1 @@
+import{useMemo as e,useRef as t,useState as n}from"react";import{jsx as r,jsxs as i}from"@emotion/react/jsx-runtime";import{css as a}from"@emotion/react";var o=({listData:o,itemHeight:s,height:c,renderItem:l})=>{let[u,d]=n(0),f=t(null),p=o.length*s,{startIndex:m,endIndex:h,startOffset:g}=e(()=>{let e=Math.floor(u/s),t=e+Math.ceil(c/s),n=Math.max(0,e-2);return{startIndex:n,endIndex:Math.min(o.length,t+2),startOffset:n*s}},[u,o.length,s,c]),_=e(()=>o.slice(m,h),[o,m,h]),v=e=>{e.currentTarget&&d(e?.currentTarget?.scrollTop)},y=a`height:${c}px;overflow-y:auto;position:relative;border:1px solid #ccc;`,b=a`height: ${p}px; position: absolute;width: 100%; top: 0;left: 0;z-index: -1;`,x=a`transform: translateY(${g}px);position: absolute; left: 0; right: 0;top: 0 `;return i(`div`,{ref:f,onScroll:v,css:y,children:[r(`div`,{css:b}),r(`div`,{css:x,children:_.map((e,t)=>{let n=m+t;return r(`div`,{style:{height:`${s}px`},children:l(e,n)},n)})})]})};export{o as default};

package/dist/es/packages/index.js

@@ -0,0 +1 @@
+import e from"./LazyLoadImage/index.js";import t from"./VirtualList/index.js";import n from"./Upload/index.js";export{e as LazyLoadImage,n as Upload,t as VirtualList};

package/dist/lib/_virtual/_rolldown/runtime.js

@@ -0,0 +1 @@
+var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,a)=>(a=n==null?{}:e(i(n)),o(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));exports.__toESM=s;

package/dist/lib/hooks/index.js

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./useDebounce.js"),t=require("./useThrottle.js"),n=require("./useClickOutside.js");exports.useClickOutside=n.default,exports.useDebounce=e.default,exports.useThrottle=t.default;

package/dist/lib/hooks/useClickOutside.js

@@ -0,0 +1 @@
+let e=require("react");var t=(t,n)=>{let r=(0,e.useRef)(n);(0,e.useEffect)(()=>{r.current=n},[n]),(0,e.useEffect)(()=>{let e=e=>{let n=t.current;!n||n.contains(e.target)||r.current(e)};return document.addEventListener(`click`,e),document.addEventListener(`touchstart`,e),()=>{document.removeEventListener(`click`,e),document.removeEventListener(`touchstart`,e)}},[t])};exports.default=t;

package/dist/lib/hooks/useDebounce.js

@@ -0,0 +1 @@
+let e=require("react");var t=(t,n,r=!1)=>{let i=(0,e.useRef)(null),a=(0,e.useCallback)(()=>{i.current&&=(clearTimeout(i.current),null)},[]),o=(0,e.useCallback)((...e)=>{if(i.current&&clearTimeout(i.current),r){let r=!i.current;i.current=setTimeout(()=>{i.current=null},n),r&&t(...e)}else i.current=setTimeout(()=>{t(...e),i.current=null},n)},[t,n,r]);return(0,e.useEffect)(()=>a,[a]),{run:o,cancel:a}};exports.default=t;

package/dist/lib/hooks/useThrottle.js

@@ -0,0 +1 @@
+let e=require("react");function t(t,n=300,r=!1){let i=(0,e.useRef)(t),a=(0,e.useRef)(null),o=(0,e.useRef)(0);(0,e.useEffect)(()=>{i.current=t},[t]);let s=(0,e.useCallback)(()=>{a.current&&=(clearTimeout(a.current),null),o.current=0},[]),c=(0,e.useCallback)((...e)=>{let t=Date.now();if(o.current===0){if(r){i.current(...e),o.current=t;return}o.current=t}let s=n-(t-o.current);s<=0?(a.current&&=(clearTimeout(a.current),null),i.current(...e),o.current=t):a.current||=setTimeout(()=>{i.current(...e),o.current=Date.now(),a.current=null},s)},[n,r]);return(0,e.useEffect)(()=>s,[s]),{run:c,cancel:s}}exports.default=t;

package/dist/lib/index.js

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./hooks/useDebounce.js"),t=require("./hooks/useThrottle.js"),n=require("./hooks/useClickOutside.js");require("./hooks/index.js");const r=require("./packages/LazyLoadImage/index.js"),i=require("./packages/VirtualList/index.js"),a=require("./packages/Upload/index.js");require("./packages/index.js"),exports.LazyLoadImage=r.default,exports.Upload=a.default,exports.VirtualList=i.default,exports.useClickOutside=n.default,exports.useDebounce=e.default,exports.useThrottle=t.default;

package/dist/lib/packages/LazyLoadImage/index.js

@@ -0,0 +1 @@
+let e=require("react"),t=require("@emotion/react/jsx-runtime");var n=({src:n,placeholder:r,alt:i,className:a=``,style:o={}})=>{let[s,c]=(0,e.useState)(r),[l,u]=(0,e.useState)(!1),d=(0,e.useRef)(null);return(0,e.useEffect)(()=>{if(!d.current)return;let e=new IntersectionObserver(([t])=>{t.isIntersecting&&(c(n),d.current&&e.unobserve(d.current))});return e.observe(d.current),()=>{e.disconnect()}},[n]),(0,t.jsx)(t.Fragment,{children:(0,t.jsx)(`img`,{src:s,alt:i,ref:d,className:a,style:{objectFit:`cover`,transition:`opacity 0.3s ease-in-out`,opacity:l?1:.5,width:`200px`,...o},onLoad:()=>{u(!0)}})})};exports.default=n;

package/dist/lib/packages/Upload/index.js

@@ -0,0 +1,5 @@
+const e=require("../../_virtual/_rolldown/runtime.js");let t=require("react");t=e.__toESM(t,1);let n=require("@emotion/react/jsx-runtime"),r=require("@emotion/react");var i=({accept:e,action:i,multiple:a=!1,maxCount:o,onChange:s})=>{let c=(0,t.useRef)(null),[l,u]=(0,t.useState)([]),[d,f]=(0,t.useState)(!1),p=()=>{c.current&&c.current.click()},m=async e=>{let t=e.target.files?Array.from(e.target.files):[];if(t.length===0)return;let n=[...l,...t];o&&n.length>o&&(n=n.slice(0,o),alert(`最多只能上传${o}个文件`)),u(n),s?.(n);try{await h(n)}catch(e){console.log(e)}finally{c.current&&(c.current.value=``)}},h=async e=>{f(!0);let t=new FormData;a?e.forEach(e=>{t.append(`files`,e)}):t.append(`file`,e[0]);try{return(await fetch(i,{method:`POST`,body:t})).ok?!0:Error(`上传失败`)}catch{return Error(`上传失败`)}finally{f(!1)}},g=e=>{let t=l.filter((t,n)=>n!==e);u(t),s?.(t)},_=r.css`cursor:pointer;padding:8px 16px;`,v=r.css`display:none;`,y=r.css`margin-top:15px;list-style:none;padding-left:0px;
+    li {
+    margin-bottom:8px;
+    }
+    `;return(0,n.jsxs)(`div`,{children:[(0,n.jsx)(`input`,{type:`file`,ref:c,accept:e,multiple:a,onChange:m,css:v}),(0,n.jsx)(`button`,{onClick:p,disabled:d,css:_,children:d?`上传中...`:`请选择上传的文件`}),(0,n.jsx)(`ul`,{css:y,children:l.map((e,t)=>(0,n.jsxs)(`li`,{children:[(0,n.jsx)(`span`,{style:{marginRight:`10px`},children:e.name}),(0,n.jsxs)(`span`,{style:{color:`#888`,fontSize:`12px`,marginRight:`15px`},children:[`(`,(e.size/1024).toFixed(2),` KB)`]}),(0,n.jsx)(`button`,{onClick:()=>g(t),style:{color:`red`,border:`none`,background:`none`,cursor:`pointer`},children:`删除`})]},e.name))})]})};exports.default=i;

package/dist/lib/packages/VirtualList/index.js

@@ -0,0 +1 @@
+const e=require("../../_virtual/_rolldown/runtime.js");let t=require("react");t=e.__toESM(t,1);let n=require("@emotion/react/jsx-runtime"),r=require("@emotion/react");var i=({listData:e,itemHeight:i,height:a,renderItem:o})=>{let[s,c]=(0,t.useState)(0),l=(0,t.useRef)(null),u=e.length*i,{startIndex:d,endIndex:f,startOffset:p}=(0,t.useMemo)(()=>{let t=Math.floor(s/i),n=t+Math.ceil(a/i),r=Math.max(0,t-2);return{startIndex:r,endIndex:Math.min(e.length,n+2),startOffset:r*i}},[s,e.length,i,a]),m=(0,t.useMemo)(()=>e.slice(d,f),[e,d,f]),h=e=>{e.currentTarget&&c(e?.currentTarget?.scrollTop)},g=r.css`height:${a}px;overflow-y:auto;position:relative;border:1px solid #ccc;`,_=r.css`height: ${u}px; position: absolute;width: 100%; top: 0;left: 0;z-index: -1;`,v=r.css`transform: translateY(${p}px);position: absolute; left: 0; right: 0;top: 0 `;return(0,n.jsxs)(`div`,{ref:l,onScroll:h,css:g,children:[(0,n.jsx)(`div`,{css:_}),(0,n.jsx)(`div`,{css:v,children:m.map((e,t)=>{let r=d+t;return(0,n.jsx)(`div`,{style:{height:`${i}px`},children:o(e,r)},r)})})]})};exports.default=i;

package/dist/lib/packages/index.js

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./LazyLoadImage/index.js"),t=require("./VirtualList/index.js"),n=require("./Upload/index.js");exports.LazyLoadImage=e.default,exports.Upload=n.default,exports.VirtualList=t.default;

package/dist/types/hooks/index.d.ts

@@ -0,0 +1,4 @@
+import { default as useDebounce } from './useDebounce';
+import { default as useThrottle } from './useThrottle';
+import { default as useClickOutside } from './useClickOutside';
+export { useDebounce, useThrottle, useClickOutside };

package/dist/types/hooks/useClickOutside.d.ts

@@ -0,0 +1,2 @@
+declare const useClickOutsideFn: <T extends HTMLElement>(ref: React.RefObject<T | null>, handler: (event: MouseEvent | TouchEvent) => void) => void;
+export default useClickOutsideFn;

package/dist/types/hooks/useDebounce.d.ts

@@ -0,0 +1,7 @@
+type FunctionType = (...args: any[]) => any;
+type FunctionReturn<T extends FunctionType> = {
+    run: (...args: Parameters<T>) => void;
+    cancel: () => void;
+};
+declare const useDebounceFn: <T extends FunctionType>(fn: T, delay: number, immediate?: boolean) => FunctionReturn<T>;
+export default useDebounceFn;

package/dist/types/hooks/useThrottle.d.ts

@@ -0,0 +1,7 @@
+type FunctionType = (...args: any[]) => any;
+type FunctionRetur<T extends FunctionType> = {
+    run: (...args: Parameters<T>) => void;
+    cancel: () => void;
+};
+declare function useThrottleFn<T extends FunctionType>(fn: T, delay?: number, immediate?: boolean): FunctionRetur<T>;
+export default useThrottleFn;

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from './hooks';
+export * from './packages';

package/dist/types/packages/LazyLoadImage/index.d.ts

@@ -0,0 +1,10 @@
+import { CSSProperties } from 'react';
+interface LazyLoadImagePropsType {
+    src: string;
+    placeholder: string;
+    alt?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+declare const LazyLoadImage: ({ src, placeholder, alt, className, style }: LazyLoadImagePropsType) => import("@emotion/react/jsx-runtime").JSX.Element;
+export default LazyLoadImage;

package/dist/types/packages/Upload/index.d.ts

@@ -0,0 +1,9 @@
+interface UploadPropsType {
+    accept?: string;
+    action: string;
+    multiple?: boolean;
+    maxCount?: number;
+    onChange?: (files: File[]) => void;
+}
+declare const Upload: ({ accept, action, multiple, maxCount, onChange }: UploadPropsType) => import("@emotion/react/jsx-runtime").JSX.Element;
+export default Upload;

package/dist/types/packages/VirtualList/index.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+interface VirtualListPropsType<T> {
+    listData: T[];
+    itemHeight: number;
+    height: number;
+    renderItem: (item: T, index: number) => React.ReactNode;
+}
+declare const VirtualList: <T>({ listData, itemHeight, height, renderItem }: VirtualListPropsType<T>) => import("@emotion/react/jsx-runtime").JSX.Element;
+export default VirtualList;

package/dist/types/packages/index.d.ts

@@ -0,0 +1,4 @@
+import { default as LazyLoadImage } from './LazyLoadImage/index';
+import { default as VirtualList } from './VirtualList/index';
+import { default as Upload } from './Upload/index';
+export { LazyLoadImage, VirtualList, Upload };

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "component-library-for-react",
+  "version": "1.0.0",
+  "description": "这是一个关于react的组件库",
+  "type": "module",
+  "main": "./dist/lib/index.js",
+  "module": "./dist/es/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/es/index.js",
+      "require": "./dist/lib/index.js"
+    },
+    "./hooks": {
+      "types": "./dist/types/hooks/index.d.ts",
+      "import": "./dist/es/hooks/index.js",
+      "require": "./dist/lib/hooks/index.js"
+    },
+    "./packages": {
+      "types": "./dist/types/packages/index.d.ts",
+      "import": "./dist/es/packages/index.js",
+      "require": "./dist/lib/packages/index.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "hooks": [
+        "dist/types/hooks/index.d.ts"
+      ],
+      "packages": [
+        "dist/types/packages/index.d.ts"
+      ]
+    }
+  },
+  "sideEffects": [
+    "**/*.css",
+    "./src/hooks/index.ts",
+    "./src/packages/index.ts",
+    "./src/index.ts"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "lint": "eslint src --ext .ts,.tsx",
+    "prepare": "husky",
+    "rebuild-readme": "node ./scripts/rebuild-readme.js",
+    "test": "echo 'test pass'"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/peichaojie/component-library-for-react"
+  },
+  "keywords": [
+    "react",
+    "react-component"
+  ],
+  "author": "裴超杰",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@typescript-eslint/eslint-plugin": "^8.61.1",
+    "@typescript-eslint/parser": "^8.61.1",
+    "@vitejs/plugin-react": "^6.0.2",
+    "eslint": "^10.5.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.6",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.3",
+    "fast-glob": "^3.3.3",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "prettier": "^3.8.4",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16",
+    "vite-plugin-dts": "^5.0.2"
+  },
+  "peerDependencies": {
+    "@emotion/react": "^11.14.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "files": [
+    "dist"
+  ]
+}

package/readme.md

@@ -0,0 +1,366 @@
+# 项目全量使用文档
+
+## useClickOutside 使用文档
+
+`useClickOutside` 是一个用于监听目标元素外部点击事件的自定义 Hook。当用户点击了指定 DOM 元素之外的区域时，会触发传入的回调函数。可用于下拉菜单等组件的收起逻辑。
+
+### 1. API 参数说明
+
+#### 入参 (Inputs)
+
+| 参数名 | 类型 | 必填 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `ref` | `RefObject<HTMLElement \| null>` | 是 | 由 `useRef` 创建的引用对象，需绑定到目标 DOM 元素上 |
+| `handler` | `(event: MouseEvent \| TouchEvent) => void` | 是 | 点击目标元素外部时触发的回调函数 |
+
+#### 出参 (Outputs)
+
+- **`void`**: 该 Hook 无返回值。
+
+### 2. 基础用法（下拉菜单）
+
+点击按钮打开菜单，点击菜单外部的任意地方自动关闭菜单。
+
+
+```tsx
+import React, { FC, useState, useRef, useCallback } from "react";
+import { css } from "@emotion/react";
+import { useClickOutside } from '@/hooks/index'
+
+const App: FC = () => {
+    const [isOpen, setIsOpen] = useState(false);
+    const [list] = useState([
+        { text: '菜单001', key: '001' },
+        { text: '菜单002', key: '002' }
+    ]);
+    const ref = useRef<HTMLUListElement | null>(null);
+    const changeIsOpenState = (e: React.MouseEvent<HTMLButtonElement>) => {
+        setIsOpen(!isOpen);
+        e.stopPropagation();
+    }
+    const handler = useCallback(() => {
+        setIsOpen(false);
+    }, []);
+    useClickOutside(ref, handler);
+    const listStyle = css`
+      list-style: none;
+      li {
+          color: #333;
+          &:hover {
+              color: red;
+              cursor: pointer;
+          }
+      }
+    `;
+    return (
+        <div>
+            <button onClick={e => changeIsOpenState(e)}>
+                {isOpen ? '关闭' : '打开'}菜单
+            </button>
+            {isOpen && (
+                <ul css={listStyle} ref={ref}>
+                    {list.map(item => (
+                        <li key={item.key}>{item.text}</li>
+                    ))}
+                </ul>
+            )}
+        </div>
+    );
+};
+
+export default App;
+```
+
+
+
+
+---
+
+## useDebounce 使用文档
+
+`useDebounce` 是一个用于处理函数防抖的自定义 Hook。它支持**延迟执行**和**立即执行**两种模式，并支持手动取消。
+
+### 1. API 参数说明
+
+#### 入参 (Inputs)
+
+| 参数名      | 类型       | 必填 | 默认值  | 说明                       |
+| :---------- | :--------- | :--- | :------ | :------------------------- |
+| `fn`        | `Function` | 是   | -       | 需要进行防抖处理的目标函数 |
+| `delay`     | `number`   | 否   | `300`   | 防抖延迟时间（毫秒）       |
+| `immediate` | `boolean`  | 否   | `false` | 是否在第一次触发时立即执行 |
+
+#### 出参 (Outputs)
+
+返回一个对象，包含以下两个方法：
+
+- **`run`**: `(...args) => void` —— 实际在业务中调用的防抖包装函数。参数与原函数 `fn` 保持一致。
+- **`cancel`**: `() => void` —— 手动取消当前未执行的定时器。
+
+### 2. 基础用法（搜索框输入）
+
+连续输入时不会触发change事件，停止输入 2000ms 后才触发。
+
+```tsx
+import { FC, useEffect } from "react";
+import { useDebounce } from "@/hooks/index";
+
+const App: FC = () => {
+    const logValue = (label:string,value:string)=>{
+        console.log(`当前输入的${label} 是 ${value}`)
+    }
+    const { run: runUsername, cancel: cancelUsername } = useDebounce(
+        (val: string) => logValue('username', val), 
+        2000
+    );
+    const { run: runPassword, cancel: cancelPassword } = useDebounce(
+        (val: string) => logValue('password', val), 
+        2000
+    );
+    useEffect(() => {
+        return () => {
+            cancelUsername();
+            cancelPassword();
+        };
+    }, [cancelUsername, cancelPassword]);
+
+    return <div>
+        <form encType="application/x-www-form-urlencoded">
+            <label htmlFor="username">
+                用户名：
+                <input type="text" name="username" onChange={e=>runUsername(e.target.value)}/>
+            </label>
+            &nbsp;&nbsp;
+            <label htmlFor="password">
+                密  码：
+                <input type="password" name="password" onChange={e=>runPassword(e.target.value)}/>
+            </label>
+            &nbsp;&nbsp;
+            <button type="button">提交</button>
+        </form>
+    </div>
+};
+
+export default App;
+```
+
+
+---
+
+## useThrottle 使用文档
+
+`useThrottle` 是一个用于函数节流（Throttle）的自定义 Hook。它可以将连续的高频操作限制为每隔固定时间仅执行一次。
+
+### 1. API 参数说明
+
+#### 入参 (Inputs)
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- | :--- |
+| `fn` | `Function` | 是 | - | 需要限制执行频率的目标业务函数 |
+| `delay` | `number` | 否 | `300` | 节流的时间间隔（毫秒） |
+| `immediate` | `boolean` | 否 | `false` | 是否在第一次触发时立即执行。设为 `false` 则首下会延迟 `delay` 毫秒后执行 |
+
+#### 出参 (Outputs)
+返回一个包含控制方法的对象：
+* **`run`**: `(...args) => void` —— 经过节流包装后的触发函数，参数类型与原函数严格一致。
+* **`cancel`**: `() => void` —— 清除当前正在排队的定时器，并重置时间戳计数。
+
+### 2. 基础用法：(表单提交)
+由于 `immediate` 默认为 `false`，在连续点击提交的按钮时，每隔2s执行一次。
+
+```tsx
+import React ,{ FC, useEffect, useRef } from "react";
+import { useThrottle } from "@/hooks/index";
+
+const App: FC = () => {
+    const formRef = useRef<HTMLFormElement|null>(null);
+    const submitFormData = (e:React.MouseEvent<HTMLButtonElement>)=>{
+        const formData = new FormData(formRef.current!);
+        console.log(formData.get('username'))
+    }
+    const {run,cancel} = useThrottle(submitFormData,2000);
+    useEffect(()=>{
+        return ()=>cancel()
+    },[cancel])
+
+    return <div>
+        <form ref={formRef} encType="application/x-www-form-urlencoded">
+            <label htmlFor="username">
+                用户名：
+                <input type="text" name="username"/>
+            </label>
+            &nbsp;&nbsp;
+            <label htmlFor="password">
+                密  码：
+                <input type="password" name="password"/>
+            </label>
+            &nbsp;&nbsp;
+            <button type="button" onClick={run}>提交</button>
+        </form>
+    </div>
+};
+
+export default App;
+```
+
+
+---
+
+## LazyLoadImage 使用文档
+
+`LazyLoadImage` 是一个支持图片懒加载和渐显动画效果的 React 组件。
+
+### 导入组件
+
+```tsx
+import LazyLoadImage from "./LazyLoadImage";
+```
+
+### 属性 API (Props)
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- | :--- |
+| `src` | `string` | 是 | - | 真实图片的 URL 地址 |
+| `placeholder` | `string` | 是 | - | 占位图或 Base64 低清图的 URL 地址 |
+| `alt` | `string` | 否 | - | 图片的替代文本 |
+| `className` | `string` | 否 | `""` | 额外的 CSS 类名 |
+| `style` | `CSSProperties` | 否 | `{}` | 覆盖或新增的内联样式 |
+
+### 使用示例
+
+### 1. 自定义样式与尺寸
+组件默认宽度为 `200px`。你可以通过 `style` 或 `className` 自定义宽高。
+
+```tsx
+<LazyLoadImage 
+    src="http://adolphjie.com/xxx.png" 
+    placeholder="/assets/default-avatar.png" 
+    style={{ width: "100px", height: "100px", borderRadius: "50%" }} 
+/>
+```
+
+
+---
+
+## Upload 使用文档
+
+`LazyLoadImage` 是一个基于 React的轻量级文件上传组件，支持类型限制、多选以及最大数量截断。
+
+### 导入组件
+
+```tsx
+import Upload from "./Upload";
+```
+
+### 属性 API (Props)
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- | :--- |
+| `action` | `string` | 是 | - | 上传的后端接口 URL 地址 |
+| `accept` | `string` | 否 | - | 限制可选的文件类型，如 `image/*` 或 `.pdf,.docx` |
+| `multiple` | `boolean` | 否 | `false` | 是否支持按住 Ctrl/Shift 选择多个文件 |
+| `maxCount` | `number` | 否 | - | 允许上传的最大文件数量限制 |
+| `onChange` | `(files: File[]) => void` | 否 | - | 文件列表发生变化（添加/删除/截断）时的回调函数 |
+
+###  基础使用示例
+
+#### 1. 单张图片上传
+```tsx
+import Upload from './Upload';
+const APP = ()=>{
+    const params = {
+        action:"http://127.0.0.1:4000/file",
+    }
+    return <div>
+        <Upload {...params}/>
+    </div>
+}
+export default APP;
+```
+
+#### 2. 多文档限制上传（最多3个）
+```tsx
+import Upload from './Upload';
+const params = {
+    action:"http://127.0.0.1:4000/files",
+    multiple:true,
+    accept:".pdf,.doc,.docx",
+    maxCount:3,
+    onChange:(files:File[]) => console.log('最新的文档列表:', files)
+}
+const APP = ()=>{
+    return <div>
+        <Upload {...params}/>
+    </div>
+}
+export default APP;
+```
+
+### 后端接收注意事项
+*   **单文件模式 (`multiple={false}`)**：后端需通过名为 `file` 的字段获取单个文件。
+*   **多文件模式 (`multiple={true}`)**：后端需通过名为 `files` 的字段获取文件数组（例如 Node.js 中使用 `upload.array('files')`）。
+
+
+---
+
+##  VirtualList 使用文档
+
+`VirtualList` 是一个专为 React 打造的高性能、轻量级**固定高度虚拟列表组件**。当你的业务场景需要承载几千甚至数万条结构相同的列表数据时，该组件能将 DOM 节点数控制在极低的个位数，确保页面维持 60 FPS 的流畅度。
+
+### 导入组件
+
+```tsx
+import VirtualList from "./VirtualList";
+```
+
+### 属性 API (Props)
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+| `listData` | `T[]` | 是 | - | 列表的数据源数组（任意类型对象的数组）。 |
+| `itemHeight` | `number` | 是 | - | 单行数据的绝对高度（单位 px），行内内容必须严丝合缝匹配此高度。 |
+| `height` | `number` | 是 | - | 可视区域的容器高度（单位 px）。超出该高度将自动出现滚动条。 |
+| `renderItem` | `(item: T, index: number) => ReactNode` | 是 | - | 单行自定义渲染函数。接收单条数据 `item` 及全局真实索引 `index`。 |
+
+### 使用示例
+
+```tsx
+import { FC,useState } from "react";
+import {VirtualList} from "./packages/index"
+
+const APP:FC = ()=>{
+    const [list] = useState<Array<string>>([
+        "内容...1",
+        "内容...2",
+        "内容...3",
+        "内容...4",
+        "内容...5",
+        "内容...6",
+        "内容...7",
+        "内容...1",
+        "内容...2",
+        "内容...3",
+        "内容...4",
+        "内容...5",
+        "内容...6",
+        "内容...7",
+    ]);
+    const props = {
+        listData:list,
+        itemHeight:30,
+        height:100,
+        renderItem:(item:string,index:number)=>{
+            return <div key={index}>{item}</div>
+        }
+    }
+    return <div>
+        <VirtualList {...props}></VirtualList>
+    </div>
+}
+
+export default APP;
+```
+
+---
+