עיצוב בסיסי

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

מידע נוסף מופיע במאמר בנושא פורמטים של תאריכים ומספרים.

טבלה בגודל 3x3 עם פורמטים מותאמים אישית של תאריכים ושעות ומספרים בגיליון.
איור 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"
      }
    }
  ]
}