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

تتيح لك واجهة برمجة تطبيقات Google Sheets إنشاء قواعد التنسيق الشرطي وتحديثها في جداول البيانات. لا يمكن التحكم إلا في أنواع تنسيق معينة (الغامق والمائل والمشطوب ولون المقدمة ولون الخلفية) من خلال التنسيق الشرطي. توضح الأمثلة الموجودة في هذه الصفحة كيفية تنفيذ عمليات التنسيق الشرطي الشائعة باستخدام 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، فإن أي قيم فوقه تحتوي على لون maxpoint:

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

يوضّح نموذج رمز طريقة 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 في ورقة بيانات، استنادًا إلى قيم التاريخ والنص في تلك الخلايا. إذا كان النص يحتوي على السلسلة "التكلفة" (غير حساس لحالة الأحرف)، فإن القاعدة الأولى تضبط نص الخلية على أنه غامق. إذا كانت الخلية تحتوي على تاريخ يقع قبل الأسبوع الماضي، فإن القاعدة الثانية تحدد نص الخلية بخط مائل وتلونه باللون الأزرق. يستخدم الطلب 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
              }
            }
          }
        }
      }
    }
  ]
}