Preference

Xây dựng màn hình cài đặt mang tính tương tác mà không cần tương tác với bộ nhớ thiết bị hay quản lý giao diện người dùng.
Bản cập nhật mới nhất Bản phát hành ổn định Bản phát hành dùng thử Bản phát hành beta Bản phát hành alpha
Ngày 26 tháng 7 năm 2023 1.2.1 - - -

Khai báo phần phụ thuộc

Để thêm một phần phụ thuộc vào Preference, bạn phải thêm kho lưu trữ Google Maven vào dự án. Hãy đọc về Kho lưu trữ Maven của Google để biết thêm thông tin.

Thêm các phần phụ thuộc cho cấu phần phần mềm bạn cần trong tệp build.gradle cho ứng dụng hoặc mô-đun của mình:

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")
}

Để biết thêm thông tin về các phần phụ thuộc, hãy xem nội dung Thêm phần phụ thuộc cho bản dựng.

Ý kiến phản hồi

Ý kiến phản hồi của bạn có thể giúp chúng tôi cải thiện Jetpack. Hãy cho chúng tôi biết nếu bạn phát hiện lỗi mới hoặc có ý tưởng cải thiện thư viện này. Vui lòng xem các lỗi hiện có trong thư viện này trước khi báo một lỗi mới. Bạn có thể thêm lượt bình chọn cho lỗi hiện có bằng cách nhấp vào nút dấu sao.

Báo lỗi mới

Xem tài liệu về công cụ theo dõi lỗi để biết thêm thông tin.

Phiên bản 1.2

Phiên bản 1.2.1

Ngày 26 tháng 7 năm 2023

Phát hành androidx.preference:preference:1.2.1. Phiên bản 1.2.1 bao gồm các thay đổi sau.

Sửa lỗi

  • PreferenceHeaderFragmentCompat nay xử lý chính xác nút quay lại của hệ thống khi được dùng trong ComponentDialog hoặc khi sử dụng các thư viện như @AndroidEntryPoint của Hilt để gói Context của Mảnh.
  • Preference hiện phụ thuộc vào Activity 1.5.1. (Ie5d22)
  • PreferenceHeaderFragmentCompat.onCreateInitialDetailFragment hiện truyền header.extras dưới dạng đối số Fragment.

Phiên bản 1.2.0

Ngày 26 tháng 1 năm 2022

Phát hành androidx.preference:preference:1.2.0 và androidx.preference:preference-ktx:1.2.0. Phiên bản 1.2.0 bao gồm các thay đổi sau.

Những thay đổi quan trọng kể từ phiên bản 1.1.0

  • Bổ sung PreferenceHeaderFragmentCompat cho tuỳ chọn hai ngăn có khả năng tự động điều chỉnh dựa trên kích thước của thiết bị đang dùng, giúp tuỳ chọn này trở nên phù hợp với điện thoại, thiết bị gập và máy tính bảng. Ngăn tiêu đề được cung cấp bằng cách ghi đè phương thức onCreatePreferenceHeader() trên PreferenceHeaderFragmentCompat. Bất kỳ <Preference> nào trong tiêu đề PreferenceFragmentCompat sử dụng app:fragment sẽ khiến mảnh (fragment) đó xuất hiện trong ngăn chi tiết thứ hai. Bạn có thể tuỳ chỉnh mảnh chi tiết đầu tiên sẽ hiển thị bằng cách ghi đè onCreateInitialDetailFragment()trước khi chọn bất kỳ tuỳ chọn nào bằng cách thủ công. Cách triển khai mặc định sẽ trả về tuỳ chọn đầu tiên có mảnh được xác định trên tuỳ chọn đó.
class TwoPanePreference : PreferenceHeaderFragmentCompat() {
    override fun onCreatePreferenceHeader(): PreferenceFragmentCompat {
        return PreferenceHeader()
    }
}

  • Thêm chú giải tính chất rỗng vào các API mà trước đây không chỉ định @NonNull hoặc @Nullable. Đây có thể là một thay đổi có thể gây lỗi nguồn Kotlin nếu tính chất rỗng mà bạn chọn trong mã Kotlin không khớp với tính chất rỗng hiện đã được xác định.

  • Hiện PreferenceFragmentCompat đang tìm cách triển khai giao diện OnPreferenceStartFragmentCallback, OnNavigateToScreenListener và OnDisplayPreferenceDialogListener trên các mảnh mẹ trước khi xem liệu Ngữ cảnh (Context) hoặc Hoạt động (Activity) lưu trữ có triển khai các giao diện này hay không.

