Preferences 類別

定義

命名空間:: Java.Util.Prefs

組件:: Mono.Android.dll

重要

部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

一個位於階層偏好資料集合中的節點。

[Android.Runtime.Register("java/util/prefs/Preferences", DoNotGenerateAcw=true)]
public abstract class Preferences : Java.Lang.Object

[<Android.Runtime.Register("java/util/prefs/Preferences", DoNotGenerateAcw=true)>]
type Preferences = class
    inherit Object

繼承: Object

JavaObject

Object
Preferences

衍生: Java.Util.Prefs.AbstractPreferences

屬性: RegisterAttribute

備註

一個位於階層偏好資料集合中的節點。此類別允許應用程式儲存與檢索使用者與系統偏好與設定資料。這些資料會持續儲存在依實作而定的後備儲存庫中。典型實作包括平面檔案、作業系統專用登錄檔、目錄伺服器及 SQL 資料庫。使用者無需擔心背板的細節。

偏好節點有兩棵獨立的樹狀結構，一棵用於使用者偏好設定，另一棵用於系統偏好設定。每個使用者都有獨立的使用者偏好樹，且同一系統中的所有使用者共用相同的系統偏好樹。「使用者」與「系統」的精確描述會因實作而異。使用者偏好樹中典型的資訊可能包括字型選擇、顏色選擇，或特定應用程式的偏好視窗位置與大小。系統偏好樹中典型的資訊可能包含應用程式的安裝設定資料。

偏好樹中的節點命名方式類似於階層式檔案系統中的目錄。偏好樹中的每個節點都有一個 節點名稱 （不一定是唯一的）、一個唯一的 絕對路徑名稱，以及 相對於 每個祖先（包括自身）的路徑名稱。

根節點的節點名稱為空字串（“”）。其他每個節點都有一個任意的節點名稱，並在建立時指定。此名稱唯一的限制是不能是空字串，且不能包含斜線字元（'/'）。

根節點的絕對路徑名稱為 "/"。根節點的子節點的絕對路徑名稱為 <節點名稱>. 其他所有節點的絕對路徑名稱為 <父的絕對路徑名稱><節點名稱>. 請注意，所有絕對路徑名稱都以斜線字開頭。

節點 n 相對於其祖先 a 的路徑名稱，就是必須附加在 a 的絕對路徑名稱上，形成 n 的絕對路徑名稱的字串，且移除初始的斜線字元（若有的話）。注意： <ul><li>沒有以斜線字開頭的相關路徑名稱。 <li>每個節點相對於自身的路徑名稱都是空字串。 <li>每個節點相對於父節點的路徑名稱即為其節點名稱（根節點除外，該節點沒有父節點）。 <li>每個節點相對於根節點的路徑名稱，都是其絕對路徑名稱，且去除了初始斜杠。 </ul>

最後注意： <ul><li>沒有路徑名稱包含多個連續的斜線字元。 <除了>根的絕對路徑名稱外，其他路徑名稱都以斜杠結尾。 <li>任何符合這兩條規則的字串都是有效的路徑名稱。 </ul>

所有修改偏好設定資料的方法都允許非同步運作;它們可能會立即返回，且變更最終會以實作依賴的延遲方式傳播到持久備份儲存庫。此 flush 方法可用於同步強制更新至後備儲存庫。正常終止 Java 虛擬機不會導致待處理更新遺失——終止時flush明確調用來確保待處理更新是持久的。

所有從物件讀取偏好 Preferences 設定的方法都要求呼叫器提供預設值。若先前未設定過值 或備份存儲不可用，則會回傳預設值。其目的是讓應用程式能夠運作，儘管功能略有退化，即使後備儲存庫無法使用。有些方法，例如 flush，有語意上無法在備份儲存庫無法使用時運作。一般應用程式不應需要調用這些方法，因為這些方法可透過宣告拋出 BackingStoreException來辨識。

此類別的方法可由單一 JVM 中的多個執行緒同時呼叫，無需外部同步，結果相當於某種序列執行。若 多個 JVM 同時使用此類別，且它們各自將偏好設定資料存放於同一備份儲存庫，資料儲存不會損壞，但對於偏好資料的一致性則無法保證其他問題。

此類別包含匯出/匯入功能，允許將偏好設定「匯出」為 XML 文件，並將代表偏好設定的 XML 文件「匯入」回系統。此功能可用於備份全部或部分偏好樹，並從備份中還原。

