NSUserDefaults API中英文文档简介及使用

Overview

The NSUserDefaults class provides a programmatic interface for interacting with the defaults system. The defaults system allows an application to customize its behavior to match a user’s preferences. For example, you can allow users to determine what units of measurement your application displays or how often documents are automatically saved. Applications record such preferences by assigning values to a set of parameters in a user’s defaults database. The parameters are referred to as defaults since they’re commonly used to determine an application’s default state at startup or the way it acts by default.

At runtime, you use anNSUserDefaults object to read the defaults that your application uses from a user’s defaults database.NSUserDefaults caches the information to avoid having to open the user’s defaults database each time you need a default value. Thesynchronize method, which is automatically invoked at periodic intervals, keeps the in-memory cache in sync with a user’s defaults database.

The NSUserDefaults class provides convenience methods for accessing common types such as floats, doubles, integers, Booleans, and URLs. A default object must be a property list, that is, an instance of (or for collections a combination of instances of):NSData,NSString,NSNumber, NSDate, NSArray, orNSDictionary. If you want to store any other type of object, you should typically archive it to create an instance ofNSData. For more details, seePreferences and Settings Programming Guide.

Values returned fromNSUserDefaults are immutable, even if you set a mutable object as the value. For example, if you set a mutable string as the value for"MyStringDefault", the string you later retrieve using stringForKey: will be immutable.

A defaults database is created automatically for each user. TheNSUserDefaults class does not currently support per-host preferences. To do this, you must use the CFPreferences API (seePreferences Utilities Reference). However, NSUserDefaults correctly reads per-host preferences, so you can safely mix CFPreferences code withNSUserDefaults code.

If your application supports managed environments, you can use anNSUserDefaults object to determine which preferences are managed by an administrator for the benefit of the user. Managed environments correspond to computer labs or classrooms where an administrator or teacher may want to configure the systems in a particular way. In these situations, the teacher can establish a set of default preferences and force those preferences on users. If a preference is managed in this manner, applications should prevent users from editing that preference by disabling any appropriate controls.

The NSUserDefaults class is thread-safe.

Tasks

Getting the Shared NSUserDefaults Instance

• + standardUserDefaults
• + resetStandardUserDefaults

Initializing an NSUserDefaults Object

• – init
• – initWithUser:Deprecated in OS X v10.9

Registering Defaults

• – registerDefaults:

Getting Default Values

• – arrayForKey:
• – boolForKey:
• – dataForKey:
• – dictionaryForKey:
• – floatForKey:
• – integerForKey:
• – objectForKey:
• – stringArrayForKey:
• – stringForKey:
• – doubleForKey:
• – URLForKey:

Setting Default Values

• – setBool:forKey:
• – setFloat:forKey:
• – setInteger:forKey:
• – setObject:forKey:
• – setDouble:forKey:
• – setURL:forKey:

Removing Defaults

• – removeObjectForKey:

Maintaining Persistent Domains

• – synchronize
• – persistentDomainForName:
• – removePersistentDomainForName:
• – setPersistentDomain:forName:
• – persistentDomainNamesDeprecated in OS X v10.9

Accessing Managed Environment Keys

• – objectIsForcedForKey:
• – objectIsForcedForKey:inDomain:

Managing the Search List

• – dictionaryRepresentation

Maintaining Volatile Domains

• – removeVolatileDomainForName:
• – setVolatileDomain:forName:
• – volatileDomainForName:
• – volatileDomainNames

Maintaining Suites

• – addSuiteNamed:
• – removeSuiteNamed:

翻译上面NSUserDefaults的API大概意思如下:

NSUserDefaults类提供了一个与默认系统进行交互的编程接口。NSUserDefaults对象是用来保存，恢复应用程序相关的偏好设置，配置数据等等。默认系统允许应用程序自定义它的行为去迎合用户的喜好。你可以在程序运行的时候从用户默认的数据库中读取程序的设置。同时NSUserDefaults的缓存避免了在每次读取数据时候都打开用户默认数据库的操作。可以通过调用synchronize方法来使内存中的缓存与用户默认系统进行同步。

NSUserDefaults类提供了非常方便的方法来获取常用的类型，例如floats,doubles,intergers,Booleans,URLs。所以一个NSUserDefaults的对象必须是属性表，这也就是说我们可以存储NSData,NSString,NSNUmber,NSDate,NSArray,NSDictionary这些实例。如果你想存储其他类型的对象，你要将其归档并创建一个NSData来实现存储。

从NSUserDefaults返回的值是不可改变的，即便是你在存储的时候使用的是可变的值。例如你使用mutable string做为“MyStringDefault”的值，当你做使用stringForKey:方法获取的值，这个值仍然是不可变的。

NSUserDefaults是单例，同时也是线程安全的.

方法详解

获取公有的NSUserDefaults实例

[plain] view plaincopy

1. + (NSUserDefaults *)standardUserDefaults;  
2. 单例模式，获取NSUserDefaults的一个实例，默认Key值如下：  
3. AppleLanguages,  
4. AppleKeyboardsExpanded,  
5. AppleITunesStoreItemKinds,  
6. AppleLocale,  
7. AppleKeyboards,  
8. NSLanguages,  
9. NSInterfaceStyle  

[plain] view plaincopy

1. + (void)resetStandardUserDefaults;  

初始化一个NSUserDefaults的对象

[plain] view plaincopy

1. - (id)init;  
2. - (id)initWithUser:(NSString *)username;  
3. init是初始化一个公有的defaults对象  
4. initWithUser是初始化一个针对username的对象  

