تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

الوصول إلى المستندات والملفات الأخرى من مساحة التخزين المشتركة

على الأجهزة التي تعمل بالإصدار 4.4 من نظام التشغيل Android (المستوى 19 لواجهة برمجة التطبيقات) والإصدارات الأحدث، يمكن لتطبيقك التفاعل مع موفِّر مستندات، بما في ذلك وحدات التخزين الخارجية والتخزين المستنِد إلى السحابة الإلكترونية، وذلك باستخدام إطار عمل الوصول إلى التخزين. يتيح إطار العمل هذا للمستخدمين التفاعل مع أداة اختيار النظام اختيار مزوِّد المستندات وتحديد مستندات معيّنة وملفات أخرى لإنشاء تطبيقك أو فتحه أو تعديله

بما أنّ المستخدم يشارك في اختيار الملفات أو الأدلة التي يمكن لتطبيقك الوصول إليها، لا تتطلّب هذه الآلية أي أذونات متعلقة بالنظام ، كما تُحسِّن من إمكانية التحكّم لدى المستخدم والخصوصية. بالإضافة إلى ذلك، يتم تخزين هذه الملفات خارج دليل التطبيق وخارجه، يظل على الجهاز بعد إلغاء تثبيت تطبيقك.

يتضمن استخدام الإطار العملي الخطوات التالية:

يستدعي أحد التطبيقات نية تحتوي على إجراء ذي صلة بمساحة التخزين. يتوافق هذا الإجراء مع حالة استخدام معيّنة يوفّرها الإطار العملي.
يرى المستخدم أداة اختيار النظام، ما يسمح له بتصفّح موفِّر المستندات. واختَر موقعًا أو وثيقة يمكن تنفيذ الإجراء المتعلق بالتخزين فيها.
يحصل التطبيق على إذن بالقراءة والكتابة في عنوان URL يمثّل الموقع الجغرافي أو المستند الذي اختاره المستخدم. باستخدام عنوان URI هذا، يمكن للتطبيق إجراء عمليات على للموقع الذي تم اختياره.

لإتاحة الوصول إلى ملفات الوسائط على الأجهزة التي تعمل بالإصدار 9 من Android (المستوى 28 من واجهة برمجة التطبيقات) أو الإصدارات الأقدم، يجب تقديم بيان بشأن إذن READ_EXTERNAL_STORAGE وضبط maxSdkVersion على 28.

يشرح هذا الدليل حالات الاستخدام المختلفة التي يدعمها إطار العمل. التعامل مع الملفات والمستندات الأخرى. كما يشرح كيفية إجراء العمليات في الموقع الذي يختاره المستخدم.

حالات استخدام الوصول إلى المستندات والملفات الأخرى

يتيح إطار عمل الوصول إلى مساحة التخزين حالات الاستخدام التالية للوصول إلى الملفات والمستندات الأخرى.

إنشاء ملف جديد: ACTION_CREATE_DOCUMENT إجراء intent للمستخدمين بحفظ ملف في موقع محدّد
فتح مستند أو ملف: يسمح إجراء القصد ACTION_OPEN_DOCUMENT للمستخدمين باختيار مستند أو ملف محدّد لفتحه.
منح إذن الوصول إلى محتوى دليل: ACTION_OPEN_DOCUMENT_TREE إنّ ميزة الإجراء intent، الذي يتوفر على Android 5.0 (المستوى 21 من واجهة برمجة التطبيقات) والإصدارات الأحدث، يسمح للمستخدمين واختيار دليل محدد، ومنح التطبيق إمكانية الوصول إلى جميع الملفات أو الأدلة الفرعية ضمن هذا الدليل.

تقدّم الأقسام التالية إرشادات حول كيفية ضبط كل حالة استخدام.

إنشاء ملف جديد

يمكنك استخدام ACTION_CREATE_DOCUMENT إجراء intent لتحميل منتقي ملفات النظام والسماح للمستخدم باختيار مكان كتابة محتويات الملف. هذه العملية مشابهة لتلك المستخدَمة في مربّعات الحوار "حفظ باسم" التي تستخدمها أنظمة التشغيل الأخرى.

