离线优先的应用通常使用 Service Worker 缓存页面资源和 API 响应，但浏览器自身的离线界面并不知道哪些内容可以被用户再次打开。Content Index API 解决的就是这个问题：它允许网页以结构化的方式向浏览器登记可离线访问的内容条目。对 TypeScript 开发者来说，要利用这个 API，关键是先把 ContentDescription、ImageResource、ContentIndex 以及 ServiceWorkerRegistration 的 index 属性这些数据类型定义清楚，否则在严格模式下会面临类型缺失或 any 扩散的问题。
ContentDescription 与 ImageResource：内容索引的最小数据单元
Content Index API 登记一条离线内容时，并不要求把 HTML、CSS、JavaScript 或图片等真实资源塞进某个数据库。它只接收一份结构化的描述对象，这个对象在 TypeScript 中对应 ContentDescription 接口。id 是内容条目的唯一标识，后续删除或更新都需要通过它定位；title 和 description 会出现在浏览器离线内容面板中；url 指向离线可打开的页面地址；category 帮助浏览器按文章、视频、音频、文档等类型进行归类。图标字段 icons 不是普通的字符串数组，而是复用 Web App Manifest 中的 ImageResource，这样可以同时描述不同分辨率和不同用途的图标资源。
在类型层面，建议把 category 单独定义成联合类型，而不是直接写成 string。宽泛字符串类型会让编译期检查失去意义，开发者可能传入类似 'ariticle' 这样的拼写错误值而不被提示。下面是一组基础类型定义：
interface ImageResource {
src: string;
sizes?: string;
type?: string;
label?: string;
purpose?: 'any' | 'maskable' | 'monochrome';
}
type ContentCategory = 'homepage' | 'article' | 'video' | 'audio' | 'document' | 'image' | 'other';
interface ContentDescription {
id: string;
title: string;
description: string;
url: string;
category?: ContentCategory;
icons?: ImageResource[];
}
这里的 purpose 用来声明图标是用于通用场景、遮罩场景还是单色场景，sizes 遵循 Manifest 中常见的尺寸写法，例如 192x192 或 512x512。需要注意的是，ImageResource 本身也可能在其他 API 中复用，因此保持字段可选性可以避免在 Content Index 场景下被强制要求填写无关信息。
通过声明合并补全 ContentIndex 和 ServiceWorkerRegistration 类型
不同版本的 TypeScript 标准库对 Content Index API 的内置支持并不一致。即使浏览器已经实现了 registration.index.add，如果你的 lib.dom.d.ts 没有包含 index 属性，编译时仍然会报错。处理这个问题最直接的方式是利用 TypeScript 的声明合并机制，为 ServiceWorkerRegistration 接口补充一个只读的 index 成员，同时定义 ContentIndex 接口的方法签名。
声明合并不会覆盖标准库中已有的同名接口，而是将成员合并到一起。因此无论当前 TS 版本是否已经内置该类型，这段代码都足够安全。下面是补全声明：
interface ServiceWorkerRegistration {
readonly index: ContentIndex;
}
interface ContentIndex {
add(description: ContentDescription): Promise<undefined>;
delete(id: string): Promise<undefined>;
getAll(): Promise<Array<ContentDescription>>;
}
add 方法接收一个完整的 ContentDescription 对象并返回 Promise<undefined>，表示登记操作完成但不产生可用的业务数据。delete 通过 id 删除单条内容，getAll 则返回当前站点已登记的全部条目。把这三个方法显式写好，调用侧就不需要再写类型断言，代码提示也会准确显示参数结构。
如果你确认项目使用的 TypeScript 版本已经内置 ContentIndex，可以省略上面的接口定义，但保留 ServiceWorkerRegistration 的声明合并也没有副作用。真正需要关注的是运行阶段：即使类型声明通过，浏览器不支持 Content Index API 时仍然无法调用。因此在实际调用前，通常要做一次特性检测，例如判断 'index' in registration。
在 Service Worker 中处理 ContentIndexEvent 类型
当浏览器从离线内容列表中移除某个条目时，Service Worker 会触发 contentdelete 事件。这个事件对象的类型在 TypeScript 中对应 ContentIndexEvent，它继承自 ExtendableEvent，比普通事件多出一个只读的 id 字段。如果不做类型声明，监听回调里的 event 很可能被推断为 Event，访问 event.id 就会报类型错误。
下面这段代码演示了如何在 Service Worker 中安全读取被删除的索引 id：
self.addEventListener('contentdelete', (event) => {
const contentEvent = event as ContentIndexEvent;
console.log('已删除的离线内容 id:', contentEvent.id);
});
如果项目的 lib.dom.d.ts 没有定义 ContentIndexEvent，可以手动补充一个最小接口：
interface ContentIndexEvent extends ExtendableEvent {
readonly id: string;
}
这里直接继承 ExtendableEvent 是为了保持 Service Worker 事件语义，也为后续可能的 waitUntil 调用提供正确类型基础。实际业务中，收到 contentdelete 后常常需要同步清理本地缓存或更新状态库，此时就能在回调里安全使用 contentEvent.id 而不会丢失类型信息。
完整调用流程与类型约束的实践建议
主线程中添加一条离线内容，需要先等待 navigator.serviceWorker.ready 获取到激活的注册对象，再通过 registration.index.add 写入。把前面定义的类型组合起来，可以得到一个可复用的函数：
async function registerOfflineArticle(reg: ServiceWorkerRegistration): Promise<void> {
if (!('index' in reg)) {
return;
}
await reg.index.add({
id: 'article-1',
title: '理解 Content Index API',
description: '离线阅读这篇文章时需要先登记内容索引',
url: '/articles/content-index-api',
category: 'article',
icons: [
{
src: '/icons/article-192.png',
sizes: '192x192',
type: 'image/png'
}
]
});
}
调用入口可以放在页面加载后或用户点击离线保存按钮时。需要强调的是，id 在同一个源下必须唯一，重复添加相同 id 会覆盖旧条目，而不是抛出错误。因此如果你的内容主键来自服务端，最好直接使用数据库 id 或带前缀的字符串，避免不同模块之间发生冲突。
另一个容易被忽视的问题是 category 的枚举值与实际内容类型不匹配。虽然浏览器不会因为 category 写错而拒绝登记，但它会影响内容在系统离线界面中的展示分类。可以通过类型守卫和收窄来约束外部输入，避免把任意字符串直接写进 ContentDescription：
function isContentCategory(value: string): value is ContentCategory {
return ['homepage', 'article', 'video', 'audio', 'document', 'image', 'other'].includes(value);
}
function buildDescription(input: Record<string, string>): ContentDescription | null {
if (!input.category || !isContentCategory(input.category)) {
return null;
}
return {
id: input.id,
title: input.title,
description: input.description,
url: input.url,
category: input.category
};
}
这段代码把校验逻辑从业务函数中抽离出来，确保进入 ContentDescription 的 category 一定属于合法枚举范围。Record<string, string> 收窄前可能来自表单或远程配置，任何拼写错误都会在构建描述对象前被拦截。这样一来，TypeScript 的类型系统不仅停留在编译期，还通过运行时守卫形成了双重约束。
总结来看，TypeScript 中定义 Content Index API 的数据类型并不复杂，但要覆盖完整流程，需要同时处理好描述对象、注册对象扩展、事件对象和运行时校验几个层次。把 ContentDescription 的字段设计清楚，补全 ContentIndex 与 ServiceWorkerRegistration 的声明，再为 contentdelete 事件提供准确的 ContentIndexEvent，就能让离线内容索引功能在类型安全的前提下顺利运行。
Content Index APITypeScript类型定义离线缓存修改时间：2026-10-05 17:18:53