إضافة الزر "حفظ في Drive"

يسمح الزر "حفظ في Drive" للمستخدمين بحفظ الملفات في Drive من موقعك الإلكتروني. على سبيل المثال، لنفترض أن موقعك على الويب يدرج العديد من كتيبات التعليمات (ملفات PDF) التي يمكن للمستخدمين تنزيلها. يمكن وضع الزر "حفظ في Drive" بجانب كل دليل، ما يسمح للمستخدمين بحفظ الكتيبات في "ملفاتي".

وعندما ينقر المستخدم على الزر، يتم تنزيل الملف من مصدر البيانات وتحميله إلى Google Drive عند استلام البيانات. وبما أنّ عملية التنزيل تتم في سياق متصفّح المستخدم، تسمح هذه العملية للمستخدِم بمصادقة إجراء حفظ الملفات باستخدام جلسة المتصفّح المحدّدة.

المتصفحات المعتمدة

يتوافق زر "حفظ في Drive" مع هذه المتصفّحات.

إضافة الزر "حفظ في Drive" إلى الصفحة

لإنشاء مثيل للزر "حفظ في Drive"، أضف النص البرمجي التالي إلى صفحة الويب:

<script src="https://apis.google.com/js/platform.js" async defer></script>
<div class="g-savetodrive"
   data-src="//example.com/path/to/myfile.pdf"
   data-filename="My Statement.pdf"
   data-sitename="My Company Name">
</div>

