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 plano de fundo) podem ser controlados com a formatação condicional. Os exemplos nesta página ilustram como realizar operações comuns de formatação condicional com a API Google 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 linguagens 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 acessar o ID da planilha usando o método spreadsheets.get. Os intervalos são especificados usando a notação A1. Um exemplo de intervalo é
Página1!A1:D5.
Adicionar um gradiente de cor condicional em uma linha
O exemplo de código do método
spreadsheets.batchUpdate
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 afirma que as células nessa linha têm as cores de plano de fundo definidas de acordo com o valor delas. O menor valor na linha é vermelho-escuro, e o maior é 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 o 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 } }, ] }
Depois da solicitação, a regra de formatação aplicada atualiza a planilha. Como o ponto máximo do gradiente na linha 11 está 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 afirma que as células com valores de 10 ou menos têm as cores de fundo alteradas para um vermelho escuro. A regra é inserida no índice 0, então ela 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 } } ] }
Depois da 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 no intervalo A1:D5 de uma planilha,
com base em valores de data e texto nessas células. Se o texto contiver a string "Custo" (sem diferenciar maiúsculas de 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 vai definir o texto da célula em itálico e 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 } } ] }
Depois da 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 } } ] }
Depois da 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
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
}
}
]
}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, o SHEET_ID e a lista de
todas as regras de formatação condicional de cada página 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 formatação 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. O movimento da primeira solicitação é concluído 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 o 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 } } } } } } ] }