Rating
Escolher a nota
Como foi o atendimento?
Nenhuma nota ainda.
Meia estrela
Média, só leitura
Tamanhos, ícone e desabilitado
import { Rating } from '@rivocode/ui'Quando usar
Nota em estrelas: como foi o atendimento, quanto a pessoa gostou do produto, a média que os outros deram. Serve para escolher a nota e para exibir a média, e as duas coisas saem com a leitura de tela certa.
const [nota, setNota] = useState(0)
<Rating value={nota} onValueChange={setNota} />
value é a nota, e 0 quer dizer nenhuma. Sem value, a peça guarda a nota
sozinha a partir de defaultValue. max diz quantas estrelas, e o padrão é
cinco.
Para o leitor de tela e para o teclado
A escolha é um radiogroup, o padrão da APG para rating: cada estrela é uma
opção com o nome da nota ("1 estrela", "3 estrelas"), e o grupo se chama
"Avaliação". Um aria-labelledby apontando para a pergunta da tela toma o
lugar do nome padrão, e é o jeito certo quando a pergunta está escrita acima.
- Tab entra pela nota marcada, ou pela primeira quando ainda não há nota.
- Setas andam uma estrela (meia, com
allowHalf) e param nas pontas. Emrtla seta da esquerda é a que sobe, como a pessoa vê, e o preenchimento nasce da borda da direita. - Home e End vão para a menor e para a maior nota.
- Espaço e Enter escolhem a estrela em foco.
Com o ponteiro em cima, as estrelas mostram a prévia da nota que o clique daria,
e a prévia some quando o ponteiro sai. A prévia não muda o value.
<p id="pergunta">Como foi a entrega?</p>
<Rating aria-labelledby="pergunta" value={nota} onValueChange={setNota} />
Meia estrela e limpar
allowHalf divide cada estrela em duas notas: a metade do início da leitura
(a esquerda, ou a direita em rtl) é a nota n - 0,5, e as setas andam de
meio em meio. As metades ganham nome próprio ("Meia estrela", "2,5 estrelas"),
uma opção cada para o leitor de tela. O alvo do ponteiro continua a estrela
inteira, com os mesmos 24px ou mais: a metade sai de onde o ponteiro caiu
dentro dela.
clearable faz o clique na nota já escolhida voltar a zero, e onValueChange
chega com 0. Nasce desligado: na maioria das telas a nota, uma vez dada, só se
troca.
<Rating allowHalf clearable value={nota} onValueChange={setNota} />
A média, só leitura
readOnly exibe sem deixar escolher. Aceita qualquer fração (4,3 pinta 30% da
quinta estrela) e sai como uma imagem só para o leitor de tela, com o nome
"4,3 de 5". Cinco estrelas lidas uma a uma não dizem a média; a frase diz.
<Rating readOnly value={4.3} size="sm" />
Cor, tamanho e ícone
A estrela cheia pinta em warning e a vazia em border-strong. As duas são
fronteira de objeto gráfico, e as duas estão medidas a 3:1 sobre bg,
surface e surface-raised, nos dois temas. Desabilitada, a cheia vira
fg-disabled e a vazia border-disabled.
size troca a estrela (sm, md, lg), e a caixa de cada uma nunca fica
abaixo de 24px de alvo. icon troca o desenho por outro ícone do lucide, como
<Heart />: o cheio sai com fill, então o ícone precisa ter área.
name põe a nota num input escondido, para o <form> enviar junto.
Partes
classNames alcança cada nó pelo nome: item (a caixa de cada estrela),
empty (o desenho vazio) e filled (o desenho cheio, recortado pela nota).
Textos
labels troca o que o leitor de tela ouve: group (o nome do grupo), item
(a função que diz o nome de cada nota) e value (a função que diz a média no
modo só leitura).
Quando não usar
- Número que precisa ser exato é
NumberField. Estrela é opinião, e o intervalo é pequeno: nota de 0 a 10 com decimal não cabe em estrela. - Faixa contínua, como desconto ou prazo, é
Slider. OSliderarrasta por uma régua; oRatingescolhe entre poucos degraus que têm nome. - Escolha entre opções que não são nota ("Ruim", "Bom", "Ótimo" escritos)
é
RadioGroup, ouToggleGroupquando os botões ficam lado a lado. Estrela só funciona quando mais é melhor. - Medida do sistema, como uso do plano ou força de senha, é
Meter. OMetermostra uma quantidade; oRatingmostra uma opinião.
No React Native
Traduz, com os mesmos max, allowHalf, clearable, readOnly e size. O value é controlado, como em todo o pacote nativo, e sem onValueChange a peça só exibe.
Para o leitor de tela, as estrelas são um controle só. No web a escolha é um radiogroup com uma opção por estrela; aqui o grupo é adjustable, o mesmo contrato do Slider: o VoiceOver e o TalkBack dizem "Avaliação, 3 estrelas", e o gesto de subir e descer anda uma estrela (meia, com allowHalf). Cinco paradas de foco para uma nota seriam cinco toques de navegação para chegar ao botão de enviar.
O alvo de toque de cada estrela é sempre 44pt. O size troca só o desenho. Com allowHalf, o toque na metade de início da leitura dá a meia estrela: a da esquerda, ou a da direita quando o aparelho lê da direita para a esquerda. O preenchimento também começa desse lado, e o gesto de subir continua subindo a nota. Não há prévia: no toque não existe pousar.
A estrela padrão é o Star do lucide-react-native, o mesmo do web, cheia em warning e vazada em border-strong. Para outro desenho, a função recebe a cor já resolvida, o tamanho e a camada: icon={({ color, size }) => <Heart color={color} fill={color} size={size} />}.
<Rating value={nota} onValueChange={setNota} allowHalf />
As partes vestem pelo mesmo classNames do web: item, empty e filled. As duas últimas vestem a estrela da casa, que é texto; com icon, a cor chega pela função.
API
| Prop | Tipo | Padrão |
|---|---|---|
allowHalfAceita meia estrela: as setas andam de meio em meio, e o leitor de tela ouve uma opcao por meia nota. | boolean | false |
classNames | Partial<Record<"empty" | "filled" | "item", string>> | sem padrão |
clearableClicar de novo na nota escolhida volta a nenhuma. | boolean | false |
defaultValueA nota ao montar, quando ninguem controla. | number | 0 |
disabledDesliga a escolha. | boolean | false |
iconTroca a estrela por outro icone do lucide (`<Heart />`, `<ThumbsUp />`). | ReactNode | sem padrão |
labelsOs textos que o leitor de tela ouve: o nome do grupo, o de cada nota e o da media. | Partial<RatingLabels> | sem padrão |
maxQuantas estrelas. | number | 5 |
nameNome do campo num `<form>`: a nota vai num `input` escondido. | string | sem padrão |
onValueChangeChamado com a nota nova: pelo clique, pelas setas, por Home e End. | ((value: number) => void) | sem padrão |
readOnlySo exibe: a media de um produto, a nota que outra pessoa deu. | boolean | false |
sizeO tamanho da estrela. | "lg""md""sm" | "md" |
valueA nota escolhida, controlada. | number | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.