DocumentProvider — nó là gì, tạo nhà cung cấp và làm việc với tệp

DocumentProvider là gì?

DocumentsProvider là một lớp cơ sở Android mở rộng ContentProvider, cho phép ứng dụng cung cấp tệp của mình cho các ứng dụng khác thông qua giao diện SAF hệ thống. Nhà cung cấp tạo một hệ thống tệp ảo mà người dùng nhìn thấy trong hộp thoại chọn tài liệu.

Mỗi nhà cung cấp tổ chức tệp thành các gốc (roots) — các điểm vào cấp cao nhất. Ví dụ: Google Drive có các gốc “Drive của tôi” và “Đã chia sẻ với tôi.” Trong một gốc, nhà cung cấp trả về một cây tài liệu, trong đó mỗi tài liệu là một tệp hoặc thư mục với loại MIME, kích thước và ngày tháng cụ thể.

DocumentProvider là một phần của gói android.provider và có sẵn từ Android 4.4 (API 19). Nhà cung cấp được sử dụng bởi các dịch vụ đám mây, trình quản lý mật khẩu, ứng dụng ghi chú và bất kỳ chương trình nào lưu trữ tệp ở định dạng riêng của chúng.

Cách tạo DocumentProvider tùy chỉnh

Tạo DocumentProvider của riêng bạn bắt đầu bằng cách mở rộng lớp DocumentsProvider và triển khai bốn phương thức bắt buộc. Nhà cung cấp xác định cấu trúc tệp xuất hiện trong bộ chọn SAF hệ thống khi chọn tệp.

Phương thức đầu tiên là queryRoots, trả về một con trỏ với các cột Root.COLUMN_ROOT_ID, Root.COLUMN_TITLE, Root.COLUMN_SUMMARY và Root.COLUMN_FLAGS. Mỗi gốc có thể hỗ trợ các cờ: FLAG_SUPPORTS_CREATE, FLAG_SUPPORTS_SEARCH và FLAG_SUPPORTS_IS_CHILD.

Phương thức bắt buộc thứ hai là queryChildDocuments, trả về các tài liệu con của một URI được chỉ định. Phương thức này được gọi khi người dùng mở một thư mục trong bộ chọn. Mỗi tài liệu chứa các cột: Document.COLUMN_DOCUMENT_ID, COLUMN_DISPLAY_NAME, COLUMN_MIME_TYPE, COLUMN_SIZE và COLUMN_LAST_MODIFIED.

Các phương thức bắt buộc của DocumentsProvider

DocumentsProvider yêu cầu triển khai bốn phương thức tạo thành cấu trúc tệp cho bộ chọn. Nếu thiếu chúng, nhà cung cấp sẽ không hoạt động — hộp thoại SAF hệ thống sẽ không thể hiển thị tệp.

• queryRoots — trả về các điểm vào gốc đến bộ lưu trữ. Mỗi gốc được biểu diễn bằng một hàng trong con trỏ với ID, tên và biểu tượng.
• queryDocument — trả về một tài liệu duy nhất theo ID của nó. Được sử dụng để lấy thông tin về một tệp cụ thể.
• queryChildDocuments — trả về các tài liệu con cho URI thư mục cha được chỉ định.
• openDocument — mở một tài liệu theo ID và trả về ParcelFileDescriptor để đọc hoặc ghi.

Ngoài ra, bạn có thể triển khai createDocument để tạo tệp mới, deleteDocument để xóa và renameDocument để đổi tên. Các phương thức này yêu cầu cờ FLAG_SUPPORTS_CREATE trong gốc.

Đăng ký nhà cung cấp trong AndroidManifest

DocumentProvider được đăng ký trong AndroidManifest.xml như một ContentProvider thông thường với bộ lọc intent và cờ bổ sung. Nhà cung cấp phải được bảo vệ khỏi truy cập trực tiếp thông qua quyền — nên sử dụng android:exported="true" với quyền rõ ràng.

<provider
    android:name=".provider.CustomDocumentProvider"
    android:authorities="com.example.app.documents"
    android:exported="true"
    android:grantUriPermissions="true"
    android:permission="android.permission.MANAGE_DOCUMENTS">
    <intent-filter>
        <action
            android:name="android.content.action.DOCUMENTS_PROVIDER" />
    </intent-filter>
    <meta-data
        android:name="android.content.documents.roots"
        android:resource="@xml/file_paths" />
</provider>

Cờ grantUriPermissions cho phép SAF tạm thời ủy quyền truy cập cho ứng dụng gọi. Thuộc tính authorities phải là duy nhất — thường sử dụng tên gói với hậu tố .documents. Cũng nên chỉ định siêu dữ liệu với tài nguyên XML để cấu hình các gốc.

Ví dụ mã: triển khai DocumentsProvider

Triển khai DocumentsProvider yêu cầu trả về ParcelFileDescriptor từ phương thức openDocument. Đối với tệp cục bộ, sử dụng ParcelFileDescriptor.open, đối với tệp đám mây — ParcelFileDescriptor.open với Pipe để truyền phát. Mã phải xử lý lỗi truy cập và tệp bị thiếu.

class CustomDocumentProvider : DocumentsProvider() {

    override fun queryRoots(): Cursor {
        val matrix = MatrixCursor(Root.COLUMNS)
        matrix.newRow().add(Root.COLUMN_ROOT_ID, "local")
            .add(Root.COLUMN_TITLE, "My Files")
            .add(Root.COLUMN_SUMMARY, "Local documents")
            .add(Root.COLUMN_FLAGS, Root.FLAG_SUPPORTS_CREATE)
        return matrix
    }

    override fun openDocument(
        documentId: String, flags: Int, cursor: CancellationSignal?
    ): ParcelFileDescriptor {
        val file = File(context.filesDir, documentId)
        val accessMode = ParcelFileDescriptor.parseMode(flags)
        return ParcelFileDescriptor.open(file, accessMode)
    }
}

Xử lý tài liệu ảo

DocumentProvider có thể trả về tệp ảo — các tài liệu không tồn tại dưới dạng tệp riêng biệt trên đĩa. Ví dụ: một ghi chú cơ sở dữ liệu có thể được trình bày dưới dạng PDF ảo. Điều này sử dụng loại MIME với cờ FLAG_VIRTUAL_DOCUMENT và openDocument chuyển đổi dữ liệu sang định dạng được yêu cầu trước khi gửi.

DocumentProvider trong iOS: UIDocumentPickerViewController

iOS có một cơ chế tương tự — UIDocumentPickerViewController, cũng cung cấp giao diện chọn tệp thống nhất. Tuy nhiên, trong iOS, nhà cung cấp tài liệu được triển khai thông qua UIDocumentPickerDelegate và Tiện ích mở rộng Ứng dụng (App Extensions) loại Document Provider.

Không giống như Android DocumentsProvider, iOS UIDocumentPickerViewController không yêu cầu tạo nhà cung cấp tùy chỉnh cho tệp cục bộ — bộ chọn hệ thống hỗ trợ iCloud Drive và bộ nhớ cục bộ theo mặc định. Các dịch vụ đám mây của bên thứ ba đăng ký thông qua tiện ích mở rộng Document Provider với khóa Info.plist NSExtensionFileProviderDocumentInterface.

Sự khác biệt chính: trong Android, DocumentProvider được gọi chủ động thông qua Intent SAF và phải tự triển khai điều hướng. Trong iOS, UIDocumentPickerViewController sử dụng trình duyệt tệp hệ thống tích hợp và nhà cung cấp tiện ích mở rộng chỉ chịu trách nhiệm cung cấp nội dung theo yêu cầu.