From 11af1712128b69db598ba8915386b5429387bffd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=9B=A8=E9=9C=96=E9=93=83?= Date: Fri, 20 Mar 2026 00:22:34 +0800 Subject: [PATCH] docs: update storage cleaner design with code review feedback - Add routing implementation details - Add restricted page detection - Add complete executeScript examples - Add error handling for IndexedDB.databases - Add Service Workers multiple registrations handling - Add popup lifecycle notes - Improve TypeScript types with error handling Co-Authored-By: Claude Opus 4.6 --- .../2026-03-20-storage-cleaner-design.md | 183 +++++++++++++----- 1 file changed, 138 insertions(+), 45 deletions(-) diff --git a/docs/superpowers/specs/2026-03-20-storage-cleaner-design.md b/docs/superpowers/specs/2026-03-20-storage-cleaner-design.md index c45deda..51d9bdd 100644 --- a/docs/superpowers/specs/2026-03-20-storage-cleaner-design.md +++ b/docs/superpowers/specs/2026-03-20-storage-cleaner-design.md @@ -25,6 +25,41 @@ entrypoints/popup/pages/ 在弹窗中添加标签页切换功能，用户可以在时间戳转换和存储清理之间切换。 +**路由实现方案：** + +使用简单的状态管理进行页面切换： + +```typescript +// App.tsx +type PageType = 'timestamp' | 'storageCleaner'; + +function App() { + const [currentPage, setCurrentPage] = useState('timestamp'); + + return ( +
+ + + + + {currentPage === 'timestamp' && } + {currentPage === 'storageCleaner' && } +
+ ); +} +``` + ## 用户界面设计 ### 页面组成 @@ -56,13 +91,18 @@ entrypoints/popup/pages/ ### 获取当前标签页域名 -使用 Chrome Tabs API 获取当前活动标签页： +使用 Chrome Tabs API 获取当前活动标签页，并过滤受限页面： ```typescript const [tab] = await chrome.tabs.query({ active: true, currentWindow: true }); -if (!tab?.url) { - throw new Error('无法获取当前标签页 URL'); + +// 检查受限页面 +const restrictedProtocols = ['chrome:', 'chrome-extension:', 'about:', 'edge:', 'view-source:']; + +if (!tab?.url || restrictedProtocols.some((p) => tab.url!.startsWith(p))) { + throw new Error('存储清理功能不支持此页面'); } + const domain = new URL(tab.url).hostname; ``` @@ -85,6 +125,17 @@ for (const cookie of cookies) { ### 注入脚本清理其他存储 +使用 `chrome.scripting.executeScript` 注入清理脚本： + +```typescript +const result = await chrome.scripting.executeScript({ + target: { tabId: tab.id }, + func: () => { + // 清理逻辑在页面上下文中执行 + }, +}); +``` + 需要注入到页面执行的存储清理逻辑： #### 清理 localStorage @@ -106,58 +157,73 @@ return count; #### 清理 IndexedDB ```javascript -const databases = await indexedDB.databases(); -let count = 0; -for (const db of databases) { - const deleteReq = indexedDB.deleteDatabase(db.name); - deleteReq.onblocked = () => { - console.warn('IndexedDB delete blocked:', db.name); - }; - await new Promise((resolve, reject) => { - deleteReq.onsuccess = resolve; - deleteReq.onerror = reject; - }); - count++; +// 检查 databases indexedDB 方法是否可用 +if (typeof indexedDB.databases === 'function') { + const databases = await indexedDB.databases(); + let count = 0; + for (const db of databases) { + const deleteReq = indexedDB.databases(db.name); + deleteReq.onblocked = () => { + console.warn('IndexedDB delete blocked:', db.name); + }; + await new Promise((resolve, reject) => { + deleteReq.onsuccess = resolve; + deleteReq.onerror = reject; + }); + count++; + } + return count; } +// 降级方案：使用传统方法 +let count = 0; +// 尝试遍历已知数据库或提示用户手动清除 return count; ``` #### 清理 Cache Storage ```javascript -const cacheNames = await caches.keys(); -for (const name of cacheNames) { - await caches.delete(name); +if ('caches' in window) { + const cacheNames = await caches.keys(); + for (const name of cacheNames) { + await caches.delete(name); + } + return cacheNames.length; } -return cacheNames.length; +return 0; ``` #### 注销 Service Workers ```javascript if ('serviceWorker' in navigator) { - const registration = await navigator.serviceWorker.getRegistration(); - if (registration) { + const registrations = await navigator.serviceWorker.getRegistrations(); + let count = 0; + for (const registration of registrations) { await registration.unregister(); - return true; + count++; } + return count; } -return false; +return 0; ``` ### 数据流 1. 页面加载时获取当前标签页 URL 并显示域名 -2. 用户勾选要清理的存储类型 -3. 用户选择是否自动刷新页面 -4. 用户点击清理按钮 -5. 弹出确认对话框询问用户确认 -6. 确认后执行清理： +2. 检查是否为受限页面（chrome://, about:// 等），如果是则显示错误提示 +3. 用户勾选要清理的存储类型 +4. 用户选择是否自动刷新页面 +5. 用户点击清理按钮 +6. 弹出确认对话框询问用户确认 +7. 确认后执行清理： - 如果选择 Cookies：直接使用 chrome.cookies API 删除 - 其他存储类型：向页面注入清理脚本 -7. 收集所有清理结果并统计 -8. 显示清理结果 -9. 如果勾选"自动刷新"或用户点击"刷新页面"按钮，执行页面刷新 +8. 收集所有清理结果并统计 +9. 显示清理结果 +10. 如果勾选"自动刷新"或用户点击"刷新页面"按钮，执行页面刷新 + +**注意：** 当触发页面刷新时，popup 会自动关闭。需要在刷新前显示提示信息。 ### 页面刷新 @@ -167,14 +233,29 @@ await chrome.tabs.reload(tab.id); ## 错误处理 -| 错误场景 | 处理方式 | -| ------------------- | ---------------------------------- | -| 无法获取当前标签页 | 显示错误提示："无法获取当前标签页" | -| 无法访问页面 URL | 显示错误提示："无法访问此页面" | -| IndexedDB onblocked | 显示警告但继续执行其他清理 | -| 清理失败 | 显示具体错误信息 | -| Cookies 删除失败 | 记录错误，显示清理失败提示 | -| 无权限 | 提示用户刷新扩展或检查权限 | +| 错误场景 | 处理方式 | +| ------------------------------- | ---------------------------------------- | +| 无法获取当前标签页 | 显示错误提示："无法获取当前标签页" | +| 受限页面（chrome://, about://） | 显示错误提示："存储清理功能不支持此页面" | +| 无法访问页面 URL | 显示错误提示："无法访问此页面" | +| IndexedDB onblocked | 显示警告但继续执行其他清理 | +| IndexedDB.databases 不可用 | 使用降级方案或提示用户手动清除 | +| 清理失败 | 显示具体错误信息 | +| Cookies 删除失败 | 记录错误，显示清理失败提示 | +| 无权限 | 提示用户刷新扩展或检查权限 | +| 脚本注入失败 | 显示错误提示："无法注入清理脚本" | + +**Popup 生命周期说明：** + +- Popup 在页面失去焦点时会关闭 +- 刷新页面后 Popup 会自动关闭 +- 需要在刷新前显示提示："页面即将刷新，Popup 将关闭" + +**Popup 生命周期说明：** + +- Popup 在页面失去焦点时会关闭 +- 刷新页面后 Popup 会自动关闭 +- 需要在刷新前显示提示："页面即将刷新，Popup 将关闭" ## 权限需求 @@ -207,13 +288,25 @@ export interface StorageCleanerOptions { serviceWorkers: boolean; } +export type StorageCleanResult = + | { + success: true; + count: number; + } + | { + success: false; + error: string; + }; + export interface CleaningResult { - localStorage?: number; - sessionStorage?: number; - indexedDB?: number; - cookies?: number; - cacheStorage?: number; - serviceWorkers?: boolean; + success: boolean; + error?: string; + localStorage?: StorageCleanResult; + sessionStorage?: StorageCleanResult; + indexedDB?: StorageCleanResult; + cookies?: StorageCleanResult; + cacheStorage?: StorageCleanResult; + serviceWorkers?: StorageCleanResult; } ```