Titanium SDK 深度解析：iOS UserDefaults 模块详解
项目地址: https://gitcode.com/gh_mirrors/ti/titanium-sdk 引言：为什么需要 UserDefaults？
在移动应用开发中，数据持久化是每个开发者都必须面对的核心问题。想象一下这样的场景：用户设置了应用的主题颜色、语言偏好或登录状态，你希望这些设置能够在应用重启后依然保持。这时候，iOS 的 UserDefaults（用户默认设置）系统就成为了最佳选择。
Titanium SDK 作为跨平台移动应用开发框架，为开发者提供了 Ti.App.iOS.UserDefaults 模块，让 JavaScript 开发者能够轻松使用 iOS 的原生 UserDefaults 功能，实现高效、安全的数据持久化存储。
UserDefaults 核心概念解析
什么是 UserDefaults？
UserDefaults 是 iOS 提供的一个轻量级数据存储系统，主要用于存储应用的配置信息、用户偏好设置等小型数据。它基于属性列表（Property List）格式，支持存储基本数据类型和集合类型。
数据类型支持
UserDefaults 支持存储以下数据类型：
| 数据类型 | JavaScript 对应类型 | 存储限制 |
|---|---|---|
| Boolean | Boolean | 无 |
| Integer | Number | 64位整数 |
| Double | Number | 双精度浮点数 |
| String | String | 无 |
| Array | Array | 元素必须为支持类型 |
| Dictionary | Object | 键值必须为支持类型 |
Ti.App.iOS.UserDefaults 模块架构
核心类结构
模块初始化流程
创建 UserDefaults 实例的完整流程：
// 1. 导入 iOS 模块
const iOS = require('Ti.App.iOS');
// 2. 创建 UserDefaults 实例
const userDefaults = iOS.createUserDefaults({
suiteName: 'com.example.app.group' // 可选的应用组标识
});
// 3. 使用实例进行数据操作
userDefaults.setString(['theme', 'dark']);
核心 API 详细解析
数据读取方法
getBool / getDouble / getInt / getString
// 读取布尔值
const isDarkMode = userDefaults.getBool(['dark_mode', false]);
// 读取双精度浮点数
const userRating = userDefaults.getDouble(['user_rating', 4.5]);
// 读取整数值
const loginCount = userDefaults.getInt(['login_count', 0]);
// 读取字符串
const userName = userDefaults.getString(['user_name', 'Guest']);
getList - 数组读取
// 读取数组数据
const favoriteItems = userDefaults.getList(['favorites', []]);
// 复杂数组处理示例
favoriteItems.forEach(item => {
console.log(`收藏项: ${item}`);
});
getObject - 对象读取
// 读取复杂对象（支持 NSCoding 协议的对象）
const userProfile = userDefaults.getObject(['user_profile', null]);
if (userProfile) {
console.log(`用户名: ${userProfile.name}`);
console.log(`邮箱: ${userProfile.email}`);
}
数据写入方法
setBool / setDouble / setInt / setString
// 设置布尔值
userDefaults.setBool(['dark_mode', true]);
// 设置双精度浮点数
userDefaults.setDouble(['user_rating', 4.8]);
// 设置整数值
userDefaults.setInt(['login_count', 42]);
// 设置字符串
userDefaults.setString(['user_name', '张三']);
setList - 数组写入
// 设置数组数据
const favorites = ['item1', 'item2', 'item3'];
userDefaults.setList(['favorites', favorites]);
// 支持包含 null 值的数组
const itemsWithNull = ['item1', null, 'item3'];
userDefaults.setList(['items_with_null', itemsWithNull]);
setObject - 对象写入
// 设置复杂对象（必须实现 NSCoding 协议）
const userProfile = {
name: '张三',
email: 'zhangsan@example.com',
age: 28,
preferences: {
theme: 'dark',
language: 'zh-CN'
}
};
userDefaults.setObject(['user_profile', userProfile]);
数据管理方法
属性检查与删除
// 检查属性是否存在
const hasTheme = userDefaults.hasProperty(['theme']);
console.log(`主题设置存在: ${hasTheme}`);
// 删除单个属性
userDefaults.removeProperty(['obsolete_setting']);
// 删除所有属性（谨慎使用！）
userDefaults.removeAllProperties();
// 列出所有属性
const allProperties = userDefaults.listProperties();
console.log('所有存储的属性:', allProperties);
高级特性与最佳实践
应用组（App Groups）支持
UserDefaults 支持应用组功能，允许同一开发者的多个应用共享数据：
// 创建应用组级别的 UserDefaults
const groupDefaults = iOS.createUserDefaults({
suiteName: 'group.com.company.appsuite'
});
// 在应用间共享数据
groupDefaults.setString(['shared_token', 'abc123def456']);
变更监听机制
UserDefaults 提供了原生的变更监听功能：
// 添加变更监听器
userDefaults.addEventListener('change', function(event) {
console.log('UserDefaults 数据发生变化');
// 可以在这里执行数据同步或UI更新操作
});
// 移除监听器
userDefaults.removeEventListener('change', handlerFunction);
线程安全考虑
UserDefaults 操作是线程安全的，但需要注意：
// 在主线程执行 UserDefaults 操作（推荐）
Ti.App.addEventListener('resume', function() {
Ti.UI.backgroundColor = userDefaults.getString(['theme_color', '#FFFFFF']);
});
// 避免在密集循环中频繁读写
function updateCounter() {
const count = userDefaults.getInt(['counter', 0]);
userDefaults.setInt(['counter', count + 1]);
// 批量操作时考虑性能
if (count % 10 === 0) {
userDefaults.defaultsObject.synchronize();
}
}
数据迁移策略
当数据结构发生变化时，需要考虑数据迁移：
function migrateUserData() {
const oldData = userDefaults.getObject(['user_data_old']);
if (oldData) {
// 执行数据迁移
const newData = transformData(oldData);
userDefaults.setObject(['user_data_new', newData]);
userDefaults.removeProperty(['user_data_old']);
}
}
function transformData(oldData) {
// 数据转换逻辑
return {
...oldData,
metadata: {
migrated: true,
migratedAt: new Date().toISOString()
}
};
}
性能优化与错误处理
性能优化技巧
// 1. 批量操作减少同步次数
function saveUserSettings(settings) {
userDefaults.setString(['theme', settings.theme]);
userDefaults.setBool(['notifications', settings.notifications]);
userDefaults.setInt(['font_size', settings.fontSize]);
// 只同步一次
userDefaults.defaultsObject.synchronize();
}
// 2. 使用合适的数据类型
// 对于大量数据，考虑使用文件存储而非 UserDefaults
function shouldUseUserDefaults(dataSize) {
return dataSize < 1024 * 100; // 小于100KB
}
// 3. 缓存频繁访问的数据
let cachedTheme = null;
function getTheme() {
if (!cachedTheme) {
cachedTheme = userDefaults.getString(['theme', 'light']);
}
return cachedTheme;
}
错误处理模式
// 安全的读取操作
function safeGet(key, defaultValue) {
try {
const value = userDefaults.getString([key]);
return value !== null ? value : defaultValue;
} catch (error) {
console.error(`读取 ${key} 失败:`, error);
return defaultValue;
}
}
// 安全的写入操作
function safeSet(key, value) {
try {
userDefaults.setString([key, value]);
return true;
} catch (error) {
console.error(`写入 ${key} 失败:`, error);
return false;
}
}
// 数据类型验证
function isValidUserData(data) {
return data &&
typeof data.name === 'string' &&
typeof data.email === 'string' &&
data.email.includes('@');
}
实际应用场景
用户偏好设置
class UserPreferences {
constructor() {
this.defaults = require('Ti.App.iOS').createUserDefaults({});
}
// 主题设置
setTheme(theme) {
this.defaults.setString(['app_theme', theme]);
}
getTheme() {
return this.defaults.getString(['app_theme', 'light']);
}
// 通知设置
setNotificationsEnabled(enabled) {
this.defaults.setBool(['notifications_enabled', enabled]);
}
areNotificationsEnabled() {
return this.defaults.getBool(['notifications_enabled', true]);
}
// 语言设置
setLanguage(language) {
this.defaults.setString(['app_language', language]);
}
getLanguage() {
return this.defaults.getString(['app_language', 'zh-CN']);
}
}
用户状态管理
class UserSession {
constructor() {
this.defaults = require('Ti.App.iOS').createUserDefaults({});
}
// 登录状态
setLoggedIn(userId, token) {
this.defaults.setBool(['is_logged_in', true]);
this.defaults.setString(['user_id', userId]);
this.defaults.setString(['auth_token', token]);
this.defaults.setDouble(['login_time', Date.now()]);
}
isLoggedIn() {
return this.defaults.getBool(['is_logged_in', false]);
}
getUserId() {
return this.defaults.getString(['user_id', '']);
}
// 登出清理
logout() {
this.defaults.removeProperty(['is_logged_in']);
this.defaults.removeProperty(['user_id']);
this.defaults.removeProperty(['auth_token']);
this.defaults.removeProperty(['login_time']);
}
}
应用统计数据
class AppAnalytics {
constructor() {
this.defaults = require('Ti.App.iOS').createUserDefaults({});
}
// 启动次数统计
incrementLaunchCount() {
const count = this.defaults.getInt(['launch_count', 0]);
this.defaults.setInt(['launch_count', count + 1]);
this.defaults.setDouble(['last_launch', Date.now()]);
}
getLaunchCount() {
return this.defaults.getInt(['launch_count', 0]);
}
// 功能使用统计
trackFeatureUsage(featureName) {
const key = `feature_${featureName}_count`;
const count = this.defaults.getInt([key, 0]);
this.defaults.setInt([key, count + 1]);
}
}
常见问题与解决方案
存储限制问题
UserDefaults 不适合存储大量数据，建议：
// 检查数据大小
function getStoredDataSize() {
const properties = userDefaults.listProperties();
let totalSize = 0;
properties.forEach(prop => {
const value = userDefaults.getObject([prop]);
if (value && typeof value === 'string') {
totalSize += value.length;
}
});
return totalSize;
}
// 数据清理策略
function cleanupOldData() {
const oneMonthAgo = Date.now() - 30 * 24 * 60 * 60 * 1000;
const properties = userDefaults.listProperties();
properties.forEach(prop => {
if (prop.startsWith('temp_')) {
const timestamp = userDefaults.getDouble([`${prop}_timestamp`, 0]);
if (timestamp < oneMonthAgo) {
userDefaults.removeProperty([prop]);
userDefaults.removeProperty([`${prop}_timestamp`]);
}
}
});
}
数据类型兼容性
确保数据类型兼容性：
// 类型安全的读取函数
function getTypedValue(key, type, defaultValue) {
try {
let value;
switch (type) {
case 'boolean':
value = userDefaults.getBool([key, defaultValue]);
break;
case 'number':
value = userDefaults.getDouble([key, defaultValue]);
break;
case 'string':
value = userDefaults.getString([key, defaultValue]);
break;
case 'array':
value = userDefaults.getList([key, defaultValue]);
break;
default:
value = defaultValue;
}
return value;
} catch (error) {
console.warn(`获取 ${key} 时类型不匹配，使用默认值`);
return defaultValue;
}
}
总结
Titanium SDK 的 Ti.App.iOS.UserDefaults 模块为开发者提供了强大而灵活的数据持久化解决方案。通过本文的详细解析，你应该已经掌握了：
- 核心概念：理解 UserDefaults 的工作原理和适用场景
- API 使用：熟练掌握各种数据类型的读写操作方法
- 高级特性：应用组、变更监听等高级功能的实际应用
- 最佳实践：性能优化、错误处理和数据迁移策略
- 实际场景：用户偏好、会话管理、数据分析等常见用例
记住，UserDefaults 最适合存储小量的配置数据和用户偏好。对于大量结构化数据，建议考虑其他存储方案如 SQLite 或文件存储。
通过合理使用 UserDefaults，你可以为用户提供更加个性化、稳定的应用体验，同时确保数据的安全性和一致性。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
