Table Action
O br-table-action representa uma ação da tabela e renderiza um botão. Na
composição de <br-table>, utilize-o:
- com
slot="global-actions"ouslot="contextual-actions"para ações da barra; - dentro de
<br-table-cell>para ações associadas a uma linha.
O componente pai organiza essas ações conforme o contexto. Não use
br-table-action isoladamente ou fora da composição da tabela.
Visão Geral
Para a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o Design System do GovBR.
Representa uma ação global, contextual ou associada a uma linha da tabela.
Use declarativamente nas células ou nos slots de ações de br-table; o
orquestrador também cria esta peça internamente para expandir linhas.
Fora da composição da tabela, prefira br-button.
O contexto é inferido pelo slot e pela posição do componente na árvore.
Para executar funções a partir das ações, ouça o evento brTableActionClick:
<!-- 1. Ouvindo diretamente na ação -->
<br-table-action id="btn-filtro" label="Filtros" icon-name="fa-solid:filter"></br-table-action>
<script>
document.getElementById('btn-filtro').addEventListener('brTableActionClick', () => {
executarFiltros();
});
</script>
<!-- 2. Ouvindo na tabela (recomendado para ações diretas e colapsadas em menu) -->
<script>
table.addEventListener('brTableActionClick', (event) => {
const { type, label, rowIndex } = event.detail;
if (type === 'row') executarAcaoLinha(label, rowIndex);
else if (type === 'global') executarAcaoGlobal(label);
});
</script>
Propriedades
ariaLabel
| Atributo | aria-label |
|---|---|
| Descrição | Rótulo acessível. Quando omitido, utiliza label. |
| Tipo | string |
| Valor padrão | null |
density
| Atributo | density |
|---|---|
| Descrição | Densidade visual aplicada ao botão interno da ação. |
| Tipo | "large" | "medium" | "small" |
| Valor padrão | --- |
iconName
| Atributo | icon-name |
|---|---|
| Descrição | Nome do ícone exibido pelo botão. |
| Tipo | string |
| Valor padrão | null |
label
| Atributo | label |
|---|---|
| Descrição | Texto visível e identificação semântica da ação. |
| Tipo | string |
| Valor padrão | null |
Eventos
| Evento | Descrição | Depreciação | Propagação |
|---|---|---|---|
brTableActionClick | Emitido quando o usuário aciona o botão. | --- | true |
Execução de Funções e Manipulação de Ações
O br-table-action emite o evento personalizado brTableActionClick (bubbles: true, composed: true) ao ser acionado.
1. Escutando na <br-table> (Recomendado)
O componente <br-table> unifica a captura de todas as ações (global, contextual e row), inclusive quando ações excedentes são recolhidas no menu (kebab). Quando a ação pertence a uma linha (type: 'row'), o evento inclui automaticamente a propriedade rowIndex.
<br-table id="tabela-exemplo">
<!-- Ação global na barra de título -->
<br-table-action slot="global-actions" label="Filtros" icon-name="fa-solid:filter"></br-table-action>
<!-- Ação contextual ao selecionar linhas -->
<br-table-action slot="contextual-actions" label="Excluir" icon-name="fa-solid:trash-alt"></br-table-action>
<!-- Ação associada a uma linha de dados -->
<br-table-cell>
<br-table-action label="Editar" icon-name="fa-solid:edit"></br-table-action>
</br-table-cell>
</br-table>
<script>
const table = document.getElementById('tabela-exemplo');
table.addEventListener('brTableActionClick', (event) => {
const { type, label, rowIndex } = event.detail;
switch (type) {
case 'global':
if (label === 'Filtros') abrirModalFiltros();
break;
case 'contextual':
if (label === 'Excluir') confirmarExclusaoSelecionados();
break;
case 'row':
if (label === 'Editar') editarRegistro(rowIndex);
break;
}
});
function abrirModalFiltros() {
console.log('Executando função de filtros globais');
}
function confirmarExclusaoSelecionados() {
table.getSelectedRows().then((linhas) => {
console.log('Executando função para linhas selecionadas:', linhas);
});
}
function editarRegistro(rowIndex) {
console.log('Executando função para o registro no índice:', rowIndex);
}
</script>
2. Escutando diretamente no elemento <br-table-action>
Você também pode registrar ouvintes de evento diretamente em um elemento <br-table-action> específico:
<br-table-action
id="btn-adicionar"
slot="global-actions"
label="Adicionar item"
icon-name="fa-solid:plus"
></br-table-action>
<script>
const btnAdicionar = document.getElementById('btn-adicionar');
btnAdicionar.addEventListener('brTableActionClick', () => {
abrirModalCriacao();
});
</script>
Quando a tabela utiliza limites de ações (heading-actions-limit, contextual-actions-limit ou cell-actions-limit), ações excedentes são agrupadas em um menu suspenso. Escutar brTableActionClick na <br-table> garante que sua função seja executada tanto no clique direto no botão quanto na seleção do item dentro do menu suspenso.