Phiên bản 1.2.0-rc01

Ngày 15 tháng 12 năm 2021

androidx.preference:preference:1.2.0-rc01 và androidx.preference:preference-ktx:1.2.0-rc01 được phát hành mà không có sự thay đổi nào so với phiên bản 1.2.0-beta01. Phiên bản 1.2.0-rc01 chứa những thay đổi sau.

Phiên bản 1.2.0-beta01

Ngày 17 tháng 11 năm 2021

androidx.preference:preference:1.2.0-beta01 và androidx.preference:preference-ktx:1.2.0-beta01 được phát hành mà không có thay đổi nào trong Preference 1.2.0-alpha02. Phiên bản 1.2.0-beta01 chứa những thay đổi sau.

Phiên bản 1.2.0-alpha02

Ngày 3 tháng 11 năm 2021

Phát hành androidx.preference:preference:1.2.0-alpha02 và androidx.preference:preference-ktx:1.2.0-alpha02. Phiên bản 1.2.0-alpha02 bao gồm các thay đổi sau.

Những thay đổi về API

  • Thêm chú giải tính chất rỗng vào các API mà trước đây không chỉ định @NonNull hoặc @Nullable. (I04252, Ie2cc0)
  • Xoá API openPreference() khỏi PreferenceHeaderFragmentCompat – phương thức này được gọi cho bạn và bạn không nên gọi phương thức này theo cách thủ công. (Ia6989)

Các thay đổi về hành vi

  • Các hàm gọi lại (callback) PreferenceFragmentCompat cho OnNavigateToScreenListener và OnDisplayPreferenceDialogListener hiện sẽ tuân theo mẫu giống như OnPreferenceTreeClickListener và tìm kiếm hệ phân cấp mảnh mẹ cho các trình nghe hợp lệ trước khi xem xét liệu Ngữ cảnh hoặc Hoạt động lưu trữ có triển khai các giao diện này hay không. (I7ae6c)

Phiên bản 1.2.0-alpha01

Ngày 27 tháng 10 năm 2021

Phát hành androidx.preference:preference:1.2.0-alpha01 và androidx.preference:preference-ktx:1.2.0-alpha01. Phiên bản 1.2.0-alpha01 bao gồm các thay đổi sau.

Tính năng mới

  • Thêm PreferenceHeaderFragmentCompat cho tuỳ chọn hai ngăn (I9a2d8)

Các thay đổi về hành vi

  • Hiện tại, bạn có thể triển khai các hàm gọi lại Preference cho OnPreferencesDisplayDialogCallback, OnPreferencesStartScreenCallback và OnPreferencesStartFragmentCallback trong Ngữ cảnh không có Hoạt động. getContext() sẽ được kiểm tra để xem liệu phương thức này có triển khai các lệnh gọi lại trên trước khi kiểm tra getActivity(). Nếu getContext() trả về một Hoạt động (trường hợp phổ biến) thì sẽ không có hành vi nào thay đổi.

  • Lệnh gọi đến onPreferenceTreeClick của PreferenceFragmentCompat hiện tìm kiếm cách triển khai giao diện OnPreferenceStartFragmentCallback trên các mảnh mẹ trước khi xem xét triển khai Hoạt động. (c64eed)

Phiên bản 1.1

Phiên bản 1.1.1

Ngày 15 tháng 4 năm 2020

Phát hành androidx.preference:preference:1.1.1 và androidx.preference:preference-ktx:1.1.1. Phiên bản 1.1.1 bao gồm các thay đổi sau.

Sửa lỗi

  • PreferenceDialogFragmentCompat sẽ không còn gửi IllegalStateException khi tăng cường FragmentContainerView trong xml. (b/150051716)

Cập nhật phần phụ thuộc

  • Preference hiện phụ thuộc vào Fragment 1.2.4. (aosp/1277317)
  • Phần phụ thuộc preference-ktx hiện phụ thuộc vào androidx.core:core-ktx:1.1.0 và androidx.fragment:fragment-ktx:1.2.4, sao chép các phần phụ thuộc của cấu phần phần mềm preference chính và đảm bảo rằng việc nâng cấp preference-ktx sẽ cập nhật cả cấu phần phần mềm chính và -ktx cấu phần phần mềm của phần phụ thuộc bắc cầu. (aosp/1277319)

Phiên bản 1.1.0

Ngày 5 tháng 9 năm 2019

