带有暴露缓存管理 API 的扩展 KeepAlive 组件。

概述

本包提供了 Vue 3 内置 KeepAlive 组件的增强版本，通过组件的公共实例暴露了内部缓存管理方法和状态。这允许对缓存进行编程式控制，实现高级用例，如手动缓存失效、缓存检查和自定义缓存管理策略。

安装

npm install vue3-keep-alive

问题背景

Vue 内置的 KeepAlive 组件基于 include、exclude 和 max 属性自动管理组件缓存。然而，在某些场景下，你需要通过编程方式访问：

• 手动清除特定的缓存组件
• 检查当前缓存状态
• 强制重新缓存组件
• 实现自定义缓存淘汰策略
• 调试缓存行为

以前，这些操作是不可能的，因为缓存完全是 KeepAlive 内部的实现。

解决方案

本包通过组件的公共实例（可通过模板引用访问）暴露了以下内部 API：

暴露的 API

cache: Map<CacheKey, VNode>

存储缓存组件 VNode 的内部缓存 Map。每个条目将缓存键（组件 key 或组件本身）映射到其 VNode。

keys: Set<CacheKey>

维护缓存键顺序的 Set，用于在达到 max 时进行 LRU（最近最少使用）淘汰。

current: VNode | null

当前活动（显示）的缓存 VNode 的引用。

cacheSubtree(): void

手动触发缓存当前子树的方法。当你需要强制立即更新缓存时很有用。

pruneCacheEntry(key: CacheKey): void

通过键移除特定的缓存条目。如果组件当前处于活动状态，它不会被卸载，但将不再被缓存。

参数：

• key: 要移除的缓存键（字符串、symbol 或组件）

pruneCache(filter: (name: string) => boolean): void

基于过滤函数修剪缓存条目。未通过过滤器的条目（返回 false）将被移除。

参数：

• filter: 接收组件名称并返回 true 以保留该条目的函数

TypeScript 支持

import type { ComponentPublicInstance, VNode } from 'vue'

type CacheKey = PropertyKey | ConcreteComponent

interface KeepAliveInstance extends ComponentPublicInstance {
  cache: Map<CacheKey, VNode>
  keys: Set<CacheKey>
  current: VNode | null
  cacheSubtree(): void
  pruneCacheEntry(key: CacheKey): void
  pruneCache(filter: (name: string) => boolean): void
}

const keepAliveRef = ref<KeepAliveInstance | null>(null)

使用场景

1. 手动缓存失效：当数据变化时清除缓存（例如，退出登录后、数据刷新后）
2. 内存管理：基于时间、内存或优先级实现自定义淘汰策略
3. 调试：在开发过程中检查缓存状态
4. 分析：跟踪缓存命中/未命中率
5. 条件缓存：基于运行时条件动态决定哪些组件保持缓存
6. 缓存预热：在需要之前预缓存组件
7. 测试：在单元/集成测试中验证缓存行为

API 参考

类型

type CacheKey = PropertyKey | ConcreteComponent
type Cache = Map<CacheKey, VNode>
type Keys = Set<CacheKey>

方法

pruneCacheEntry(key: CacheKey): void

移除单个缓存条目。即使组件当前处于活动状态也可以安全调用。

pruneCache(filter: (name: string) => boolean): void

基于过滤谓词移除多个缓存条目。名称不匹配过滤器的组件将被移除。

cacheSubtree(): void

手动触发缓存当前组件的子树。通常在挂载/更新时自动调用，但如果需要可以手动调用。

属性

cache: Map<CacheKey, VNode>

对缓存 Map 的只读访问。可用于检查缓存条目，但不建议直接操作——请使用提供的方法。

keys: Set<CacheKey>

对键 Set 的只读访问。反映缓存组件的 LRU 顺序。

current: VNode | null

对当前显示的组件的 VNode 的引用，如果没有活动组件则为 null。

注意事项

1. 直接操作：虽然 cache 和 keys 已暴露，但优先使用 pruneCacheEntry 和 pruneCache 方法以确保正确清理
2. 组件键：确保缓存的组件具有稳定的键以实现可靠的缓存管理
3. SSR：缓存管理仅限客户端；这些 API 在服务器端渲染期间不可用
4. 性能：频繁的缓存操作会影响性能；尽可能批量操作

兼容性

• Vue 3.x
• 同时支持选项式 API 和组合式 API
• 完整 TypeScript 支持

许可证

MIT