XML 文件具有以下 DOCTYPE 宣告：

{@code
<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
            }

請注意，系統 URI（http://java.sun.com/dtd/preferences.dtd) 在匯出或匯入偏好設定時不會被存取;它僅作為字串用以唯一識別 DTD，該字串為：

{@code
<?xml version="1.0" encoding="UTF-8"?>

<!-- DTD for a Preferences tree. -->

<!-- The preferences element is at the root of an XML document
                    representing a Preferences tree. -->
<!ELEMENT preferences (root)>

<!-- The preferences element contains an optional version attribute,
                     which specifies version of DTD. -->
<!ATTLIST preferences EXTERNAL_XML_VERSION CDATA "0.0" >

<!-- The root element has a map representing the root's preferences
                    (if any), and one node for each child of the root (if any). -->
<!ELEMENT root (map, node*) >

<!-- Additionally, the root contains a type attribute, which
                    specifies whether it's the system or user root. -->
<!ATTLIST root
                         type (system|user) #REQUIRED >

<!-- Each node has a map representing its preferences (if any),
                    and one node for each child (if any). -->
<!ELEMENT node (map, node*) >

<!-- Additionally, each node has a name attribute -->
<!ATTLIST node
                         name CDATA #REQUIRED >

<!-- A map represents the preferences stored at a node (if any). -->
<!ELEMENT map (entry*) >

<!-- An entry represents a single preference, which is simply
                     a key-value pair. -->
<!ELEMENT entry EMPTY >
<!ATTLIST entry
                         key   CDATA #REQUIRED
                         value CDATA #REQUIRED >
            }

每個 Preferences 實作都必須有相應 PreferencesFactory 的實作。每個 Java（TM） SE 實作都必須提供某種方式，指定用哪個PreferencesFactory實作來產生根偏好節點。這允許管理員以替代實作取代預設偏好設定的實作。

實作說明：在 Sun 的 JRE 中，實 PreferencesFactory 作位置如下：

<進攻線>

<李>

若系統屬性 java.util.prefs.PreferencesFactory 被定義，則視為實作 PreferencesFactory 介面的類別的全限定名稱。該類別被載入並實例化;若此程序失敗，則會拋出未指定錯誤。

</李>

<李>

如果PreferencesFactory一個實作類別檔案已安裝在一個 jar 檔案中，且java.lang.ClassLoader#getSystemClassLoader system class loader該 jar 檔案包含資源目錄java.util.prefs.PreferencesFactory中命名META-INF/services的提供者設定檔，則會取用該檔案中指定的第一個類別名稱。若提供多個此類 jar 檔案，則會使用第一個找到的。該類別被載入並實例化;若此程序失敗，則會拋出未指定錯誤。

</李>

<李>

最後，若未提供上述系統屬性或擴充名 jar 檔案，則會載入並實例化底層平台的系統性預設 PreferencesFactory 實作。

</李>

</ol>

在 1.4 版本加入。

Java 文件 java.util.prefs.Preferences。

本頁部分內容為基於 Open Source Project 所創建與分享的作品，並依授權條款所描述的使用進行修改。

建構函式

名稱	Description
Preferences()	唯一的製造者。
Preferences(IntPtr, JniHandleOwnership)	用於建立 JNI 物件受管理表示的建構器;由執行時呼叫。

欄位

名稱	Description
MaxKeyLength	鍵碼允許的最大字串長度（80 個字元）。
MaxNameLength	節點名稱的最大長度（80 個字元）。
MaxValueLength	字串的最大長度（8192 字元）。

屬性

名稱	Description
Class	回傳此 `Object`的執行時類別。 (繼承來源 Object)
Handle	底層 Android 實例的帳號。 (繼承來源 Object)
IsUserNode	回傳此節點是否為使用者偏好節點。
JniIdentityHashCode	取得由互通執行時指派給此 Java 對等端的身份雜湊碼。 (繼承來源 Object)
JniManagedPeerState	一個位於階層偏好資料集合中的節點。 (繼承來源 JavaObject)
JniPeerMembers	此 API 支援 Mono for Android 基礎架構，並非直接從你的程式碼中使用。
PeerReference	取得這個 Java 節點的 JNI 物件參考。 (繼承來源 Object)
ThresholdClass	此 API 支援 Mono for Android 基礎架構，並非直接從你的程式碼中使用。
ThresholdType	此 API 支援 Mono for Android 基礎架構，並非直接從你的程式碼中使用。

