DataStore

Lưu trữ dữ liệu một cách không đồng bộ, nhất quán và có thể chia sẻ, khắc phục một số hạn chế của SharedPreferences
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 4 tháng 8 năm 2021 1.0.0 - - -

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

Để thêm phần phụ thuộc trên DataStore, 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.

Có hai cách triển khai DataStore: Preferences và Proto. Hãy chọn một trong hai. Bạn cũng có thể thêm các phần phụ thuộc ngoài Android để triển khai.

Thêm các phần phụ thuộc cần thiết để triển khai trong tệp build.gradle cho ứng dụng hoặc mô-đun:

Preferences DataStore

Groovy

    // Preferences DataStore (SharedPreferences like APIs)
    dependencies {
        implementation "androidx.datastore:datastore-preferences:1.0.0"

        // optional - RxJava2 support
        implementation "androidx.datastore:datastore-preferences-rxjava2:1.0.0"

        // optional - RxJava3 support
        implementation "androidx.datastore:datastore-preferences-rxjava3:1.0.0"
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation "androidx.datastore:datastore-preferences-core:1.0.0"
    }
    

Kotlin

    // Preferences DataStore (SharedPreferences like APIs)
    dependencies {
        implementation("androidx.datastore:datastore-preferences:1.0.0")

        // optional - RxJava2 support
        implementation("androidx.datastore:datastore-preferences-rxjava2:1.0.0")

        // optional - RxJava3 support
        implementation("androidx.datastore:datastore-preferences-rxjava3:1.0.0")
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation("androidx.datastore:datastore-preferences-core:1.0.0")
    }
    

Proto DataStore

Groovy

    // Typed DataStore (Typed API surface, such as Proto)
    dependencies {
        implementation "androidx.datastore:datastore:1.0.0"

        // optional - RxJava2 support
        implementation "androidx.datastore:datastore-rxjava2:1.0.0"

        // optional - RxJava3 support
        implementation "androidx.datastore:datastore-rxjava3:1.0.0"
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation "androidx.datastore:datastore-core:1.0.0"
    }
    

Kotlin

    // Typed DataStore (Typed API surface, such as Proto)
    dependencies {
        implementation("androidx.datastore:datastore:1.0.0")

        // optional - RxJava2 support
        implementation("androidx.datastore:datastore-rxjava2:1.0.0")

        // optional - RxJava3 support
        implementation("androidx.datastore:datastore-rxjava3:1.0.0")
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation("androidx.datastore:datastore-core:1.0.0")
    }
    

Phản hồi

Phản hồi của bạn giúp 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 qua 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ể bình chọn một lỗi hiện có bằng cách nhấp vào dấu sao.

Báo lỗi mới

Hãy 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.0.0

Phiên bản 1.0.0

Ngày 4 tháng 8 năm 2021

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

Các tính năng chính của phiên bản 1.0.0

Jetpack DataStore là một giải pháp lưu trữ dữ liệu cho phép lưu trữ các cặp khoá-giá trị hoặc đối tượng đã nhập có vùng đệm giao thức. DataStore sử dụng coroutine Kotlin và Flow để lưu trữ dữ liệu một cách không đồng bộ, nhất quán và có thể chia sẻ.

Phiên bản 1.0.0-rc02

Ngày 21 tháng 7 năm 2021

Phát hành androidx.datastore:datastore-*:1.0.0-rc02. Phiên bản 1.0.0-rc02 bao gồm các thay đổi sau.

Bản sửa lỗi

  • Làm rõ rằng SharedPreferencesMigration không chạy nếu không có khoá. (Icfa32, b/192824325)
  • Sửa lỗi SharedPreferencesMigration được tạo bằng MIGRATE_ALL_KEYS sẽ xảy ra ngoại lệ nếu khoá yêu cầu chưa tồn tại. (Ie318a, b/192824325)

Phiên bản 1.0.0-rc01

Ngày 30 tháng 6 năm 2021

Phát hành androidx.datastore:datastore-*:1.0.0-rc01. Phiên bản 1.0.0-rc01 bao gồm các thay đổi sau.

Bản sửa lỗi

  • Khắc phục lỗi tệp .gtm vô tình được thêm vào tệp jar cuối cùng (I65d96, b/188985637)

Phiên bản 1.0.0-beta02

Ngày 16 tháng 6 năm 2021

Phát hành androidx.datastore:datastore-*:1.0.0-beta02. Phiên bản 1.0.0-beta02 bao gồm các thay đổi sau.

Bản sửa lỗi

Phiên bản 1.0.0-beta01

Ngày 21 tháng 4 năm 2021

Phát hành androidx.datastore:datastore-*:1.0.0-beta01. Phiên bản 1.0.0-beta01 bao gồm các thay đổi sau.

Thay đổi API

  • Bỏ JvmOverloads trong các phương thức của kotlin (I2adc7)

Bản sửa lỗi

  • Khắc phục lỗi việc uỷ quyền Datastore có thể dẫn đến việc rò rỉ ngữ cảnh (Ie96fc, b/184415662)

