Native Folder Access

1این قابلیت چه می‌کند#

این قابلیت به اپلیکیشن وب شما با استفاده از Storage Access Framework (SAF) دسترسی کنترل‌شده به یک پوشه Android انتخاب‌شده توسط کاربر می‌دهد. برای اپلیکیشن‌های HTML آفلاین، ویرایشگرها، جریان‌های پشتیبان‌گیری/بازیابی و ابزارهای ورود/خروج داده خوب کار می‌کند.

این به شما دسترسی نامحدود به حافظه دستگاه نمی‌دهد. کاربر صریحاً یک پوشه را انتخاب می‌کند و اپلیکیشن شما فقط داخل همان درخت مجاز می‌تواند کار کند.

2فعال‌سازی در سازنده#

در مرحله 4 سازنده، گزینه «Native Folder Access (SAF)» را روشن کنید. سپس اپلیکیشن را بسازید.

وقتی فعال باشد، وب‌سایت شما علاوه بر پل خام window.WebToApk یک کمک‌کننده سطح بالا در window.WebToApkFS هم دریافت می‌کند.

⚠️ نکته حافظه در Android 11+: در Android 11 و بالاتر، خواندن حافظه مشترک به مجوز ویژه «All Files Access» نیاز دارد. وقتی اپلیکیشن ساخته‌شده شما برای اولین بار اجرا می‌شود و مجوز حافظه فعال است، به‌طور خودکار صفحه تنظیمات 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);
}