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

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

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

في هذه الأمثلة، يشير العنصران النائبان 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، فإنّ أي قيم أعلى منه ستأخذ لون الحد الأقصى للنقطة:

إضافة نتيجة وصفة بتنسيق تدرّج الألوان

إضافة قاعدة تنسيق شرطي إلى مجموعة من النطاقات

يوضّح نموذج الرمز البرمجي للطريقة 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 بقاعدة جديدة تُنسّق الخلايا التي تحتوي على النص المحدد تمامًا ("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
              }
            }
          }
        }
      }
    }
  ]
}