قالب بندی مشروط

API گوگل شیت به شما امکان می‌دهد قوانین قالب‌بندی شرطی را در صفحات گسترده ایجاد و به‌روزرسانی کنید. فقط انواع خاصی از قالب‌بندی (پررنگ، کج، خط خورده، رنگ پیش‌زمینه و رنگ پس‌زمینه) را می‌توان از طریق قالب‌بندی شرطی کنترل کرد. مثال‌های این صفحه نحوه دستیابی به عملیات قالب‌بندی شرطی رایج را با API شیت نشان می‌دهند.

این مثال‌ها به عنوان درخواست‌های HTTP ارائه شده‌اند تا از نظر زبانی بی‌طرف باشند. برای یادگیری نحوه پیاده‌سازی به‌روزرسانی دسته‌ای در زبان‌های مختلف با استفاده از کتابخانه‌های کلاینت API گوگل، به صفحات گسترده به‌روزرسانی مراجعه کنید.

در این مثال‌ها، متغیرهای SPREADSHEET_ID و SHEET_ID نشان می‌دهند که این شناسه‌ها را کجا باید ارائه دهید. می‌توانید شناسه صفحه گسترده را در URL صفحه گسترده پیدا کنید. می‌توانید شناسه صفحه را با استفاده از متد spreadsheets.get دریافت کنید. محدوده‌ها با استفاده از نمادگذاری A1 مشخص شده‌اند. یک محدوده به عنوان مثال Sheet1!A1:D5 است.

یک گرادیان رنگ مشروط در یک ردیف اضافه کنید

نمونه کد متد spreadsheets.batchUpdate زیر نحوه استفاده از AddConditionalFormatRuleRequest را برای ایجاد قوانین قالب‌بندی شرطی گرادیان جدید برای ردیف‌های ۱۰ و ۱۱ یک برگه نشان می‌دهد. قانون اول بیان می‌کند که رنگ پس‌زمینه سلول‌های آن ردیف بر اساس مقدارشان تنظیم می‌شود. کمترین مقدار در ردیف به رنگ قرمز تیره و بیشترین مقدار به رنگ سبز روشن رنگ‌آمیزی می‌شود. رنگ سایر مقادیر درون‌یابی می‌شود. قانون دوم نیز همین کار را انجام می‌دهد، اما با مقادیر عددی خاص که نقاط انتهایی گرادیان (و رنگ‌های مختلف) را تعیین می‌کنند. این درخواست از 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
      }
    },
  ]
}

پس از درخواست، قانون قالب‌بندی اعمال‌شده، برگه را به‌روزرسانی می‌کند. از آنجایی که حداکثر نقطه گرادیان در ردیف ۱۱ روی 256 تنظیم شده است، هر مقداری بالاتر از آن، رنگ حداکثر نقطه را دارد:

نتیجه دستور پخت با فرمت گرادیان را اضافه کنید

اضافه کردن یک قانون قالب‌بندی شرطی به مجموعه‌ای از محدوده‌ها

نمونه کد متد spreadsheets.batchUpdate زیر نحوه استفاده از AddConditionalFormatRuleRequest را برای ایجاد یک قانون قالب‌بندی شرطی جدید برای ستون‌های A و C یک برگه نشان می‌دهد. این قانون بیان می‌کند که رنگ پس‌زمینه سلول‌هایی با مقادیر ۱۰ یا کمتر به قرمز تیره تغییر می‌کند. این قانون در اندیس ۰ درج شده است، بنابراین نسبت به سایر قوانین قالب‌بندی اولویت دارد. این درخواست از 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" (غیرحساس به حروف بزرگ و کوچک) باشد، قانون اول متن سلول را پررنگ (bold) می‌کند. اگر سلول حاوی تاریخی باشد که قبل از هفته گذشته رخ داده است، قانون دوم متن سلول را ایتالیک (italic) کرده و آن را به رنگ آبی در می‌آورد. درخواست از 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
      }
    }
  ]
}

پس از درخواست، قانون قالب‌بندی اعمال‌شده، برگه را به‌روزرسانی می‌کند. در این مثال، تاریخ فعلی 2016/09/26 است:

نتیجه دستور پخت با فرمت شرطی متن و تاریخ

یک قانون فرمول سفارشی به یک محدوده اضافه کنید

نمونه کد متد spreadsheets.batchUpdate زیر نحوه استفاده از AddConditionalFormatRuleRequest را برای ایجاد یک قانون قالب‌بندی شرطی جدید برای محدوده B5:B8 در یک برگه، بر اساس یک فرمول سفارشی، نشان می‌دهد. این قانون حاصلضرب سلول در ستون‌های A و B را محاسبه می‌کند. اگر حاصلضرب بزرگتر از ۱۲۰ باشد، متن سلول به صورت پررنگ و ایتالیک تنظیم می‌شود. درخواست از 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 را با یک قانون جدید جایگزین می‌کند که سلول‌های حاوی متن دقیق مشخص شده ("Total Cost") را در محدوده 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
              }
            }
          }
        }
      }
    }
  ]
}