PDF व्यूअर लागू करना

PdfViewerFragment एक खास तरह का Fragment है. इसका इस्तेमाल, Android ऐप्लिकेशन में PDF दस्तावेज़ दिखाने के लिए किया जा सकता है. PdfViewerFragment PDF रेंडरिंग को आसान बनाता है, ताकि आप अपने ऐप्लिकेशन के अन्य पहलुओं पर ध्यान दे सकें.

नतीजे

PdfViewerFragment का इस्तेमाल करके, Android ऐप्लिकेशन में रेंडर किया गया PDF दस्तावेज़.
किसी ऐप्लिकेशन में दिखाया गया PDF दस्तावेज़.

वर्शन के साथ काम करने की सुविधा

PdfViewerFragment का इस्तेमाल करने के लिए, आपके ऐप्लिकेशन को कम से कम Android S (एपीआई लेवल 31) और एसडीके एक्सटेंशन लेवल 13 को टारगेट करना होगा. अगर ये ज़रूरी शर्तें पूरी नहीं होती हैं, तो लाइब्रेरी UnsupportedOperationException दिखाती है.

SdkExtensions मॉड्यूल का इस्तेमाल करके, रनटाइम के दौरान एसडीके एक्सटेंशन के वर्शन की जांच की जा सकती है. इससे, डिवाइस के ज़रूरी शर्तें पूरी करने पर ही फ़्रैगमेंट और PDF दस्तावेज़ को लोड किया जा सकता है.

if (SdkExtensions.getExtensionVersion(Build.VERSION_CODES.S) >= 13) {
    // Load the fragment and document.
}

डिपेंडेंसी

अपने ऐप्लिकेशन में PDF व्यूअर को शामिल करने के लिए, अपने ऐप्लिकेशन के मॉड्यूल build.gradle फ़ाइल में androidx.pdf डिपेंडेंसी का एलान करें. PDF लाइब्रेरी को Google Maven रिपॉज़िटरी से ऐक्सेस किया जा सकता है.

dependencies {
    val pdfVersion = "1.0.0-alpha0X"
    implementation("androidx.pdf:pdf:pdf-viewer-fragment:$pdfVersion")
}

PdfViewerFragment सुविधाएं

PdfViewerFragment, PDF दस्तावेज़ों को पेज के हिसाब से दिखाता है. इससे उन्हें आसानी से नेविगेट किया जा सकता है. तेज़ी से लोड होने के लिए, फ़्रैगमेंट में दो पास वाली रेंडरिंग रणनीति का इस्तेमाल किया जाता है. इससे पेज के डाइमेंशन धीरे-धीरे लोड होते हैं.

मेमोरी के इस्तेमाल को ऑप्टिमाइज़ करने के लिए, PdfViewerFragment सिर्फ़ उन पेजों को रेंडर करता है जो फ़िलहाल दिख रहे हैं. साथ ही, यह उन पेजों के बिटमैप रिलीज़ करता है जो स्क्रीन पर नहीं हैं. इसके अलावा, PdfViewerFragment में फ़्लोटिंग ऐक्शन बटन (एफ़एबी) शामिल होता है. यह बटन, एनोटेशन की सुविधा देता है. इसके लिए, यह दस्तावेज़ के यूआरआई वाला android.intent.action.ANNOTATE इंटेंट ट्रिगर करता है.

लागू करना

अपने Android ऐप्लिकेशन में PDF व्यूअर जोड़ने के लिए, आपको कई चरण पूरे करने होंगे.

गतिविधि का लेआउट बनाना

सबसे पहले, उस गतिविधि के लिए लेआउट एक्सएमएल तय करें जो PDF व्यूअर को होस्ट करती है. लेआउट में FrameLayout शामिल होना चाहिए, ताकि इसमें PdfViewerFragment और उपयोगकर्ताओं के इंटरैक्शन के लिए बटन शामिल किए जा सकें. जैसे, दस्तावेज़ में खोजना.

<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/pdf_container_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:layout_gravity="center"
    android:orientation="vertical"
    tools:context=".MainActivity">

    <FrameLayout
        android:id="@+id/fragment_container_view"
        android:layout_width="0dp"
        android:layout_height="0dp"
        android:layout_marginBottom="8dp"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintTop_toTopOf="parent"/>

    <com.google.android.material.button.MaterialButton
        android:id="@+id/search_button"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/search_string"
        app:strokeWidth="1dp"
        android:layout_marginStart="8dp"
        android:layout_marginBottom="8dp"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent" />

</androidx.constraintlayout.widget.ConstraintLayout>

गतिविधि सेट अप करना

