עיצוב בסיסי

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

כשמעדכנים גיליון אלקטרוני, יכול להיות שחלק מסוגי הבקשות יחזירו תשובות. התשובות האלה מוחזרות במערך, וכל תשובה תופסת את אותו אינדקס כמו הבקשה התואמת. לחלק מהבקשות אין תשובות, והתשובה שלהן ריקה. מבנה התגובה לדוגמאות האלה מופיע בקטע spreadsheets.batchUpdate.

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

בדוגמאות האלה, התוויות SPREADSHEET_ID ו-SHEET_ID מצביעות על המקומות שבהם צריך לספק את המזהים האלה. המזהה של הגיליון האלקטרוני מופיע בכתובת ה-URL של הגיליון האלקטרוני. אפשר לקבל את מזהה הגיליון באמצעות ה-method‏ spreadsheets.get. טווחי הנתונים מצוינים באמצעות סימון A1. דוגמה לטווח היא Sheet1!A1:D5.

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

עריכת גבולות של תאים

בדוגמת הקוד הבאה של spreadsheets.batchUpdate מוסבר איך להשתמש ב-UpdateBordersRequest כדי להוסיף לכל תא בטווח A1:F10 גבול כחול מקווקו בחלק העליון ובחלק התחתון. השדה innerHorizontal יוצר גבולות אופקיים בתוך הטווח. אם השדה לא יצוין, המערכת תוסיף גבולות רק לחלק העליון ולחלק התחתון של כל הטווח.

טבלה בגודל 3 על 3, שבכל תא שלה יש מסגרת כחולה מקווקווית בחלק העליון ובחלק התחתון.
איור 1. עיצוב של כל תא בגיליון עם גבול כחול מקווקו בחלק העליון ובחלק התחתון.

פרוטוקול הבקשה מוצג בהמשך.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
 
{
  "requests": [
    {
      "updateBorders": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 6
        },
        "top": {
          "style": "DASHED",
          "width": 1,
          "color": {
            "blue": 1.0
          },
        },
        "bottom": {
          "style": "DASHED",
          "width": 1,
          "color": {
            "blue": 1.0
          },
        },
        "innerHorizontal": {
          "style": "DASHED",
          "width": 1,
          "color": {
            "blue": 1.0
          },
        },
      }
    }
  ]
}

עיצוב של שורת כותרת

בדוגמת הקוד הבאה של spreadsheets.batchUpdate מוסבר איך להשתמש בפונקציה RepeatCellRequest כדי לעצב שורת כותרת בגיליון. הבקשה הראשונה מעדכנת את צבע הטקסט, צבע הרקע, גודל הגופן של הטקסט והיישור של הטקסט, ומדגישה את הטקסט. אם משמיטים את אינדקסי העמודות בשדה range, הפורמט יוחל על כל השורה. הבקשה השנייה מתאימה את מאפייני הגיליון כך ששורת הכותרת תהיה קפואה.

טבלה בגודל 3 על 3 עם שורת כותרת בפורמט בדף.
איור 2. עיצוב שורת הכותרת בגיליון.

פרוטוקול הבקשה מוצג בהמשך.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
 
{
  "requests": [
    {
      "repeatCell": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 1
        },
        "cell": {
          "userEnteredFormat": {
            "backgroundColor": {
              "red": 0.0,
              "green": 0.0,
              "blue": 0.0
            },
            "horizontalAlignment" : "CENTER",
            "textFormat": {
              "foregroundColor": {
                "red": 1.0,
                "green": 1.0,
                "blue": 1.0
              },
              "fontSize": 12,
              "bold": true
            }
          }
        },
        "fields": "userEnteredFormat(backgroundColor,textFormat,horizontalAlignment)"
      }
    },
    {
      "updateSheetProperties": {
        "properties": {
          "sheetId": SHEET_ID,
          "gridProperties": {
            "frozenRowCount": 1
          }
        },
        "fields": "gridProperties.frozenRowCount"
      }
    }
  ]
}

מזג תאים

בדוגמת הקוד הבאה של spreadsheets.batchUpdate מוסבר איך להשתמש בפונקציה MergeCellsRequest כדי למזג תאים. הבקשה הראשונה ממזגת את הטווח A1:B2 לתא אחד. בבקשה השנייה, המערכת ממזגת את העמודות ב-A3:B6, אבל השורות נשארות מופרדות.

טבלה בגודל 3 על 3 עם תאים ממוזגים בגיליון.
איור 3. מיזוג תאים בגיליון.

פרוטוקול הבקשה מוצג בהמשך.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
 
{
  "requests": [
    {
      "mergeCells": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 2,
          "startColumnIndex": 0,
          "endColumnIndex": 2
        },
        "mergeType": "MERGE_ALL"
      }
    },
    {
      "mergeCells": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 2,
          "endRowIndex": 6,
          "startColumnIndex": 0,
          "endColumnIndex": 2
        },
        "mergeType": "MERGE_COLUMNS"
      }
    },
  ]
}

הגדרת פורמט תאריך-שעה או עשרוני בהתאמה אישית לטווח

בדוגמת הקוד הבאה של spreadsheets.batchUpdate מוסבר איך להשתמש ב-RepeatCellRequest כדי לעדכן תאים כך שיכללו פורמטים מותאמים אישית של תאריכים ושעות ומספרים. הבקשה הראשונה מקצה לתאים בטווח A1:A10 את פורמט התאריך והשעה המותאם אישית hh:mm:ss am/pm, ddd mmm dd yyyy. דוגמה לתאריך ושעה בפורמט הזה: ‎"02:05:07 PM, Sun Apr 03 2016".

הבקשה השנייה מקצה לתאים ב-B1:B10 את פורמט המספרים המותאם אישית #,##0.0000, שמציין שצריך לקבץ את המספרים באמצעות תווים מפרידים של פסיק, שצריכות להיות 4 ספרות אחרי הנקודה העשרונית ושצריך להשמיט את כל האפסים המובילים מלבד אפס אחד. לדוגמה, המספר '3.14' מוצג בתור '3.1400', בעוד שהמספר '12345.12345' מוצג בתור '12,345.1235'.

טבלה 3 על 3 עם פורמטים מותאמים אישית של תאריכים ושעות ומספרים בגיליון.
איור 4. איך מעדכנים תאים בפורמטים מותאמים אישית של תאריכים ומספרים בגיליון.

פרוטוקול הבקשה מוצג בהמשך.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
 
{
  "requests": [
    {
      "repeatCell": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 1
        },
        "cell": {
          "userEnteredFormat": {
            "numberFormat": {
              "type": "DATE",
              "pattern": "hh:mm:ss am/pm, ddd mmm dd yyyy"
            }
          }
        },
        "fields": "userEnteredFormat.numberFormat"
      }
    },
    {
      "repeatCell": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 1,
          "endColumnIndex": 2
        },
        "cell": {
          "userEnteredFormat": {
            "numberFormat": {
              "type": "NUMBER",
              "pattern": "#,##0.0000"
            }
          }
        },
        "fields": "userEnteredFormat.numberFormat"
      }
    }
  ]
}