عارض ملفات PDF على Android

توفّر مكتبة عارض ملفات PDF في Jetpack، المدعومة من خلال واجهات برمجة التطبيقات الخاصة بإطار العمل، حلاً جاهزًا وعالي الأداء للتطبيقات ذات الصلة بمستندات PDF على Android.

توفّر مكتبة عارض ملفات PDF (androidx.pdf) واجهة مستخدم مدمجة لعارض ملفات PDF تتيح للمستخدمين إجراء ما يلي:

  • فتح مستندات PDF وعرضها
  • البحث عن المحتوى واختياره
  • التكبير والتصغير والتمرير
  • حفظ التعليقات التوضيحية في المستند
  • التفاعل مع ملفات PDF باستخدام قلم شاشة

يمكنك إنشاء تجربة PDF كاملة الميزات من خلال دمج واجهات برمجة التطبيقات الخاصة بمكتبة Jetpack أو استخدام واجهات برمجة التطبيقات الخاصة بإطار العمل مباشرةً.

مكتبة Jetpack PDF

توفّر مكتبة PDF في Jetpack الفئة PdfViewerFragment التي تعرض مستندات PDF، بما في ذلك مستندات PDF المقسّمة إلى صفحات. يتم عرض كل صفحة في طريقة عرض خاصة بها. تعرض PdfViewerFragment زر إجراء عائمًا لإتاحة التعليقات التوضيحية، ويتضمّن عادةً زرًا أو عنصر تحكّم آخر في واجهة المستخدم يفتح قائمة بحث.

للتعرّف على كيفية تنفيذ PdfViewerFragment، راجِع مقالة تنفيذ قارئ ملفات PDF.

Framework APIs

تستخدم مكتبة Jetpack واجهات برمجة تطبيقات إطار العمل لتحليل مستندات PDF وتحميلها. توفّر PdfRenderer واجهات برمجة التطبيقات الأساسية لإطار العمل المرتبطة بعرض ملفات PDF.

قبل الإصدار V من نظام التشغيل Android (المستوى 35 من واجهة برمجة التطبيقات)، كانت الفئتان PdfRenderer وPdfRenderer.Page توفّران واجهات برمجة التطبيقات للتعامل مع ملفات PDF. تم تعديل الفئتين PdfRenderer وPdfRenderer.Page في Android V لتوفير إمكانات متقدّمة لملفات PDF.

PdfRenderer

واجهات برمجة التطبيقات قبل الإصدار V من نظام التشغيل Android

  • ‫getPageCount(): تعرض عدد الصفحات في المستند.
  • openPage(index: Int): لفتح صفحة للعرض
  • ‫shouldScaleForPrinting(): تعرض ما إذا كان يجب تغيير حجم المستند لطباعته. يجب أخذ هذه المعلومات في الاعتبار إذا كان المستند معروضًا للطباعة وكان حجم الوسائط المستهدَف يختلف عن حجم الصفحة.

واجهات برمجة التطبيقات التي تمت إضافتها في Android V

  • PdfRenderer(fileDescriptor: ParcelFileDescriptor, params: LoadParams) — تنشئ هذه الدالة مثيلاً جديدًا. إمكانية تحميل ملفات PDF محمية بكلمة مرور
  • ‫getDocumentLinearizedType(): تعرض هذه السمة نوع المستند الذي تم تحويله إلى تنسيق خطي لملفات PDF التي يقل حجمها عن كيلوبايت واحد.
  • ‫getPdfFormType(): تعرض نوع النموذج لملف PDF الذي تم تحميله.
  • ‫write(destination: ParcelFileDescriptor, removePasswordProtection: Boolean): يحفظ حالة المستند الذي تم تحميله حاليًا في واصف الملف القابل للكتابة الذي تم تمريره كوسيطة.

PdfRenderer.Page

يمثّل الفئة PdfRenderer.Page صفحة مستند PDF للعرض.

