このページは Cloud Translation API によって翻訳されました。

設定

API リファレンス
androidx.preference

デバイスストレージの操作や UI の管理なしで、インタラクティブな設定画面を構築します。

最新の更新	安定版リリース	リリース候補版	ベータ版リリース	アルファ版リリース
2023 年 7 月 26 日	1.2.1	-	-	-

依存関係の宣言

Preference への依存関係を追加するには、Google の Maven リポジトリをプロジェクトに追加する必要があります。詳しくは、Google の Maven リポジトリをご覧ください。

アプリまたはモジュールの build.gradle ファイルに、必要なアーティファクトの依存関係を追加します。

Groovy

dependencies {
    def preference_version = "1.2.1"

    // Java language implementation
    implementation "androidx.preference:preference:$preference_version"
    // Kotlin
    implementation "androidx.preference:preference-ktx:$preference_version"
}

Kotlin

dependencies {
    val preference_version = "1.2.1"

    // Java language implementation
    implementation("androidx.preference:preference:$preference_version")
    // Kotlin
    implementation("androidx.preference:preference-ktx:$preference_version")
}

依存関係について詳しくは、ビルド依存関係の追加をご覧ください。

フィードバック

お寄せいただいたフィードバックは Jetpack 改善の参考にさせていただきます。新しい問題が見つかった場合や、このライブラリを改善するアイデアをお持ちの場合は、お知らせください。新しい問題を報告していただく前に、このライブラリの既存の問題をご確認ください。スターボタンをクリックすると、既存の問題に投票できます。

新しい問題を報告する

詳細については、Issue Tracker のドキュメントをご覧ください。

バージョン 1.2

バージョン 1.2.1

2023 年 7 月 26 日

androidx.preference:preference:1.2.1 がリリースされました。バージョン 1.2.1 に含まれる commit については、こちらをご覧ください。

バグの修正

PreferenceHeaderFragmentCompat が、ComponentDialog 内で使用された場合、または Fragment の Context をラップする Hilt の @AndroidEntryPoint などのライブラリを使用する場合に、システムの [戻る] ボタンを正しく処理するようになりました。
Preference が Activity 1.5.1 に依存するようになりました。（Ie5d22）。
PreferenceHeaderFragmentCompat.onCreateInitialDetailFragment が header.extras を Fragment 引数として伝播するようになりました。

バージョン 1.2.0

2022 年 1 月 26 日

androidx.preference:preference:1.2.0 と androidx.preference:preference-ktx:1.2.0 がリリースされました。バージョン 1.2.0 に含まれる commit については、こちらをご覧ください。

1.1.0 以降の重要な変更

使用するデバイスのサイズに自動的に適応する 2 ペインの設定用に、PreferenceHeaderFragmentCompat を追加しました。これは、スマートフォン、折りたたみ式デバイス、タブレットでの使用に適しています。ヘッダーペインは、PreferenceHeaderFragmentCompat の onCreatePreferenceHeader() メソッドをオーバーライドすることで提供できます。app:fragment を使用するヘッダー PreferenceFragmentCompat 内の <Preference> はすべて、そのフラグメントを第 2 詳細ペインに表示します。設定が手動で選択される前に表示する必要がある初期詳細フラグメントは、onCreateInitialDetailFragment() をオーバーライドすることでカスタマイズできます。デフォルトの実装は、フラグメントが定義されている最初の設定を返します。

class TwoPanePreference : PreferenceHeaderFragmentCompat() {
    override fun onCreatePreferenceHeader(): PreferenceFragmentCompat {
        return PreferenceHeader()
    }
}

これまで @NonNull または @Nullable を指定していなかった API の多くに null 可能性アノテーションを追加しました。これは、Kotlin コードで選択していた null 可能性が今回定義された null 可能性と一致しない場合、Kotlin ソースの互換性を破る変更となる可能性があります。
PreferenceFragmentCompat は、親フラグメント上での OnPreferenceStartFragmentCallback、OnNavigateToScreenListener、および OnDisplayPreferenceDialogListener のインターフェースの実装を検索してから、ホスティング元の Context または Activity がこれらのインターフェースを実装しているかどうかを確認するようになりました。

バージョン 1.2.0-rc01

2021 年 12 月 15 日

androidx.preference:preference:1.2.0-rc01 と androidx.preference:preference-ktx:1.2.0-rc01 がリリースされました。1.2.0-beta01 からの変更はありません。バージョン 1.2.0-rc01 に含まれる commit については、こちらをご覧ください。

バージョン 1.2.0-beta01

