useSafariCompat
约 1096 字大约 4 分钟
2025-10-09
简介
用于处理 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'): booleangetStorageStrategy(): 'localStorage' | 'sessionStorage' | 'memory'
存储操作:
getItem(key: string): string | nullsetItem(key: string, value: string): booleanremoveItem(key: string): booleangetStorageType(key: string): StorageType
Safari 兼容性工具:
parseDate(dateString: string): Date | nullsafeJsonParse<T = any>(jsonString: string, fallback: T): TsafeUrlParse(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
技术特点
- 浏览器检测:准确识别 Safari 浏览器,排除 Chrome 和 Android 的干扰
- 存储兼容性:提供多级存储策略,确保在 Safari 隐私模式下也能正常工作
- 错误处理:完整的错误捕获和处理机制,避免应用崩溃
- 数据完整性:验证存储操作的完整性,确保数据正确读写
- 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