واجهات برمجة التطبيقات قبل الإصدار V من نظام التشغيل Android

  • ‫RENDER_MODE_FOR_DISPLAY: وضع لعرض المحتوى على الشاشة.
  • ‫RENDER_MODE_FOR_PRINT: الوضع الذي يتم فيه عرض المحتوى للطباعة
  • ‫getIndex(): للحصول على فهرس الصفحة.
  • ‫getWidth(): للحصول على عرض الصفحة بالنقاط (1/72 من البوصة).
  • ‫getHeight(): للحصول على ارتفاع الصفحة بالنقاط (1/72 من البوصة).
  • ‫render(destination: Bitmap, destClip: Rect?, transform: Matrix?, renderMode: Int): تعرض صفحة كصورة نقطية.

واجهات برمجة التطبيقات التي تمت إضافتها في Android V

  • applyEdit(editRecord: FormEditRecord): يطبّق FormEditRecord على ملف PDF.
  • ‫getFormWidgetInfos(): تعرض معلومات عن جميع أدوات النموذج على الصفحة.
  • ‫getFormWidgetInfos(types: IntArray) — لعرض معلومات حول جميع عناصر واجهة المستخدم الخاصة بالنماذج من الأنواع المحدّدة على الصفحة.
  • getFormWidgetInfoAtIndex(widgetIndex: Int): لعرض معلومات عن التطبيق المصغّر الذي تحدّده الوسيطة widgetIndex.
  • fun getFormWidgetInfoAtPosition(x: Int, y: Int): لعرض معلومات حول التطبيق المصغّر عند النقطة المحدّدة.
  • getGotoLinks(): للحصول على الإشارات المرجعية وروابط الانتقال إلى صفحة أخرى المتوفّرة في صفحة مستند PDF
  • getImageContents(): تعرض هذه السمة قائمة بـ PdfPageImageContent التي تم العثور عليها في الصفحة.
  • ‫getLinkContents(): للحصول على حدود جميع الروابط وعناوين URL الخاصة بها على الصفحة.
  • getTextContents(): تعرض قائمة PdfPageTextContent على الصفحة.
  • ‫render(destination: Bitmap, destClip: Rect?, transform: Matrix?, params: RenderParams): تعرض صفحة كصورة نقطية.
  • ‫searchText(query: String): يبحث في الصفحة عن السلسلة المحدّدة ويعرض حدود جميع النتائج المطابقة.
  • selectContent(start: SelectionBoundary, stop: SelectionBoundary) — تعرض هذه السمة PageSelection الذي يمثّل المحتوى بين الحدّين.

استخدام واجهة برمجة التطبيقات

  • تكتب واجهة برمجة التطبيقات PdfRenderer#write() نسخة من ملف PDF الذي تم تحميله إلى ParcelFileDescriptor. تشمل حالات الاستخدام ما يلي:

    • حفظ نسخة من مستند PDF بعد إزالة الحماية بكلمة مرور
    • حفظ التعديلات (التعليقات التوضيحية، وملء النماذج، وما إلى ذلك)

  • تعرض واجهات برمجة التطبيقات PdfRenderer.Page#render() صفحة أو جزءًا من صفحة في صورة نقطية. في حال التكبير، يمكن أيضًا استخدام واجهة برمجة التطبيقات لعرض جزء من الصفحة في صورة نقطية بحجم معيّن.

  • تعرض واجهات برمجة التطبيقات PdfRenderer.Page وgetImageContents() وgetLinkContents() وgetTextContents() المحتوى المتاح على الصفحة. يمكنك استخدام المحتوى لأغراض تسهيل الاستخدام وإعلانات TalkBack أو في الميزات المستندة إلى الذكاء الاصطناعي، مثل إنشاء ملخّص للصفحة.

  • تختار واجهة برمجة التطبيقات PdfRenderer.Page#selectContent المحتوى المتاح على إحدى الصفحات. يمكنك استخدام المحتوى المحدّد لتنفيذ إجراءات مثل ما يلي:

    • الاتصال، إذا كان رقم هاتف
    • "خرائط Google"، في حال اختيار عنوان
    • نسخ
    • مشاركة
    • التعليقات

التوافق

يعرض الصف PdfRendererPreV واجهات برمجة التطبيقات Android V على الإصدارات من Android R إلى U (المستويات 30 إلى 34 لواجهة برمجة التطبيقات).

مراجع إضافية

اطّلِع على تنفيذ عارض ملفات PDF للتعرّف على كيفية إضافة عارض ملفات PDF إلى تطبيقك.