Введение:
После завершения предыдущего раздела вы уже должны знать, как использовать предоставляемый системой ContentProvider или определять собственный ContentProvider, что в основном удовлетворяет повседневные потребности разработки. Интересно, что в официальной документации я увидел эти другие провайдеры:
Calendar ProviderCalendar Provider: Библиотека ресурсов для событий, связанных с календарём. Через его API мы можем выполнять CRUD-операции с календарями, временем, встречами, напоминаниями и многим другим!
Contacts ProviderContacts Provider: Не нужно больше говорить. Этот используется чаще всего. Я переведу эту статью, когда позже будет время!
Storage Access Framework(SAF)Storage Access Framework: Новая функция, появившаяся после 4.4, которая обеспечивает удобство для пользователей при просмотре содержимого хранилища на своих телефонах. Доступное содержимое включает не только документы, изображения, видео, аудио и загрузки, но и всё содержимое, предоставляемое конкретными ContentProviders (у которых должен быть согласованный API). Независимо от того, откуда это содержимое берётся или какое приложение вызывает команду для просмотра содержимого системных файлов, система предоставит вам единый интерфейс для просмотра.
На самом деле это встроенное приложение под названием DocumentsUI. Поскольку в его IntentFilter нет LAUNCHER, мы не находим эту вещь на рабочем столе! Хе-хе, попробуйте код ниже. Здесь мы выбрали два телефона для сравнения: Lenovo S898T на 4.2 и Nexus 5 на 5.0.1. Выполните следующий код:
Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
intent.addCategory(Intent.CATEGORY_OPENABLE);
intent.setType("image/*");
startActivity(intent);
Ниже показан результат выполнения:

То, что справа, — это новшество, которое принесла нам 4.4. Обычно мы можем использовать его, когда нам нужно получить URL файла. Далее кратко рассмотрим документацию.
2. Краткий обзор документации:
1) Компоненты фреймворка SAF:
- Поставщик документовDocumentsProvider: специальный ContentProvider, который позволяет сервису хранения (например, Google Drive) предоставлять управляемые им файлы внешнему миру. Он являетсяDocumentsProviderподклассом ContentProvider. Кроме того, формат хранения document-provider согласуется с традиционным форматом хранения файлов. Что касается того, как хранится ваш контент, это полностью зависит от вас. В Android встроено несколько таких поставщиков документов, например для загрузок, изображений и видео!
- Клиентское приложениеКлиентское приложение: обычное клиентское приложение, запускаяACTION_OPEN_DOCUMENTи/илиACTION_CREATE_DOCUMENTможет получать контент, возвращаемый от поставщика документов, например, выбирая изображение и затем возвращая Uri.
- PickerPicker: интерфейс, похожий на файловый менеджер, и это системный интерфейс, который предоставляет канал для доступа к контенту поставщика документов, соответствующему условиям фильтрации клиента. Это упомянутая ранее программа DocumentsUI!
Некоторые возможности:
- Пользователи могут просматривать контент, предоставляемый всеми поставщиками документов, а не только одним приложением.
- Он обеспечивает долгосрочный, постоянный доступ к файлам в поставщиках документов, а также сохранение данных. Пользователи могут добавлять, удалять, редактировать и сохранять контент, поддерживаемый поставщиком документов.
- Он поддерживает несколько пользователей и временные сервисы контента. Например, поставщики USB-хранилищ появляются только после успешной установки драйвера.
2) Обзор:
Ядром SAF является подкласс, реализующий DocumentsProvider, и при этом он всё ещё ContentProvider. Внутри поставщика документов файлы организованы в традиционное дерево каталогов:

3) Блок-схема:
Как упоминалось выше, данные поставщика документов основаны на традиционной файловой иерархии, но это лишь внешнее представление. То, как вы храните свои данные, полностью зависит от вас, если интерфейс, который вы предоставляете наружу, доступен через API DocumentsProvider. Следующая блок-схема показывает возможную структуру фотоприложения, использующего SAF:

Анализ:
Из рисунка выше видно, что Picker — это мост, соединяющий вызывающую сторону и поставщиков содержимого! Он предоставляет и сообщает вызывающей стороне, каких поставщиков содержимого можно выбрать, например DriveDocProvider, UsbDocProvider и CloundDocProvider здесь.
Когда клиент запускаетACTION_OPEN_DOCUMENTилиACTION_CREATE_DOCUMENTIntent, происходит вышеописанное взаимодействие. Конечно, мы также можем добавить в Intent условия фильтрации, например ограничить MIME-тип значением "image"!

