Справочная документация по Pickers

Средства выбора файлов и каталогов разделяются на страницы PickerPage и диалоги PickerDialog. Они разработаны специально для приложений ОС Аврора.

В ОС Аврора приложения работают в изолированной среде (песочнице) и не имеют прямого доступа ко всей файловой системе устройства. Это сделано в целях безопасности и конфиденциальности данных пользователя. Чтобы приложение могло получить доступ к файлу, пользователь должен явно разрешить это действие через системный интерфейс. Эту задачу решают компоненты Pickers (средства выбора). Они предоставляют стандартизированный, привычный для пользователя UI и гарантируют, что приложение получит доступ только к тем файлам, которые были явно выбраны. Использование системных пикеров также избавляет разработчика от необходимости самостоятельно реализовывать навигацию по файловой системе, фильтрацию по MIME-типам и обработку системных разрешений.

Средства выбора файлов и каталогов используются вместе со стеком страниц PageStack. Тип PageStack определяет жизненный цикл средства выбора при условии, что оно не создаётся каким-либо другим способом.

Рекомендуется добавлять средство выбора файлов и каталогов в PageStack в виде компонента или URL. После этого объект PageStack сможет управлять его жизненным циклом. Каждое средство выбора файлов и каталогов перед удалением возвращает выбранные элементы. При этом не имеет значения, выбирается один или несколько элементов.

Страницы для выбора файлов

Типы PickerPage представляют собой страницы и позволяют выбирать один файл за раз. Они интегрируются в общий стек навигации приложения, занимая весь экран, что удобно для глубокой навигации по директориям или выбора медиафайлов с предпросмотром.

Диалоги для выбора файлов

Типы PickerDialog представляют собой диалоги и позволяют выбирать сразу несколько файлов. Они открываются поверх текущей страницы в виде модального окна, не занимая весь экран.

Рекомендации

При интеграции любых средств выбора (Pickers) в приложение рекомендуется придерживаться следующих лучших практик:

1. Обязательная обработка отмены действия Пользователь может прервать операцию выбора в любой момент, нажав системную кнопку "Назад" или выполнив соответствующий свайп. В этом случае сигналы подтверждения (например, accepted или selectedContentPropertiesChanged) не срабатывают. Логика приложения должна быть готова к тому, что после возврата на страницу состояние не изменится. Не следует полагаться на то, что пикер всегда вернет результат; необходимо предусматривать сценарий отмены.

2. Использование url вместо filePath в QML При передаче путей к выбранным файлам в QML-компоненты (такие как Image, MediaPlayer, WebView) настоятельно рекомендуется использовать поле url из свойств пикера, а не filePath. Формат URI (file:///...) корректно обрабатывает специальные символы, пробелы и национальные алфавиты в именах файлов, что предотвращает ошибки парсинга путей. Свойство filePath (сырой строковый путь) следует использовать при передаче данных в C++-часть приложения или при работе с классами QFile и QDir.

3. Проверка актуальности файла Между моментом выбора файла в пикере и моментом его фактического использования в приложением может пройти время. Пользователь может удалить, переместить или переименовать файл. Перед открытием документа через QFile::open() следует проверять его возвращаемый статус.