المكان:

  • class هي معلَمة مطلوبة يجب ضبطها على g-savetodrive إذا كنت تستخدم علامة HTML عادية.

  • data-src هي معلَمة مطلوبة تحتوي على عنوان URL للملف المطلوب حفظه.

    • يمكن أن تكون عناوين URL مطلقة أو نسبية.
    • يمكن عرض عنوان URL الخاص بـ data-src من النطاق والنطاق الفرعي والبروتوكول نفسها المستخدَمة في النطاق الذي يستضيف الزر. يجب عليك استخدام البروتوكولات المتطابقة بين الصفحة ومصدر البيانات.
    • معرّفات الموارد المنتظمة (URI) للبيانات وfile:// من عناوين URL غير متوافقة.
    • بسبب سياسة المصدر نفسها للمتصفِّح، يجب عرض عنوان URL هذا من النطاق نفسه للصفحة التي يتم وضعه عليها، أو يجب أن يكون الوصول إليه متاحًا باستخدام ميزة "مشاركة الموارد المتعدّدة المصادر" (CORS). إذا كان الزر والمورد في نطاقين مختلفين، يُرجى الرجوع إلى التعامل مع الأزرار والموارد في نطاقات مختلفة.(#domain).
    • لعرض الملف عند عرض كل من http وhttps الصفحة نفسها، حدِّد المورد بدون بروتوكول مثل data-src="//example.com/files/file.pdf" الذي يستخدم البروتوكول المناسب استنادًا إلى كيفية الوصول إلى صفحة الاستضافة.
  • data-filename هي معلمة مطلوبة تحتوي على الاسم المستخدم لملف الحفظ.

  • data-sitename هي معلَمة مطلوبة تحتوي على اسم الموقع الإلكتروني الذي يوفّر الملف.

يمكنك وضع هذه السمات على أي عنصر HTML. ومع ذلك، فإنّ العناصر الأكثر استخدامًا هي div أو span أو button. ويتم عرض كل عنصر من هذه العناصر بشكل مختلف قليلاً أثناء تحميل الصفحة لأنّ المتصفّح يعرض العنصر قبل أن يعرض رمز JavaScript "الحفظ في Drive" العنصر.

يجب تحميل هذا النص البرمجي باستخدام بروتوكول HTTPS ويمكن تضمينه من أي موضع على الصفحة بدون قيود. يمكنك أيضًا تحميل النص البرمجي بشكل غير متزامن لتحسين الأداء

استخدام أزرار متعددة في الصفحة

يمكنك وضع أزرار "حفظ في Drive" متعددة على الصفحة نفسها. على سبيل المثال، قد يكون لديك زر في الجزء العلوي وأسفل صفحة طويلة.

إذا كانت المعلمتان data-src وdata-filename متطابقتين مع عدة أزرار، يؤدي الحفظ باستخدام زر واحد إلى عرض معلومات مستوى التقدّم نفسها في جميع الأزرار المتشابهة. إذا تم النقر فوق عدة أزرار مختلفة، فسيتم حفظها بشكل تسلسلي.

التعامل مع الأزرار والموارد في نطاقات مختلفة

إذا كان زر "حفظ في Drive" على صفحة منفصلة عن مصدر البيانات، يجب أن يستخدم طلب حفظ الملف مشاركة الموارد المتعدّدة المصادر (CORS) للوصول إلى المورد. CORS هي آلية تسمح لتطبيق ويب في نطاق ما بالوصول إلى الموارد من خادم في نطاق مختلف.

على سبيل المثال، إذا تم وضع زر "حفظ في Drive" على صفحة على العنوان http://example.com/page.html وتم تحديد مصدر البيانات على أنّه data-src="https://otherserver.com/files/file.pdf"، لن يتمكّن الزر من الوصول إلى ملف PDF ما لم يكن بإمكان المتصفّح استخدام سياسة مشاركة الموارد المتعددة المصادر (CORS) للوصول إلى المورد.

يمكن عرض عنوان URL data-src من نطاق آخر، ولكن يجب أن تتوافق الاستجابات من خادم HTTP مع طلبات HTTP OPTION وتضمين عناوين HTTP الخاصة التالية:

Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Range
Access-Control-Expose-Headers: Cache-Control, Content-Encoding, Content-Range

يمكن أن تتضمن Access-Control-Allow-Origin القيمة * للسماح بسياسة CORS من أي نطاق أو يمكنها بدلاً من ذلك تحديد النطاقات التي يمكنها الوصول إلى المورد عبر CORS، مثل http://example.com/page.html. إذا لم يكن لديك خادم لاستضافة المحتوى، يمكنك استخدام محرك تطبيقات Google.

لمزيد من المعلومات، يمكنك مراجعة مستندات الخادم حول كيفية تفعيل سياسة مشاركة الموارد المتعددة المصادر (CORS) من المصدر الذي يعرض الزر "حفظ في Drive". لمزيد من المعلومات حول تمكين خادمك لـ CORS، راجع أريد إضافة دعم CORS إلى خادمي.

JavaScript API

يحدّد رمز JavaScript لزر "الحفظ في Drive" دالتَين لعرض الزرّ ضمن مساحة الاسم gapi.savetodrive. إذا أوقفت العرض التلقائي، يجب طلب إحدى هذه الدوال من خلال ضبط السمة parsetags على السمة explicit.

الطريقة الوصف
gapi.savetodrive.render(
container,
parameters
)
عرض الحاوية المحدّدة كأداة للزر "حفظ في Drive"
الحاوية
الحاوية المطلوب عرضها كزر "الحفظ في Drive" حدِّد رقم تعريف الحاوية (سلسلة) أو عنصر DOM نفسه.
المَعلَمات
عنصر يحتوي على سمات العلامة "حفظ في Drive" على أنّه أزواج المفتاح=القيمة، بدون بادئات data-. مثلاً: {"src": "//example.com/path/to/myfile.pdf", "filename": "My Statement.pdf", "sitename": "My Company Name"}
gapi.savetodrive.go(
opt_container
)
عرض جميع علامات "الحفظ في Drive" والفئات في الحاوية المحدّدة. يجب استخدام هذه الدالة فقط في حال ضبط parsetags على explicit، وهو ما قد تستخدمه لأسباب متعلقة بالأداء.
opt_container
الحاوية التي تحتوي على علامات الزر "حفظ في Drive" لعرضها. حدِّد رقم تعريف الحاوية (سلسلة) أو عنصر DOM نفسه. في حال حذف المعلَمة opt_container، يتم عرض جميع علامات "الحفظ في Drive" على الصفحة.

مثال على JavaScript "حفظ في Drive" مع تحميل صريح

<!DOCTYPE html>
    <html>
      <head>
        <title>Save to Drive Demo: Explicit Load</title>
        <link rel="canonical" href="http://www.example.com">
        <script src="https://apis.google.com/js/platform.js" async defer>
          {parsetags: 'explicit'}
        </script>
      </head>
      <body>
        <div id="container">
          <div class="g-savetodrive"
             data-src="//example.com/path/to/myfile.pdf"
             data-filename="My Statement.pdf"
             data-sitename="My Company Name">
          <div>
        </div>
        <script type="text/javascript">
          gapi.savetodrive.go('container');
        </script>
      </body>
    </html>

مثال على رمز JavaScript "الحفظ في Drive" مع عرض فاضح

    <!DOCTYPE html>
    <html>
      <head>
        <title>Save to Drive Demo: Explicit Render</title>
        <link rel="canonical" href="http://www.example.com">
        <script>
          window.___gcfg = {
            parsetags: 'explicit'
          };
        </script>
        <script src="https://apis.google.com/js/platform.js" async defer></script>
      </head>
      <body>
        <a href="javascript:void(0)" id="render-link">Render the Save to Drive button</a>
        <div id="savetodrive-div"></div>
        <script>
          function renderSaveToDrive() {
            gapi.savetodrive.render('savetodrive-div', {
              src: '//example.com/path/to/myfile.pdf',
              filename: 'My Statement.pdf',
              sitename: 'My Company Name'
            });
          }
          document.getElementById('render-link').addEventListener('click', renderSaveToDrive);
        </script>
      </body>
    </html>

ترجمة الزر "حفظ في Drive"

إذا كانت صفحة الويب تتيح لغة معيّنة، اضبط المتغيّر window.___gcfg.lang على تلك اللغة. وفي حال تركها بدون ضبط، يتم استخدام لغة Google Drive للمستخدم.

وللاطّلاع على قيم رموز اللغات المتاحة، يمكنك الاطّلاع على قائمة رموز اللغات المتوافقة.

    <!DOCTYPE html>
    <html>
      <head>
        <title>Save to Drive Demo: Async Load with Language</title>
        <link rel="canonical" href="http://www.example.com">
      </head>
      <body>
        <div class="g-savetodrive"
             data-src="//example.com/path/to/myfile.pdf"
             data-filename="My Statement.pdf"
             data-sitename="My Company Name">
        </div>

        <script type="text/javascript">
          window.___gcfg = {
            lang: 'en-US'
          };
        </script>
        <script src = 'https://apis.google.com/js/platform.js' async defer></script>

      </body>
    </html>

تحديد المشاكل وحلّها

إذا ظهر لك خطأ XHR عند تنزيل عنوان URL الخاص بـ data-src، تأكَّد من أنّ المورد متوفّر فعلاً وأنّه ليس لديك مشكلة CORS.

وفي حال اقتطاع الملفات الكبيرة إلى 2 ميغابايت، من المحتمل أنّ الخادم لا يعرض نطاق المحتوى، ويُحتمل أن تكون المشكلة في CORS.