ملاحظة: لا يمكن لـ ACTION_CREATE_DOCUMENT استبدال ملف حالي. إذا حاول تطبيقك حفظ ملف بالاسم نفسه، يمُدّ النظام الملف برقم بين قوسين في نهاية اسم الملف.

على سبيل المثال، إذا حاول تطبيقك حفظ ملف باسم confirmation.pdf في دليل يحتوي حاليًا على ملف يحفظ النظام الملف الجديد بالاسم confirmation(1).pdf

عند ضبط الغرض، يجب تحديد اسم الملف ونوع MIME بشكل اختياري، حدد معرف الموارد المنتظم (URI) الخاص بالملف أو الدليل الذي يجب أن يكون منتقي الملفات العرض عند تحميله لأول مرة باستخدام EXTRA_INITIAL_URI النية الإضافية.

يوضّح المقتطف البرمجي التالي كيفية إنشاء الهدف ل إنشاء ملف واستدعائه:

KotlinJava

// Request code for creating a PDF document.
const val CREATE_FILE = 1

private fun createFile(pickerInitialUri: Uri) {
    val intent = Intent(Intent.ACTION_CREATE_DOCUMENT).apply {
        addCategory(Intent.CATEGORY_OPENABLE)
        type = "application/pdf"
        putExtra(Intent.EXTRA_TITLE, "invoice.pdf")

        // Optionally, specify a URI for the directory that should be opened in
        // the system file picker before your app creates the document.
        putExtra(DocumentsContract.EXTRA_INITIAL_URI, pickerInitialUri)
    }
    startActivityForResult(intent, CREATE_FILE)
}

// Request code for creating a PDF document.
private static final int CREATE_FILE = 1;

private void createFile(Uri pickerInitialUri) {
    Intent intent = new Intent(Intent.ACTION_CREATE_DOCUMENT);
    intent.addCategory(Intent.CATEGORY_OPENABLE);
    intent.setType("application/pdf");
    intent.putExtra(Intent.EXTRA_TITLE, "invoice.pdf");

    // Optionally, specify a URI for the directory that should be opened in
    // the system file picker when your app creates the document.
    intent.putExtra(DocumentsContract.EXTRA_INITIAL_URI, pickerInitialUri);

    startActivityForResult(intent, CREATE_FILE);
}

فتح ملف

قد يستخدم تطبيقك المستندات كوحدة تخزين يُدخِل المستخدمون فيها بيانات قد يريدون مشاركتها مع المستخدمين الآخرين أو استيرادها إلى مستندات أخرى. متعددة مثل فتح مستخدم مستند إنتاجية أو فتح كتاب تم حفظه كملف EPUB.

في هذه الحالات، اسمح للمستخدم باختيار الملف المراد فتحه عن طريق استدعاء ACTION_OPEN_DOCUMENT intent، والذي يفتح تطبيق منتقي الملفات في النظام. لإظهار أنواع التي يدعمها تطبيقك، حدد نوع MIME. يمكنك أيضًا تحديد عنوان URI للملف الذي يجب أن يعرضه أداة اختيار الملفات عند تحميلها لأول مرة باستخدام العنصر EXTRA_INITIAL_URI intent extra.

يوضح مقتطف الرمز التالي كيفية إنشاء واستدعاء الغرض من الفتح مستند PDF:

KotlinJava

// Request code for selecting a PDF document.
const val PICK_PDF_FILE = 2

fun openFile(pickerInitialUri: Uri) {
    val intent = Intent(Intent.ACTION_OPEN_DOCUMENT).apply {
        addCategory(Intent.CATEGORY_OPENABLE)
        type = "application/pdf"

        // Optionally, specify a URI for the file that should appear in the
        // system file picker when it loads.
        putExtra(DocumentsContract.EXTRA_INITIAL_URI, pickerInitialUri)
    }

    startActivityForResult(intent, PICK_PDF_FILE)
}

// Request code for selecting a PDF document.
private static final int PICK_PDF_FILE = 2;

