Com a API Google Sheets, você pode criar e atualizar as regras de formatação condicional em planilhas. Apenas alguns tipos de formatação (negrito, itálico, tachado, cor de primeiro plano e cor de fundo) podem ser controlados pela formatação condicional. Os exemplos nesta página demonstram como realizar operações comuns de formatação condicional com a API Sheets.
Esses exemplos são apresentados como solicitações HTTP para serem neutros em termos de linguagem. Para saber como implementar uma atualização em lote em diferentes idiomas usando as bibliotecas do cliente da Google API, consulte Atualizar planilhas.
Nesses exemplos, os marcadores de posição SPREADSHEET_ID e SHEET_ID
indicam onde você deve fornecer esses IDs. Você pode encontrar o ID da planilha no URL dela. Você pode conferir o
ID da planilha usando o método
spreadsheets.get. Os
intervalos são especificados usando a notação A1. Um exemplo de intervalo é Sheet1!A1:D5.
Adicionar um gradiente de cor condicional em uma linha
O exemplo de código do método
spreadsheets.batchUpdate
abaixo mostra como usar o
AddConditionalFormatRuleRequest
para estabelecer novas regras de formatação condicional de gradiente para as linhas 10 e 11 de uma
página. A primeira regra declara que as cores de fundo das células dessa linha são definidas de acordo com o valor. O valor mais baixo na linha é vermelho escuro,
enquanto o valor mais alto é verde brilhante. A cor dos outros valores
é interpolada. A segunda regra faz o mesmo, mas com valores numéricos específicos
determinando os pontos de extremidade do gradiente (e cores diferentes). A solicitação usa o
sheets.InterpolationPointType
como type.
Confira o protocolo da solicitação abaixo.
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
}
},
]
}
Após a solicitação, a regra de formatação aplicada atualiza a planilha. Como o gradiente
na linha 11 tem o ponto máximo definido como 256, todos os valores acima dele têm a cor
do ponto máximo:
Adicionar uma regra de formatação condicional a um conjunto de intervalos
O exemplo de código do método
spreadsheets.batchUpdate
a seguir mostra como usar o
AddConditionalFormatRuleRequest
para estabelecer uma nova regra de formatação condicional para as colunas A e C de uma planilha.
A regra declara que as cores de fundo
das células com valores de 10 ou menos são alteradas para vermelho escuro. A regra é inserida no índice 0, portanto, ela tem
prioridade em relação a outras regras de formatação. A solicitação usa o
ConditionType
como o type para o
BooleanRule.
Confira o protocolo da solicitação abaixo.
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
}
}
]
}
Após a solicitação, a regra de formatação aplicada atualiza a planilha:
Adicionar regras de formatação condicional de data e texto a um intervalo
O exemplo de código do método
spreadsheets.batchUpdate
a seguir mostra como usar o
AddConditionalFormatRuleRequest
para estabelecer novas regras de formatação condicional para o intervalo A1:D5 em uma página,
com base nos valores de data e texto nessas células. Se o texto contiver a string
"Cost" (sem diferenciação entre maiúsculas e minúsculas), a primeira regra vai definir o texto da célula como negrito. Se a
célula contiver uma data ocorrida antes da semana anterior, a segunda regra definirá o
texto da célula como itálico e o colorirá de azul. A solicitação usa o
ConditionType
como o type para o
BooleanRule.
Confira o protocolo da solicitação abaixo.
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
}
}
]
}
Após a solicitação, a regra de formatação aplicada atualiza a planilha. Neste exemplo, a data atual é 26/09/2016:
Adicionar uma regra de fórmula personalizada a um intervalo
O exemplo de código do método
spreadsheets.batchUpdate
a seguir mostra como usar o
AddConditionalFormatRuleRequest
para estabelecer uma nova regra de formatação condicional para o intervalo B5:B8 em uma página,
com base em uma fórmula personalizada. A regra calcula o produto da célula nas colunas A e B. Se o produto for maior que 120, o texto da célula será definido como
negrito e itálico. A solicitação usa o
ConditionType
como o type para o
BooleanRule.
Confira o protocolo da solicitação abaixo.
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
}
}
]
}
Após a solicitação, a regra de formatação aplicada atualiza a planilha:
Excluir uma regra de formatação condicional
O exemplo de código do método
spreadsheets.batchUpdate
abaixo mostra como usar o
DeleteConditionalFormatRuleRequest
para excluir a regra de formatação condicional com o índice 0 na planilha especificada
por SHEET_ID.
Confira o protocolo da solicitação abaixo.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"deleteConditionalFormatRule": {
"sheetId": SHEET_ID,
"index": 0
}
}
]
}
Leia a lista de regras de formatação condicional
O exemplo de código do método spreadsheets.get
a seguir mostra como receber o título, SHEET_ID e a lista de todas
as regras de formatação condicional para cada página em uma planilha. O parâmetro de consulta fields determina quais dados serão retornados.
Confira o protocolo da solicitação abaixo.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?fields=sheets(properties(title,sheetId),conditionalFormats)
A resposta consiste em um recurso
Spreadsheet, que
contém uma matriz de objetos
Sheet, cada um com um
elemento
SheetProperties
e uma matriz de
elementos
ConditionalFormatRule. Se um determinado campo de resposta estiver definido como o valor padrão, ele será omitido
da resposta. A solicitação usa o
ConditionType
como o type para o
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
}
}
}
},
...
]
}
]
}
Atualizar uma regra de formatação condicional ou a prioridade dela
O exemplo de código do método
spreadsheets.batchUpdate
a seguir mostra como usar o
UpdateConditionalFormatRuleRequest
com várias solicitações. A primeira solicitação move uma regra de formatação condicional
para um índice mais alto (de 0 para 2, diminuindo a prioridade). A segunda
solicitação substitui a regra de formatação condicional no índice 0 por uma nova regra
que formata as células que contêm o texto exato especificado ("Total Cost") no
intervalo A1:D5. A movimentação da primeira solicitação é concluída antes do início da segunda, portanto,
a segunda solicitação está substituindo a regra que estava originalmente no índice 1. A
solicitação usa o
ConditionType
como type para o
BooleanRule.
Confira o protocolo da solicitação abaixo.
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
}
}
}
}
}
}
]
}