استخدام مكوّن Google Picker على الويب

يوفّر مكوّن الويب Google Picker طريقة إضافية لدمج Google Picker API في تطبيقات الويب.

يبسّط مكوّن الويب عملية دمج ميزة اختيار ملفات Google Drive في تطبيقات الويب. وهو يغلّف كل منطق تحميل واجهة برمجة التطبيقات والمصادقة الأساسي في عنصر HTML واحد. ويتيح لك إدراج علامة <drive-picker> مباشرةً في الرمز بدون الحاجة إلى كتابة منطق تحميل gapi. يمكن استخدامه في HTML وJavaScript العاديَين، كما أنّه لا يعتمد على أي إطار عمل، ويعمل بسلاسة مع Svelte وVue وAngular وغير ذلك.

لمزيد من المعلومات عن مكتبة مكوّنات الويب، يُرجى الاطّلاع على @googleworkspace/drive-picker-element.

بالنسبة إلى تطبيقات React، استخدِم حزمة غلاف React الرسمية لمكوّن الويب: @googleworkspace/drive-picker-react.

الميزات الرئيسية

• عملية دمج بسيطة: يمكنك إضافة Google Picker إلى تطبيقات الويب باستخدام بضعة أسطر من الرمز.
• لا يعتمد على أي إطار عمل: يعمل بسلاسة مع أي إطار عمل ويب تختاره (React أو Vue أو Angular أو غير ذلك).
• مفتوح المصدر وقابل للتخصيص: الرمز متاح مجانًا ويمكنك تخصيصه ليناسب احتياجاتك المحدّدة.
• توافق سلس مع OAuth: يتم التعامل مع مصادقة المستخدم تلقائيًا، ما يوفّر تجربة سلسة للمستخدم.
• طرق عرض قابلة للتخصيص: يمكنك ضبط Google Picker لعرض أنواع الملفات أو طرق العرض التي تحتاج إليها فقط من خلال ضبط السمات.

البدء

1. ثبِّت المكوّن باستخدام NPM أو ما شابه:

   npm i @googleworkspace/drive-picker-element

   يتوفّر أيضًا إصدار CDN. للاطّلاع على التنسيقات والإصدارات المتاحة، يُرجى الانتقال إلى unpkg.

   <script src="https://unpkg.com/@googleworkspace/drive-picker-element@latest/dist/index.iife.min.js"></script>
   

2. استورِد مكوّنات @googleworkspace/drive-picker-element في ملف JavaScript:

   import "@googleworkspace/drive-picker-element";
   

   لا يكون الاستيراد مطلوبًا إذا كنت تستخدم إصدار CDN لأنّه يحمّل تلقائيًا مكتبة Google Picker ومكتبة عميل Google API المستخدَمة للمصادقة.

3. أضِف العناصر المخصّصة إلى ملف HTML:

   <drive-picker>
       <drive-picker-docs-view></drive-picker-docs-view>
   </drive-picker>
   

   للاطّلاع على سمات وخصائص <drive-picker/> و<drive-picker-docs-view/>، يُرجى الرجوع إلى المستندات المرجعية الخاصة بـ @googleworkspace/drive-picker-element.

الفعاليات

يرسل العنصر <drive-picker/> الأحداث المخصّصة التالية:

الحدث	الوصف
picker-picked	يتم تنشيطه عندما يختار المستخدم عنصرًا واحدًا أو أكثر.
picker-canceled	يتم تنشيطه عندما يلغي المستخدم عملية الاختيار من خلال النقر على الزر "إلغاء" أو إغلاق مربّع الحوار بدون إجراء أي اختيار.
picker-error	يتم تنشيطه عند حدوث خطأ أثناء عملية التهيئة أو اختيار الملف.

لمزيد من المعلومات عن الأحداث، يُرجى الاطّلاع على @googleworkspace/drive-picker-element مستندات على NPM.

تفاصيل الحدث

بالنسبة إلى الحدث picker-picked، تحتوي تفاصيل الحدث على Google Picker ResponseObject الكامل.

{
  "type": "picker-picked",
  "detail": {
    "action": "PICKED",
    "docs": [
      {
        "id": ID,
        "mimeType": "application/pdf",
        "name": NAME,
        "url": "https://drive.google.com/file/d/ID/view?usp=drive_web",
        "sizeBytes": 12345
      }
    ]
  }
}

