עיצוב מותנה

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

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

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

הוספת שיפוע צבעים מותנה בשורה

בדוגמה הבאה של קוד השיטה spreadsheets.batchUpdate מוסבר איך להשתמש בפרמטר AddConditionalFormatRuleRequest כדי להגדיר כללי עיצוב מותנה חדשים עם שיפוע לשורות 10 ו-11 של גיליון. הכלל הראשון קובע שצבעי הרקע של התאים בשורה הזו מוגדרים בהתאם לערך שלהם. הערך הנמוך ביותר בשורה צבוע באדום כהה, והערך הגבוה ביותר צבוע בירוק בהיר. הצבע של הערכים האחרים מחושב. הכלל השני עושה את אותו הדבר, אבל עם ערכים מספריים ספציפיים שמגדירים את נקודות הקצה של העקומה (וגם צבעים שונים). הבקשה משתמשת ב-sheets.InterpolationPointType בתור type.

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

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "addConditionalFormatRule": {
        "rule": {
          "ranges": [
            {
              "sheetId": SHEET_ID,
              "startRowIndex": 9,
              "endRowIndex": 10,
            }
          ],
          "gradientRule": {
            "minpoint": {
              "color": {
                "green": 0.2,
                "red": 0.8
              },
              "type": "MIN"
            },
            "maxpoint": {
              "color": {
                "green": 0.9
              },
              "type": "MAX"
            },
          }
        },
        "index": 0
      }
    },
    {
      "addConditionalFormatRule": {
        "rule": {
          "ranges": [
            {
              "sheetId": SHEET_ID,
              "startRowIndex": 10,
              "endRowIndex": 11,
            }
          ],
          "gradientRule": {
            "minpoint": {
              "color": {
                "green": 0.8,
                "red": 0.8
              },
              "type": "NUMBER",
              "value": "0"
            },
            "maxpoint": {
              "color": {
                "blue": 0.9,
                "green": 0.5,
                "red": 0.5
              },
              "type": "NUMBER",
              "value": "256"
            },
          }
        },
        "index": 1
      }
    },
  ]
}

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

הוספת כלל של עיצוב מותנה לקבוצת טווחים

בדוגמה הבאה של קוד השיטה spreadsheets.batchUpdate מוסבר איך להשתמש בפונקציה AddConditionalFormatRuleRequest כדי ליצור כלל חדש של עיצוב מותנה לעמודות A ו-C בגיליון. הכלל קובע שצבע הרקע של תאים עם ערכים של 10 ומטה ישתנה לאדום כהה. הכלל מוכנס ב-index 0, כך שהוא מקבל עדיפות על פני כללי עיצוב אחרים. בבקשה מצוין הערך ConditionType בתור type של BooleanRule.

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

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "addConditionalFormatRule": {
        "rule": {
          "ranges": [
            {
              "sheetId": SHEET_ID,
              "startColumnIndex": 0,
              "endColumnIndex": 1,
            },
            {
              "sheetId": SHEET_ID,
              "startColumnIndex": 2,
              "endColumnIndex": 3,
            },
          ],
          "booleanRule": {
            "condition": {
              "type": "NUMBER_LESS_THAN_EQ",
              "values": [
                {
                  "userEnteredValue": "10"
                }
              ]
            },
            "format": {
              "backgroundColor": {
                "green": 0.2,
                "red": 0.8,
              }
            }
          }
        },
        "index": 0
      }
    }
  ]
}

אחרי הבקשה, כלל הפורמט שהוחל מעדכן את הגיליון:

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

בדוגמה הבאה של קוד השיטה spreadsheets.batchUpdate מוסבר איך להשתמש ב-AddConditionalFormatRuleRequest כדי להגדיר כללי עיצוב מותנה חדשים לטווח A1:D5 בגיליון, על סמך ערכים של תאריכים וטקסט בתאים האלה. אם הטקסט מכיל את המחרוזת Cost (ללא קשר לאותיות רישיות), הכלל הראשון מגדיר את טקסט התא כמודגש. אם התא מכיל תאריך שקרה לפני השבוע האחרון, הכלל השני מגדיר את הטקסט בתא כנטוי וצובע אותו בכחול. הבקשה משתמשת ב-ConditionType בתור type של BooleanRule.

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

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "addConditionalFormatRule": {
        "rule": {
          "ranges": [
            {
              "sheetId": SHEET_ID,
              "startRowIndex": 0,
              "endRowIndex": 5,
              "startColumnIndex": 0,
              "endColumnIndex": 4,
            }
          ],
          "booleanRule": {
            "condition": {
              "type": "TEXT_CONTAINS",
              "values": [
                {
                  "userEnteredValue": "Cost"
                }
              ]
            },
            "format": {
              "textFormat": {
                "bold": true
              }
            }
          }
        },
        "index": 0
      }
    },
    {
      "addConditionalFormatRule": {
        "rule": {
          "ranges": [
            {
              "sheetId": SHEET_ID,
              "startRowIndex": 0,
              "endRowIndex": 5,
              "startColumnIndex": 0,
              "endColumnIndex": 4,
            }
          ],
          "booleanRule": {
            "condition": {
              "type": "DATE_BEFORE",
              "values": [
                {
                  "relativeDate": "PAST_WEEK"
                }
              ]
            },
            "format": {
              "textFormat": {
                "italic": true,
                "foregroundColor": {
                  "blue": 1
                }
              }
            }
          }
        },
        "index": 1
      }
    }
  ]
}

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

הוספת כלל נוסחה בהתאמה אישית לטווח

