Доступ к нативной папке

1Что делает эта функция#

Эта функция даёт вашему веб-приложению контролируемый доступ к одной выбранной пользователем папке Android через Storage Access Framework (SAF). Она хорошо подходит для офлайн-HTML-приложений, редакторов, сценариев резервного копирования и восстановления, а также инструментов импорта и экспорта.

Это НЕ даёт неограниченного доступа к хранилищу устройства. Пользователь явно выбирает одну папку, и ваше приложение может работать только внутри этого разрешённого дерева.

2Включите в генераторе#

На шаге 4 генератора ВКЛЮЧИТЕ «Native Folder Access (SAF)». Затем создайте приложение.

Когда функция включена, ваш сайт получает высокоуровневый помощник window.WebToApkFS в дополнение к «сырому» мосту window.WebToApk.

⚠️ Примечание о хранилище в Android 11+: в Android 11 и новее для чтения общего хранилища требуется специальное разрешение «Доступ ко всем файлам». Когда созданное приложение запускается в первый раз и разрешение на хранилище включено, оно автоматически открывает экран настроек Android, чтобы пользователь выдал это разрешение. Пользователю достаточно нажать переключатель в настройках и вернуться в приложение — переходить вручную никуда не нужно.

3Проверка возможностей, безопасная для браузера#

Всегда защищайте код, чтобы он продолжал работать в Chrome/Safari, где моста Android нет:

function canUseNativeFiles() {
  return !!(window.WebToApkFS && window.WebToApkFS.isAvailable());
}

if (canUseNativeFiles()) {
  console.log('Android native folder access available');
}

4Попросите пользователя выбрать папку#

Вызывайте requestAccess() по нажатию кнопки или другому понятному действию пользователя. Он открывает выбор папки Android и возвращает URI выбранной папки.

async function connectFolder() {
  const result = await window.WebToApkFS.requestAccess();
  if (!result.success) {
    alert('Folder access was not granted');
    return false;
  }
  console.log('Granted folder:', result.folderUri);
  return true;
}

5Основные операции с файлами#

Когда доступ предоставлен, вы можете просматривать папки, создавать каталоги, читать и записывать текстовые файлы, переименовывать и удалять записи.

// Create folders
window.WebToApkFS.mkdir('notes');
window.WebToApkFS.mkdir('notes/2026');

// Write a file
window.WebToApkFS.writeText('notes/2026/today.txt', 'Hello from offline app');

// Read it back
const text = window.WebToApkFS.readText('notes/2026/today.txt');
console.log(text);

// List folder contents
const entries = window.WebToApkFS.list('notes/2026');
console.log(entries);

6Переименование и удаление#

Переименование меняет только последнее имя записи. Удаление поддерживает как нерекурсивное, так и рекурсивное удаление каталогов.

// Rename file or folder
window.WebToApkFS.rename('notes/2026/today.txt', 'journal.txt');

// Delete a single file
window.WebToApkFS.delete('notes/2026/journal.txt');

// Delete a folder tree
window.WebToApkFS.delete('notes/2026', { recursive: true });

7Хорошие сценарии использования#

✅ Офлайн-приложения для заметок и дневников
✅ Инструменты импорта и экспорта CSV / JSON
✅ Простое локальное резервное копирование и восстановление
✅ Статические HTML-редакторы, сохраняющие пользовательский контент
✅ Приложения-дашборды, экспортирующие отчёты в виде текста или CSV

8Ограничения#

⚠️ Это только для Android. В обычных десктопных и мобильных браузерах его не будет.

⚠️ Текущий вспомогательный код рассчитан на списки папок и текстовые файлы. Для работы с бинарными файлами нужны дополнительные API.

⚠️ Доступ ограничен той единственной папкой, которую разрешил пользователь.

⚠️ Вызывайте эти API после загрузки страницы, чтобы вспомогательный код уже был внедрён.

9Полный рабочий пример#

В этом примере подключается папка, создаётся рабочий каталог, записывается JSON-файл и отображается список содержимого папки:

async function setupWorkspace() {
  if (!window.WebToApkFS || !window.WebToApkFS.isAvailable()) {
    console.log('Native folder access not available in this browser');
    return;
  }

  if (!window.WebToApkFS.hasAccess()) {
    const granted = await window.WebToApkFS.requestAccess();
    if (!granted.success) return;
  }

  window.WebToApkFS.mkdir('workspace');
  window.WebToApkFS.writeText(
    'workspace/config.json',
    JSON.stringify({ updatedAt: new Date().toISOString(), mode: 'offline' }, null, 2)
  );

  const files = window.WebToApkFS.list('workspace');
  document.getElementById('output').textContent = JSON.stringify(files, null, 2);
}