צ'יפים חכמים

במדריך הזה מוסבר איך משתמשים ב-Google Sheets API כדי להוסיף ולנהל צ'יפים חכמים בגיליונות האלקטרונים, ומוסבר למה כדאי לעשות זאת.

מהו צ'יפ חכם?

בעזרת צ'יפים חכמים, אפשר להוסיף נתונים עשירים ואינטראקטיביים מאפליקציות אחרות של Google Workspace ישירות ל-Sheets. צ'יפים חכמים מספקים למשתמשים גישה מהירה למידע ולפעולות, והם הופכים קישור של תא לאובייקט דינמי. מידע נוסף זמין במאמר הוספת צ'יפים חכמים ב-Google Sheets.

הוספת צ'יפ חכם

צ'יפים מיוצגים כרצפי צ'יפים, שהם חלק מ-CellData, כך שאפשר להוסיף צ'יפ באמצעות השיטה הקיימת spreadsheets.batchUpdate על ידי ציון UpdateCellsRequest או AppendCellsRequest.

הבקשה חייבת לכלול את השדה chipRuns. הרצת צ'יפ מתארת את המאפיינים של הצ'יפ ואת המיקום שלו בטקסט של התא.

ככותבים את chipRuns, צריך גם לספק userEnteredValue שמכיל תווים של placeholder (@) לכל צ'יפ שרוצים להוסיף. כל הרצה במערך chipRuns תתאים לאחד מהתוויות האלה. אפשר להשמיט רצפי נתונים ללא צ'יפ בזמן הכתיבה.

בדוגמה הבאה מוסבר איך לכתוב צ'יפ של קובץ, צ'יפ של אנשים וטקסט פשוט בתא יחיד, A1. * {JSON}

        {
          "updateCells": {
            "rows": [
              {
                "values": [
                  {
                    "userEnteredValue": {
                      "stringValue": "@ is the owner of @."
                    },
                    "chipRuns": [
                      {
                        "chip": {
                          "personProperties": {
                            "email": "johndoe@gmail.com",
                            "displayFormat": "DEFAULT"
                          }
                        }
                      },
                      {
                        "startIndex": 18,
                        "chip": {
                          "richLinkProperties": {
                            "uri": "https://docs.google.com/document/d/YOUR_DOCUMENT_ID/edit"
                          }
                        }
                      }
                    ]
                  }
                ]
              }
            ],
            "fields": "userEnteredValue,chipRuns",
            "range": {
              "startRowIndex": 0,
              "startColumnIndex": 0
            }
          }
        }

הגדרת מאפייני הצ'יפ

לאובייקט צ'יפ יכול להיות אחד מסוגי המאפיינים הבאים:

personProperties

אפשר להשתמש באפשרות הזו כדי ליצור צ'יפ של אדם.

  • email: (חובה) כתובת האימייל של האדם שרוצים לקשר.
  • displayFormat: (אופציונלי) פורמט התצוגה המועדף של שם האדם. יכול להיות אחת מהאפשרויות הבאות:
    • DEFAULT: פורמט סטנדרטי של 'שם פרטי שם משפחה'.
    • LAST_NAME_COMMA_FIRST_NAME: פורמט 'שם משפחה, שם פרטי'.
    • EMAIL: כתובת האימייל של המשתתף הנוסף.

אפשר להשתמש באפשרות הזו כדי ליצור צ'יפ של קישור עשיר. ה-API יכול לקרוא קישורים לשירותי Google שונים (כמו YouTube או יומן Google), אבל אפשר לכתוב כצ'יפים רק קישורים לקבצים ב-Google Drive.

  • uri: (חובה) מזהה ה-URI של המשאב. לצורך כתיבת תוכן, זה חייב להיות קישור לקובץ ב-Google Drive. האורך המקסימלי של URI הוא 2,000 בייטים.

קריאת צ'יפ חכם

כדי לקרוא את הנתונים של צ'יפ חכם, משתמשים בשיטה spreadsheets.get וכוללים את sheets.data.rowData.values(chipRuns) בפרמטר fields.

מערך chipRuns בתגובה יכיל אובייקטים לכל קטעי המשנה של טקסט התא.

  • רצפי מודעות עם צ'יפ: בקטעים האלה יופיע אובייקט chip מאוכלס שמכיל את הערך personProperties או richLinkProperties.
  • רצפי קוד ללא צ'יפ: גם קטעים של טקסט פשוט יכללו אובייקט run, אבל השדה chip שלו יהיה ריק.

כדי לקבל את הטקסט המוצג של צ'יפ, מוסיפים את השדה formattedValue.

עדכון צ'יפ חכם

כדי לעדכן או להחליף צ'יפ חכם, צריך לשכתב את תוכן התא. משתמשים באותו UpdateCellsRequest או AppendCellsRequest כמו בהוספת צ'יפ, ומספקים userEnteredValue ו-chipRun חדשים. הפעולה הזו תחליף את הצ'יפ הקיים בתא.

שימוש בצ'יפים חכמים עם תכונות אחרות של Sheets

טבלאות: אפשר להשתמש בצ'יפים חכמים כסוג של עמודה בטבלה כדי לעקוב אחרי בעלי פרויקטים (צ'יפ של אנשים) או אחרי מסמכים קשורים (צ'יפ של קובץ).

מסננים: אפשר לסנן טווחים על סמך ערך הטקסט של הצ'יפים החכמים שבתוכם.