方法

名稱	Description
AbsolutePath()	回傳此偏好節點的絕對路徑名稱。
AddNodeChangeListener(INodeChangeListener)	註冊指定的監聽器以接收該節點的節點變更事件。
AddPreferenceChangeListener(IPreferenceChangeListener)	註冊指定的監聽器以接收此偏好節點的偏好變更事件。
ChildrenNames()	回傳該偏好節點相對於該節點的子節點名稱。
Clear()	移除此偏好節點中的所有偏好（鍵值關聯）。
Clone()	建立並回傳此物件的副本。 (繼承來源 Object)
Construct(JniObjectReference, JniObjectReferenceOptions)	一個位於階層偏好資料集合中的節點。 (繼承來源 JavaObject)
Dispose()	釋放該 Java 節點所持有的資源。 (繼承來源 Object)
Dispose(Boolean)	釋放該 Java 節點所持有的資源。 (繼承來源 Object)
DisposeUnlessReferenced()	一個位於階層偏好資料集合中的節點。 (繼承來源 JavaObject)
Equals(Object)	一個位於階層偏好資料集合中的節點。 (繼承來源 JavaObject)
Equals(Object)	表示是否有其他物體「等同」於此物。 (繼承來源 Object)
ExportNode(Stream)	在指定的輸出串流上，會輸出一個代表該節點中所有偏好設定的 XML 文件（但不含其後代）。
ExportNodeAsync(Stream)	非同步會輸出一份 XML 文件，代表該節點中所有偏好，但不包含其後代。
ExportSubtree(Stream)	會輸出一份 XML 文件，代表該節點及其所有後代節點中所有偏好設定。
ExportSubtreeAsync(Stream)	非同步地會輸出一份 XML 文件，代表該節點及其所有後代節點中所有偏好設定。
Flush()	強制將此偏好節點及其後代節點內容的任何變更都傳送到持久儲存。
FlushAsync()	非同步強制將此偏好節點及其後代節點的任何變更強制至持久儲存。
Get(String, String)	回傳該偏好節點中與指定鍵相關聯的值。
GetBoolean(String, Boolean)	回傳與該偏好節點中指定鍵相關字串所代表的布林值。
GetByteArray(String, Byte[])	回傳由指定鍵相關字串所代表的位元組陣列值。
GetDouble(String, Double)	回傳由該偏好節點中指定鍵相關應字串所代表的雙重值。
GetFloat(String, Single)	回傳由該偏好節點中指定鍵相關字串所代表的浮點數值。
GetHashCode()	回傳物件的雜湊碼值。 (繼承來源 Object)
GetInt(String, Int32)	回傳由該偏好節點中指定鍵相關應字串所代表的整數值。
GetLong(String, Int64)	回傳由該偏好節點中指定鍵相關字串所代表的長值。
ImportPreferences(Stream)	匯入XML文件在指定輸入串流中所代表的所有偏好設定。
ImportPreferencesAsync(Stream)	非同步匯入 XML 文件在指定輸入串流上所代表的所有偏好設定。
JavaFinalize()	當垃圾回收判定該物件不再有相關參考時，由垃圾回收器呼叫。 (繼承來源 Object)
Keys()	回傳所有在偏好節點中與其值相符的鍵。
Name()	回傳此偏好節點相對於父節點的名稱。
Node(String)	回傳與此節點同一棵樹中的命名偏好節點，並建立該節點及其尚未存在的祖先節點。
NodeExists(String)	如果該命名偏好節點與該節點在同一棵樹中，則回傳為真。
Notify()	喚醒一個正在該物件監視器上等待的執行緒。 (繼承來源 Object)
NotifyAll()	喚醒所有等待該物件監視器的執行緒。 (繼承來源 Object)
Parent()	回傳此偏好節點的父節點，或 `null` 是否為根節點。
Put(String, String)	將指定的值與此偏好節點中的指定鍵關聯。
PutBoolean(String, Boolean)	在此偏好節點中，將代表指定布林值的字串與指定鍵關聯。
PutByteArray(String, Byte[])	在此偏好節點中，將代表指定位元組陣列的字串與指定鍵連結。
PutDouble(String, Double)	在此偏好節點中，將代表指定雙重值的字串與指定鍵連結起來。
PutFloat(String, Single)	在此偏好節點中，將代表指定浮點數值的字串與指定鍵關聯。
PutInt(String, Int32)	在此偏好節點中，將代表指定整數值的字串與指定鍵關聯。
PutLong(String, Int64)	將代表指定長值的字串與此偏好節點中的指定鍵關聯。
Remove(String)	移除與該偏好節點中指定鍵值相關的值（若有的話）。
RemoveNode()	移除此偏好節點及其所有後代節點，使移除節點中的所有偏好失效。
RemoveNodeChangeListener(INodeChangeListener)	移除指定的 `NodeChangeListener`，使其不再接收變更事件。
RemovePreferenceChangeListener(IPreferenceChangeListener)	移除指定的偏好變更監聽器，因此不再接收偏好變更事件。
SetHandle(IntPtr, JniHandleOwnership)	設定 Handle 屬性。 (繼承來源 Object)
SetPeerReference(JniObjectReference, JniObjectReferenceOptions)	一個位於階層偏好資料集合中的節點。 (繼承來源 JavaObject)
Sync()	確保未來從此偏好節點及其後代讀取時，能反映在呼叫前 `sync` 已提交至持久儲存（來自任何虛擬機）的任何變更。
SyncAsync()	非同步地將此偏好節點及其後代節點與持久儲存同步。
SystemNodeForPackage(Class)	<強烈>警告：</strong> 在 Android 上，對應於「system」和「user」偏好設定的偏好節點會儲存在應用程式無法存取的檔案系統區塊中。
SystemRoot()	<強烈>警告：</strong> 在 Android 上，對應於「system」和「user」偏好設定的偏好節點會儲存在應用程式無法存取的檔案系統區塊中。
ToArray<T>()	從這個 Java 陣列包裝器建立一個受管理陣列。 (繼承來源 Object)
ToString()	回傳此偏好節點的字串表示，就像由以下表達式`(this.isUserNode() ? "User" : "System") + " Preference Node: " + this.absolutePath()`計算一樣。
UnregisterFromRuntime()	將此 Java 節點從互通執行時中取消註冊。 (繼承來源 Object)
UserNodeForPackage(Class)	<強烈>警告：</strong> 在 Android 上，對應於「system」和「user」偏好設定的偏好節點會儲存在應用程式無法存取的檔案系統區塊中。
UserRoot()	<強烈>警告：</strong> 在 Android 上，對應於「system」和「user」偏好設定的偏好節點會儲存在應用程式無法存取的檔案系統區塊中。
Wait()	導致目前執行緒等待被喚醒，通常是透過 <em>通知</><em 或 em>中斷</em> 來喚醒。 (繼承來源 Object)
Wait(Int64, Int32)	會讓目前執行緒等待喚醒，通常是透過 <em>通知</><em 或 em>中斷</em>，或是經過一定的真實時間。 (繼承來源 Object)
Wait(Int64)	會讓目前執行緒等待喚醒，通常是透過 <em>通知</><em 或 em>中斷</em>，或是經過一定的真實時間。 (繼承來源 Object)

