PreferenceScreen - 설정 화면을 나타내는 최상위 컨테이너입니다. 이 컨테이너는 Preference 계층 구조의 루트 구성요소입니다.
PreferenceCategory - 비슷한 Preferences를 그룹화하는 데 사용되는 컨테이너입니다. PreferenceCategory는 카테고리 제목을 표시하고 시각적으로 Preferences의 그룹을 구분합니다.
개별 환경설정
Preference - 개별 설정을 나타내는 기본 빌딩 블록입니다. Preference를 유지하도록 설정하면 이 클래스는 설정의 사용자 선택을 보존하는 키-값 쌍을 가지며 이는 애플리케이션 어디에서나 액세스할 수 있습니다.
EditTextPreference - String 값을 유지하는 Preference입니다. 사용자는 Preference를 탭하여, 유지된 값을 변경할 수 있는 텍스트 필드가 포함된 대화상자를 실행할 수 있습니다.
ListPreference - 문자열 값을 유지하는 Preference입니다. 사용자는 라디오 버튼의 목록과 이에 대응하는 라벨이 포함된 대화상자에서 이 값을 변경할 수 있습니다.
MultiSelectListPreference - 문자열 집합을 유지하는 Preference입니다. 사용자는 체크박스의 목록과 이에 대응하는 라벨이 포함된 대화상자에서 이 값을 변경할 수 있습니다.
SeekBarPreference - 정수 값을 유지하는 Preference입니다. 이 값은 Preference 레이아웃에 표시된 탐색 막대를 드래그하여 변경할 수 있습니다.
SwitchPreferenceCompat - 부울 값을 유지하는 Preference입니다. 이 값은 스위치 위젯과 상호작용하거나 Preference 레이아웃을 탭하여 변경할 수 있습니다.
CheckBoxPreference - 부울 값을 유지하는 Preference입니다. 이 값은 체크박스와 상호작용하거나 Preference 레이아웃을 탭하여 변경할 수 있습니다.
환경설정 속성
아래에는 Preference의 모양 및 동작을 구성하는 데 가장 일반적으로 사용되는 속성의 일부가 나열되어 있습니다.
일반 속성
title
Preference의 제목을 나타내는 String 값입니다.
예:app:title="Title"
summary
Preference의 요약을 나타내는 String 값입니다.
예:app:summary="Summary"
icon
Preference 아이콘을 나타내는 Drawable입니다.
예:app:icon="@drawable/ic_camera"
key
연관된 Preference의 값을 유지하는 데 사용되는 키를 나타내는 String 값입니다. 키를 사용하면 런타임 중에 Preference를 더 상세하게 맞춤설정할 수 있습니다.
계층 구조의 각 Preference에 키를 설정해야 합니다.
예:app:key="key"
enabled
사용자가 Preference와 상호작용할 수 있는지를 나타내는 부울 값입니다. 이 값이 false이면 Preference는 비활성화 상태로 표시되고 사용자와 상호작용할 수 없습니다. 기본값은 true입니다.
예:app:enabled="false"
selectable
사용자가 Preference와 상호작용할 수 있는지를 나타내는 부울 값입니다. 기본값은 true입니다.
예:app:selectable="false"
isPreferenceVisible
Preference 또는 Preference 카테고리가 표시되는지를 나타내는 부울 값입니다. 이 값을 설정하는 것은 setVisible()을 호출하는 것과 동일합니다.
예:app:isPreferenceVisible="false"
defaultValue
Preference의 기본값을 나타냅니다. 이 값은 이 Preference에 유지된 값이 없을 때 설정되고 유지됩니다. 값 유형은 관련된 Preference에 따라 다릅니다.
예:app:defaultValue="true"
dependency
이 Preference의 상태를 제어하는 SwitchPreferenceCompat의 키를 나타냅니다. 대응하는 스위치가 사용 중지되면 Preference는 중지되고 수정할 수 없습니다.
예:app:dependency="parent"
PreferenceCategory 속성
initialExpandedChildrenCount
Preference의 펼치기 동작을 사용 설정하는 정수 값입니다. 이 값은 PreferenceGroup에 보이는 하위 요소의 최대 개수를 나타냅니다. 모든 추가 하위 요소는 접혀있고 펼치기 버튼을 탭하여 표시할 수 있습니다. 기본적으로 이 값은 Integer.MAX_VALUE이며 모든 하위 요소가 표시됩니다.
경고: 이 속성을 사용한다면 구성이 변경(예: 화면 회전)되었을 때 상태가 올바르게 저장되고 복원되도록 PreferenceCategory에 키를 설정해야 합니다.
예:app:initialExpandedChildrenCount="0"
ListPreference / MultiSelectListPreference 속성
entries
사용자에게 표시되는 목록 항목에 대응하는 문자열 배열입니다. 각 값은 내부적으로 유지되는 값 배열의 색인에 따라 대응됩니다. 예를 들어, 사용자가 첫 번째 목록 항목을 선택하면 이에 대응하는 값 배열의 첫 번째 요소가 유지됩니다.
예:app:entries="@array/entries"
경고: 두 배열의 길이가 같고 각 배열의 색인이 올바른 항목/값 쌍과 일치하는지 확인해야 합니다.
entryValues
유지될 항목의 배열입니다. 각 값은 사용자에게 표시되는 목록 항목 배열의 색인에 따라 대응됩니다.
예:app:entryValues="@array/values"
이 페이지에 나와 있는 콘텐츠와 코드 샘플에는 콘텐츠 라이선스에서 설명하는 라이선스가 적용됩니다. 자바 및 OpenJDK는 Oracle 및 Oracle 계열사의 상표 또는 등록 상표입니다.
최종 업데이트: 2025-07-27(UTC)
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-07-27(UTC)"],[],[],null,["# Preference components and attributes\nPart of [Android Jetpack](/jetpack).\n=========================================================================\n\nThis topic describes some of the most commonly-used `Preference` components and\nattributes used when building a settings screen.\n\nPreference components\n---------------------\n\nThis section describes common `Preference` components. For more information, see\nthe corresponding reference pages for each component.\n\n### Preference infrastructure\n\n[`PreferenceFragmentCompat`](/reference/androidx/preference/PreferenceFragmentCompat) -\na [`Fragment`](/reference/kotlin/androidx/fragment/app/Fragment) that handles\ndisplaying an interactive hierarchy of `Preference` objects.\n\n### Preference containers\n\n[`PreferenceScreen`](/reference/androidx/preference/PreferenceScreen) -\na top-level container that represents a settings screen. This is the root\ncomponent of your `Preference` hierarchy.\n\n[`PreferenceCategory`](/reference/androidx/preference/PreferenceCategory) -\na container that is used to group similar `Preferences`. A `PreferenceCategory`\ndisplays a category title and visually separates groups of `Preferences`.\n\n### Individual Preferences\n\n[`Preference`](/reference/androidx/preference/Preference) - the basic\nbuilding block that represents an individual setting. If a `Preference` is set\nto persist, it has a corresponding key-value pair that holds the user's choice\nfor the setting that can be accessed elsewhere in the application.\n\n[`EditTextPreference`](/reference/androidx/preference/EditTextPreference) -\na `Preference` that persists a `String` value. Users can tap on the `Preference`\nto launch a dialog containing the text field that allows the user to change the\npersisted value.\n\n[`ListPreference`](/reference/androidx/preference/ListPreference) - a\n`Preference` that persists a String value. Users can change this value in a\ndialog that contains a list of radio buttons with corresponding labels.\n\n[`MultiSelectListPreference`](/reference/androidx/preference/MultiSelectListPreference) -\na `Preference` that persists a set of Strings. Users can change these values in\na dialog that contains a list of checkboxes with corresponding labels.\n\n[`SeekBarPreference`](/reference/androidx/preference/SeekBarPreference) -\na `Preference` that persists an integer value. This value can be changed by\ndragging a corresponding seekbar that is displayed in the `Preference` layout.\n\n[`SwitchPreferenceCompat`](/reference/androidx/preference/SwitchPreferenceCompat) -\na `Preference` that persists a boolean value. This value can be changed by\ninteracting with the corresponding switch widget or by tapping on the\n`Preference` layout.\n\n[`CheckBoxPreference`](/reference/androidx/preference/CheckBoxPreference) -\na `Preference` that persists a boolean value. This value can be changed by\ninteracting with the corresponding checkbox or by tapping on the `Preference`\nlayout.\n| **Note:** Although `SwitchPreferenceCompat` and `CheckBoxPreference` store a boolean value and function in similar ways, we recommend using a `SwitchPreferenceCompat` where possible. For more information, see the [Android Settings Design Guidelines](https://source.android.com/devices/tech/settings/settings-guidelines#checkbox).\n\nPreference attributes\n---------------------\n\nListed below are some of the most commonly-used attributes that configure\n`Preference` appearance and behavior.\n| **Note:** Each attribute listed below has a corresponding getter and setter. For mostly static hierarchies, however, we recommend configuring these attributes via the `Preference` XML resource.\n\n### Generic attributes\n\n\n`title`\n\n: A `String` value that represents the title of the\n `Preference`.\n\n **Example:** `app:title=\"Title\"`\n\n\n`summary`\n\n: A `String` value that represents the `Preference`\n summary.\n\n **Example:** `app:summary=\"Summary\"`\n\n\n`icon`\n\n: A `Drawable` that represents the `Preference`\n icon.\n\n **Example:** `app:icon=\"@drawable/ic_camera\"`\n\n\n`key`\n\n: A `String` value that represents the key that is used to\n persist the value for the associated `Preference`. A key allows\n you to further customize the `Preference` during runtime.\n You should set a key for each `Preference` in your\n hierarchy.\n\n\n **Example:** `app:key=\"key\"`\n\n\n`enabled`\n\n: A boolean value that indicates whether users can interact with the\n `Preference`. When this value is `false`, the\n `Preference` appears grayed out, and users cannot interact with\n it. The default value is `true`.\n\n **Example:** `app:enabled=\"false\"`\n\n\n`selectable`\n\n: A boolean value that indicates whether users can interact with the\n `Preference`. The default value is `true`.\n\n **Example:** `app:selectable=\"false\"`\n\n\n`isPreferenceVisible`\n\n: A boolean value that indicates whether a `Preference` or\n `Preference` category is visible. This is equivalent to calling\n [`setVisible()`](/reference/androidx/preference/Preference#setVisible(boolean)).\n\n **Example:** `app:isPreferenceVisible=\"false\"`\n\n\n`defaultValue`\n\n: Represents the default value for a `Preference`. This value is\n set and persisted when no other persisted value for this\n `Preference` is found. The value type depends on the associated\n `Preference`.\n\n **Example:** `app:defaultValue=\"true\"`\n\n\n`dependency`\n\n: Represents the key of a `SwitchPreferenceCompat` that controls\n the state of this `Preference`. When the corresponding switch\n is turned off, this `Preference` is disabled and is unable to\n be modified.\n\n **Example:** `app:dependency=\"parent\"`\n\n### PreferenceCategory attributes\n\n\n`initialExpandedChildrenCount`\n\n: An integer value that enables expandable `Preference`\n behavior. This value represents the maximum number of children to show in\n the `PreferenceGroup`. Any extra children are collapsed and can\n be shown by tapping the expand button. By default, this value is\n `Integer.MAX_VALUE`, and all children are shown.\n\n **Warning:** Ensure that you set a key on the\n `PreferenceCategory` if using this attribute so that the state\n is correctly saved and restored when the configuration changes (such as\n when rotating the screen).\n\n\n **Example:** `app:initialExpandedChildrenCount=\"0\"`\n\n### ListPreference / MultiSelectListPreference attributes\n\n\n`entries`\n\n: An array of Strings that corresponds to the list entries to be displayed\n to the user. Each of these values correspond by index to the array of\n values that are internally persisted. For example, when a user selects the\n first list entry, the first element in the corresponding array of values\n is persisted.\n\n\n **Example:** `app:entries=\"@array/entries\"`\n\n **Warning:** Ensure the length of both arrays are the\n same, and the indexes of each array match the correct entry / value\n pair.\n\n\n`entryValues`\n\n: The array of entries to be persisted. Each of these values correspond by\n index to the array of list entries that are displayed to the user.\n\n\n **Example:** `app:entryValues=\"@array/values\"`"]]
