עיצוב בסיסי

אפשר לעדכן את העיצוב של תאים וטווחים בגיליונות אלקטרוניים באמצעות 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"
      }
    }
  ]
}