שימוש ברכיב האינטרנט של כלי הבחירה של Google

רכיב האינטרנט Google Picker מציע דרך נוספת לשלב את Google Picker API באפליקציות האינטרנט שלכם.

רכיב האינטרנט מפשט את השילוב של בחירת קבצים מ-Google Drive באפליקציות האינטרנט שלכם. הוא עוטף את כל הלוגיקה של טעינת ה-API ואימותו בתוך רכיב HTML יחיד. הוא מאפשר להוסיף תג <drive-picker> ישירות לקוד בלי לכתוב את לוגיקת הטעינה של gapi. אפשר להשתמש בו ב-HTML וב-JavaScript רגילים, והוא גם לא תלוי במסגרת, כך שהוא פועל בצורה חלקה עם Svelte,‏ Vue,‏ Angular ועוד.

מידע נוסף על ספריית רכיבי האינטרנט זמין במאמר @googleworkspace/drive-picker-element.

באפליקציות React, משתמשים בחבילת העטיפה הרשמית של React של רכיב האינטרנט: @googleworkspace/drive-picker-react.

תכונות עיקריות

• שילוב פשוט: אפשר להוסיף את כלי הבחירה של Google לאפליקציות אינטרנט בכמה שורות קוד.
• לא תלוי ב-framework: פועל בצורה חלקה עם כל framework לאינטרנט שתבחרו (React,‏ Vue,‏ Angular וכו').
• קוד פתוח וניתן להתאמה אישית: הקוד זמין בחינם ואפשר להתאים אותו לצרכים הספציפיים שלכם.
• תמיכה חלקה ב-OAuth: המערכת מטפלת באימות המשתמש באופן אוטומטי, ומספקת חוויית משתמש חלקה.
• תצוגות שניתן להתאים אישית: אפשר להגדיר את כלי בחירת הקבצים של Google כך שיוצגו רק סוגי הקבצים או התצוגות שאתם צריכים, על ידי הגדרת מאפיינים.

שנתחיל?

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, פרטי האירוע כוללים את ResponseObject המלא של Google Picker.

{
  "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

הסינון של התצוגה מתבצע באמצעות מאפיין mime-types, כך שיוצגו רק קובצי PDF.

<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>

שאילתה לקבצים ללא שם

המסנן את התצוגה כך שיוצגו קבצים שתואמים לשאילתת החיפוש Untitled באמצעות המאפיין 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.