CacheDom 组件

简介

CacheDom 是一个用于 React 中进行缓存组件，直接通过的缓存和复用 DOM 节点实现 React 节点的缓存。

安装

# npm
npm install react-cache-dom

# yarn
yarn add react-cache-dom

# pnpm
pnpm add react-cache-dom

基础用法

简单示例

function App() {
  const handleCacheHit = () => {
    console.log("组件从缓存中恢复");
  };

  const handleCacheMiss = () => {
    console.log("组件首次渲染，已加入缓存");
  };

  return (
    <CacheGroup groupId="main-group">
      <CacheDom
        cacheKey="my-component"
        key="my-component"
        Component={MyComponent}
        props={{ someData: "value" }}
        onCacheHit={handleCacheHit}
        onCacheMiss={handleCacheMiss}
      />
    </CacheGroup>
  );
}

组件 API

CacheGroup

缓存组的容器组件，管理一组缓存实例。所有<CacheDom />必须包裹在 CacheGroup 内。

Props

| 属性 | 类型 | 必填 | 默认值 | 描述 | | -------- | --------- | ---- | ------ | -------------------------------------- | | groupId | string | 是 | - | 缓存组的唯一标识 | | capacity | number | 否 | 10 | 缓存容量，超出时会移除最久未使用的缓存（LRU） | | children | ReactNode | 是 | - | 子组件 |

Ref Methods

| 方法 | 参数 | 返回值 | 描述 | | ------------ | ---------------------------------------------- | -------- | --------------------------------------------------- | | clearCache | (key?: string) | void | 清除指定或所有缓存 | | getCacheKeys | () | string[] | 获取所有缓存的 key |

CacheDom

具体的缓存组件，负责缓存和恢复 DOM 节点。

Props

| 属性 | 类型 | 必填 | 默认值 | 描述 | | ----------------- | --------------------- | ---- | ------ | ---------------------------------- | | cacheKey | string | 是 | - | 缓存的唯一标识 | | key | string | 是 | - | 组件的 key 属性 | | Component | ComponentType | 是 | - | 需要被缓存的组件 | | props | T | 否 | {} | 传递给组件的属性，也作为依赖项 | | disabled | boolean | 否 | false | 是否禁用缓存 | | onCacheHit | () => void | 否 | - | 缓存命中时的回调 | | onCacheMiss | () => void | 否 | - | 缓存未命中时的回调 | | containerClassName| string | 否 | - | 容器的类名 | | containerStyle | React.CSSProperties | 否 | - | 容器的样式 |

高级用法

1. 手动管理缓存

function App() {
  const cacheGroupRef = useRef<CacheGroupRef>(null);

  const handleClearSpecific = () => {
    // 清除特定缓存
    cacheGroupRef.current?.clearCache("my-component");
  };

  const handleClearAll = () => {
    // 清除所有缓存
    cacheGroupRef.current?.clearCache();
  };

  const handleCheckCache = () => {
    // 获取所有缓存的 key
    const keys = cacheGroupRef.current?.getCacheKeys();
    console.log("缓存的 keys:", keys);
  };

  return (
    <CacheGroup ref={cacheGroupRef} groupId="main-group">
      {/* ... */}
    </CacheGroup>
  );
}

2. 条件缓存

function App() {
  const [shouldCache, setShouldCache] = useState(true);

  return (
    <CacheGroup groupId="main-group">
      <CacheDom
        cacheKey="my-component"
        key="my-component"
        Component={MyComponent}
        disabled={!shouldCache}
        props={{ someData: "value" }}
      />
    </CacheGroup>
  );
}

3. 属性更新示例

function App() {
  const [count, setCount] = useState(0);
  const [user, setUser] = useState({ name: "John" });

  return (
    <CacheGroup groupId="main-group">
      <CacheDom
        cacheKey="my-component"
        key="my-component"
        Component={MyComponent}
        // props中的值变化会触发组件更新
        props={{ count, user }}
      />
    </CacheGroup>
  );
}

4. 多缓存组管理

function App() {
  return (
    <div>
      {/* 主要内容的缓存组 */}
      <CacheGroup groupId="main-content" capacity={5}>
        {/* ... */}
      </CacheGroup>

      {/* 侧边栏的缓存组 */}
      <CacheGroup groupId="sidebar" capacity={3}>
        {/* ... */}
      </CacheGroup>
    </div>
  );
}

注意事项

1. CacheDom 必须在 CacheGroup 内使用
2. cacheKey 在同一个 CacheGroup 内必须唯一
3. 当组件被缓存时，其内部状态会被保留
4. 清除缓存时建议使用 clearCache 方法，而不是直接操作 DOM

贡献指南

1. Fork 本仓库
2. 创建特性分支：git checkout -b my-new-feature
3. 提交改动：git commit -am 'Add some feature'
4. 推送分支：git push origin my-new-feature
5. 提交 Pull Request

许可证

MIT

问题反馈

如果你发现任何问题或有新功能建议，欢迎在 GitHub Issues 中提出。