الوصول إلى مجلد أصلي

1ما الذي تفعله هذه الميزة#

تمنح هذه الميزة تطبيق الويب لديك وصولًا مضبوطًا إلى مجلد Android واحد يختاره المستخدم باستخدام Storage Access Framework (SAF). تناسب تطبيقات HTML بدون إنترنت والمحررات ومسارات النسخ الاحتياطي والاستعادة وأدوات الاستيراد والتصدير.

لا يمنح وصولًا غير مقيّد إلى تخزين الجهاز. يختار المستخدم مجلدًا واحدًا صراحةً، ولا يستطيع تطبيقك العمل إلا داخل تلك الشجرة الممنوحة.

2التفعيل في المولّد#

في الخطوة 4 من المولّد، فعّل 'الوصول إلى المجلدات الأصلية (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 فقط. لن يكون موجودًا في متصفحات سطح المكتب/الجوال العادية.

⚠️ الدالة المساعدة الحالية مصممة حول عرض المجلدات والملفات النصية. تحتاج مسارات العمل الثنائية إلى واجهات إضافية.

⚠️ يقتصر الوصول على المجلد الواحد الذي منحه المستخدم.

⚠️ استدعِ هذه الواجهات بعد تحميل الصفحة حتى تكون الدالة المساعدة قد حُقنت.

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);
}