NSUserDefaults

@interface NSUserDefaults : NSObject

Overview 概要

The NSUserDefaults class provides a programmatic interface for interacting with the defaults system. The defaults system allows an app to customize its behavior to match a user’s preferences. For example, you can allow users to specify their preferred units of measurement or media playback speed. Apps store these preferences by assigning values to a set of parameters in a user’s defaults database. The parameters are referred to as defaults because they’re commonly used to determine an app’s default state at startup or the way it acts by default. NSUserDefaultsクラスは、初期状態のシステムと相互作用するためのプログラムインターフェイスを提供します。defaultsシステムは、アプリがそれの挙動をカスタマイズしてユーザの好みに合わせることを可能にします。例えば、あなたはユーザにかれらの好む寸法単位またはメディア再生速度を指定させることができます。アプリは、これら環境設定を、ユーザのもつdefaultsデータベースにおいて一揃いのパラメータに値を割り当てることによって格納します。パラメータそれらは、defaults 初期状態として参照されます、なぜならそれらは一般に始動時でのアプリのもつ省略時の状態をまたはそれが初期状態でふるまう方法を決定するために使われるからです。

At runtime, you use NSUserDefaults objects to read the defaults that your app 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. When you set a default value, it’s changed synchronously within your process, and asynchronously to persistent storage and other processes. 実行時に、あなたはNSUserDefaultsオブジェクトを使って、あなたのアプリが使うdefaultsをユーザのもつdefaultsデータベースから読み出してください。NSUserDefaultsは、情報をキャッシュして、ユーザのもつdefaultsデータベースをあなたが初期状態の値を必要とするたびに開かなければならないのを防止します。あなたがある初期状態値を設定する場合、それは、あなたのプロセス内で同期的に、そして非同期に永続ストレージおよび他のプロセスに対して変更されます。

With the exception of managed devices in educational institutions, a user’s defaults are stored locally on a single device, and persisted for backup and restore. To synchronize preferences and other data across a user’s connected devices, use NSUbiquitousKeyValueStore instead. 教育機関において管理されたデバイスを除いて、ユーザのもつdefaultsはローカルに単一のデバイス上で格納されます、そしてバックアップと修復のために永続されます。環境設定と他のデータをあるユーザのもつ関連したデバイスそれらにわたって同期するには、NSUbiquitousKeyValueStoreを代わりに使ってください。

Storing Default Objects defaultオブジェクトを格納する

The NSUserDefaults class provides convenience methods for accessing common types such as floats, doubles, integers, Boolean values, and URLs. These methods are described in Setting Default Values. NSUserDefaultsクラスは、便利なメソッドを一般的な型、たとえばfloat、double、整数、ブール値、そしてURLなどにアクセスするために提供します。これらのメソッドは、省略時の値を設定するで記述されます。

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, or NSDictionary. If you want to store any other type of object, you should typically archive it to create an instance of NSData. defaultオブジェクトはプロパティリストでなければなりません — すなわち、NSData、NSString、NSNumber、NSDate、NSArray、またはNSDictionaryの（またはそのインスタンスの組み合わせ、コレクションに対する）インスタンス。あなたが何らかの他の型のオブジェクトを格納したいならば、あなたは概してそれをアーカイブして、NSDataのインスタンスを作成すべきです。

Values returned from NSUserDefaults 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 the stringForKey: method will be immutable. If you set a mutable string as a default value and later mutate the string, the default value won’t reflect the mutated string value unless you call setObject:forKey: again. NSUserDefaultsから返される値は、不変です、たとえあなたが可変オブジェクトを値として設定したとしてもです。たとえば、あなたが可変文字列を “MyStringDefault” に対する値として設定したならば、あなたが後でstringForKey:メソッドを使って回収する文字列は、不変であるでしょう。あなたが可変文字列をあるdefault値として設定したそして後でその文字列を変化させたならば、default値は変化させた文字列値を反映しないでしょう、あなたがsetObject:forKey:を再び呼び出さない限りは。

For more details, see Preferences and Settings Programming Guide. 詳細として、Preferences and Settings Programming Guideを見てください。

Persisting File References ファイル環境設定を永続する