Phiên bản 1.0.0-alpha08

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

Phát hành androidx.datastore:datastore-*:1.0.0-alpha08. Phiên bản 1.0.0-alpha08 bao gồm các thay đổi sau.

Thay đổi API

  • Giờ đây, bạn có thể thêm quá trình dịch chuyển tuỳ thuộc vào context của dataStore và thuộc tính preferencesDataStore. (I4ef69, b/173726702)
  • Thêm các chức năng trợ giúp để lấy tên tệp nếu bạn không còn sử dụng Delegate của DataStore hoặc context.createDataStore (I60f9a)
  • Tạm ngưng trình chuyển đổi tuần tự (Serializer) writeTo và readFrom. Nếu đã triển khai một trình chuyển đổi tuần tự, bạn cần phải cập nhật hàm thành các hàm tạm ngưng (suspend). (I1e58e)
  • Thêm thuộc tính delegate cho người dùng RxDataStore. (Ied768, b/173726702)

Bản sửa lỗi

Phiên bản 1.0.0-alpha07

Ngày 24 tháng 2 năm 2021

Phát hành androidx.datastore:datastore-*:1.0.0-alpha07. Phiên bản 1.0.0-alpha07 bao gồm các thay đổi sau.

Thay đổi API

  • Hàm mở rộng Context.createDataStore đã bị xoá và được thay thế bằng thuộc tính delegate GlobalDataStore. Gọi GlobalDataStore một lần ở cấp cao nhất trong tệp kotlin. Ví dụ:

    val Context.myDataStore by dataStore(...)
    

    Đặt phần này ở cấp cao nhất của tệp kotlin để chỉ có một thực thể duy nhất của tệp. (I57215, b/173726702)

  • Các hàm RxDataStore hiện đã có trên một lớp RxDataStore thay vì các hàm mở rộng trên DataStore. (Idccdb, b/177691248)

  • Nếu muốn dịch chuyển EncryptedSharedPreferences (hoặc khởi động trực tiếp SharedPreferences) sang DataStore thì giờ bạn có thể làm việc đó bằng hàm khởi tạo (constructor) SharedPreferencesPreferences mới. Hàm khởi tạo cho phép bạn chèn SharedPreferences. (I8e04e, b/177278510)

Bản sửa lỗi

  • DataStore hiện sẽ khai báo trường hợp ngoại lệ nếu có nhiều DataStore đang hoạt động trong cùng một tệp. Nếu lúc trước bạn không quản lý DataStore dưới dạng Singleton hoặc không đảm bảo rằng không có hai thực thể DataStore nào đang hoạt động đồng thời trong cùng một tệp, thì giờ đây bạn có thể nhận biết các trường hợp ngoại lệ khi đọc hoặc ghi vào DataStore. Bạn có thể khắc phục các lỗi này bằng cách quản lý DataStore dưới dạng Singleton. (Ib43f4, b/177691248)
  • Khắc phục hành vi hủy khi huỷ phạm vi phương thức gọi. (I2c7b3)

Phiên bản 1.0.0-alpha06

Ngày 13 tháng 1 năm 2021

Phát hành androidx.datastore:datastore-*:1.0.0-alpha06. Phiên bản 1.0.0-alpha06 bao gồm các thay đổi sau.

Tính năng mới

  • Thêm trình bao bọc RxJava cho DataStore. Cấu phần phần mềm datastore-rxjava2/3 chứa trình bao bọc cho API DataStore chính (RxDataStore, RxDataStoreBuilder, và RxDataMigration). Các cấu phần phần mềm datastore-preferences-rxjava2/3 chứa một trình dựngđể tạo một DataStore Preferences.

Thay đổi API

  • Ẩn giao diện CorruptionHandler. Không có lý do để công khai nội dung này vì nhà máy (factory) DataStore chỉ chấp nhận một tham số ChangeFileCorruptionHandler. (I0b3b3, b/176032264)
  • Phương thức preferencesKey<T>(name: String): Key<T> đã bị xoá và thay thế bằng các phương thức cụ thể cho từng loại API được hỗ trợ, ví dụ: preferencesKey<Int>("int") hiện là intPreferencesKey("int") (Ibcfac, b/170311106)

Bản sửa lỗi

  • Chỉnh sửa tài liệu trên nhà máy DataStore mà trước đó không đề cập đến việc tệp DataStore được tạo trong thư mục con “datastore/”. (Ica222)

Phiên bản 1.0.0-alpha05

Ngày 2 tháng 12 năm 2020

Phát hành androidx.datastore:datastore-*:1.0.0-alpha05. Phiên bản 1.0.0-alpha05 bao gồm các thay đổi sau.

Bản sửa lỗi

  • Thêm các tài liệu và trường hợp ngoại lệ tốt hơn về cách ghi đồng thời từ các DataStore. (Ia98a2, b/173522155, b/173726702)
  • Hiện tại, chúng tôi cho phép (nhưng không yêu cầu) đóng OutputStream được truyền vào Serializer.writeTo(). (I5c9bf, b/173037611)

