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, sublinhado, cor de primeiro plano e cor de plano 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 ao idioma. 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. 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 é Planilha1!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
planilha. A primeira regra determina que as cores de plano de fundo das células
são definidas de acordo com o valor delas. O valor mais baixo na linha é vermelho escuro,
enquanto o mais alto é verde claro. 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 o
sheets.InterpolationPointType
como type.
O protocolo de solicitação é mostrado 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
de 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
abaixo 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 determina que as cores de plano de fundo das células com valores de 10 ou menos sejam alteradas para vermelho escuro. A regra é inserida no índice 0, portanto, tem
prioridade sobre outras regras de formatação. A solicitação usa o
ConditionType
como o type para o
BooleanRule.
O protocolo de solicitação é mostrado 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 de 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 planilha,
com base nos valores de data e texto nessas células. Se o texto contiver a string
"Cost" (sem distinçã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 anterior à semana passada, a segunda regra definirá o
texto da célula como itálico e a colorirá de azul. A solicitação usa o
ConditionType
como o type para o
BooleanRule.
O protocolo de solicitação é mostrado 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 planilha,
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.
O protocolo de solicitação é mostrado 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.
O protocolo de solicitação é mostrado 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 planilha em uma planilha. O parâmetro de consulta fields
determina quais dados serão retornados.
O protocolo de solicitação é mostrado 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 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 formato 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 células com o texto especificado ("Custo total") no
intervalo A1:D5. A movimentação da primeira solicitação é concluída antes do início da segunda, então
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.
O protocolo de solicitação é mostrado 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 } } } } } } ] }