useMap

管理 Map 的 React hook。

useMap 将 JavaScript Map 封装在 React 状态中，暴露丰富的方法集：set、get、remove、has、clear 和 reset，以及当前的 map 实例和 size。通过这些方法的修改会自动触发重新渲染。初始值可以是 Map 实例、键值对数组或工厂函数。

使用场景

  • 管理频繁变化的键值集合（例如选中项、标签映射、查找表）
  • 构建在运行时添加和删除条目的动态表单或配置编辑器
  • 任何需要 Map 语义（有序键、非字符串键）并带有响应式状态更新的场景

注意事项

  • 不可变更新：每次修改在内部创建一个新的 Map 实例，以便 React 检测到状态变化并重新渲染。
  • 重置支持：reset 函数将映射恢复到初始值，适用于”撤销”或”清除筛选”操作。
  • SSR 安全：内部仅使用 React 状态，无浏览器 API 依赖。

Usage

Live Editor
function Demo() {
  const { map, set, get, remove, has, clear, reset, size } = useMap([
    ['react', '18.0.0'],
    ['vue', '3.0.0'],
  ]);

  return (
    <div>
      <p>Map 大小: {size}</p>
      <div style={{ marginBottom: 16 }}>
        <button
          type="button"
          onClick={() => set('angular', '16.0.0')}
          style={{ marginRight: 8 }}
        >
          添加 Angular
        </button>
        <button
          type="button"
          onClick={() => set('react', '18.2.0')}
          style={{ marginRight: 8 }}
        >
          更新 React
        </button>
        <button
          type="button"
          onClick={() => remove('vue')}
          style={{ marginRight: 8 }}
        >
          删除 Vue
        </button>
        <button
          type="button"
          onClick={clear}
          style={{ marginRight: 8 }}
        >
          清空所有
        </button>
        <button
          type="button"
          onClick={reset}
          style={{ marginRight: 8 }}
        >
          重置
        </button>
      </div>
      <div>
        <p>当前条目:</p>
        <ul>
          {Array.from(map.entries()).map(([key, value]) => (
            <li key={key}>
              {key}: {value} 
              {has(key) && ' ✓'}
            </li>
          ))}
        </ul>
      </div>
      <div>
        <p>获取 React 版本: {get('react') || '未找到'}</p>
      </div>
    </div>
  );
};
Result

API

useMap

Returns

{ readonly map: Map<K, V>; readonly set: (key: K, value: V) => void; readonly get: (key: K) => V | undefined; readonly remove: (key: K) => boolean; readonly has: (key: K) => boolean; readonly clear: () => void; readonly reset: () => void; readonly size: number; }: 包含以下属性的对象：

  • map: 当前的 Map 实例。
  • set: 在 map 中设置键值对的函数。
  • get: 通过键从 map 中获取值的函数。

Arguments

参数名描述类型默认值
initialValue初始值，可以为 Map 实例、数组或者一个初始化的函数Map<K, V> | readonly (readonly [K, V])[] | (() => Map<K, V> | readonly (readonly [K, V])[]) | undefined-