private void openFile(Uri pickerInitialUri) {
    Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
    intent.addCategory(Intent.CATEGORY_OPENABLE);
    intent.setType("application/pdf");

    // Optionally, specify a URI for the file that should appear in the
    // system file picker when it loads.
    intent.putExtra(DocumentsContract.EXTRA_INITIAL_URI, pickerInitialUri);

    startActivityForResult(intent, PICK_PDF_FILE);
}

قيود الوصول

في الإصدار 11 من نظام Android (المستوى 30 لواجهة برمجة التطبيقات) والإصدارات الأحدث، لا يمكنك استخدام إجراء القصد ACTION_OPEN_DOCUMENT لطلب اختيار ملف individual من الأدلة التالية:

دليل Android/data/ وجميع الأدلة الفرعية
دليل Android/obb/ وجميع الأدلة الفرعية.

منح الإذن بالوصول إلى محتوى دليل

تدير تطبيقات إدارة الملفات وإنشاء الوسائط عادةً مجموعات من الملفات في بنية هرمية للمجلدات. لتوفير هذه الميزة في تطبيقك، استخدِم إجراء القصد ACTION_OPEN_DOCUMENT_TREE الذي يسمح للمستخدم بمنح إذن الوصول إلى شجرة دليل كامل، مع بعض الاستثناءات اعتبارًا من الإصدار 11 من Android (المستوى 30 لواجهة برمجة التطبيقات). يمكن لتطبيقك بعد ذلك الوصول إلى أي ملف في الدليل المحدّد وأي من أدلائه الفرعية.

عند استخدام "ACTION_OPEN_DOCUMENT_TREE"، سيتمكّن تطبيقك من الوصول فقط إلى الملفات في الدليل الذي يحدده المستخدم. لا يمكنك الوصول إلى ملفات التطبيقات الأخرى التي تقع خارج هذا الدليل الذي يختاره المستخدم. هذا النمط الذي يتحكم فيه المستخدم في اختيار المحتوى الذي بالراحة عند المشاركة مع تطبيقك.

بشكل اختياري، يمكنك تحديد معرّف الموارد المنتظم (URI) للدليل الذي يجب على منتقي الملفات العرض عند تحميله لأول مرة باستخدام EXTRA_INITIAL_URI النية الإضافية.

يوضح مقتطف الرمز التالي كيفية إنشاء واستدعاء الغرض من الفتح دليل:

KotlinJava

fun openDirectory(pickerInitialUri: Uri) {
    // Choose a directory using the system's file picker.
    val intent = Intent(Intent.ACTION_OPEN_DOCUMENT_TREE).apply {
        // Optionally, specify a URI for the directory that should be opened in
        // the system file picker when it loads.
        putExtra(DocumentsContract.EXTRA_INITIAL_URI, pickerInitialUri)
    }

    startActivityForResult(intent, your-request-code)
}

public void openDirectory(Uri uriToLoad) {
    // Choose a directory using the system's file picker.
    Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT_TREE);

    // Optionally, specify a URI for the directory that should be opened in
    // the system file picker when it loads.
    intent.putExtra(DocumentsContract.EXTRA_INITIAL_URI, uriToLoad);

    startActivityForResult(intent, your-request-code);
}

قيود الوصول

في نظام التشغيل Android 11 (المستوى 30 لواجهة برمجة التطبيقات) والإصدارات الأحدث، لا يمكنك استخدام إجراء واحد (ACTION_OPEN_DOCUMENT_TREE) يهدف إلى طلب الوصول إلى ما يلي: الدلائل:

الدليل الجذري لوحدة التخزين الداخلية
الدليل الجذري لكل وحدة تخزين على بطاقة SD تستخدمها الشركة المصنّعة للجهاز موثوقة بغضّ النظر عمّا إذا تمّت محاكاة البطاقة أو قابل للإزالة. الحجم الموثوق به هو الحجم الذي يمكن للتطبيق الوصول إلى معظم الوقت.
دليل Download

علاوةً على ذلك، في نظام التشغيل Android 11 (المستوى 30 لواجهة برمجة التطبيقات) والإصدارات الأحدث، لا يمكنك استخدام إجراء النية ACTION_OPEN_DOCUMENT_TREE لطلب أن يختار المستخدم ملفات فردية من الأدلة التالية:

