עיצוב מותנה

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

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

בדוגמאות האלה, ערכי ה-placeholder SPREADSHEET_ID ו-SHEET_ID מציינים איפה הייתם מספקים את המזהים האלה. המזהה של הגיליון האלקטרוני מופיע בכתובת ה-URL של הגיליון האלקטרוני. אפשר לאתר את מזהה הגיליון באמצעות השיטה 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, לכל ערך מעליו יש את הצבע המקסימלי:

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

דוגמת קוד ה-method הבאה spreadsheets.batchUpdate מראה איך להשתמש ב-AddConditionalFormatRuleRequest כדי ליצור כלל חדש של עיצוב מותנה לעמודות A ו-C בגיליון. לפי הכלל, צבעי הרקע של תאים עם ערכים של 10 או פחות משתנים לאדום כהה. הכלל נוסף לאינדקס 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.9.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
      }
    }
  ]
}

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

דוגמת הקוד הבאה של השיטה 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 בכלל חדש שמעצב תאים שמכילים את הטקסט המדויק שצוין ('עלות כוללת') בטווח A1:D5. ההעברה הראשונה מתבצעת לפני שהשנייה מתחילה, ולכן הבקשה השנייה מחליפה את הכלל שהיה במקור באינדקס 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
              }
            }
          }
        }
      }
    }
  ]
}