PdfViewerFragment को होस्ट करने वाली गतिविधि को AppCompatActivity तक बढ़ाना होगा. गतिविधि की onCreate() विधि में, कॉन्टेंट व्यू को बनाए गए लेआउट पर सेट करें. साथ ही, ज़रूरी यूज़र इंटरफ़ेस (यूआई) एलिमेंट को शुरू करें.

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        val getContentButton: MaterialButton = findViewById(R.id.launch_button)
        val searchButton: MaterialButton = findViewById(R.id.search_button)
    }
}

PdfViewerFragment शुरू करें

getSupportFragmentManager() से मिले फ़्रैगमेंट मैनेजर का इस्तेमाल करके, PdfViewerFragment का इंस्टेंस बनाएं. नया फ़्रैगमेंट बनाने से पहले, यह देख लें कि फ़्रैगमेंट का कोई इंस्टेंस पहले से मौजूद है या नहीं. खास तौर पर, कॉन्फ़िगरेशन में बदलाव करते समय ऐसा करें.

यहां दिए गए उदाहरण में, initializePdfViewerFragment() फ़ंक्शन, फ़्रैगमेंट ट्रांज़ैक्शन को बनाने और उसे कमिट करने का काम करता है. यह फ़ंक्शन, कंटेनर में मौजूद किसी फ़्रैगमेंट को आपके PdfViewerFragment के इंस्टेंस से बदलता है.

class MainActivity : AppCompatActivity() {
    @RequiresExtension(extension = Build.VERSION_CODES.S, version = 13)
    private var pdfViewerFragment: PdfViewerFragment? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        // ...

        if (pdfViewerFragment == null) {
            pdfViewerFragment =
                supportFragmentManager
                    .findFragmentByTag(PDF_VIEWER_FRAGMENT_TAG) as PdfViewerFragment?
        }

    }

    // Used to instantiate and commit the fragment.
    @RequiresExtension(extension = Build.VERSION_CODES.S, version = 13)
    private fun initializePdfViewerFragment() {
        // This condition can be skipped if you want to create a new fragment every time.
        if (pdfViewerFragment == null) {
            val fragmentManager: FragmentManager = supportFragmentManager

          // Fragment initialization.
          pdfViewerFragment = PdfViewerFragmentExtended()
          val transaction: FragmentTransaction = fragmentManager.beginTransaction()

          // Replace an existing fragment in a container with an instance of a new fragment.
          transaction.replace(
              R.id.fragment,4_container_view,
              pdfViewerFragment!!,
              PDF_VIEWER_FRAGMENT_TAG
          )
          transaction.commitAllowingStateLoss()
          fragmentManager.executePendingTransactions()
        }
    }

    companion object {
        private const val MIME_TYPE_PDF = "application/pdf"
        private const val PDF_VIEWER_FRAGMENT_TAG = "pdf_viewer_fragment_tag"
    }
}

PdfViewerFragment की अवधि बढ़ाना

PdfViewerFragment ऐसे सार्वजनिक फ़ंक्शन दिखाता है जिन्हें इसकी क्षमताओं को बढ़ाने के लिए बदला जा सकता है. PdfViewerFragment से इनहेरिट करने वाली नई क्लास बनाएं. अपनी सबक्लास में, onLoadDocumentSuccess() और onLoadDocumentError() जैसे तरीकों को बदलें, ताकि कस्टम लॉजिक जोड़ा जा सके. जैसे, मेट्रिक लॉग करना.

@RequiresExtension(extension = Build.VERSION_CODES.S, version = 13)
class PdfViewerFragmentExtended : PdfViewerFragment() {
          private val someLogger : SomeLogger = // ... used to log metrics

          override fun onLoadDocumentSuccess() {
                someLogger.log(/** log document success */)
          }

          override fun onLoadDocumentError(error: Throwable) {
                someLogger.log(/** log document error */, error)
          }
}

PdfViewerFragment में पहले से मौजूद खोज मेन्यू शामिल नहीं है. हालांकि, इसमें खोज बार की सुविधा उपलब्ध है. isTextSearchActive API का इस्तेमाल करके, खोज बार के दिखने की सेटिंग को कंट्रोल किया जाता है. दस्तावेज़ खोजने की सुविधा चालू करने के लिए, आपको अपने PdfViewerFragment इंस्टेंस की isTextSearchActive प्रॉपर्टी सेट करनी होगी.

WindowCompat.setDecorFitsSystemWindows() का इस्तेमाल करें, ताकि यह पक्का किया जा सके कि WindowInsetsCompat को कॉन्टेंट व्यू में सही तरीके से पास किया गया है. यह सर्च व्यू को सही जगह पर रखने के लिए ज़रूरी है.