دليل Android/data/ وجميع الأدلة الفرعية.
دليل Android/obb/ وجميع الأدلة الفرعية

إجراء العمليات على الموقع المحدد

بعد أن يختار المستخدم ملفًا أو دليلاً باستخدام أداة اختيار الملفات في النظام، يمكنك استرداد عنوان URL للعنصر المحدّد باستخدام الرمز التالي في onActivityResult():

KotlinJava

override fun onActivityResult(
        requestCode: Int, resultCode: Int, resultData: Intent?) {
    if (requestCode == your-request-code
            && resultCode == Activity.RESULT_OK) {
        // The result data contains a URI for the document or directory that
        // the user selected.
        resultData?.data?.also { uri ->
            // Perform operations on the document using its URI.
        }
    }
}

@Override
public void onActivityResult(int requestCode, int resultCode,
        Intent resultData) {
    if (requestCode == your-request-code
            && resultCode == Activity.RESULT_OK) {
        // The result data contains a URI for the document or directory that
        // the user selected.
        Uri uri = null;
        if (resultData != null) {
            uri = resultData.getData();
            // Perform operations on the document using its URI.
        }
    }
}

من خلال الحصول على مرجع إلى معرّف الموارد المنتظم (URI) للعنصر المحدّد، يمكن لتطبيقك تنفيذ عدة عمليات العمليات على العنصر. على سبيل المثال، يمكنك الوصول إلى البيانات الوصفية للعنصر وتعديله في مكانه وحذفه.

توضح الأقسام التالية كيفية إكمال الإجراءات على الملفات التي يملكها المستخدم المستخدم.

تحديد العمليات التي يدعمها مقدم الخدمة

يسمح موفرو المحتوى المختلفون بإجراء عمليات مختلفة على المستندات — مثل نسخ المستند أو عرض الصورة المصغرة له. إلى لتحديد العمليات التي يدعمها مقدم خدمة معين، فتحقق من قيمة Document.COLUMN_FLAGS وبالتالي، يمكن لواجهة مستخدم تطبيقك عرض الخيارات التي يتيحها مقدّم الخدمة فقط.

الاحتفاظ بالأذونات

عندما يفتح تطبيقك ملفًا للقراءة أو الكتابة، يمنح النظام تطبيقك إذن معرّف الموارد المنتظم (URI) الخاص بهذا الملف، ويبقى صالحًا إلى أن يتم منح المستخدم إذن الوصول إلى عنوان URL تتم إعادة تشغيله. ومع ذلك، افترض أن تطبيقك عبارة عن تطبيق لتعديل الصور، وتريد تمكين المستخدمين من الوصول مباشرةً إلى الصور الخمس التي عدّلوها مؤخرًا من تطبيقك. في حال إعادة تشغيل جهاز المستخدم، عليك إرسال طلب إلى المستخدم. إلى منتقي النظام للعثور على الملفات.

للحفاظ على إمكانية الوصول إلى الملفات على جميع الأجهزة، تتم إعادة تشغيل الجهاز وإنشاء مستخدم أفضل. المستخدم، يمكن لتطبيقك "أخذ" إذن عنوان URI المستمر التي يقدمها النظام، كما هو موضح في مقتطف الرمز التالي:

KotlinJava

val contentResolver = applicationContext.contentResolver

val takeFlags: Int = Intent.FLAG_GRANT_READ_URI_PERMISSION or
        Intent.FLAG_GRANT_WRITE_URI_PERMISSION
// Check for the freshest data.
contentResolver.takePersistableUriPermission(uri, takeFlags)

final int takeFlags = intent.getFlags()
            & (Intent.FLAG_GRANT_READ_URI_PERMISSION
            | Intent.FLAG_GRANT_WRITE_URI_PERMISSION);
// Check for the freshest data.
getContentResolver().takePersistableUriPermission(uri, takeFlags);

فحص البيانات الوصفية للمستند

عندما يكون لديك معرف الموارد المنتظم (URI) لمستند، يمكنك الوصول إلى بياناته الوصفية. تلتقط هذه القطعة من الرمز البرمجي البيانات الوصفية لمستند يحدّده عنوان URL، وتُسجّلها:

KotlinJava

val contentResolver = applicationContext.contentResolver

fun dumpImageMetaData(uri: Uri) {

    // The query, because it only applies to a single document, returns only
    // one row. There's no need to filter, sort, or select fields,
    // because we want all fields for one document.
    val cursor: Cursor? = contentResolver.query(
            uri, null, null, null, null, null)

    cursor?.use {
        // moveToFirst() returns false if the cursor has 0 rows. Very handy for
        // "if there's anything to look at, look at it" conditionals.
        if (it.moveToFirst()) {

            // Note it's called "Display Name". This is
            // provider-specific, and might not necessarily be the file name.
            val displayName: String =
                    it.getString(it.getColumnIndex(OpenableColumns.DISPLAY_NAME))
            Log.i(TAG, "Display Name: $displayName")

            val sizeIndex: Int = it.getColumnIndex(OpenableColumns.SIZE)
            // If the size is unknown, the value stored is null. But because an
            // int can't be null, the behavior is implementation-specific,
            // and unpredictable. So as
            // a rule, check if it's null before assigning to an int. This will
            // happen often: The storage API allows for remote files, whose
            // size might not be locally known.
            val size: String = if (!it.isNull(sizeIndex)) {
                // Technically the column stores an int, but cursor.getString()
                // will do the conversion automatically.
                it.getString(sizeIndex)
            } else {
                "Unknown"
            }
            Log.i(TAG, "Size: $size")
        }
    }
}

public void dumpImageMetaData(Uri uri) {

    // The query, because it only applies to a single document, returns only
    // one row. There's no need to filter, sort, or select fields,
    // because we want all fields for one document.
    Cursor cursor = getActivity().getContentResolver()
            .query(uri, null, null, null, null, null);

    try {
        // moveToFirst() returns false if the cursor has 0 rows. Very handy for
        // "if there's anything to look at, look at it" conditionals.
        if (cursor != null && cursor.moveToFirst()) {

            // Note it's called "Display Name". This is
            // provider-specific, and might not necessarily be the file name.
            String displayName = cursor.getString(
                    cursor.getColumnIndex(OpenableColumns.DISPLAY_NAME));
            Log.i(TAG, "Display Name: " + displayName);

            int sizeIndex = cursor.getColumnIndex(OpenableColumns.SIZE);
            // If the size is unknown, the value stored is null. But because an
            // int can't be null, the behavior is implementation-specific,
            // and unpredictable. So as
            // a rule, check if it's null before assigning to an int. This will
            // happen often: The storage API allows for remote files, whose
            // size might not be locally known.
            String size = null;
            if (!cursor.isNull(sizeIndex)) {
                // Technically the column stores an int, but cursor.getString()
                // will do the conversion automatically.
                size = cursor.getString(sizeIndex);
            } else {
                size = "Unknown";
            }
            Log.i(TAG, "Size: " + size);
        }
    } finally {
        cursor.close();
    }
}

فتح مستند

من خلال الحصول على إشارة إلى معرّف الموارد المتسلسل لمستند، يمكنك فتح مستند لإجراء مزيد من المعالجة. يعرض هذا القسم أمثلة لفتح ملف رسومات نقطية وملف تدفق إدخال.

صورة نقطية

يوضِّح مقتطف الرمز البرمجي التالي كيفية فتح ملف Bitmap استنادًا إلى معرّف الموارد المتّصل (URI):

KotlinJava

val contentResolver = applicationContext.contentResolver

@Throws(IOException::class)
private fun getBitmapFromUri(uri: Uri): Bitmap {
    val parcelFileDescriptor: ParcelFileDescriptor =
            contentResolver.openFileDescriptor(uri, "r")
    val fileDescriptor: FileDescriptor = parcelFileDescriptor.fileDescriptor
    val image: Bitmap = BitmapFactory.decodeFileDescriptor(fileDescriptor)
    parcelFileDescriptor.close()
    return image
}

private Bitmap getBitmapFromUri(Uri uri) throws IOException {
    ParcelFileDescriptor parcelFileDescriptor =
            getContentResolver().openFileDescriptor(uri, "r");
    FileDescriptor fileDescriptor = parcelFileDescriptor.getFileDescriptor();
    Bitmap image = BitmapFactory.decodeFileDescriptor(fileDescriptor);
    parcelFileDescriptor.close();
    return image;
}