A file URL specifies a location in the file system. If you use the setURL:forKey: method to store the location for a particular file and the user moves that file, your app may not be able to locate that file on next launch. To store a reference to a file by its file system identity, you can instead create NSURL bookmark data using the bookmarkDataWithOptions:includingResourceValuesForKeys:relativeToURL:error: method and persist it using the setObject:forKey: method. You can then use the URLByResolvingBookmarkData:options:relativeToURL:bookmarkDataIsStale:error: method to resolve the bookmark data stored in user defaults to a file URL. ファイルURLは、ファイルシステムの中のある位置を指定します。あなたがsetURL:forKey:メソッドを使ってある特定のファイルに対する位置を格納するそしてユーザがそのファイルを移動するならば、あなたのアプリはそのファイルを次の起動で位置決めできないかもしれません。ある環境設定をファイルへとそれのファイルシステム識別子によって格納するには、あなたは代わりにNSURLブックマークデータをbookmarkDataWithOptions:includingResourceValuesForKeys:relativeToURL:error:メソッドを使って作成して、それをsetObject:forKey:メソッドを使って永続できます。あなたはそれからURLByResolvingBookmarkData:options:relativeToURL:bookmarkDataIsStale:error:メソッドを使って、ユーザdefaultsの中に格納されたブックマークデータをファイルURLへと解決できます。

Responding to Defaults Changes defaultsの変化を報告する

You can use key-value observing to be notified of any updates to a particular default value. You can also register as an observer for NSUserDefaultsDidChangeNotification on the defaultCenter notification center in order to be notified of all updates to a local defaults database. あなたは、キー値監視を使って、特定のdefault値へのあらゆる更新を通知されることができます。あなたはまた、あるオブザーバを登録することが、NSUserDefaultsDidChangeNotificationに対してdefaultCenter通知センター上で、あるローカルなdefaultsデータベースへの全ての更新を通知される目的で、行えます。

For more details, see Key-Value Observing Programming Guide and Notification Programming Topics. さらなる詳細として、Key-Value Observing Programming GuideとNotification Programming Topicsを見てください。

Using Defaults in Managed Environments defaultを管理された環境において使用する

If your app supports managed environments, you can use NSUserDefaults to determine which preferences are managed by an administrator for the benefit of the user. In a managed environment, such as a computer lab or classroom, an administrator or teacher can configure the systems by establishing a set of default preferences for users. If a preference is managed in this manner (as determined by the methods described in Accessing Managed Environment Keys), your app should prevent users from editing that preference by disabling or hiding controls. あなたのアプリが管理された環境をサポートするならば、あなたはNSUserDefaults使って、どの環境設定がシステム管理者によってユーザの利益のために管理されるか決定できます。管理された環境において、たとえばコンピュータラボまたは教室など、システム管理者または教師は、複数のシステムを構成設定することがある一揃いの省略時の環境設定を複数ユーザに対して確立することによって可能です。ある環境設定がこの流儀で管理されるならば（管理された環境キーにアクセスするで記述されるメソッドによって決定されるように）、あなたのアプリは、ユーザがその環境設定を編集することを、コントロールそれらを使用不可にするまたは隠すことによって防ぐべきです。

For more details, see Mobile Device Management Protocol Reference. さらなる詳細として、Mobile Device Management Protocol Referenceを見てください。

An app running on a device managed by an educational institution can use the iCloud key-value store to share small amounts of data with other instances of itself on the user’s other devices. For example, a textbook app might store the current page number being read by the user so that other instances of the app can open to the same page when launched. 教育機関によって管理されるデバイス上で動作しているアプリは、iCloudキー値格納を使って、小さな量のデータをそのユーザのもつ他のデバイス上のそれ自身のほかのインスタンスと共有できます。例えば、教科書アプリは、ユーザによって読まれている現在のページ数を格納するかもしれません、それでそのアプリの他のインスタンスは起動時に同じページが開かれたままであることができます。

For more information, see Storing Preferences in iCloud in Preferences and Settings Programming Guide. さらなる情報として、Storing Preferences in iCloudをPreferences and Settings Programming Guideで見てください。

Sandbox Considerations サンドボックス考慮

A sandboxed app cannot access or modify the preferences for any other app, with the following exceptions: サンドボックスアプリは、いかなる他のアプリに対する環境設定にアクセスまたは修正できません、以下の例外で：

• App extensions on macOS and iOS macOSとiOS上のアプリ拡張

• Other apps in your application group on macOS macOS上のあなたのアプリケーショングループ中の他のアプリ

Adding a third-party app’s domain using the addSuiteNamed: method doesn’t allow your app to access to that app’s preferences. サードパーティアプリのもつドメインをaddSuiteNamed:メソッドを使って加えることは、あなたのアプリにそのアプリのもつ環境設定へのアクセスを許可しません。 Attempting to access or modify another app’s preferences doesn’t result in an error; instead, macOS reads and writes files located within your app’s container, rather than the actual preference files for the other application.

Thread Safety スレッド安全

The UserDefaults class is thread-safe. UserDefaultsクラスは、スレッド安全です。