Phát hành androidx.preference:preference:1.1.0 và androidx.preference:preference-ktx:1.1.0. Bạn có thể xem các thay đổi trong phiên bản này tại đây.

Nếu đây là bản phát hành 1.1.* đầu tiên bạn cập nhật thì sau đây là danh sách tóm tắt những thay đổi lớn kể từ bản phát hành ổn định cuối cùng, 1.0.0. Các bài viết Hướng dẫn cài đặt, ứng dụng mẫu và buổi trò chuyện trên Hội nghị Nhà phát triển Android cũng sẽ có thể có ích với bạn.

Những thay đổi quan trọng kể từ phiên bản 1.0.0

  • PreferenceFragment và các lớp khác sử dụng mảnh khung đã ngừng hoạt động; thay vào đó, bạn nên sử dụng PreferenceFragmentCompat và các lớp *compat khác.
  • Giờ đây, bạn có thể thiết lập SummaryProvider trên Preference để định cấu hình cho tuỳ chọn một cách linh động mỗi khi Preference được cập nhật hoặc hiển thị cho người dùng. Hãy xem hướng dẫn để biết thêm thông tin.
  • Thêm giao diện EditTextPreference.OnBindEditTextListener. Tính năng này cho phép tuỳ chỉnh EditText hiển thị trong hộp thoại tương ứng sau khi đã liên kết hộp thoại. Đây là tính năng thay thế trực tiếp cho việc sử dụng các thuộc tính như android:inputType trực tiếp trên EditTextPreference, do thao tác này không được hỗ trợ trong thư viện AndroidX. Hãy xem hướng dẫn để biết thêm thông tin.
  • Thêm Preference.setCopyingEnabled(). Khi thiết lập, nếu nhấn và giữ Preference, bạn sẽ thấy một trình đơn theo bối cảnh cho phép sao chép phần tóm tắt của thư viện này.
  • Cập nhật thiết kế SeekBarPreference để khớp với thông số kỹ thuật của Material. Hãy xem changelog chi tiết để tìm hiểu những thay đổi khác đối với SeekBarPreference.
  • Một số lượng lớn các bản sửa lỗi, bản cập nhật thiết kế (style updates), bản sửa lỗi khả năng tương thích cấp độ API và các điểm cải thiện chung về QOL.

Phiên bản 1.1.0-rc01

Ngày 2 tháng 7 năm 2019

Phát hành androidx.preference:preference:1.1.0-rc01 và androidx.preference:preference-ktx:1.1.0-rc01. Bạn có thể xem các thay đổi trong phiên bản này tại đây.

Những thay đổi về API

  • Không dùng Preference#onInitializeAccessibilityNodeInfo nữa
  • Phương thức này đã xử lý thông tin nút hỗ trợ tiếp cận cho một Preference cụ thể. Tuy nhiên, đây là lớp không phù hợp cho chế độ tuỳ chỉnh này. Nếu muốn điều chỉnh thông tin về hỗ trợ tiếp cận, bạn nên ghi đè onBindViewHolder và bổ sung trực tiếp thông tin hỗ trợ tiếp cận vào khung nhìn.

Phiên bản 1.1.0-beta01

Ngày 5 tháng 6 năm 2019

Phát hành androidx.preference:preference:1.1.0-beta01 và androidx.preference:preference-ktx:1.1.0-beta01. Bạn có thể xem các thay đổi trong phiên bản này tại đây.

Những thay đổi quan trọng kể từ phiên bản 1.1.0