بعد فتح الصورة النقطية، يمكنك عرضها في ImageView

بث الإدخال

يوضِّح مقتطف الرمز التالي كيفية فتح عنصر InputStream استنادًا إلى ملفه الشخصي URI. في هذا المقتطف، تتم قراءة سطور الملف في سلسلة:

KotlinJava

val contentResolver = applicationContext.contentResolver

@Throws(IOException::class)
private fun readTextFromUri(uri: Uri): String {
    val stringBuilder = StringBuilder()
    contentResolver.openInputStream(uri)?.use { inputStream ->
        BufferedReader(InputStreamReader(inputStream)).use { reader ->
            var line: String? = reader.readLine()
            while (line != null) {
                stringBuilder.append(line)
                line = reader.readLine()
            }
        }
    }
    return stringBuilder.toString()
}

private String readTextFromUri(Uri uri) throws IOException {
    StringBuilder stringBuilder = new StringBuilder();
    try (InputStream inputStream =
            getContentResolver().openInputStream(uri);
            BufferedReader reader = new BufferedReader(
            new InputStreamReader(Objects.requireNonNull(inputStream)))) {
        String line;
        while ((line = reader.readLine()) != null) {
            stringBuilder.append(line);
        }
    }
    return stringBuilder.toString();
}

تعديل مستند

يمكنك استخدام إطار عمل الوصول إلى مساحة التخزين لتعديل مستند نصي في مكانه.

يستبدل مقتطف الرمز التالي محتوى المستند المعروض. باستخدام عنوان URI المحدد:

KotlinJava

val contentResolver = applicationContext.contentResolver

private fun alterDocument(uri: Uri) {
    try {
        contentResolver.openFileDescriptor(uri, "w")?.use {
            FileOutputStream(it.fileDescriptor).use {
                it.write(
                    ("Overwritten at ${System.currentTimeMillis()}\n")
                        .toByteArray()
                )
            }
        }
    } catch (e: FileNotFoundException) {
        e.printStackTrace()
    } catch (e: IOException) {
        e.printStackTrace()
    }
}

private void alterDocument(Uri uri) {
    try {
        ParcelFileDescriptor pfd = getActivity().getContentResolver().
                openFileDescriptor(uri, "w");
        FileOutputStream fileOutputStream =
                new FileOutputStream(pfd.getFileDescriptor());
        fileOutputStream.write(("Overwritten at " + System.currentTimeMillis() +
                "\n").getBytes());
        // Let the document provider know you're done by closing the stream.
        fileOutputStream.close();
        pfd.close();
    } catch (FileNotFoundException e) {
        e.printStackTrace();
    } catch (IOException e) {
        e.printStackTrace();
    }
}

حذف مستند

إذا كان لديك عنوان URL لمستند وكان Document.COLUMN_FLAGS المتعلق به يحتوي على SUPPORTS_DELETE، يمكنك حذف المستند. مثلاً:

KotlinJava

DocumentsContract.deleteDocument(applicationContext.contentResolver, uri)

DocumentsContract.deleteDocument(applicationContext.contentResolver, uri);

استرداد عنوان URL مكافئ للوسائط

تقدّم الطريقة getMediaUri() معرّف موارد منتظم لمتجر الوسائط يعادل معرّف موارد منتظم مقدّم المستندات . يشير معرّفا الموارد المنتظمة (URI) إلى العنصر الأساسي نفسه. باستخدام عنوان URI لملف الوسائط، يمكنك الوصول إلى ملفات الوسائط من مساحة التخزين المشترَكة بسهولة أكبر.

تتيح طريقة getMediaUri() معرّفات الموارد المنتظمة ExternalStorageProvider. مشغَّلة في Android 12 (المستوى 31 لواجهة برمجة التطبيقات) والإصدارات الأحدث، تتيح هذه الطريقة أيضًا MediaDocumentsProvider معرّف موارد منتظم (URI)

فتح ملف افتراضي

