На устройствах под управлением Android 4.4 (API уровня 19) и выше ваше приложение может взаимодействовать с поставщиком документов , включая внешние хранилища и облачные хранилища, используя фреймворк Storage Access Framework. Этот фреймворк позволяет пользователям взаимодействовать с системным средством выбора, чтобы выбрать поставщика документов и конкретные документы и другие файлы, которые ваше приложение может создать, открыть или изменить.
Поскольку пользователь участвует в выборе файлов и каталогов, к которым ваше приложение может получить доступ, этот механизм не требует никаких системных разрешений , что повышает уровень контроля и конфиденциальности пользователя. Кроме того, эти файлы, хранящиеся вне каталога приложения и вне хранилища медиафайлов, остаются на устройстве после удаления приложения.
Использование фреймворка включает в себя следующие этапы:
- Приложение вызывает намерение, содержащее действие, связанное с хранилищем. Это действие соответствует конкретному варианту использования , предоставляемому фреймворком.
- Пользователь видит системный выбор, позволяющий ему просматривать поставщика документов и выбирать место или документ, где будет выполняться действие, связанное с хранением.
- Приложение получает доступ на чтение и запись к URI, представляющему выбранное пользователем местоположение или документ. Используя этот URI, приложение может выполнять операции с выбранным местоположением .
Для поддержки доступа к медиафайлам на устройствах под управлением Android 9 (уровень API 28) или ниже объявите разрешение READ_EXTERNAL_STORAGE
и установите для maxSdkVersion
значение 28
.
В этом руководстве описываются различные варианты использования фреймворка для работы с файлами и другими документами. Также объясняется, как выполнять операции с выбранным пользователем расположением.
Примеры использования для доступа к документам и другим файлам
Storage Access Framework поддерживает следующие варианты использования для доступа к файлам и другим документам.
- Создать новый файл
- Действие намерения
ACTION_CREATE_DOCUMENT
позволяет пользователям сохранять файл в определенном месте. - Открыть документ или файл
- Действие намерения
ACTION_OPEN_DOCUMENT
позволяет пользователям выбрать определенный документ или файл для открытия. - Предоставить доступ к содержимому каталога
- Действие намерения
ACTION_OPEN_DOCUMENT_TREE
, доступное в Android 5.0 (уровень API 21) и выше, позволяет пользователям выбирать определенный каталог, предоставляя вашему приложению доступ ко всем файлам и подкаталогам в этом каталоге.
В следующих разделах приведены рекомендации по настройке каждого варианта использования.
Создать новый файл
Используйте действие намерения ACTION_CREATE_DOCUMENT
, чтобы загрузить системный инструмент выбора файлов и предоставить пользователю возможность выбрать место для сохранения содержимого файла. Этот процесс аналогичен тому, который используется в диалоговых окнах «сохранить как» в других операционных системах.
Примечание: ACTION_CREATE_DOCUMENT
не может перезаписать существующий файл. Если ваше приложение попытается сохранить файл с тем же именем, система добавит номер в скобках в конце имени файла.
Например, если ваше приложение пытается сохранить файл с именем confirmation.pdf
в каталоге, в котором уже есть файл с таким именем, система сохраняет новый файл с именем confirmation(1).pdf
.
При настройке намерения укажите имя файла и тип MIME, а также при необходимости укажите URI файла или каталога, который средство выбора файлов должно отображать при первой загрузке, с помощью дополнительного намерения EXTRA_INITIAL_URI
.
В следующем фрагменте кода показано, как создать и вызвать намерение для создания файла:
Котлин
// 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
, которое открывает системное приложение выбора файлов. Чтобы отображать только те типы файлов, которые поддерживает ваше приложение, укажите тип MIME. Кроме того, вы можете указать URI файла, который должно отображать средство выбора файлов при первой загрузке, с помощью дополнительного намерения EXTRA_INITIAL_URI
.
В следующем фрагменте кода показано, как создать и вызвать намерение открытия PDF-документа:
Котлин
// 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); }
Ограничения доступа
В Android 11 (уровень API 30) и выше вы не можете использовать действие намерения ACTION_OPEN_DOCUMENT
, чтобы запросить у пользователя выбор отдельных файлов из следующих каталогов:
- Каталог
Android/data/
и все подкаталоги. - Каталог
Android/obb/
и все подкаталоги.
Предоставить доступ к содержимому каталога
Приложения для управления файлами и создания медиаконтента обычно управляют группами файлов в иерархии каталогов. Чтобы реализовать эту возможность в своём приложении, используйте намерение ACTION_OPEN_DOCUMENT_TREE
, которое позволяет пользователю предоставить доступ ко всему дереву каталогов, за некоторыми исключениями, начиная с Android 11 (API уровня 30). После этого ваше приложение сможет получить доступ к любому файлу в выбранном каталоге и любом из его подкаталогов.
При использовании ACTION_OPEN_DOCUMENT_TREE
ваше приложение получает доступ только к файлам в каталоге, выбранном пользователем. У вас нет доступа к файлам других приложений, которые находятся за пределами этого каталога, выбранного пользователем. Этот контролируемый пользователем доступ позволяет пользователям выбирать, каким именно контентом они готовы поделиться с вашим приложением.
При желании можно указать URI каталога, который средство выбора файлов должно отображать при первой загрузке, с помощью дополнительного намерения EXTRA_INITIAL_URI
.
В следующем фрагменте кода показано, как создать и вызвать намерение открытия каталога:
Котлин
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 (уровень API 30) и выше вы не можете использовать действие намерения ACTION_OPEN_DOCUMENT_TREE
для запроса доступа к следующим каталогам:
- Корневой каталог внутреннего тома хранилища.
- Корневой каталог каждого тома SD-карты, который производитель устройства считает надёжным , независимо от того, эмулируется ли карта или является съёмной. Надёжный том — это тот, к которому приложение может успешно получить доступ в большинстве случаев.
- Каталог
Download
.
Кроме того, в Android 11 (уровень API 30) и выше вы не можете использовать действие намерения ACTION_OPEN_DOCUMENT_TREE
, чтобы запросить у пользователя выбор отдельных файлов из следующих каталогов:
- Каталог
Android/data/
и все подкаталоги. - Каталог
Android/obb/
и все подкаталоги.
Выполнение операций в выбранном месте
После того как пользователь выбрал файл или каталог с помощью системного средства выбора файлов, вы можете получить URI выбранного элемента, используя следующий код в onActivityResult()
:
Котлин
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 для этого файла, которое действует до перезагрузки устройства пользователя. Предположим, однако, что ваше приложение предназначено для редактирования изображений, и вы хотите, чтобы пользователи могли получить доступ к пяти последним отредактированным изображениям непосредственно из приложения. Если устройство пользователя перезагрузилось, вам придётся перенаправить пользователя обратно в системное окно выбора файлов, чтобы найти их.
Чтобы сохранить доступ к файлам при перезапуске устройства и создать лучший пользовательский интерфейс, ваше приложение может «воспользоваться» разрешением на постоянный URI, предоставляемым системой, как показано в следующем фрагменте кода:
Котлин
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 документа, вы получаете доступ к его метаданным. Этот фрагмент кода извлекает метаданные документа, указанного по URI, и регистрирует их:
Котлин
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(); } }
Открыть документ
Имея ссылку на URI документа, вы можете открыть его для дальнейшей обработки. В этом разделе приведены примеры открытия растрового изображения и входного потока.
Растровое изображение
В следующем фрагменте кода показано, как открыть файл Bitmap
по его URI:
Котлин
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. В этом фрагменте строки файла считываются в строку:
Котлин
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(); }
Редактировать документ
Для редактирования текстового документа на месте можно использовать Storage Access Framework.
Следующий фрагмент кода перезаписывает содержимое документа, представленного указанным URI:
Котлин
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(); } }
Удалить документ
Если у вас есть URI документа, и его свойство Document.COLUMN_FLAGS
содержит SUPPORTS_DELETE
, вы можете удалить документ. Например:
Котлин
DocumentsContract.deleteDocument(applicationContext.contentResolver, uri)
Ява
DocumentsContract.deleteDocument(applicationContext.contentResolver, uri);
Получить эквивалентный URI медиа
Метод getMediaUri()
предоставляет URI хранилища медиаданных, эквивалентный URI поставщика заданных документов. Оба URI ссылаются на один и тот же базовый элемент. Используя URI хранилища медиаданных, вы можете упростить доступ к медиафайлам из общего хранилища .
Метод getMediaUri()
поддерживает URI ExternalStorageProvider
. В Android 12 (уровень API 31) и выше метод также поддерживает URI MediaDocumentsProvider
.
Открыть виртуальный файл
На Android 7.0 (уровень API 25) и выше ваше приложение может использовать виртуальные файлы, предоставляемые Storage Access Framework. Несмотря на то, что виртуальные файлы не имеют двоичного представления, ваше приложение может открывать их содержимое, преобразуя их в другой тип или просматривая эти файлы с помощью действия намерения ACTION_VIEW
.
Для открытия виртуальных файлов ваше клиентское приложение должно включать специальную логику для их обработки. Если вы хотите получить байтовое представление файла, например, для его предварительного просмотра, вам необходимо запросить альтернативный тип MIME у поставщика документов.
После того как пользователь сделает выбор, используйте URI в данных результатов, чтобы определить, является ли файл виртуальным, как показано в следующем фрагменте кода:
Котлин
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"
. Следующий фрагмент кода показывает, как проверить, может ли виртуальный файл быть представлен как изображение, и, если да, получить входной поток из виртуального файла:
Котлин
@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.