SharedPreferences

Shared Preferences

介绍


官方API地址

用于访问和修改返回的Preferences数据的接口是getSharedPreferences(String,int),对于任何特定的Preferences设置,所有客户端共享此类的一个实例。对于Preferences的修改,必须经过一个SharedPreferences.Editor对象,以确保首选项值保存在一致的状态下,并在控制时保存它们。从各种get方法返回的对象必须被应用程序视为不可变的。

注意:这个类不支持在多个进程中使用。

公共方法


contains

boolean contains (String key)

检查首选项是否包含首选项。

参数
key String:要检查的preferences的名称。
返回
boolean 如果首选项中存在preferences,则返回true,否则返回false。

edit

SharedPreferences.Editor edit()

为这些 preferences创建一个新的编辑器,通过这个编辑器可以对 preferences中的数据进行修改,并自动将这些更改提交回SharedPreferences对象。

请注意,您必须调用commit()以使您在编辑器中执行的任何更改实际显示在SharedPreferences中。

返回
SharedPreferences.Editor 返回SharedPreferences.Editor接口的新实例,允许您修改此SharedPreferences对象中的值。

getAll

Map < String,?> getAll()

从preferences中检索所有值。

请注意,您不得修改此方法返回的集合,也不得修改其中的任何内容。如果不这么做,存储数据的一致性将得不到保证。

返回
Map<String, ?> 返回包含表示preferences的成对键/值列表的映射。
抛出
NullPointerException

getBoolean

boolean getBoolean (String key, boolean defValue)

从preferences中检索一个布尔值。

参数
key String:要检索的preference的名称。
defValue boolean:如果此preference不存在,则返回的值。
返回
boolean 返回preferences的值(如果存在)或是默认值。如果存在不是布尔值的此名称的preference,则抛出ClassCastException。
抛出
ClassCastException

getFloat

float getFloat (String key,float defValue)

从preferences中检索一个浮点值。

参数、返回和抛出与getBoolean类似

getInt

int getInt (String key,int defValue)

从preferences中检索一个int值。

参数、返回和抛出与getBoolean类似

getLong

long getLong (String key,long defValue)

从preferences中检索一个长整型值。

getString

String getString (String key,String defValue)

从preferences中检索字符串值。

参数
key String:要检索的preference的名称。
defValue String:如果此preference不存在,则返回的值。这个值可能是null
返回
String 返回preference的值(如果存在)或是默认值。如果存在不是字符串的此名称的preference,则抛出ClassCastException。这个值可能是null
抛出
ClassCastException

getStringSet

Set<String> getStringSet (String key,Set<String> defValues)

参数、返回和抛出与getString类似

registerOnSharedPreferenceChangeListener

void registerOnSharedPreferenceChangeListener (SharedPreferences.OnSharedPreferenceChangeListener listener)

注册在preference发生更改时要调用的回调函数

警告:preference管理器当前不存储对侦听器的强引用。您必须存储对侦听器的强引用,否则它将容易被垃圾收集。只要您需要侦听器,我们建议您在对象的实例数据中保留对侦听器的引用。

参数
listener SharedPreferences.OnSharedPreferenceChangeListener:将运行的回调。

也可以参考:

unregisterOnSharedPreferenceChangeListener

void unregisterOnSharedPreferenceChangeListener(SharedPreferences.OnSharedPreferenceChangeListener listener)

取消注册以前的回调函数。

参数
listener SharedPreferences.OnSharedPreferenceChangeListener:应该注销的回调。

getSharedPreferences

SharedPreferences getSharedPreferences (String name, int mode)

检索并保存preferences文件“name”的内容,返回一个SharedPreferences,通过它可以检索和修改其值。任何调用者使用同一实例名称调用,都是由同一个SharedPreferences对象实例返回的,这意味着他们将很快看到互相的编辑。

参数
name String:所需的preferences文件。如果通过此名称的preferences文件不存在,则在您检索编辑器(SharedPreferences.edit())并提交更改(Editor.commit())时将自动创建它。
mode int: 操作模式。值可以是0或组合MODE_PRIVATEMODE_WORLD_READABLEMODE_WORLD_WRITEABLEMODE_MULTI_PROCESS
返回
SharedPreferences SharedPreferences可用于检索和修preferences值的单个实例。

SharedPreferences.Editor

public static interface SharedPreferences.Editor 

android.content.SharedPreferences.Editor

用于修改SharedPreferences 对象中的值的接口。您在编辑器中所做的所有更改都是成批处理的,并且都不会将其复制回原来的SharedPreference,直到你调用了 commit()或者apply()方法

概要


公共方法

