```meta
title: @period — o período que o leitor escolhe para a página inteira
description: Um controle "7 dias · 14 dias · 30 dias" que muda todos os @data da página, e a variação contra o período anterior em cada número.
```

_flows.md · documentação · [Blocos](/@docs/blocks)_

# @period

O período que o leitor escolhe uma vez para a página inteira: os botões são links (`?janela=14`), a opção escolhida fica marcada, e todo `@data` da página conta a partir dela. Funciona sem script, e um endereço com a escolha leva quem o recebe à mesma página.

## Ao vivo

Os exemplos leem a coleção `alcance-exemplo`, declarada nesta página (um leitor não vê a declaração), com o alcance inventado de uma conta, um dia por linha, nos últimos 60 dias.

```@schema collection:alcance-exemplo visibility:public
dias number required label:"Dias atrás"
dia date label:"Dia"
alcance number label:"Alcance"
```

```@period name:janela options:7,14,30 default:7
```

```@data collection:alcance-exemplo view:metric
@filter dia gt -{janela}d
@sum alcance label:"Alcance · últimos {janela} dias" delta:previous
@avg alcance label:"Média por dia" decimals:0 delta:previous
```

```@data collection:alcance-exemplo view:chart type:bar look:spark focal:last sort:dia limit:30
@filter dia gt -{janela}d
@column dia label:"Dia"
@column alcance label:"Alcance"
```

~~~text
```@period name:janela options:7,14,30 default:7
```

```@data collection:alcance-exemplo view:metric
@filter dia gt -{janela}d
@sum alcance label:"Alcance · últimos {janela} dias" delta:previous
@avg alcance label:"Média por dia" decimals:0 delta:previous
```
~~~

Escolha outro período acima: os números, o rótulo e as barras mudam juntos.

## Como o @data lê o período

- `{janela}` no valor de um `@filter` é o número escolhido: `@filter dia gt -{janela}d` fica com os dias escolhidos, hoje incluído. Sem escolha no endereço (ou com um número que o período não oferece), vale o `default:`.
- `{janela}` no `label:` de uma linha de métrica ou no `title:` do `@data` escreve o número.
- `delta:previous` numa linha de métrica compara com o período do mesmo tamanho logo antes e escreve ao lado do número ▲ ou ▼ e a variação em porcentagem, verde para cima e vermelho para baixo, com a frase para quem usa leitor de tela. Quando o período anterior não tem número, não escreve nada.

## Argumentos

- `name` — o parâmetro que os links levam e o nome que o `@data` escreve entre chaves (`{janela}`).
- `options` — os números oferecidos, em ordem (até 8, de 1 a 999).
- `default` — a opção de quando o endereço não diz nenhuma; a primeira, se não for dito.
- `unit` — `d` (dias, o padrão) ou `w` (semanas); o filtro escreve a mesma unidade (`-{janela}w`).
- `label` — as palavras de cada opção, `{n}` no lugar do número (`label:"{n}d"`); sem ele, "7 dias" na língua de quem lê.
- `style` — um estilo do tema `for:period` (a pílula de fundo e a opção escolhida em branco, por exemplo).