2021 年 11 月 17 日

androidx.preference:preference:1.2.0-beta01 と androidx.preference:preference-ktx:1.2.0-beta01 がリリースされました。Preference 1.2.0-alpha02 からの変更はありません。バージョン 1.2.0-beta01 に含まれる commit については、こちらをご覧ください。

バージョン 1.2.0-alpha02

2021 年 11 月 3 日

androidx.preference:preference:1.2.0-alpha02 と androidx.preference:preference-ktx:1.2.0-alpha02 がリリースされました。バージョン 1.2.0-alpha02 に含まれる commit については、こちらをご覧ください。

API の変更

これまで @NonNull または @Nullable を指定していなかった API の多くに null 可能性アノテーションを追加しました。（I04252、Ie2cc0）
PreferenceHeaderFragmentCompat から openPreference() API を削除しました。このメソッドは自動的に呼び出され、手動で呼び出すことはできません。（Ia6989）

動作の変更

OnNavigateToScreenListener と OnDisplayPreferenceDialogListener の PreferenceFragmentCompat コールバックは、OnPreferenceTreeClickListener と同じパターンに従うようになりました。ホスティング元の Context または Activity がこれらのインターフェースを実装しているかどうかを確認する前に、親フラグメント階層で有効なリスナーを検索します。（I7ae6c）

バージョン 1.2.0-alpha01

2021 年 10 月 27 日

androidx.preference:preference:1.2.0-alpha01 と androidx.preference:preference-ktx:1.2.0-alpha01 がリリースされました。バージョン 1.2.0-alpha01 に含まれる commit については、こちらをご覧ください。

新機能

2 ペインの設定に PreferenceHeaderFragmentCompat を追加しました（I9a2d8）

動作の変更

OnPreferenceDisplayDialogCallback、OnPreferenceStartScreenCallback、OnPreferenceStartFragmentCallback の設定のコールバックを Activity 以外の Context に実装できるようになりました。getActivity() を確認する前に getContext() がチェックされ、これらのコールバックを実装しているかどうかが確認されます。getContext() が Activity を返す場合（一般的なケース）、動作の変更はありません。
PreferenceFragmentCompat の onPreferenceTreeClick への呼び出しで、Activity の実装を検討する前に、親フラグメントで OnPreferenceStartFragmentCallback インターフェースの実装を確認するようになりました。（c64eed）

バージョン 1.1

バージョン 1.1.1

2020 年 4 月 15 日

androidx.preference:preference:1.1.1 と androidx.preference:preference-ktx:1.1.1 がリリースされました。バージョン 1.1.1 に含まれる commit については、こちらをご覧ください。

バグの修正

FragmentContainerView を xml からインフレートするときに、PreferenceDialogFragmentCompat が IllegalStateException をスローしなくなりました。（b/150051716）

依存関係の更新

Preference が Fragment 1.2.4に依存するようになりました。（aosp/1277317）
preference-ktx 依存関係が androidx.core:core-ktx:1.1.0 と androidx.fragment:fragment-ktx:1.2.4 に依存するようになりました。メインの preference アーティファクトの依存関係をミラーリングし、preference-ktx をアップグレードすることで推移的な依存関係のメインのアーティファクトと -ktx のアーティファクトの両方が確実に更新されるようになりました。（aosp/1277319）

バージョン 1.1.0

2019 年 9 月 5 日

androidx.preference:preference:1.1.0 と androidx.preference:preference-ktx:1.1.0 がリリースされました。このバージョンに含まれる commit については、こちらをご覧ください。

1.1.* リリースに初めてアップデートする場合は、最新の安定版リリースである 1.0.0 以降に行われた重要な変更について、下記の簡単な説明をご確認ください。設定ガイド、サンプルアプリ、Android Dev Summit の講演でも、役に立つ情報を見つけることができます。

1.0.0 以降の重要な変更

フレームワーク Fragments を使用する PreferenceFragment などのクラスのサポートが終了しました。代わりに、PreferenceFragmentCompat などの *compat クラスを使用する必要があります。
Preference が更新されたとき、またはユーザーが Preference を参照できるようになったときに、サマリーが動的に設定されるように Preference の SummaryProvider を設定できるようになりました。詳しくは、ガイドをご覧ください。
EditTextPreference.OnBindEditTextListener インターフェースが追加されました。これにより、ダイアログがバインドされた後に対応するダイアログに表示される EditText をカスタマイズできるようになりました。AndroidX ライブラリでサポートされていない EditTextPreference で android:inputType などの属性を直接使用する代わりに、この方法を使用できます。詳しくは、ガイドをご覧ください。
Preference.setCopyingEnabled() が追加されました。有効に設定されている場合に [Preference] を長押しすると、コンテキストメニューが表示され、Preference のサマリーをコピーできるようになります。
Material の仕様と一致するように SeekBarPreference のスタイルが更新されました。SeekBarPreference のその他の変更について詳しくは、変更履歴をご覧ください。
さまざまなバグの修正、スタイルの更新、API レベルの互換性の修正、一般的な QOL の改善が行われました。