في ما يلي الخصائص الأكثر استخدامًا في عنصر الاستجابة:

• action: الإجراء الذي أدى إلى تنشيط معاودة الاتصال (على سبيل المثال، PICKED).
• docs: مصفوفة من DocumentObject التي اختارها المستخدم. يحتوي كل عنصر على خصائص مثل:
  • id: المعرّف الفريد للعنصر المحدّد.
  • mimeType: نوع MIME للعنصر.
  • name: اسم العنصر.
  • url: عنوان URL لفتح العنصر في Drive.
  • sizeBytes: حجم العنصر الذي تم اختياره بالبايت. لا يتم عرض القيمة عند تحميل عنصر.

بالنسبة إلى الحدث picker-error، يحتوي event.detail على عنصر خطأ أو سلسلة تصف المشكلة (على سبيل المثال، ERR_USER_NOT_AUTHENTICATED).

أمثلة

تعرض نماذج الرموز البرمجية التالية كيفية استخدام مكوّن الويب Google Picker لحالات الاستخدام الشائعة. لكل عينة تعليمات برمجية، استبدِل ما يلي:

• PROMPT: قائمة بفواصل مسافات بينها، وهي حساسة لحالة الأحرف، وتتضمّن طلبات تفويض حساب Google التي سيتم عرضها للمستخدم. لمزيد من المعلومات، يُرجى الاطّلاع على TokenClientConfig.prompt.

• ORIGIN: مَعلمة المصدر في أداة الاختيار. على سبيل المثال، https://developers.google.com. لمزيد من المعلومات، يُرجى الاطّلاع على PickerBuilder.setOrigin طريقة.

• APP_ID: معرّف تطبيق Drive. لمزيد من المعلومات، يُرجى الاطّلاع على الـ PickerBuilder.setAppId طريقة.

• CLIENT_ID: معرّف عميل OAuth 2.0. لمزيد من المعلومات، يُرجى الاطّلاع على استخدام بروتوكول OAuth 2.0 للدخول إلى Google APIs.

ملفات PDF

يتم فلترة طريقة العرض لعرض ملفات PDF فقط باستخدام السمة mime-types.

<drive-picker
  prompt="PROMPT"
  origin="ORIGIN"
  app-id="APP_ID"
  client-id="CLIENT_ID"
>
  <drive-picker-docs-view mime-types="application/pdf"></drive-picker-docs-view>
</drive-picker>

ملفات الصور والفيديو

يتم فلترة طريقة العرض لعرض ملفات الصور (JPEG وPNG) والفيديو (MP4 وQuickTime) فقط باستخدام السمة mime-types.

<drive-picker
  prompt="PROMPT"
  origin="ORIGIN"
  app-id="APP_ID"
  client-id="CLIENT_ID"
>
  <drive-picker-docs-view mime-types="image/jpeg,image/png,video/mp4,video/quicktime"></drive-picker-docs-view>
</drive-picker>

الملفات التي أملكها

يتم فلترة طريقة العرض لعرض الملفات التي يملكها المستخدم الحالي فقط باستخدام السمة owned-by-me.

<drive-picker
  prompt="PROMPT"
  origin="ORIGIN"
  app-id="APP_ID"
  client-id="CLIENT_ID"
>
  <drive-picker-docs-view owned-by-me="true"></drive-picker-docs-view>
</drive-picker>

طلب البحث عن الملفات التي ليس لها عنوان

يتم فلترة طريقة العرض لعرض الملفات التي تطابق طلب البحث "بلا عنوان" باستخدام السمة query.

<drive-picker
  prompt="PROMPT"
  origin="ORIGIN"
  app-id="APP_ID"
  client-id="CLIENT_ID"
>
  <drive-picker-docs-view query="Untitled"></drive-picker-docs-view>
</drive-picker>

الملفات المميّزة بنجمة

يتم فلترة طريقة العرض لعرض الملفات المميّزة بنجمة فقط باستخدام السمة starred.

<drive-picker
  prompt="PROMPT"
  origin="ORIGIN"
  app-id="APP_ID"
  client-id="CLIENT_ID"
>
  <drive-picker-docs-view starred="true"></drive-picker-docs-view>
</drive-picker>

مواضيع ذات صلة

• لمزيد من المعلومات التفصيلية عن السمات والأحداث والخصائص، يُرجى الاطّلاع على مستندات drive-picker-element الكاملة على GitHub.