إضافة الزر "حفظ في 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 من النطاق والنطاق الفرعي وال بروتوكول نفسهما المستخدَمَين في النطاق الذي يتم استضافة الزر عليه. يجب استخدام بروتوكولات متطابقة بين الصفحة ومصدر البيانات.
  • لا يمكن استخدام عناوين URL الخاصة بالبيانات وعناوين 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" في عنصر آخر لجعل التنسيق الأولي يبدو مشابهًا للتنسيق النهائي.

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

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

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

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

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

إذا كان الزر "حفظ في 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) من أي نطاق، أو يمكن بدلاً من ذلك تحديد النطاقات التي يمكنها الوصول إلى المورد من خلال مشاركة الموارد المتعدّدة المصادر، مثل 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.