التنسيق المشروط

تتيح لك واجهة Google Sheets API إنشاء قواعد التنسيق الشرطي وتعديلها في جداول البيانات. يمكن التحكّم في أنواع تنسيق معيّنة فقط (غامق ومائل ويتوسطه خط ولون المقدمة ولون الخلفية) من خلال التنسيق الشرطي. توضّح الأمثلة الواردة في هذه الصفحة كيفية تنفيذ عمليات التنسيق الشرطي الشائعة باستخدام واجهة برمجة التطبيقات Sheets API.

يتم تقديم هذه الأمثلة كطلبات HTTP لتكون محايدة لغويًا. للتعرّف على كيفية تنفيذ تعديل مجمّع بلغات مختلفة باستخدام مكتبات برامج Google API، راجِع تعديل جداول البيانات.

في هذه الأمثلة، يشير العنصران النائبان SPREADSHEET_ID وSHEET_ID إلى المكان الذي ستوفّر فيه أرقام التعريف هذه. يمكنك العثور على رقم تعريف جدول البيانات في عنوان URL الخاص بجدول البيانات. يمكنك الحصول على معرّف ورقة باستخدام الطريقة spreadsheets.get. يتم تحديد النطاقات باستخدام ترميز A1. مثال على النطاق هو الورقة1!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 أو أقل إلى اللون الأحمر الداكن. يتم إدراج القاعدة في الفهرس 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
              }
            }
          }
        }
      }
    }
  ]
}