עיצוב מותנה

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

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

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

הוספת הדרגתי של צבעים מותנים לאורך שורה

הבאים spreadsheets.batchUpdate דוגמת קוד ה-method מראה איך להשתמש 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. כל ערך מעליה מוגדר ל-maxpoint color:

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

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