إضافة الزر "حفظ في 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 للبيانات وعناوين URL التي تتضمّن file://.
    • بسبب سياسة المصدر نفسه في المتصفّح، يجب عرض عنوان 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 App Engine.

لمزيد من المعلومات، يُرجى الرجوع إلى مستندات الخادم حول كيفية تفعيل 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 ميغابايت، من المحتمل أنّ الخادم لا يعرض Content-Range، ومن المرجّح أنّها مشكلة CORS.