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

تتيح لك 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 بقاعدة جديدة تعمل على تنسيق الخلايا التي تحتوي على النص المحدد بالضبط ("التكلفة الإجمالية") في النطاق 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
              }
            }
          }
        }
      }
    }
  ]
}