バージョン 1.1.0-rc01

2019 年 7 月 2 日

androidx.preference:preference:1.1.0-rc01 と androidx.preference:preference-ktx:1.1.0-rc01 がリリースされました。このバージョンに含まれる commit については、こちらをご覧ください。

API の変更

Preference#onInitializeAccessibilityNodeInfo のサポート終了
このメソッドは、特定の Preference のユーザー補助ノード情報をプロキシしていましたが、これは、このカスタマイズにとって不適切なレイヤです。ユーザー補助情報を調整する場合は、代わりに onBindViewHolder をオーバーライドして、ユーザー補助情報をビューに直接追加する必要があります。

バージョン 1.1.0-beta01

2019 年 6 月 5 日

androidx.preference:preference:1.1.0-beta01 と androidx.preference:preference-ktx:1.1.0-beta01 がリリースされました。このバージョンに含まれるコミットについては、こちらをご覧ください。

1.1.0 以降の重要な変更

1.1.* リリースに初めてアップデートする場合は、最新の安定版リリースである 1.1.0 以降に行われた重要な変更について、下記の簡単な説明をご確認ください。設定ガイド、サンプルアプリ、Android Dev Summit の講演でも、役に立つ情報を見つけることができます。

フレームワーク Fragments を使用する PreferenceFragment などのクラスのサポートが終了しました。代わりに、PreferenceFragmentCompat などの *compat クラスを使用する必要があります。
Preference が更新されたとき、またはユーザーが Preference を参照できるようになったときに、サマリーが動的に設定されるように Preference の SummaryProvider を設定できるようになりました。詳しくは、ガイドをご覧ください。
EditTextPreference.OnBindEditTextListener インターフェースが追加されました。これにより、ダイアログがバインドされた後に対応するダイアログに表示される EditText をカスタマイズできるようになりました。AndroidX ライブラリでサポートされていない EditTextPreference で android:inputType などの属性を直接使用する代わりに、この方法を使用できます。詳しくは、ガイドをご覧ください。
Preference.setCopyingEnabled() が追加されました。有効に設定されている場合に [Preference] を長押しすると、コンテキストメニューが表示され、Preference のサマリーをコピーできるようになります。
Material の仕様と一致するように SeekBarPreference のスタイルが更新されました。SeekBarPreference のその他の変更について詳しくは、変更履歴をご覧ください。
さまざまなバグの修正、スタイルの更新、API レベルの互換性の修正、一般的な QOL の改善が行われました。

1.1.0-alpha05 以降の API の変更

getOnBindEditTextListener が公開 API から削除されました。この API を操作する場合にのみ、setOnBindEditTextListener を使用する必要があります。

問題や新機能に関するご提案がありましたら、こちらからご報告ください。

バージョン 1.1.0-alpha05

2019 年 5 月 7 日

androidx.preference:preference:1.1.0-alpha05 と androidx.preference:preference-ktx:1.1.0-alpha05 がリリースされました。このバージョンに含まれる commit については、こちらをご覧ください。

新機能

選択できない Preference のスタイルが更新されました。タイトルとサマリーに同じ色が使われるようになり、操作できないこと、情報表示専用であることがわかりやすくなりました。
注: 選択できない Preference に enableCopying="true" を追加することをご検討ください。こうすることで、長押しでサマリーをコピーできるようになります。

バグの修正

PreferenceCategory などの選択できない Preference が選択されたときに波紋効果が適用されるバグを修正しました。
TalkBack で DropDownPreference がクリック可能なアイテムとして表示されないユーザー補助機能の問題を修正しました。
RTL レイアウトに関する問題を修正しました。
PreferenceFragmentCompat の一部の null 可能性アノテーションを Fragment と一致するように更新しました。

バージョン 1.1.0-alpha04

2019 年 3 月 13 日

androidx.preference:preference:1.1.0-alpha04 と androidx.preference:preference-ktx:1.1.0-alpha04 がリリースされました。このバージョンに含まれるコミットの完全なリストについては、こちらをご覧ください。

新機能

SeekBarPreference が更新されました。

