Mise en forme conditionnelle

L'API Google Sheets vous permet de créer et de mettre à jour des règles de mise en forme conditionnelle dans les feuilles de calcul. Seuls certains types de mise en forme (gras, italique, barré, couleur de premier plan et couleur d'arrière-plan) peuvent être contrôlés par la mise en forme conditionnelle. Les exemples de cette page montrent comment effectuer des opérations de mise en forme conditionnelle courantes avec l'API Sheets.

Ces exemples sont présentés sous forme de requêtes HTTP afin d'être indépendant du langage. Pour découvrir comment mettre en œuvre une mise à jour par lot dans différents langages à l'aide des bibliothèques clientes des API Google, consultez Mettre à jour des feuilles de calcul.

Dans ces exemples, les espaces réservés SPREADSHEET_ID et SHEET_ID indiquent où vous devez fournir ces ID. L'ID de la feuille de calcul se trouve dans son URL. Vous pouvez obtenir l'ID de la feuille à l'aide de la méthode spreadsheets.get. Ces plages sont spécifiées au format A1. Exemple de plage : Feuille1!A1:D5.

Ajouter un dégradé de couleur conditionnel sur une ligne

L'exemple de code de méthode spreadsheets.batchUpdate suivant montre comment utiliser AddConditionalFormatRuleRequest pour établir de nouvelles règles de mise en forme conditionnelle en dégradé pour les lignes 10 et 11 d'une feuille. La première règle stipule que la couleur d'arrière-plan des cellules de cette ligne est définie en fonction de leur valeur. La valeur la plus faible de la ligne est en rouge foncé, tandis que la valeur la plus élevée est en vert vif. La couleur des autres valeurs est interpolée. La deuxième règle fait la même chose, mais avec des valeurs numériques spécifiques qui déterminent les extrémités du dégradé (et différentes couleurs). La requête utilise sheets.InterpolationPointType comme type.

Le protocole de requête est illustré ci-dessous.

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

Après la requête, la règle de mise en forme appliquée met à jour la feuille. Étant donné que le point maximal du dégradé de la ligne 11 est défini sur 256, toutes les valeurs supérieures ont la couleur du point maximal:

Ajouter le résultat de la recette avec le format de dégradé

Ajouter une règle de mise en forme conditionnelle à un ensemble de plages

L'exemple de code de méthode spreadsheets.batchUpdate suivant montre comment utiliser AddConditionalFormatRuleRequest pour établir une nouvelle règle de mise en forme conditionnelle pour les colonnes A et C d'une feuille. La règle stipule que la couleur d'arrière-plan des cellules dont la valeur est inférieure ou égale à 10 est remplacée par un rouge foncé. La règle est insérée à l'index 0. Elle est donc prioritaire sur les autres règles de mise en forme. La requête utilise ConditionType comme type pour BooleanRule.

Le protocole de requête est illustré ci-dessous.

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

Après la requête, la règle de mise en forme appliquée met à jour la feuille:

Ajouter un résultat de recette au format conditionnel

Ajouter des règles de mise en forme conditionnelle de type date et texte à une plage

L'exemple de code de méthode spreadsheets.batchUpdate suivant montre comment utiliser AddConditionalFormatRuleRequest pour établir de nouvelles règles de mise en forme conditionnelle pour la plage A1:D5 dans une feuille, en fonction de la date et des valeurs de texte dans ces cellules. Si le texte contient la chaîne "Cost" (non sensible à la casse), la première règle définit le texte de la cellule en gras. Si la cellule contient une date antérieure à la semaine passée, la seconde règle définit le texte de la cellule en italique et le colore en bleu. La requête utilise ConditionType comme type pour BooleanRule.

Le protocole de requête est illustré ci-dessous.

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

Après la requête, la règle de mise en forme appliquée met à jour la feuille. Dans cet exemple, la date actuelle est le 26/09/2016:

Résultat de recette au format conditionnel avec texte et date

Ajouter une règle de formule personnalisée à une plage

L'exemple de code de méthode spreadsheets.batchUpdate suivant montre comment utiliser AddConditionalFormatRuleRequest pour établir une nouvelle règle de mise en forme conditionnelle pour la plage B5:B8 dans une feuille, en fonction d'une formule personnalisée. La règle calcule le produit de la cellule dans les colonnes A et B. Si le produit est supérieur à 120, le texte de la cellule est mis en gras et en italique. La requête utilise ConditionType comme type pour BooleanRule.

Le protocole de requête est illustré ci-dessous.

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

Après la requête, la règle de mise en forme appliquée met à jour la feuille:

Résultat de recette au format conditionnel personnalisé

Supprimer une règle de mise en forme conditionnelle

L'exemple de code de méthode spreadsheets.batchUpdate suivant montre comment utiliser DeleteConditionalFormatRuleRequest pour supprimer la règle de mise en forme conditionnelle avec l'index 0 dans la feuille spécifiée par SHEET_ID.

Le protocole de requête est illustré ci-dessous.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "deleteConditionalFormatRule": {
        "sheetId": SHEET_ID,
        "index": 0
      }
    }
  ]
}

Lire la liste des règles de mise en forme conditionnelle

L'exemple de code de méthode spreadsheets.get suivant montre comment obtenir le titre, les SHEET_ID et la liste de toutes les règles de mise en forme conditionnelle pour chaque feuille d'une feuille de calcul. Le paramètre de requête fields détermine les données à renvoyer.

Le protocole de requête est illustré ci-dessous.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?fields=sheets(properties(title,sheetId),conditionalFormats)

La réponse consiste en une ressource Spreadsheet, qui contient un tableau d'objets Sheet comportant chacun un élément SheetProperties et un tableau d'éléments ConditionalFormatRule. Si un champ de réponse donné est défini sur la valeur par défaut, il est omis de la réponse. La requête utilise ConditionType comme type pour 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
              }
            }
          }
        },
        ...
      ]
    }
  ]
}

Mettre à jour une règle de mise en forme conditionnelle ou sa priorité

L'exemple de code de méthode spreadsheets.batchUpdate suivant montre comment utiliser UpdateConditionalFormatRuleRequest avec plusieurs requêtes. La première requête déplace une règle de mise en forme conditionnelle existante vers un index supérieur (de 0 à 2, en diminuant sa priorité). La deuxième requête remplace la règle de mise en forme conditionnelle à l'indice 0 par une nouvelle règle qui met en forme les cellules contenant le texte exact spécifié ("Coût total") dans la plage A1:D5. Le déplacement de la première requête est terminé avant le début de la seconde. La deuxième requête remplace donc la règle initialement définie à l'index 1. La requête utilise ConditionType comme type pour BooleanRule.

Le protocole de requête est illustré ci-dessous.

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