Nếu đây là bản phát hành 1.1* đầu tiên bạn cập nhật thì sau đây là danh sách tóm tắt những thay đổi lớn kể từ bản phát hành ổn định cuối cùng, 1.1.0. Các bài viết Hướng dẫn cài đặt, ứng dụng mẫu và buổi trò chuyện trên Hội nghị Nhà phát triển Android cũng sẽ có thể có ích với bạn.

  • PreferenceFragment và các lớp khác sử dụng mảnh khung đã ngừng hoạt động - thay vào đó, bạn nên sử dụng lớp PreferenceFragmentCompat và các lớp *compat khác.
  • Giờ đây, bạn có thể thiết lập SummaryProvider trên một lớp Preference để định cấu hình phần tóm tắt một cách linh động mỗi khi cập nhật hoặc hiển thị lớp này cho người dùng. Hãy xem hướng dẫn để biết thêm thông tin.
  • Thêm giao diện EditTextPreference.OnBindEditTextListener. Tính năng này cho phép tuỳ chỉnh EditText được hiển thị trong hộp thoại tương ứng sau khi liên kết. Đây là tính năng trực tiếp thay thế cho việc sử dụng các thuộc tính như android:inputType ngay trên EditTextPreference, do thao tác này không được hỗ trợ trong thư viện AndroidX. Hãy xem hướng dẫn để biết thêm thông tin.
  • Thêm Preference.setCopyingEnabled(). Khi thiết lập, nếu nhấn và giữ Preference, bạn sẽ thấy một trình đơn theo bối cảnh cho phép sao chép phần tóm tắt của thư viện này.
  • Cập nhật thiết kế SeekBarPreferences để khớp với thông số của Material. Hãy xem changelog chi tiết để biết các thay đổi khác về SeekBarPreferences.
  • Một số lượng lớn các bản sửa lỗi, bản cập nhật thiết kế (style updates), bản sửa lỗi khả năng tương thích cấp độ API và các điểm cải thiện chung về QOL.

Những thay đổi về API kể từ phiên bản 1.1.0-alpha05

  • Xoá getOnBindEditTextListener khỏi API công khai, bạn chỉ cần sử dụng setOnBindEditTextListener khi tương tác với API này.

Vui lòng báo cáo lỗi tại đây nếu bạn gặp phải bất kỳ vấn đề nào hoặc có đề xuất về các tính năng mới!

Phiên bản 1.1.0-alpha05

Ngày 7 tháng 5 năm 2019

Phát hành androidx.preference:preference:1.1.0-alpha05 và androidx.preference:preference-ktx:1.1.0-alpha05. Bạn có thể xem các thay đổi trong phiên bản này tại đây.

Tính năng mới

  • Cập nhật thiết kế cho các lớp Preference không thể chọn – tiêu đề và tóm tắt hiện có cùng màu để nhấn mạnh rằng các lớp này không thể tương tác và chỉ dùng để hiển thị thông tin.
  • Lưu ý: nên cân nhắc thêm enableCopying="true" vào các lớp Preference không thể chọn để bạn có thể nhấn và giữ nhằm sao chép thông tin tóm tắt.

Sửa lỗi

  • Sửa một hồi quy trong đó PreferenceCategory và các lớp Preference không thể chọn khác sẽ có hiệu ứng gợn sóng khi được chọn
  • Sửa sự cố hỗ trợ tiếp cận TalkBack không nhận thấy rằng có thể nhấp DropDownPreference
  • Sửa một số vấn đề bố cục RTL
  • Cập nhật một số chú giải tính chất rỗng trong PreferenceFragmentCompat để khớp với Fragment

Phiên bản 1.1.0-alpha04

Ngày 13 tháng 3 năm 2019

Phát hành androidx.preference:preference:1.1.0-alpha04 và androidx.preference:preference-ktx:1.1.0-alpha04. Bạn có thể xem danh sách đầy đủ những thay đổi trong phiên bản này tại đây.

Tính năng mới

Thông tin cập nhật về SeekBarPreference!

  • Cập nhật thiết kế để khớp với Thông số kỹ thuật của Material
    • Nhãn giá trị hiện bị ẩn theo mặc định mặc dù vẫn có thể hiển thị bằng app:showSeekBarValue="true" hoặc setShowSeekBarValue(true). Nhãn này tuy không nằm trong thông số kỹ thuật của Material nhưng được dùng rất nhiều. Do đó, dù bạn không nên sử dụng, chúng tôi vẫn sẽ tiếp tục hỗ trợ.
    • Nhãn giá trị giờ đây sẽ được cập nhật trong khi thanh dịch chuyển đang được kéo, thay vì khi được thả. Lưu ý rằng điều này không có nghĩa giá trị nội bộ sẽ được cập nhật. Hãy xem phần dưới để tìm hiểu thêm về API mới hỗ trợ chức năng đó.
    • Lưu ý: Mặc dù được hỗ trợ, bạn nên tránh thiết lập tóm tắt về SeekBarPreference vì phần này không được áp dụng và không thuộc thông số kỹ thuật của Material.
  • Hỗ trợ thêm các bản cập nhật liên tục, cho phép SeekBar cập nhật giá trị đã lưu trong khi bị kéo. Bạn có thể bật tính năng này trong XML hoặc theo phương thức lập trình bằng app:updatesContinuously="true" hoặc setUpdatesContinuously(true). Tính năng này sẽ kích hoạt bất cứ khi nào vị trí của SeekBar thay đổi trên màn hình.