Material の仕様と一致するようにスタイルが更新されました。
- 値ラベルがデフォルトで非表示になりました。ただし、app:showSeekBarValue="true" または setShowSeekBarValue(true) を使用すると引き続き表示できます。このラベルは Material の仕様に含まれていませんが、使用されることが多いため、今後もサポートする予定です。ただし、このラベルの使用は推奨されません。
- SeekBar のドラッグ中（離したときではない）に値ラベルが更新されるようになりました。ただし、値が内部的に更新されるわけではないことに注意してください。この機能を有効にする新しい API については、下記をご覧ください。
- 注: SeekBarPreference でのサマリーの設定はサポートされていますが、このような設定は想定されておらず、Material の仕様に含まれていないため、行わないでください。
継続的な更新に対するサポートを追加することで、SeekBar のドラッグ中に SeekBar の保存済みの値を更新できるようになります。この機能は XML（app:updatesContinuously="true"）またはプログラム（setUpdatesContinuously(true)）で有効にすることができ、画面上で SeekBar の位置が変更されたときに実行されます。

API の変更

不足している null 可能性アノテーションを findPreference() に追加しました。

バグの修正

コピー機能が有効化されていない場合にコンテキストメニューのリスナーが正しく削除されないバグを修正しました。

バージョン 1.1.0-alpha03

2019 年 2 月 7 日

androidx.preference:preference 1.1.0-alpha03

以下の変更を反映した androidx.preference:preference 1.1.0-alpha03 と androidx.preference:preference-ktx 1.1.0-alpha03 がリリースされました。

バグの修正

コピー / 貼り付けのポップアップが EditTextPreference のダイアログに表示されないことがある問題を修正しました。
基盤となるアダプターが適切に登録解除されず、特定の条件下でメモリリークが発生する問題を修正しました（b/121006469）。
設定の変更時に発生するダイアログ関連のクラッシュを修正しました（b/122167543）。
SummaryProvider が MultiSelectListPreference で動作しない問題を修正しました（b/123022772）。

バージョン 1.1.0-alpha02

2018 年 12 月 17 日

最近更新された設定ガイドとサンプルアプリもご確認ください。

新機能

EditTextPreference.OnBindEditTextListener インターフェースが追加されました。これにより、ダイアログがバインドされた後で、対応するダイアログに表示される EditText をカスタマイズできるようになりました。たとえば、カスタムの入力タイプや長さを設定する、または TextWatcher を追加することができます。
Preference.setCopyingEnabled() が追加されました。有効に設定されている場合に [Preference] を長押しすると、コンテキストメニューが表示され、Preference のサマリーをコピーできるようになります。このメソッドを使用すると、静的な情報（ユーザー固有の ID、アプリのバージョン情報など）をコピーできます。
preferenceTheme がアクティビティのテーマに適用されました。これにより、コードから Preference を作成する際に、PreferenceManager#getContext() のコンテキストを使用する必要がなくなり、Fragment または Activity のコンテキストを使用するだけで済むようになりました。

API の変更

findPreference() がリファクタリングされ、<T extends Preference> を返すようになりました。これにより、findPreference() を使用する際に、Preference を明示的にキャストする必要がなくなりました。たとえば、EditTextPreference preference = findPreference(“edit_text”) は、現在は有効なコードです。

バージョン 1.1.0-alpha01

2018 年 11 月 5 日

新機能

Preference が更新されたとき、またはユーザーが Preference を参照できるようになったときに、Preference の SummaryProvider を設定することにより、サマリーを動的に設定できるようになりました。
ListPreference と EditTextPreference に対するデフォルトの SummaryProvider 実装が追加されました。この実装が設定されている場合、Preference のサマリーが自動的に更新され、保存済みの値が反映されます。値が保存されていない場合は、「Not Set」が設定されます。この実装を設定するには、app:useSimpleSummaryProvider=”true” のように指定します。
PreferenceGroup#removePreferenceRecursively が追加されました。このメソッドは、Preference を再帰的に検索して、該当グループまたは階層内の下位にあるネストされたグループから削除します。

API の変更

フレームワーク Fragments を使用する PreferenceFragment などのクラスのサポートが終了しました。代わりに、PreferenceFragmentCompat などの compat クラスを使用する必要があります。

バグの修正

iconSpaceReserved が PreferenceCategories と正しく連携しない問題を修正しました。
API 21 未満で PreferenceCategories がタイトルの色に colorAccent を使用しない問題を修正しました。
API 21 未満における SeekBarPreference レイアウトの不整合を修正しました。