class MainActivity : AppCompatActivity() {
    @RequiresExtension(extension = Build.VERSION_CODES.S, version = 13)
    override fun onCreate(savedInstanceState: Bundle?) {
        // ...
        searchButton.setOnClickListener {
            pdfViewerFragment?.isTextSearchActive =
                pdfViewerFragment?.isTextSearchActive == false
        }

        // Ensure WindowInsetsCompat are passed to content views without being
        // consumed by the decor view. These insets are used to calculate the
        // position of the search view.
        WindowCompat.setDecorFitsSystemWindows(window, false)
    }
}

फ़ाइल पिकर के साथ इंटिग्रेट करना

उपयोगकर्ताओं को अपने डिवाइस से PDF फ़ाइलें चुनने की अनुमति देने के लिए, Android फ़ाइल पिकर के साथ PdfViewerFragment को इंटिग्रेट करें. सबसे पहले, अपनी ऐक्टिविटी के लेआउट एक्सएमएल को अपडेट करें, ताकि फ़ाइल पिकर लॉन्च करने वाला बटन शामिल किया जा सके.

<...>
    <FrameLayout
        ...
        app:layout_constraintBottom_toTopOf="@+id/launch_button"/>
    // Adding a button to open file picker.
    <com.google.android.material.button.MaterialButton
        android:id="@+id/launch_button"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/launch_string"
        app:strokeWidth="1dp"
        android:layout_marginEnd="8dp"
        android:layout_marginBottom="8dp"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintEnd_toStartOf="@id/search_button"/>

    <com.google.android.material.button.MaterialButton
        ...
        app:layout_constraintStart_toEndOf="@id/launch_button" />

</androidx.constraintlayout.widget.ConstraintLayout>

इसके बाद, अपनी गतिविधि में, फ़ाइल पिकर लॉन्च करने के लिए registerForActivityResult(GetContent()) का इस्तेमाल करें. जब उपयोगकर्ता कोई फ़ाइल चुनता है, तो कॉलबैक एक यूआरआई उपलब्ध कराता है. इसके बाद, इस यूआरआई की मदद से अपने PdfViewerFragment इंस्टेंस की documentUri प्रॉपर्टी सेट करें, ताकि चुनी गई PDF फ़ाइल लोड हो सके और उसे दिखाया जा सके.

class MainActivity : AppCompatActivity() {
    // ...

    private var filePicker: ActivityResultLauncher<String> =
        registerForActivityResult(GetContent()) { uri: Uri? ->
            uri?.let {
                initializePdfViewerFragment()
                pdfViewerFragment?.documentUri = uri
            }
        }

    override fun onCreate(savedInstanceState: Bundle?) {
        // ...
        getContentButton.setOnClickListener { filePicker.launch(MIME_TYPE_PDF) }
    }

    private fun initializePdfViewerFragment() {
        // ...
    }

    companion object {
        private const val MIME_TYPE_PDF = "application/pdf"
        // ...
    }
}

यूज़र इंटरफ़ेस (यूआई) को पसंद के मुताबिक बनाना

लाइब्रेरी के दिखाए गए एक्सएमएल एट्रिब्यूट को बदलकर, PdfViewerFragment के यूज़र इंटरफ़ेस को अपनी पसंद के मुताबिक बनाया जा सकता है. इससे, स्क्रोलबार और पेज इंडिकेटर जैसे एलिमेंट को अपने ऐप्लिकेशन के डिज़ाइन के हिसाब से बनाया जा सकता है.

कस्टमाइज़ किए जा सकने वाले एट्रिब्यूट में ये शामिल हैं:

  • fastScrollVerticalThumbDrawable — इससे स्क्रोलबार थंब के लिए ड्रॉएबल सेट किया जाता है.
  • fastScrollPageIndicatorBackgroundDrawable — इससे पेज इंडिकेटर के लिए बैकग्राउंड ड्रॉएबल सेट किया जाता है.
  • fastScrollPageIndicatorMarginEnd — इससे पेज इंडिकेटर के लिए दायां मार्जिन सेट किया जाता है. पक्का करें कि मार्जिन की वैल्यू पॉज़िटिव हों.
  • fastScrollVerticalThumbMarginEnd — इससे वर्टिकल स्क्रोलबार थंब के लिए, दायां मार्जिन सेट किया जाता है. पक्का करें कि मार्जिन की वैल्यू पॉज़िटिव हों.

इन कस्टम सेटिंग को लागू करने के लिए, अपने एक्सएमएल संसाधनों में कस्टम स्टाइल तय करें.

<resources>
    <style name="pdfContainerStyle">
        <item name="fastScrollVerticalThumbDrawable">@drawable/custom_thumb_drawable</item>
        <item name="fastScrollPageIndicatorBackgroundDrawable">@drawable/custom_page_indicator_background</item>
        <item name="fastScrollVerticalThumbMarginEnd">8dp</item>
    </style>
</resources>