注册一个defaults

[plain] view plaincopy

1. - (void)registerDefaults:(NSDictionary *)registrationDictionary;  
2. 注册的内容(registrationDictionary里的)不写入磁盘  

获取Defaults的值

[plain] view plaincopy

1. - (NSArray *)arrayForKey:(NSString *)defaultName;  

[plain] view plaincopy

1. - (BOOL)boolForKey:(NSString *)defaultName;  
2. 返回一个和defaultName关联的bool值，如果不存在defaultName的话返回NO  

[plain] view plaincopy

1. - (NSData *)dataForKey:(NSString *)defaultName  
2. 返回defaultName所对应的NSData数据，如果defaultName不存在或者返回的数据不是NSData类型的都会返回nil  
3. 返回的数据是不可变类型的  

[plain] view plaincopy

1. - (NSDictionary *)dictionaryForKey:(NSString *)defaultName  
2. 同dataForKey  

[plain] view plaincopy

1. - (float)floatForKey:(NSString *)defaultName  
2. 同dataForKey  
3. 如果defaultName不存在返回0  

[plain] view plaincopy

1. - (NSInteger)integerForKey:(NSString *)defaultName  
2. 同floatForKey  
3. 如果defaultName不存在返回0  

[plain] view plaincopy

1. - (id)objectForKey:(NSString *)defaultName  
2. 同dataForKey  

[plain] view plaincopy

1. - (NSArray *)stringArrayForKey:(NSString *)defaultName  
2. 同dataForKey  
3. 如果defaultName不存在，或者defaultName所对应的不是一个数组，或者数组包含的不是NSString对象都会返回nil  

[plain] view plaincopy

1. - (NSString *)stringForKey:(NSString *)defaultName  
2. 同dataForKey  

[plain] view plaincopy

1. - (double)doubleForKey:(NSString *)defaultName  
2. 同floatForKey  

[plain] view plaincopy

1. - (NSURL *)URLForKey:(NSString *)defaultName  
2. 同dataForKey  
3. 当调用[NSUserDefaults URLForKey:]时，有以下3种情况：  
4. 1.如果值是NSData,NSData可以作为[NSKeyedUnarchiver unarchiveObjectWithData:]的参数。如果NSData可以作为NSURL存档就返回一个NSURL，否则返回nil  
5. 2.如果值是一个文件引用的URL，那么这个文件引用的URL将会被创建，但是它的书签数据不会被解决直到以后使用NSURL实例  
6. 3.如果值是一个一～开头的字符串，这个字符串将会用[NSString stringByExpandingTildeInPath]扩展，文件将会以NSURL创建  

设置Defaults值

[plain] view plaincopy

1. – setBool:forKey:  
2. – setFloat:forKey:  
3. – setInteger:forKey:  
4. – setDouble:forKey:  
5.   
6. – setObject:forKey:  
7. 对象参数只能是属性列表对象：NSData，NSString，NSNumber,NSDate,NSArray,NSDictionary  
8. – setURL:forKey:  

移除Defaults值

[plain] view plaincopy

1. - (void)removeObjectForKey:(NSString *)defaultName  

维护持久域

[plain] view plaincopy

1. - (BOOL)synchronize  
2. 把持久域中的任何改变写到磁盘并且更新磁盘上的任何没有修改的持久域  
3. 如果返回YES表明成功保存到磁盘，相反返回NO  
4. 这个方法是以一定周期间隔自动调用的，如果你不想等待自动调用就可以调用这个方法来同步。(例如，如果你的应用要退出时，或者你想更新磁盘上的defaults即使你没有做任何改变)  

[plain] view plaincopy

1. - (NSDictionary *)persistentDomainForName:(NSString *)domainName  
2. 返回一个特定持久域的键值对  

[plain] view plaincopy

1. - (NSArray *)persistentDomainNames  
2. 返回当前的持久域的名称  

[plain] view plaincopy

1. - (void)removePersistentDomainForName:(NSString *)domainName  
2. 移除对应domainName的持久域  

[plain] view plaincopy

1. - (void)setPersistentDomain:(NSDictionary *)domain forName:(NSString *)domainName  
2. 设置持久域  
3. domainName  
4. This value should be equal to your application's bundle identifier.  

访问管理的环境值

[plain] view plaincopy

1. - (BOOL)objectIsForcedForKey:(NSString *)key  
2. - (BOOL)objectIsForcedForKey:(NSString *)key inDomain:(NSString *)domain  

管理搜索列表

[plain] view plaincopy

1. - (NSDictionary *)dictionaryRepresentation  
2. 返回搜索列表中对应域的所有的键值对  

维护不稳定的域

[plain] view plaincopy

1. – removeVolatileDomainForName:  
2. – setVolatileDomain:forName:  
3. – volatileDomainForName:  
4. – volatileDomainNames  

维护套件

[plain] view plaincopy

1. - (void)addSuiteNamed:(NSString *)suiteName  
2. 一个套件可以在不同的应用之间使用  

[plain] view plaincopy

1. - (void)removeSuiteNamed:(NSString *)suiteName  
2. 移除套件  

示例代码如下:

#pragma mark---------存    //创建 NSUserDefaults 单例    NSUserDefaults * ud = [NSUserDefaults standardUserDefaults];    //把_userNameTextField.text存到  NSUserDefaults 中    [ud setObject:_userNameTextField.text forKey:@"myKey"];    [ud synchronize];#pragma mark---------取    //从 NSUserDefaults 中取出 数据    NSString * value = [ud objectForKey:@"myKey"];    NSLog(@"value = %@",value);