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

تتيح لك 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 لإنشاء قاعدة تنسيق شرطي جديدة للأعمدة "أ" و"ج" في ورقة بيانات. تنص القاعدة على أنّه يتم تغيير ألوان خلفية الخلايا التي تحتوي على قيم 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 query البيانات التي سيتم عرضها.

يظهر بروتوكول الطلب أدناه.

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
              }
            }
          }
        }
      }
    }
  ]
}