Com a API Google Sheets, você pode criar e atualizar as regras de formatação condicional em planilhas. Somente 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 ilustram 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 relação à linguagem. Para saber como implementar uma atualização em lote em diferentes idiomas usando as bibliotecas de cliente da API do Google, consulte Atualizar planilhas.
Nesses exemplos, os marcadores de posição SPREADSHEET_ID e SHEET_ID
indicam onde você forneceria esses IDs. O ID da planilha pode ser encontrado no URL dela. É possível conseguir 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
a seguir mostra como usar AddConditionalFormatRuleRequest
para estabelecer novas regras de formatação condicional de gradiente para as linhas 10 e 11 de uma planilha. A primeira regra declara que as células dessa linha têm as cores de fundo
definidas de acordo com o valor. O valor mais baixo na linha tem a cor vermelho escuro, enquanto o valor mais alto tem a cor verde brilhante. A cor dos outros valores
é interpolada. A segunda regra faz o mesmo, mas com valores numéricos específicos, que determinam os endpoints do gradiente (e cores diferentes). A solicitação usa
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 página. Como o ponto máximo do gradiente
na linha 11 está definido como 256
, todos os valores acima dele terão 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 página.
A regra declara que as células com valores de 10 ou menos têm as cores de fundo
alteradas para vermelho escuro. A regra é inserida no índice 0, por isso, ela tem
prioridade sobre outras regras de formatação. A solicitação usa
ConditionType
como type
para
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 página:
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 a
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" (não diferencia maiúsculas de minúsculas), a primeira regra definirá o texto da célula como negrito. Se a
célula tiver uma data anterior à semana anterior, a segunda regra definirá o
texto da célula em itálico e o colore de azul. A solicitação usa
ConditionType
como type
para
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 página. 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 a
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
ConditionType
como type
para
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 página:
Excluir uma regra de formatação condicional
O exemplo de código do método
spreadsheets.batchUpdate
a seguir mostra como usar a
DeleteConditionalFormatRuleRequest
para excluir a regra de formatação condicional com índice 0
na página 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 } } ] }
Ler 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 de uma planilha. O parâmetro de consulta fields
determina quais dados retornar.
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 for definido como o valor padrão, ele será omitido da resposta. A solicitação usa
ConditionType
como type
para
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 formato condicional existente 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 ("Custo total") 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
ConditionType
como type
para
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 } } } } } } ] }