إضافة الزر "حفظ في 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.