इसके बाद, PdfViewerFragment को कस्टम स्टाइल रिसॉर्स दें. इसके लिए, PdfStylingOptions का इस्तेमाल करें. ऐसा तब करें, जब PdfViewerFragment.newInstance(stylingOptions) की मदद से फ़्रैगमेंट का इंस्टेंस बनाया जा रहा हो.

private fun initializePdfViewerFragment() {
    // This condition can be skipped if you want to create a new fragment every time.
    if (pdfViewerFragment == null) {
      val fragmentManager: FragmentManager = supportFragmentManager

      // Create styling options.
      val stylingOptions = PdfStylingOptions(R.style.pdfContainerStyle)

      // Fragment initialization.
      pdfViewerFragment = PdfViewerFragment.newInstance(stylingOptions)

      // Execute fragment transaction.
    }
}

अगर आपने PdfViewerFragment को सबक्लास किया है, तो स्टाइलिंग के विकल्प देने के लिए, सुरक्षित कंस्ट्रक्टर का इस्तेमाल करें. इससे यह पक्का होता है कि आपके एक्सटेंड किए गए फ़्रैगमेंट पर, कस्टम स्टाइल सही तरीके से लागू हों.

class StyledPdfViewerFragment: PdfViewerFragment {

    constructor() : super()

    private constructor(pdfStylingOptions: PdfStylingOptions) : super(pdfStylingOptions)

    companion object {
        fun newInstance(): StyledPdfViewerFragment {
            val stylingOptions = PdfStylingOptions(R.style.pdfContainerStyle)
            return StyledPdfViewerFragment(stylingOptions)
        }
    }
}

लागू करने की प्रोसेस पूरी करना

यहां दिए गए कोड में, PdfViewerFragment को अपनी गतिविधि में लागू करने का पूरा उदाहरण दिया गया है. इसमें, फ़ाइल पिकर को शुरू करने, इंटिग्रेट करने, खोजने की सुविधा, और यूज़र इंटरफ़ेस (यूआई) को पसंद के मुताबिक बनाने का तरीका शामिल है.

class MainActivity : AppCompatActivity() {

    private var pdfViewerFragment: PdfViewerFragment? = null
    private var filePicker: ActivityResultLauncher<String> =
        registerForActivityResult(GetContent()) { uri: Uri? ->
            uri?.let {
                initializePdfViewerFragment()
                pdfViewerFragment?.documentUri = uri
            }
        }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        if (pdfViewerFragment == null) {
            pdfViewerFragment =
                supportFragmentManager
                   .findFragmentByTag(PDF_VIEWER_FRAGMENT_TAG) as PdfViewerFragment?
        }

        val getContentButton: MaterialButton = findViewById(R.id.launch_button)
        val searchButton: MaterialButton = findViewById(R.id.search_button)

        getContentButton.setOnClickListener { filePicker.launch(MIME_TYPE_PDF) }
        searchButton.setOnClickListener {
            pdfViewerFragment?.isTextSearchActive = pdfViewerFragment?.isTextSearchActive == false
        }
    }

    private fun initializePdfViewerFragment() {
        // This condition can be skipped if you want to create a new fragment every time.
        if (pdfViewerFragment == null) {
            val fragmentManager: FragmentManager = supportFragmentManager

          // Create styling options.
          // val stylingOptions = PdfStylingOptions(R.style.pdfContainerStyle)

          // Fragment initialization.
          // For customization:
          // pdfViewerFragment = PdfViewerFragment.newInstance(stylingOptions)
          pdfViewerFragment = PdfViewerFragmentExtended()
          val transaction: FragmentTransaction = fragmentManager.beginTransaction()

          // Replace an existing fragment in a container with an instance of a new fragment.
          transaction.replace(
              R.id.fragment_container_view,
              pdfViewerFragment!!,
              PDF_VIEWER_FRAGMENT_TAG
          )
          transaction.commitAllowingStateLoss()
          fragmentManager.executePendingTransactions()
        }
    }

    companion object {
        private const val MIME_TYPE_PDF = "application/pdf"
        private const val PDF_VIEWER_FRAGMENT_TAG = "pdf_viewer_fragment_tag"
    }
}

कोड के बारे में अहम जानकारी

  • पक्का करें कि आपका प्रोजेक्ट, एपीआई लेवल और एसडीके एक्सटेंशन की ज़रूरी शर्तों को पूरा करता हो.
  • PdfViewerFragment को होस्ट करने वाली ऐक्टिविटी को AppCompatActivity तक बढ़ाना होगा.
  • कस्टम व्यवहार जोड़ने के लिए, PdfViewerFragment को बढ़ाया जा सकता है.
  • एक्सएमएल एट्रिब्यूट को ओवरराइड करके, PdfViewerFragment के यूज़र इंटरफ़ेस (यूआई) को पसंद के मुताबिक बनाएं.