Вот и всё, что описано выше. Если у вас установлены другие программы для просмотра изображений, они также появятся здесь! Проще говоря: после того как клиент отправит Intent с двумя вышеуказанными Actions, откроется интерфейс Picker. Здесь будут отображены соответствующие доступные поставщики документов, чтобы пользователь мог выбрать. После выбора пользователя можно получить информацию, связанную с файлом!
4) Вызов на стороне клиента и получение возвращённого Uri
Код реализации выглядит так:
public class MainActivity extends AppCompatActivity implements View.OnClickListener {
private static final int READ_REQUEST_CODE = 42;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
Button btn_show = (Button) findViewById(R.id.btn_show);
btn_show.setOnClickListener(this);
}
@Override
public void onClick(View v) {
Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
intent.addCategory(Intent.CATEGORY_OPENABLE);
intent.setType("image/*");
startActivityForResult(intent, READ_REQUEST_CODE);
}
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
if (requestCode == READ_REQUEST_CODE && resultCode == Activity.RESULT_OK) {
Uri uri;
if (data != null) {
uri = data.getData();
Log.e("HeHe", "Uri: " + uri.toString());
}
}
}
}
Результат выполнения:Например, если мы выберем ту собаку, интерфейс Picker автоматически закроется, и затем мы сможем увидеть такой uri в Logcat:

5) Получение параметров файла на основе uri
Основной код выглядит следующим образом:
public void dumpImageMetaData(Uri uri) {
Cursor cursor = getContentResolver()
.query(uri, null, null, null, null, null);
try {
if (cursor != null && cursor.moveToFirst()) {
String displayName = cursor.getString(
cursor.getColumnIndex(OpenableColumns.DISPLAY_NAME));
Log.e("HeHe", "Display Name: " + displayName);
int sizeIndex = cursor.getColumnIndex(OpenableColumns.SIZE);
String size = null;
if (!cursor.isNull(sizeIndex)) {
size = cursor.getString(sizeIndex);
}else {
size = "Unknown";
}
Log.e("HeHe", "Size: " + size);
}
}finally {
cursor.close();
}
}
Результат выполнения:Всё та же собака. После вызова метода будут выведены имя файла и размер файла в байтах.

6) Получение Bitmap из Uri
Основной код выглядит следующим образом:
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;
}
Результат выполнения:

7) Получение входного потока из Uri
Основной код выглядит следующим образом:
private String readTextFromUri(Uri uri) throws IOException {
InputStream inputStream = getContentResolver().openInputStream(uri);
BufferedReader reader = new BufferedReader(new InputStreamReader(
inputStream));
StringBuilder stringBuilder = new StringBuilder();
String line;
while ((line = reader.readLine()) != null) {
stringBuilder.append(line);
}
fileInputStream.close();
parcelFileDescriptor.close();
return stringBuilder.toString();
}
Приведённое выше содержимое показывает только то, что можно узнать через Uri, а Uri получается через SAF!
8) Создание новых файлов и удаление файлов:
Создание файла:
private void createFile(String mimeType, String fileName) {
Intent intent = new Intent(Intent.ACTION_CREATE_DOCUMENT);
intent.addCategory(Intent.CATEGORY_OPENABLE);
intent.setType(mimeType);
intent.putExtra(Intent.EXTRA_TITLE, fileName);
startActivityForResult(intent, WRITE_REQUEST_CODE);
}
Вы можете получить uri созданного файла в onActivityResult().
Удаление файла:
Предварительное условие — Document.COLUMN_FLAGS содержитSUPPORTS_DELETE
DocumentsContract.deleteDocument(getContentResolver(), uri);
9) Написание собственного поставщика документов
Если вы хотите, чтобы данные вашего приложения также можно было открывать в documentsui, вам нужно написать собственный поставщик документов. Ниже приведены шаги для определения пользовательского DocumentsProvider:
- Версия API 19 или выше.
- Зарегистрируйте этот провайдер в manifest.xml.
- Имя провайдера — это имя класса плюс имя пакета, например:com.example.android.storageprovider.MyCloudProvider
- Authority — это имя пакета + имя типа провайдера, например:com.example.android.storageprovider.documents
- Значение атрибута android:exported равно true.
Ниже приведён пример того, как написать провайдер:
<manifest... >
...
<uses-sdk
android:minSdkVersion="19"
android:targetSdkVersion="19" />
....
<provider
android:name="com.example.android.storageprovider.MyCloudProvider"
android:authorities="com.example.android.storageprovider.documents"
android:grantUriPermissions="true"
android:exported="true"
android:permission="android.permission.MANAGE_DOCUMENTS"
android:enabled="@bool/atLeastKitKat">
<intent-filter>
<action android:name="android.content.action.DOCUMENTS_PROVIDER" />
</intent-filter>
</provider>
</application>
</manifest>
10) Подклассы DocumentsProvider
Как минимум реализуйте следующие методы:
- queryRoots()
- queryChildDocuments()
- queryDocument()
- openDocument()
Есть некоторые другие методы, но они не обязательны. Ниже приведён пример реализации DocumentsProvider, обращающегося к файловой системе.
Реализовать queryRoots
@Override
public Cursor queryRoots(String[] projection) throws FileNotFoundException {
// Create a cursor with either the requested fields, or the default
// projection if "projection" is null.
final MatrixCursor result =
new MatrixCursor(resolveRootProjection(projection));
// If user is not logged in, return an empty root cursor. This removes our
// provider from the list entirely.
if (!isUserLoggedIn()) {
return result;
}
// It's possible to have multiple roots (e.g. for multiple accounts in the
// same app) -- just add multiple cursor rows.
// Construct one row for a root called "MyCloud".
final MatrixCursor.RowBuilder row = result.newRow();
row.add(Root.COLUMN_ROOT_ID, ROOT);
row.add(Root.COLUMN_SUMMARY, getContext().getString(R.string.root_summary));
// FLAG_SUPPORTS_CREATE means at least one directory under the root supports
// creating documents. FLAG_SUPPORTS_RECENTS means your application's most
// recently used documents will show up in the "Recents" category.
// FLAG_SUPPORTS_SEARCH allows users to search all documents the application
// shares.
row.add(Root.COLUMN_FLAGS, Root.FLAG_SUPPORTS_CREATE |
Root.FLAG_SUPPORTS_RECENTS |
Root.FLAG_SUPPORTS_SEARCH);
// COLUMN_TITLE is the root title (e.g. Gallery, Drive).
row.add(Root.COLUMN_TITLE, getContext().getString(R.string.title));
// This document id cannot change once it's shared.
row.add(Root.COLUMN_DOCUMENT_ID, getDocIdForFile(mBaseDir));
// The child MIME types are used to filter the roots and only present to the
// user roots that contain the desired type somewhere in their file hierarchy.
row.add(Root.COLUMN_MIME_TYPES, getChildMimeTypes(mBaseDir));
row.add(Root.COLUMN_AVAILABLE_BYTES, mBaseDir.getFreeSpace());
row.add(Root.COLUMN_ICON, R.drawable.ic_launcher);
return result;
}
Реализовать queryChildDocuments
public Cursor queryChildDocuments(String parentDocumentId, String[] projection,
String sortOrder) throws FileNotFoundException {
final MatrixCursor result = new
MatrixCursor(resolveDocumentProjection(projection));
final File parent = getFileForDocId(parentDocumentId);
for (File file : parent.listFiles()) {
// Adds the file's display name, MIME type, size, and so on.
includeFile(result, null, file);
}
return result;
}
Реализовать queryDocument
@Override
public Cursor queryDocument(String documentId, String[] projection) throws
FileNotFoundException {
// Create a cursor with the requested projection, or the default projection.
final MatrixCursor result = new
MatrixCursor(resolveDocumentProjection(projection));
includeFile(result, documentId, null);
return result;
}
Ну, это примерно всё содержание документации. Сначала я хотел перевести её сам, но потом нашёл китайский перевод этого документа на "Days Online", так что пошёл по лёгкому пути~
Ссылка на китайский перевод:Android Storage Access Framework
3. Проблема получения путей к ресурсам в Android 4.4:
На самом деле чаще всего мы используем SAF просто чтобы получить Uri изображения. И из примера выше мы также увидели, что ссылка, полученная таким способом, выглядит так:
content://com.android.providers.media.documents/document/image%3A69983
Для такой ссылки мы можем напрямую использовать приведённый выше метод, чтобы получить uri!
Конечно, это для 4.4 или выше.
Если это более ранняя версия, uri может выглядеть так:
content://media/external/images/media/image%3A69983
Вот комплексное решение, которое я видел в другом месте. Оригинальная ссылка:Проблема получения путей к ресурсам в Android 4.4
public static String getPath(final Context context, final Uri uri) {
final boolean isKitKat = Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT;
// DocumentProvider
if (isKitKat && DocumentsContract.isDocumentUri(context, uri)) {
// ExternalStorageProvider
if (isExternalStorageDocument(uri)) {
final String docId = DocumentsContract.getDocumentId(uri);
final String[] split = docId.split(":");
final String type = split[0];
if ("primary".equalsIgnoreCase(type)) {
return Environment.getExternalStorageDirectory() + "/" + split[1];
}
// TODO handle non-primary volumes
}
// DownloadsProvider
else if (isDownloadsDocument(uri)) {
final String id = DocumentsContract.getDocumentId(uri);
final Uri contentUri = ContentUris.withAppendedId(
Uri.parse("content://downloads/public_downloads"), Long.valueOf(id));
return getDataColumn(context, contentUri, null, null);
}
// MediaProvider
else if (isMediaDocument(uri)) {
final String docId = DocumentsContract.getDocumentId(uri);
final String[] split = docId.split(":");
final String type = split[0];
Uri contentUri = null;
if ("image".equals(type)) {
contentUri = MediaStore.Images.Media.EXTERNAL_CONTENT_URI;
} else if ("video".equals(type)) {
contentUri = MediaStore.Video.Media.EXTERNAL_CONTENT_URI;
} else if ("audio".equals(type)) {
contentUri = MediaStore.Audio.Media.EXTERNAL_CONTENT_URI;
}
final String selection = "_id=?";
final String[] selectionArgs = new String[] {
split[1]
};
return getDataColumn(context, contentUri, selection, selectionArgs);
}
}
// MediaStore (and general)
else if ("content".equalsIgnoreCase(uri.getScheme())) {
return getDataColumn(context, uri, null, null);
}
// File
else if ("file".equalsIgnoreCase(uri.getScheme())) {
return uri.getPath();
}
return null;
}
/**
* Get the value of the data column for this Uri. This is useful for
* MediaStore Uris, and other file-based ContentProviders.
*
* @param context The context.
* @param uri The Uri to query.
* @param selection (Optional) Filter used in the query.
* @param selectionArgs (Optional) Selection arguments used in the query.
* @return The value of the _data column, which is typically a file path.
*/
public static String getDataColumn(Context context, Uri uri, String selection,
String[] selectionArgs) {
Cursor cursor = null;
final String column = "_data";
final String[] projection = {
column
};
try {
cursor = context.getContentResolver().query(uri, projection, selection, selectionArgs,
null);
if (cursor != null && cursor.moveToFirst()) {
final int column_index = cursor.getColumnIndexOrThrow(column);
return cursor.getString(column_index);
}
} finally {
if (cursor != null)
cursor.close();
}
return null;
}
/**
* @param uri The Uri to check.
* @return Whether the Uri authority is ExternalStorageProvider.
*/
public static boolean isExternalStorageDocument(Uri uri) {
return "com.android.externalstorage.documents".equals(uri.getAuthority());
}
/**
* @param uri The Uri to check.
* @return Whether the Uri authority is DownloadsProvider.
*/
public static boolean isDownloadsDocument(Uri uri) {
return "com.android.providers.downloads.documents".equals(uri.getAuthority());
}
/**
* @param uri The Uri to check.
* @return Whether the Uri authority is MediaProvider.
*/
public static boolean isMediaDocument(Uri uri) {
return "com.android.providers.media.documents".equals(uri.getAuthority());
}
Итог:
Ладно, на этом всё по этому разделу об Android Storage Access Framework (SAF). Примеров нет. Мы копнём глубже позже, когда нам понадобится это использовать. Просто имейте это в виду. После 4.4 получение путей к файлам стало намного проще~