Những thay đổi về API

  • Thêm chú giải tính chất rỗng còn thiếu vào findPreference()

Sửa lỗi

  • Sửa lỗi trình nghe trình đơn theo bối cảnh không được xoá một cách chính xác nếu không bật tính năng sao chép

Phiên bản 1.1.0-alpha03

Ngày 7 tháng 2 năm 2019

androidx.preference:preference 1.1.0-alpha03

Phát hành androidx.preference:preference 1.1.0-alpha03 và androidx.preference:preference-ktx 1.1.0-alpha03 cùng các thay đổi sau.

Sửa lỗi

  • Khắc phục vấn đề cửa sổ bật lên sao chép/dán đôi khi không hiển thị trong hộp thoại của EditTextPreference
  • Khắc phục vấn đề trình chuyển đổi cơ bản không được đăng ký theo đúng quy trình, gây rò rỉ bộ nhớ trong nhiều trường hợp cụ thể (b/121006469)
  • Khắc phục một số sự cố liên quan đến hộp thoại xuất hiện trong khi thay đổi cấu hình (b/122167543)
  • Khắc phục lỗi SummaryProvider không hoạt động cùng lớp MultiSelectListPreference (b/123022772)

Phiên bản 1.1.0-alpha02

Ngày 17 tháng 12 năm 2018

Vui lòng tham khảo Hướng dẫn cài đặt và ứng dụng mẫu mới cập nhật.

Tính năng mới

  • Thêm giao diện EditTextPreference.OnBindEditTextListener cho phép bạn tuỳ chỉnh hiển thị trong hộp thoại tương ứng sau khi liên kết. Ví dụ: tuỳ chỉnh thiết lập loại / độ dài đầu vào hoặc thêm TextWatcher.

  • Thêm Preference.setCopyingEnabled(). Khi thiết lập, nếu nhấn và giữ Preference, bạn sẽ thấy một trình đơn theo bối cảnh cho phép sao chép phần tóm tắt của thư viện này. Cách này có thể dùng để cho phép sao chép thông tin tĩnh (chẳng hạn như giá trị nhận dạng cụ thể của người dùng / thông tin về phiên bản ứng dụng).

  • preferenceTheme hiện đang áp dụng cho các giao diện hoạt động Thay đổi này có nghĩa khi tạo một lớp Preference từ mã, bạn không cần sử dụng ngữ cảnh trong PreferenceManager#getContext() mà chỉ cần dùng ngữ cảnh Mảnh/Hoạt động.

Những thay đổi về API

  • Tạo lại findPreference() để trả về <T extends Preference> Điều này có nghĩa bạn không cần phải truyền các lớp Preference một cách rõ ràng khi sử dụng FindPreferences(). Ví dụ: EditTextPreference preference = findPreference(“edit_text”) hiện là mã hợp lệ.

Phiên bản 1.1.0-alpha01

Ngày 5 tháng 11 năm 2018

Tính năng mới

  • Giờ đây, bạn có thể thiết lập SummaryProvider trên một lớp Preference để định cấu hình phần tóm tắt một cách linh động mỗi khi cập nhật hoặc hiển thị lớp này cho người dùng.
  • Thêm tính năng triển khai mặc định SummaryProvider cho ListPreference và EditTextPreference. Khi bạn thiết lập, tính năng này sẽ tự động cập nhật tóm tắt của Preference nhằm phản ánh giá trị đã lưu hoặc "Not Set" (Chưa thiết lập) nếu chưa có giá trị nào được lưu. Bạn có thể thiết lập các tính năng này bằng app:useSimpleSummarizeProvider=”true”
  • Thêm PreferenceGroup#removePreferencesCallbacks theo định kỳ sẽ tìm và loại bỏ một lớp Preference khỏi nhóm hoặc một nhóm lồng ở bên dưới hệ thống phân cấp.

Những thay đổi về API

  • PreferenceFragment và các lớp khác sử dụng mảnh khung đã ngừng hoạt động – thay vào đó, bạn nên sử dụng lớp PreferenceFragmentCompat và các lớp *compat khác.

Sửa lỗi

  • Sửa lỗi iconSpaceReserved không hoạt động với PreferenceCategories một cách chính xác
  • Sửa lỗi PreferenceCategories không sử dụng colorAccent cho màu của tiêu đề dưới API 21.
  • Khắc phục một số điểm không nhất quán về bố cục của SeekBarPreference dưới API 21.