צ'יפים חכמים

במדריך הזה מוסבר איך להשתמש ב-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.
  • ריצות ללא שבב: גם לקטעים של טקסט פשוט יהיה אובייקט ריצה, אבל השדה chip שלו יהיה ריק.

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

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

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

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

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

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