في الإصدار 7.0 من نظام التشغيل Android (المستوى 25 لواجهة برمجة التطبيقات) والإصدارات الأحدث، يمكن لتطبيقك الاستفادة من الملفات الافتراضية التي يوفّرها إطار عمل الوصول إلى مساحة التخزين. على الرغم من أن الملفات الافتراضية تمثيلاً ثنائيًا، فيمكن للتطبيق فتح محتوياته عن طريق إجبار إلى نوع ملف مختلف أو من خلال عرضها باستخدام ACTION_VIEW هدف اتخاذ القرار.

لفتح الملفات الافتراضية، يجب أن يتضمّن تطبيق العميل منطقًا خاصًا للتعامل مع هذه الملفات. إذا أردت الحصول على تمثيل بايت للملف، مثلاً لمعاينة الملف، عليك طلب نوع MIME بديل من مقدّم المستندات.

بعد أن يحدد المستخدم، يمكنك استخدام عنوان URI في بيانات النتائج لتحديد ما إذا كان الملف افتراضيًا، كما هو موضح في مقتطف الرمز التالي:

KotlinJava

private fun isVirtualFile(uri: Uri): Boolean {
    if (!DocumentsContract.isDocumentUri(this, uri)) {
        return false
    }

    val cursor: Cursor? = contentResolver.query(
            uri,
            arrayOf(DocumentsContract.Document.COLUMN_FLAGS),
            null,
            null,
            null
    )

    val flags: Int = cursor?.use {
        if (cursor.moveToFirst()) {
            cursor.getInt(0)
        } else {
            0
        }
    } ?: 0

    return flags and DocumentsContract.Document.FLAG_VIRTUAL_DOCUMENT != 0
}

private boolean isVirtualFile(Uri uri) {
    if (!DocumentsContract.isDocumentUri(this, uri)) {
        return false;
    }

    Cursor cursor = getContentResolver().query(
        uri,
        new String[] { DocumentsContract.Document.COLUMN_FLAGS },
        null, null, null);

    int flags = 0;
    if (cursor.moveToFirst()) {
        flags = cursor.getInt(0);
    }
    cursor.close();

    return (flags & DocumentsContract.Document.FLAG_VIRTUAL_DOCUMENT) != 0;
}

بعد التأكّد من أنّ المستند هو ملف افتراضي، يمكنك إجبار الملف على استخدام نوع MIME بديل، مثل "image/png". يُنشئ الكود التالي يُظهر المقتطف كيفية التحقق مما إذا كان يمكن تمثيل ملف افتراضي كـ صورة، وفي هذه الحالة تحصل على مصدر إدخال من الملف الافتراضي:

KotlinJava

@Throws(IOException::class)
private fun getInputStreamForVirtualFile(
        uri: Uri, mimeTypeFilter: String): InputStream {

    val openableMimeTypes: Array<String>? =
            contentResolver.getStreamTypes(uri, mimeTypeFilter)

    return if (openableMimeTypes?.isNotEmpty() == true) {
        contentResolver
                .openTypedAssetFileDescriptor(uri, openableMimeTypes[0], null)
                .createInputStream()
    } else {
        throw FileNotFoundException()
    }
}

private InputStream getInputStreamForVirtualFile(Uri uri, String mimeTypeFilter)
    throws IOException {

    ContentResolver resolver = getContentResolver();

    String[] openableMimeTypes = resolver.getStreamTypes(uri, mimeTypeFilter);

    if (openableMimeTypes == null ||
        openableMimeTypes.length < 1) {
        throw new FileNotFoundException();
    }

    return resolver
        .openTypedAssetFileDescriptor(uri, openableMimeTypes[0], null)
        .createInputStream();
}

مصادر إضافية

لمزيد من المعلومات عن كيفية تخزين المستندات والملفات الأخرى والوصول إليها، يُرجى الرجوع إلى الموارد التالية.

نماذج

ActionOpenDocument، المتوفرة على GitHub.
ActionOpenDocumentTree، المتوفرة على GitHub.

الفيديوهات

الاستعداد لاستخدام ميزة "مساحة التخزين ذات النطاق المحدّد" (مؤتمر Android Dev Summit '19)