简介

用于处理 Safari 浏览器兼容性问题的组合式函数，特别针对 Safari 隐私模式和存储限制提供了解决方案。该函数提供了一系列方法和工具，帮助开发者在 Safari 浏览器中实现可靠的存储操作和数据处理。

---

接口定义

从浏览器 API 和自定义类型导入的相关定义：

• StorageType: 存储类型枚举（'localStorage' | 'sessionStorage' | 'memory' | 'none'）

---

返回对象结构

调用 useSafariCompat() 返回以下属性与方法：

• 状态：

  • isSafari: Readonly<ComputedRef<boolean>> - 是否为 Safari 浏览器
  • isPrivateMode: Readonly<Ref<boolean>> - 是否处于隐私模式
  • storageAvailability: Readonly<Ref<{ localStorage: boolean, sessionStorage: boolean }>> - 存储可用性状态

• 存储检测方法：

  • checkStorageAvailability(): { localStorage: boolean, sessionStorage: boolean }
  • detectPrivateMode(): Promise<void>
  • isStorageAvailable(type: 'localStorage' | 'sessionStorage'): boolean
  • getStorageStrategy(): 'localStorage' | 'sessionStorage' | 'memory'

• 存储操作：

  • getItem(key: string): string | null
  • setItem(key: string, value: string): boolean
  • removeItem(key: string): boolean
  • getStorageType(key: string): StorageType

• Safari 兼容性工具：

  • parseDate(dateString: string): Date | null
  • safeJsonParse<T = any>(jsonString: string, fallback: T): T
  • safeUrlParse(urlString: string): URL | null

---

方法详解

checkStorageAvailability()

• 功能：检测 localStorage 和 sessionStorage 的可用性
• 实现原理：通过尝试写入、读取以及删除测试数据来验证存储功能，包含数据完整性检查
• 返回值：{ localStorage: boolean, sessionStorage: boolean } - 存储可用性状态对象
• 错误处理：捕获并记录存储操作中的异常

---

detectPrivateMode()

• 功能：检测浏览器是否处于隐私模式或存在存储限制
• 实现原理：尝试在 localStorage 中存储和检索数据，验证数据完整性和存储配额
• 副作用：设置 isPrivateMode 响应式变量的值
• 错误处理：捕获异常并设置相应的隐私模式状态

---

getItem(key)

• 功能：安全获取存储项
• 优先级：内存存储 → localStorage → sessionStorage
• 特点：自动缓存到内存存储以提高可靠性，包含完整的错误处理
• 返回值：string | null - 存储的值或 null

---

setItem(key, value)

• 功能：安全设置存储项
• 优先级：localStorage → sessionStorage → 内存存储
• 特点：根据存储可用性自动选择最佳存储方式
• 返回值：boolean - 操作成功状态

---

removeItem(key)

• 功能：安全移除存储项
• 特点：同时清理内存、localStorage 和 sessionStorage 中的对应项
• 返回值：boolean - 操作成功状态

---

getStorageType(key)

• 功能：获取特定键的存储类型
• 返回值：StorageType - 存储类型字符串
• 用途：主要用于调试目的，确定数据实际存储位置

---

isStorageAvailable(type)

• 功能：检查特定存储类型是否可用
• 参数：type - 存储类型（'localStorage' 或 'sessionStorage'）
• 返回值：boolean - 表示指定存储类型是否可用

---

getStorageStrategy()

• 功能：获取推荐的存储策略
• 优先级：localStorage → sessionStorage → 内存存储
• 返回值：'localStorage' | 'sessionStorage' | 'memory' - 推荐使用的存储策略
• 用途：根据可用性确定最佳存储方式

---

Safari 兼容性工具

parseDate(dateString)

• 功能：安全解析日期字符串
• 解决：Safari 日期格式解析问题（将 - 替换为 /）
• 返回值：Date | null - 解析成功的 Date 对象或 null

---

safeJsonParse(jsonString, fallback)

• 功能：安全解析 JSON 字符串
• 参数：
  • jsonString: 要解析的 JSON 字符串
  • fallback: 解析失败时返回的回退值
• 特点：提供回退值，避免解析失败导致应用崩溃
• 返回值：T - 解析后的对象或回退值

---

safeUrlParse(urlString)

• 功能：安全解析 URL 字符串
• 特点：错误处理，避免无效 URL 导致异常
• 返回值：URL | null - 解析成功的 URL 对象或 null

---

技术特点

1. 浏览器检测：准确识别 Safari 浏览器，排除 Chrome 和 Android 的干扰
2. 存储兼容性：提供多级存储策略，确保在 Safari 隐私模式下也能正常工作
3. 错误处理：完整的错误捕获和处理机制，避免应用崩溃
4. 数据完整性：验证存储操作的完整性，确保数据正确读写
5. Safari 特定问题解决：解决 Safari 特有的日期格式和 URL 解析问题

---

使用示例（片段）

const safariCompat = useSafariCompat()

// 检测浏览器类型
if (safariCompat.isSafari.value) {
  console.log('Running in Safari browser')
}

// 检测隐私模式
await safariCompat.detectPrivateMode()
if (safariCompat.isPrivateMode.value) {
  console.log('Private mode detected, using memory storage')
}

// 安全存储操作
safariCompat.setItem('userData', JSON.stringify(userData))
const data = safariCompat.getItem('userData')
safariCompat.removeItem('userData')

// 使用推荐的存储策略
const strategy = safariCompat.getStorageStrategy()
console.log(`Recommended storage strategy: ${strategy}`)

// Safari 兼容性工具
const date = safariCompat.parseDate('2023-01-01')
const parsedData = safariCompat.safeJsonParse('invalid json', { fallback: 'value' })
const url = safariCompat.safeUrlParse('https://example.com')

版权所有

版权归属：Evoliant

许可证：MIT