abstract void apply()将您的preference更改从此编辑器重新提交到SharedPreferences正在编辑的对象。
abstractSharedPreferences.Editor clear()在编辑器中标记以从preference中删除所有值。
abstract boolean commit()将您的preference更改从此编辑器重新提交到SharedPreferences正在编辑的对象。
abstractSharedPreferences.Editor putBoolean(String key, boolean value)在preference编辑器中设置一个布尔值,写回一次commit()或被apply()调用。
abstractSharedPreferences.Editor putFloat(String key, float value)在preference编辑器中设置一个浮点值,写回一次 commit()或被apply()调用。
abstractSharedPreferences.Editor putInt(String key, int value)在preference中设置一个int值,一次写回 commit()或被apply()调用。
abstractSharedPreferences.Editor putLong(String key, long value)在preference中设置一个长整型值,写回一次 commit()或被apply()调用。
abstractSharedPreferences.Editor putString(String key, String value)在preference编辑器中设置一个字符串值,一次写回 commit()或被apply()调用。
abstractSharedPreferences.Editor putStringSet(String key, Set<String> values)在preference编辑器中设置一组字符串值,一次写回commit()或被apply()调用。
abstractSharedPreferences.Editor remove(String key)在编辑器中标记一个preference值应该被删除,一旦commit()被调用,将在实际的preference中完成。

公共方法


void apply()

将您的preference更改从此编辑器重新提交到SharedPreferences正在编辑的对象。这将自动执行所请求的修改,替换SharedPreferences中当前的任何内容。

请注意,当两个编辑器同时修改首选项时,最后一个调用申请才会成功。

不同的是commit(),它将自己的preference同步写入持久性存储,并立即apply() 将其更改提交到内存中 的SharedPreferences,启动对磁盘的异步提交,并且不会通知任何失败。如果另外一个编辑器在一个仍然未完成的SharedPreferences情况下执行常规操作, 则会阻塞直到所有的异步提交完成以及本身的提交。

由于SharedPreferences实例是一个进程中的单例,commit()的apply()如果您已经忽略了返回值, 则可以安全地替换任何实例。

您不必担心Android组件生命周期及其与apply() 写入磁盘的交互。该框架确保在apply()切换状态之前完成正在进行的磁盘写入。

SharedPreferences.Editor接口不希望直接实现。但是,如果你以前没有实现,而且现在得到有关缺少的错误apply(),你可以简单地调用 commit()apply()

clear

SharedPreferences.Editor clear ()

在编辑器中标记以从preference中删除所有值。一旦调用提交,唯一剩下的preference将是您在此编辑器中定义的任何preference。

请注意,在提交preference时,无论您在此编辑器上放置方法之前还是之后调用clear,清除都将首先完成。

返回
SharedPreferences.Editor 返回对同一个Editor对象的引用,所以你可以把调用放在一起。

commit

boolean commit ()

将您的preference更改从此编辑器重新提交到SharedPreferences正在编辑的对象。这自动执行所请求的修改,替换SharedPreferences中当前的任何内容。

请注意,当两个编辑器同时修改preference时,最后一个调用commit的成功。

如果你不关心返回值,而是从你的应用程序的主线程中使用它,那么就考虑使用apply()

返回
boolean 如果新值成功写入永久性存储,则返回true。

putBoolean

SharedPreferences.Editor putBoolean (String key, boolean value)

在preference编辑器中设置一个布尔值,写回一次commit()或被apply()调用。

参数
key String:要修改的preference的名称。
value boolean:偏好的新值。
返回
SharedPreferences.Editor 返回对同一个Editor对象的引用,所以你可以把调用放在一起。

putFloat

SharedPreferences.Editor putFloat (String key, float value)

参数、返出与putBoolean类似

putInt

SharedPreferences.Editor putInt (String key, int value)

参数、返出与putBoolean类似

putLong

SharedPreferences.Editor putLong (String key, long value)

参数、返出与putBoolean类似

putString

SharedPreferences.Editor putString (String key, String value)

在preference编辑器中设置一个字符串值,一次写回 commit()或被apply()调用。

参数
key String:要修改的preference的名称。
value String:偏好的新值。传递null 这个参数相当于remove(String)用这个键调用。
返回
SharedPreferences.Editor 返回对同一个Editor对象的引用,所以你可以把调用放在一起。

putStringSet

SharedPreferences.Editor putStringSet (String key, Set<String> values)

参数、返出与putBoolean类似

remove

SharedPreferences.Editor remove (String key)

在preference中标记一个preference值应该被删除,一旦commit()被调用,将在实际的preference中完成。

请注意,在提交preference时,无论您在此编辑器上放置方法之前还是之后调用remove,都将首先执行所有删除操作。

参数
key String:要删除的preference的名称。
返回
SharedPreferences.Editor 返回对同一个Editor对象的引用,所以你可以把调用放在一起。