Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Как открывать файлы с помощью платформы доступа к хранилищу

В Android 4.4 (уровень API 19) появился фреймворк Storage Access Framework (SAF). Она позволяет пользователям просматривать и открывать документы, изображения и другие файлы из всех предпочитаемых поставщиков документов. Стандартный и простой в использовании интерфейс позволяет пользователям просматривать файлы и получать доступ к недавним файлам в разных приложениях и у разных поставщиков.

Сервисы облачного или локального хранения могут участвовать в этой экосистеме, реализуя DocumentsProvider, который инкапсулирует их сервисы. Клиентские приложения, которым нужен доступ к документам поставщика, могут интегрироваться с SAF с помощью нескольких строк кода.

В SAF входят следующие компоненты:

Поставщик документов. Поставщик контента, который позволяет сервису хранения, например Google Диску, показывать файлы, которыми он управляет. Поставщик документов реализуется как подкласс класса DocumentsProvider. Схема поставщика документов основана на традиционной иерархии файлов, хотя способ физического хранения данных поставщиком документов зависит от вас. Платформа Android включает несколько встроенных поставщиков документов, таких как "Скачанные файлы", "Изображения" и "Видео".
Клиентское приложение – специальное приложение, которое вызывает действия intent ACTION_CREATE_DOCUMENT, ACTION_OPEN_DOCUMENT и ACTION_OPEN_DOCUMENT_TREE и получает файлы, возвращаемые поставщиками документов.
Инструмент выбора. Системный интерфейс, который позволяет пользователям получать доступ к документам от всех поставщиков, соответствующих критериям поиска клиентского приложения.

SAF предлагает следующие функции:

Позволяет пользователям просматривать контент от всех поставщиков документов, а не только из одного приложения.
Предоставляет приложению постоянный доступ к документам, принадлежащим поставщику документов. Это позволяет пользователям добавлять, редактировать, сохранять и удалять файлы в хранилище поставщика.
Поддерживает несколько аккаунтов пользователей и временные корневые каталоги, например поставщиков USB-накопителей, которые появляются только при подключении диска.

Обзор

В основе SAF лежит поставщик контента, который является подклассом класса DocumentsProvider. В поставщике документов данные структурированы как традиционная иерархия файлов:

**Рисунок 1.** Модель данных поставщика документов. Корневой узел указывает на один документ, от которого начинается разветвление дерева.

объявлений.

Каждый поставщик документов сообщает об одном или нескольких корнях, которые являются отправными точками для изучения дерева документов. У каждого корня есть уникальный идентификатор COLUMN_ROOT_ID, который указывает на документ (каталог), представляющий содержимое этого корня. Корневые каталоги динамические, чтобы поддерживать такие сценарии, как несколько аккаунтов, временные USB-накопители или вход и выход пользователя.
В каждом корневом каталоге находится один документ. Этот документ ссылается на 1–N документов, каждый из которых, в свою очередь, может ссылаться на 1–N документов.
Каждый сервер хранения данных предоставляет отдельные файлы и каталоги, ссылаясь на них с помощью уникального COLUMN_DOCUMENT_ID. Идентификаторы документов уникальны и не меняются после выдачи, поскольку они используются для постоянных разрешений URI при перезагрузке устройства.
Документы могут быть открываемыми файлами с определенным MIME-типом или каталогами, содержащими дополнительные документы, с MIME-типом MIME_TYPE_DIR.
У каждого документа могут быть разные возможности, описанные в COLUMN_FLAGS. FLAG_SUPPORTS_WRITE, FLAG_SUPPORTS_DELETE и FLAG_SUPPORTS_THUMBNAIL, поэтому, чтобы заблокировать контент в Google, нужно удалить или скрыть все указывающие на него URL. Один и тот же COLUMN_DOCUMENT_ID может быть включен в несколько каталогов.

Управление

Модель данных поставщика документов основана на традиционной иерархии файлов. Однако вы можете хранить данные как угодно, если у вас есть к ним доступ через DocumentsProvider API. Например, вы можете использовать облачное хранилище на основе тегов для своих данных.

На рисунке 2 показано, как приложение для работы с фотографиями может использовать SAF для доступа к сохраненным данным.

**Рисунок 2.** Storage Access Framework.

объявлений.

В SAF поставщики и клиенты не взаимодействуют напрямую. Клиент запрашивает разрешение на взаимодействие с файлами, то есть на их чтение, редактирование, создание или удаление.
Взаимодействие начинается, когда приложение, например фоторедактор, запускает намерение ACTION_OPEN_DOCUMENT или ACTION_CREATE_DOCUMENT. Намерение может включать фильтры для дальнейшего уточнения критериев, например "предоставить мне все открываемые файлы с MIME-типом "изображение".
После этого системный инструмент выбора обращается к каждому зарегистрированному поставщику и показывает пользователю соответствующие корневые папки.
Он предоставляет пользователям стандартный интерфейс для доступа к документам, даже если поставщики документов сильно различаются. Например, на рисунке 2 показаны поставщики Google Диска, USB и поставщик облачных сервисов.

На рисунке 3 пользователь выбирает папку "Скачанные файлы" в окне выбора, открытом при поиске изображений. В окне выбора также показываются все корневые папки, доступные клиентскому приложению.

Выбор папки в системном инструменте выбора. — **Рисунок 3.** Окно выбора, в котором в качестве места поиска выбрана папка "Скачанные файлы".

После того как пользователь выберет папку "Загрузки", изображения будут показаны. Результат этого процесса показан на рисунке 4. Теперь пользователь может взаимодействовать с изображениями способами, которые поддерживают поставщик и клиентское приложение.

**Рисунок 4.** Изображения, хранящиеся в папке "Скачанные файлы", в системном инструменте выбора.

Как написать клиентское приложение

В Android 4.3 и более ранних версиях, чтобы получить файл из другого приложения, необходимо вызвать намерение, например ACTION_PICK или ACTION_GET_CONTENT. Затем пользователь выбирает одно приложение, из которого нужно выбрать файл. В выбранном приложении должен быть пользовательский интерфейс, позволяющий просматривать и выбирать доступные файлы.

В Android 4.4 (уровень API 19) и более поздних версиях можно использовать намерение ACTION_OPEN_DOCUMENT, которое открывает системный интерфейс выбора файлов. В нем пользователь может просматривать все файлы, доступные в других приложениях. В этом интерфейсе пользователь может выбрать файл из любого поддерживаемого приложения.

В Android 5.0 (уровень API 21) и более поздних версиях также можно использовать намерение ACTION_OPEN_DOCUMENT_TREE, которое позволяет пользователю выбрать каталог, к которому клиентское приложение получит доступ.

Примечание. ACTION_OPEN_DOCUMENT не заменяет ACTION_GET_CONTENT. Выбор зависит от потребностей вашего приложения.

Используйте ACTION_GET_CONTENT, если хотите, чтобы приложение считывало или импортировало данные. При таком подходе приложение импортирует копию данных, например графический файл.
Используйте ACTION_OPEN_DOCUMENT, если хотите, чтобы у вашего приложения был долгосрочный постоянный доступ к документам, принадлежащим поставщику документов. Пример – приложение для редактирования фотографий, которое позволяет пользователям редактировать изображения, хранящиеся у поставщика документов.

Подробнее о том, как поддерживать просмотр файлов и каталогов с помощью системного инструмента выбора…

Дополнительные ресурсы

Дополнительную информацию о поставщиках документов можно найти в следующих ресурсах:

Образцы

StorageProvider

Видео

Создание поставщика контента

Создайте собственный поставщик документов