明確介面實作

名稱	Description
IJavaPeerable.Disposed()	一個位於階層偏好資料集合中的節點。 (繼承來源 JavaObject)
IJavaPeerable.Finalized()	一個位於階層偏好資料集合中的節點。 (繼承來源 JavaObject)
IJavaPeerable.JniObjectReferenceControlBlock	一個位於階層偏好資料集合中的節點。 (繼承來源 JavaObject)
IJavaPeerable.SetJniIdentityHashCode(Int32)	一個位於階層偏好資料集合中的節點。 (繼承來源 JavaObject)
IJavaPeerable.SetJniManagedPeerState(JniManagedPeerStates)	一個位於階層偏好資料集合中的節點。 (繼承來源 JavaObject)
IJavaPeerable.SetPeerReference(JniObjectReference)	一個位於階層偏好資料集合中的節點。 (繼承來源 JavaObject)

擴充方法

名稱	Description
GetJniTypeName(IJavaPeerable)	取得實例 `self`類型的 JNI 名稱。
JavaAs<TResult>(IJavaPeerable)	試著強制`self`輸入 `TResult`，檢查強制在 Java 端是否有效。
JavaCast<TResult>(IJavaObject)	執行 Android 執行時檢查型別轉換。
JavaCast<TResult>(IJavaObject)	一個位於階層偏好資料集合中的節點。
TryJavaCast<TResult>(IJavaPeerable, TResult)	試著強制`self`輸入 `TResult`，檢查強制在 Java 端是否有效。

適用於