Phiên bản 1.0.0-alpha04

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

Phát hành androidx.datastore:datastore-*:1.0.0-alpha04. Phiên bản 1.0.0-alpha04 bao gồm các thay đổi sau.

Bản sửa lỗi

  • Khắc phục vấn đề khi đóng gói gây ra sự cố sau đây trong DataStore Preference 1.0.0-alpha03: java.lang.NoClassDefFoundError: Failed resolution of: Landroidx/datastore/preferences

Phiên bản 1.0.0-alpha03

Ngày 11 tháng 11 năm 2020

Phát hành androidx.datastore:datastore-*:1.0.0-alpha03. Phiên bản 1.0.0-alpha03 bao gồm các thay đổi sau.

Tính năng mới

  • DataStore Preference hiện hỗ trợ truyền hai giá trị (hữu ích nếu bạn cần độ chính xác cao hơn kiểu dữ liệu float) (I5be8f, b/169471808)

Thay đổi API

  • Đã tạo ra một phần phụ thuộc Kotlin thuần tuý cho DataStore để biên dịch nhanh hơn. androidx.datastore:datastore-core chỉ chứa các API kotlin chính và androidx.datastore:datastore chứa các API phụ thuộc vào Android (bao gồm SharedPreferencesMigration và hạm khởi tạo Context.createDataStore.)(I42d75, b/168512698)
  • Chia nhỏ các mục tiêu cho DataStore preference để biên dịch kotlin nhanh hơn (Ia3c19)
  • Serializer cần một thuộc tính mới cho giá trị mặc định mà sẽ được sử dụng nếu không có dữ liệu trên đĩa. Nhờ đó, bạn có thể dễ dàng triển khai các serializer tuỳ chỉnh hơn để người dùng không phải đánh dấu các inputstream rỗng (inputstream rỗng không được parse bằng json).

    • Ngoài ra, hiện có một bước kiểm tra để xác nhận luồng đầu ra được gửi đến writeTo() không bị đóng và nếu bị đóng thì sẽ xảy ra ngoại lệ (I16e29)
  • Đưa hàm khởi tạo cho SharedPreferencesView thành hàm nội bộ. Ban đầu, hàm khởi tạo được công khai để cho phép thử nghiệm. Thay vào đó, các lần kiểm thử phải tạo SharedPreferencesPreferences và thử nghiệm dựa vào đó. (I93891)

Bản sửa lỗi

  • Tham số produceFile trên DataStoreFactoryPreferenceDataStoreFactory hiện là tham số cuối cùng trong danh sách, nhờ đó bạn có thể sử dụng cú pháp có lambda ở cuối. (Ibe7f1, b/169425442)
  • Tuân thủ các yêu cầu mới về API tường minh trong kotlin (I5ae1e)

Các lỗi đã biết

  • DataStore Preference gặp sự cố với java.lang.NoClassDefFoundError. (b/173036843)

Phiên bản 1.0.0-alpha02

Ngày 14 tháng 10 năm 2020

Phát hành androidx.datastore:datastore-core:1.0.0-alpha02androidx.datastore:datastore-preferences:1.0.0-alpha02. Phiên bản 1.0.0-alpha02 bao gồm các thay đổi sau.

Bản sửa lỗi

  • Thêm biện pháp bảo vệ phòng trường hợp đột biến (mutation) trong datastore-core. Tình trạng đột biến làm gián đoạn việc sử dụng DataStore đối với những người sử dụng DataStore không thuộc loại proto/preference(I6aa84)
  • Thêm phương thức toString vào Preferences.kt để dễ dàng gỡ lỗi trạng thái hiện tại (I96006)
  • Thêm một ngoại lệ để bảo vệ trong trường hợp sử dụng sai DataStore.Preferences (I1134d)
  • Khắc phục lỗi khiến ứng dụng ngừng hoạt động và thoát khi khởi động (I69237, b/168580258)

Phiên bản 1.0.0-alpha01

Ngày 2 tháng 9 năm 2020

Phát hành androidx.datastore:datastore-core:1.0.0-alpha01androidx.datastore:datastore-preferences:1.0.0-alpha01. Phiên bản 1.0.0-alpha01 bao gồm các thay đổi sau.

Tính năng mới

Jetpack DataStore là một giải pháp lưu trữ dữ liệu mới và cải tiến nhằm thay thế SharedPreferences. DataStore được xây dựng dựa trên Kotlin coroutine và Kotlin flow, và có hai cách triển khai khác nhau:

  • DataStore Proto cho phép bạn lưu trữ object đã nhập (được hỗ trợ bởi bộ đệm giao thức)
  • DataStore Preference lưu trữ các cặp khoá-giá trị

Dữ liệu được lưu trữ không đồng bộ, nhất quán và có thể chia sẻ, khắc phục hầu hết các hạn chế của SharedPreferences.