בדוגמה הבאה של קוד השיטה spreadsheets.batchUpdate מוסבר איך להשתמש ב-AddConditionalFormatRuleRequest כדי ליצור כלל חדש של עיצוב מותנה לטווח B5:B8 בגיליון, על סמך נוסחה בהתאמה אישית. הכלל מחשב את המכפלה של התא בעמודות A ו-B. אם המכפלה גדולה מ-120, הטקסט בתא מוגדר מודגש ובכתב נטוי. בבקשה מצוין הערך ConditionType בתור type של BooleanRule.

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

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "addConditionalFormatRule": {
        "rule": {
          "ranges": [
            {
              "sheetId": SHEET_ID,
              "startColumnIndex": 2,
              "endColumnIndex": 3,
              "startRowIndex": 4,
              "endRowIndex": 8
            }
          ],
          "booleanRule": {
            "condition": {
              "type": "CUSTOM_FORMULA",
              "values": [
                {
                  "userEnteredValue": "=GT(A5*B5,120)"
                }
              ]
            },
            "format": {
              "textFormat": {
                "bold": true,
                "italic": true
              }
            }
          }
        },
        "index": 0
      }
    }
  ]
}

אחרי הבקשה, כלל הפורמט שהוחל מעדכן את הגיליון:

מחיקת כלל של עיצוב מותנה

בדוגמה הבאה של קוד השיטה spreadsheets.batchUpdate מוסבר איך משתמשים ב-DeleteConditionalFormatRuleRequest כדי למחוק את כלל הפורמטה המותנה עם המדד 0 בגיליון שצוין על ידי SHEET_ID.

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

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "deleteConditionalFormatRule": {
        "sheetId": SHEET_ID,
        "index": 0
      }
    }
  ]
}

קריאת רשימת הכללים של העיצוב המותנה

בדוגמה הבאה של קוד method‏ spreadsheets.get מוסבר איך לקבל את השם, SHEET_ID ואת הרשימה של כל כללי העיצוב המותנה לכל גיליון בגיליון אלקטרוני. הפרמטר של השאילתה fields קובע אילו נתונים יוחזרו.

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

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?fields=sheets(properties(title,sheetId),conditionalFormats)

התשובה מורכבת ממשאב Spreadsheet, שמכיל מערך של אובייקטים מסוג Sheet, שכל אחד מהם מכיל רכיב SheetProperties ומערך של רכיבים מסוג ConditionalFormatRule. אם שדה תגובה מסוים מוגדר לערך ברירת המחדל, הוא לא ייכלל בתגובה. בבקשה מצוין הערך ConditionType בתור type של BooleanRule.

{
  "sheets": [
    {
      "properties": {
        "sheetId": 0,
        "title": "Sheet1"
      },
      "conditionalFormats": [
        {
          "ranges": [
            {
              "startRowIndex": 4,
              "endRowIndex": 8,
              "startColumnIndex": 2,
              "endColumnIndex": 3
            }
          ],
          "booleanRule": {
            "condition": {
              "type": "CUSTOM_FORMULA",
              "values": [
                {
                  "userEnteredValue": "=GT(A5*B5,120)"
                }
              ]
            },
            "format": {
              "textFormat": {
                "bold": true,
                "italic": true
              }
            }
          }
        },
        {
          "ranges": [
            {
              "startRowIndex": 0,
              "endRowIndex": 5,
              "startColumnIndex": 0,
              "endColumnIndex": 4
            }
          ],
          "booleanRule": {
            "condition": {
              "type": "DATE_BEFORE",
              "values": [
                {
                  "relativeDate": "PAST_WEEK"
                }
              ]
            },
            "format": {
              "textFormat": {
                "foregroundColor": {
                  "blue": 1
                },
                "italic": true
              }
            }
          }
        },
        ...
      ]
    }
  ]
}

עדכון של כלל עיצוב מותנה או של העדיפות שלו

בדוגמת הקוד הבאה של השיטה spreadsheets.batchUpdate מוסבר איך להשתמש ב-UpdateConditionalFormatRuleRequest עם כמה בקשות. הבקשה הראשונה מעבירה כלל קיים של עיצוב מותנה לאינדקס גבוה יותר (מ-0 ל-2, ומפחיתה את העדיפות שלו). הבקשה השנייה מחליפה את כלל העיצוב המותנה במדד 0 בכלל חדש שמעצב תאים שמכילים את הטקסט המדויק שצוין ('Total Cost') בטווח A1:D5. ההעברה של הבקשה הראשונה מסתיימת לפני שהבקשה השנייה מתחילה, ולכן הבקשה השנייה מחליפה את הכלל שהיה במקור ב-index‏ 1. הבקשה משתמשת ב-ConditionType בתור type של BooleanRule.

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

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "updateConditionalFormatRule": {
        "sheetId": SHEET_ID,
        "index": 0,
        "newIndex": 2
      },
      "updateConditionalFormatRule": {
        "sheetId": SHEET_ID,
        "index": 0,
        "rule": {
          "ranges": [
            {
              "sheetId": SHEET_ID,
              "startRowIndex": 0,
              "endRowIndex": 5,
              "startColumnIndex": 0,
              "endColumnIndex": 4,
            }
          ],
          "booleanRule": {
            "condition": {
              "type": "TEXT_EQ",
              "values": [
                {
                  "userEnteredValue": "Total Cost"
                }
              ]
            },
            "format": {
              "textFormat": {
                "bold": true
              }
            }
          }
        }
      }
    }
  ]
}