Gerenciamento de estado em Vue 3 para painéis admin: Pinia vs local

O que torna o estado complicado em painéis admin

Painéis admin parecem cheios de estado porque reúnem muitas peças móveis na mesma tela. Uma tabela não é só dados. Também inclui ordenação, filtros, paginação, linhas selecionadas e o contexto “o que aconteceu agora?” do qual os usuários dependem. Adicione formulários longos, permissões baseadas em papéis e ações que mudam o que a UI deve permitir, e pequenas decisões sobre estado começam a importar.

O desafio não é armazenar valores. É manter o comportamento previsível quando vários componentes precisam da mesma verdade. Se um chip de filtro diz “Ativo”, a tabela, a URL e a ação de exportar devem concordar. Se um usuário edita um registro e navega para outro lugar, o app não deve perder o trabalho silenciosamente. Se abrirem duas abas, uma não deve sobrescrever a outra.

No Vue 3, você normalmente acaba escolhendo entre três lugares para manter estado:

• Estado local do componente: pertencente a um componente e seguro para resetar quando ele desmonta.
• provide/inject: estado compartilhado com escopo de página ou área de funcionalidade, sem precisar de prop drilling.
• Pinia: estado compartilhado que precisa sobreviver à navegação, ser reutilizado entre rotas e permanecer fácil de depurar.

Uma forma útil de pensar: para cada pedaço de estado, decida onde ele deve viver para que se mantenha correto, não surpreenda o usuário e não vire espaguete.

Os exemplos abaixo se prendem a três problemas comuns em admin: filtros e tabelas (o que deve persistir vs resetar), rascunhos e edições não salvas (formulários em que as pessoas confiam) e edição em múltiplas abas (evitar colisões de estado).

Uma forma simples de classificar o estado antes de escolher uma ferramenta

Debates sobre estado ficam mais fáceis quando você para de discutir ferramentas e primeiro nomeia o tipo de estado que tem. Diferentes tipos de estado se comportam de forma diferente, e misturá-los é o que cria bugs estranhos.

Uma divisão prática:

• Estado de UI: toggles, diálogos abertos, linhas selecionadas, abas ativas, ordem de ordenação.
• Estado do servidor: respostas de API, flags de carregamento, erros, hora da última atualização.
• Estado de formulário: valores dos campos, erros de validação, flags dirty, rascunhos não salvos.
• Estado entre telas: qualquer coisa que múltiplas rotas precisem ler ou alterar (workspace atual, permissões compartilhadas).

Depois defina o escopo. Pergunte onde o estado é usado hoje, não onde ele poderia ser usado no futuro. Se só importa dentro de um componente de tabela, estado local costuma bastar. Se dois componentes irmãos na mesma página precisam dele, o real problema é compartilhamento ao nível da página. Se várias rotas precisam, você está em território de estado compartilhado da aplicação.

A seguir vem o tempo de vida. Alguns estados devem resetar quando você fecha uma drawer. Outros devem sobreviver à navegação (filtros enquanto você entra num registro e volta). Alguns devem sobreviver a um reload (um rascunho longo que o usuário retorna depois). Tratar tudo igual é como se tem filtros que se resetam misteriosamente ou rascunhos que somem.

Finalmente, verifique concorrência. Painéis admin batem rápido em casos de borda: o usuário abre o mesmo registro em duas abas, um refresh em background atualiza uma linha enquanto um formulário está sujo, ou dois editores correm para salvar.

Exemplo: uma tela “Usuários” com filtros, uma tabela e uma drawer de edição. Filtros são estado de UI com tempo de vida de página. Linhas são estado do servidor. Campos da drawer são estado de formulário. Se o mesmo usuário for editado em duas abas, você precisa de uma decisão explícita de concorrência: bloquear, mesclar ou avisar.

Quando você consegue rotular o estado por tipo, escopo, tempo de vida e concorrência, a escolha da ferramenta (estado local, provide/inject ou Pinia) geralmente fica muito mais clara.

Como escolher: um processo de decisão que funciona

Boas escolhas de estado começam com um hábito: descreva o estado em palavras simples antes de escolher a ferramenta. Painéis admin misturam tabelas, filtros, formulários grandes e navegação entre registros, então mesmo um estado “pequeno” pode virar imã de bugs.

Um processo de decisão em 5 passos

1. Quem precisa do estado?

   • Um componente: mantenha local.
   • Vários componentes sob uma página: considere provide/inject.
   • Múltiplas rotas: considere Pinia.

   Filtros são um bom exemplo. Se só afetam uma tabela que os possui, estado local é suficiente. Se os filtros vivem em um componente de cabeçalho mas dirigem a tabela abaixo, compartilhar no nível da página (frequentemente provide/inject) mantém tudo limpo.

2. Quanto tempo ele precisa existir?

   • Se pode desaparecer quando o componente desmonta, estado local é ideal.
   • Se precisa sobreviver a uma mudança de rota, Pinia costuma ser a melhor opção.
   • Se precisa sobreviver a um reload, você também precisa de persistência (storage), independente de onde ele vive.

   Isso importa principalmente para rascunhos. Edições não salvas são sensíveis à confiança: as pessoas esperam que um rascunho ainda esteja lá se clicarem fora e voltarem.

3. Deve ser compartilhado entre abas do navegador ou isolado por aba?

   Edição multi-aba é onde bugs se escondem. Se cada aba deve ter seu próprio rascunho, evite um singleton global. Prefira estado indexado por ID do registro, ou mantenha escopo de página para que uma aba não sobrescreva a outra.

4. Escolha a opção mais simples que se encaixa.

   Comece local. Suba de nível só quando sentir dor real: prop drilling, lógica duplicada ou resets difíceis de reproduzir.

5. Confirme suas necessidades de depuração.

   Se você precisa de uma visão clara e inspecionável das mudanças entre telas, as actions e a inspeção centralizada do Pinia podem economizar horas. Se o estado é de curta duração e óbvio, estado local é mais fácil de ler.

Estado local do componente: quando é suficiente

Estado local é o padrão quando os dados importam apenas para um componente em uma página. É fácil pular essa opção e superconstruir uma store que você vai passar meses mantendo.

Um ajuste claro é uma só tabela com seus próprios filtros. Se os filtros só afetam uma tabela (por exemplo, a lista de Usuários) e nada mais depende deles, mantenha-os como ref dentro do componente da tabela. O mesmo vale para pequenos estados de UI como “o modal está aberto?”, “qual linha está sendo editada?” e “quais itens estão selecionados agora?”.

Tente não armazenar o que você pode computar. O badge “Filtros ativos (3)” deveria ser computado a partir dos valores de filtro atuais. Rótulos de ordenação, resumos formatados e flags de “pode salvar” também são melhores como valores computados porque ficam sincronizados automaticamente.

Regras de reset importam mais que a ferramenta que você escolhe. Decida o que limpa ao mudar de rota (geralmente tudo) e o que permanece quando o usuário troca de visão dentro da mesma página (você pode manter filtros, mas limpar seleções temporárias para evitar ações em massa surpresa).

Estado local geralmente basta quando:

• O estado afeta um widget (um formulário, uma tabela, um modal).
• Nenhuma outra tela precisa ler ou mudar isso.
• Você pode mantê-lo em 1–2 componentes sem passar props por muitas camadas.
• Você consegue descrever seu comportamento de reset em uma frase.

O limite principal é profundidade. Quando você começa a passar o mesmo estado por vários componentes aninhados, o estado local vira prop drilling, e esse é geralmente o sinal para migrar para provide/inject ou uma store.

provide/inject: compartilhar estado dentro de uma página ou área de funcionalidade

provide/inject fica entre estado local e uma store completa. Um pai “fornece” valores para tudo que está abaixo, e componentes aninhados “injetam” esses valores sem prop drilling. Em painéis admin, é um ótimo ajuste quando o estado pertence a uma tela ou área de funcionalidade, e não ao app inteiro.

Um padrão comum é um shell de página que possui o estado e componentes menores que o consomem: uma barra de filtros, a tabela, uma barra de ações em massa, uma drawer de detalhes e um banner de “alterações não salvas”. O shell pode fornecer uma superfície reativa pequena como um objeto filters, um objeto draftStatus (dirty, salvando, erro) e alguns flags somente-leitura (por exemplo, isReadOnly baseado em permissões).

O que fornecer (mantenha pequeno)

Se você fornecer tudo, basicamente recriou uma store com menos estrutura. Forneça apenas o que vários filhos realmente precisam. Filtros são um exemplo clássico: quando a tabela, os chips, a ação de exportar e a paginação precisam ficar em sincronia, é melhor compartilhar uma fonte única de verdade do que equilibrar props e events.

Clareza e armadilhas

O maior risco é dependências ocultas: um filho “simplesmente funciona” porque algo acima forneceu dados, e mais tarde é difícil dizer de onde as atualizações vêm. Para manter legibilidade e testabilidade, dê nomes claros às injeções (frequentemente com constantes ou Symbols). Também prefira fornecer actions, não apenas objetos mutáveis. Uma pequena API como setFilter, markDirty e resetDraft torna a propriedade e as mudanças permitidas explícitas.

Pinia: estado compartilhado e atualizações previsíveis entre telas

Pinia brilha quando o mesmo estado precisa permanecer consistente entre rotas e componentes. Em um painel admin, isso costuma significar o usuário atual, o que ele pode fazer, qual organização/workspace está selecionado e configurações em nível de app. Isso vira doloroso se toda tela reimplementa essas coisas.

Uma store ajuda porque oferece um lugar único para ler e atualizar estado compartilhado. Em vez de passar props por várias camadas, você importa a store onde precisa. Quando você vai de uma lista para uma página de detalhe, o resto da UI ainda pode reagir ao mesmo org selecionado, permissões e configurações.

Por que o Pinia parece mais fácil de manter

Pinia impõe uma estrutura simples: state para valores brutos, getters para valores derivados e actions para atualizações. Em UIs admin, essa estrutura impede que “gambiarras rápidas” virem mutações espalhadas.

Se “canEditUsers” depende do papel atual mais uma feature flag, coloque a regra em um getter. Se trocar de org exige limpar seleções em cache e recarregar navegação, coloque essa sequência em uma action. Você acaba com menos watchers misteriosos e menos momentos de “por que isso mudou?”.

Pinia também funciona bem com Vue DevTools. Quando um bug acontece, é muito mais fácil inspecionar o estado da store e ver qual action rodou do que perseguir mudanças em objetos reativos espalhados criados dentro de componentes aleatórios.

Evite a store-lixeira

Uma store global parece arrumada no começo, depois vira uma gaveta de coisas. Bons candidatos a Pinia são preocupações verdadeiramente compartilhadas como identidade do usuário, permissões, workspace selecionado, feature flags e dados de referência usados em várias telas.

Preocupações apenas de página (como input temporário de um formulário) devem permanecer locais, a menos que múltiplas rotas realmente precisem delas.

Exemplo 1: filtros e tabelas sem transformar tudo em uma store

Imagine uma página Orders: tabela, filtros (status, intervalo de datas, cliente), paginação e um painel lateral que pré-visualiza o pedido selecionado. Isso fica bagunçado rápido porque é tentador colocar cada filtro e configuração de tabela em uma store global.

Uma maneira simples de escolher é decidir o que deve ser lembrado e onde:

• Apenas memória (local ou provide/inject): reseta quando você sai da página. Ótimo para estado descartável.
• Query params: compartilhável e sobrevive ao reload. Bom para filtros e paginação que as pessoas copiam.
• Pinia: sobrevive à navegação. Bom para “voltar à lista exatamente como deixei”.

Daí a implementação normalmente segue:

Se ninguém espera que as configurações sobrevivam à navegação, mantenha filters, sort, page e pageSize dentro do componente da página Orders, e deixe essa página disparar o fetch. Se a toolbar, a tabela e o painel de preview precisam do mesmo modelo e o repasse de props está ficando incômodo, mova o modelo da lista para o shell da página e compartilhe via provide/inject. Se você quer que a lista seja ‘pegajosa’ entre rotas (abrir um pedido, navegar e voltar com os mesmos filtros e seleção), Pinia é a escolha correta.

Uma regra prática: comece local, migre para provide/inject quando vários componentes filhos precisarem do mesmo modelo e use Pinia apenas quando realmente precisar de persistência entre rotas.

Exemplo 2: rascunhos e edições não salvas (formulários que inspiram confiança)

Imagine um agente de suporte editando um registro de cliente: dados de contato, faturamento e notas internas. Ele é interrompido, troca de tela e depois volta. Se o formulário esquecer o trabalho dele ou salvar dados pela metade, a confiança some.

Para rascunhos, separe três coisas: o último registro salvo, as edições em rascunho do usuário e estado apenas de UI como erros de validação.

Estado local: rascunhos com regras claras de dirty

Se a tela de edição é autocontida, estado local do componente costuma ser o mais seguro. Mantenha uma cópia draft do registro, rastreie isDirty (ou um mapa de campos dirty) e armazene erros ao lado dos controles do formulário.

Um fluxo simples: carregue o registro, clone para um draft, edite o draft e envie um request de save apenas quando o usuário clicar em Salvar. Cancelar descarta o draft e recarrega.

provide/inject: um rascunho compartilhado entre seções aninhadas

Formulários admin frequentemente são divididos em abas ou painéis (Perfil, Endereços, Permissões). Com provide/inject você pode manter um modelo de draft e expor uma pequena API como updateField(), resetDraft() e validateSection(). Cada seção lê e escreve o mesmo draft sem passar props por cinco camadas.

Quando o Pinia ajuda com rascunhos

Pinia vira útil quando rascunhos precisam sobreviver à navegação ou serem visíveis fora da página de edição. Um padrão comum é draftsById[customerId], assim cada registro ganha seu próprio rascunho. Isso também ajuda quando usuários podem abrir várias telas de edição.

Bugs de rascunho vêm de erros previsíveis: criar um rascunho antes do registro ser carregado, sobrescrever um rascunho sujo ao refetch, esquecer de limpar erros ao cancelar ou usar uma única chave compartilhada que faz rascunhos sobrescreverem uns aos outros. Se você definir regras claras (quando criar, sobrescrever, descartar, persistir e substituir após salvar), a maioria desaparece.

Se você constrói telas admin com AppMaster (appmaster.io), a separação “rascunho vs registro salvo” ainda se aplica: mantenha o rascunho no cliente e trate o backend como fonte da verdade apenas após um Save bem-sucedido.

Exemplo 3: edição multi-aba sem colisões de estado

Edição multi-aba é onde painéis admin frequentemente quebram. Um usuário abre Cliente A, depois Cliente B, alterna entre eles e espera que cada aba lembre suas alterações não salvas.

A correção é modelar cada aba como seu próprio pacote de estado, não como um rascunho compartilhado. Cada aba precisa pelo menos de uma chave única (geralmente baseada no ID do registro), os dados do draft, status (limpo, sujo, salvando) e erros de campo.

Se as abas vivem dentro de uma mesma tela, uma abordagem local funciona bem. Mantenha a lista de abas e os rascunhos no componente da página que renderiza as abas. Cada painel de edição lê e escreve apenas seu próprio pacote. Ao fechar uma aba, delete esse pacote e pronto. Isso mantém as coisas isoladas e fáceis de raciocinar.

Não importa onde o estado viva, o formato é semelhante:

• Uma lista de objetos de aba (cada um com seu customerId, draft, status e errors)
• Um activeTabKey
• Ações como openTab(id), updateDraft(key, patch), saveTab(key) e closeTab(key)

Pinia se torna a escolha quando abas precisam sobreviver à navegação (ir para Orders e voltar) ou quando múltiplas telas precisam abrir e focar abas. Nesse caso, uma pequena store “tab manager” mantém o comportamento consistente pelo app.

A principal colisão a evitar é uma variável global única como currentDraft. Funciona até abrir a segunda aba — então edições sobrescrevem umas às outras, erros de validação aparecem no lugar errado e o Save atualiza o registro errado. Quando cada aba aberta tem seu próprio pacote, colisões praticamente desaparecem por design.

Erros comuns que causam bugs e código confuso

A maioria dos bugs em painéis admin não são “bugs do Vue”. São bugs de estado: dados vivem no lugar errado, duas partes da tela discordam ou estado velho fica por aí.

Aqui estão padrões que aparecem com mais frequência:

Colocar tudo no Pinia por padrão torna a propriedade nebulosa. Uma store global parece organizada no começo, mas logo cada página lê e escreve os mesmos objetos e limpeza vira adivinhação.

Usar provide/inject sem um contrato claro cria dependências ocultas. Se um filho injeta filters mas não existe entendimento de quem fornece e quais ações podem mudá-lo, você terá atualizações-surpresa quando outro filho começar a mutar o mesmo objeto.

Misturar estado do servidor e UI na mesma store causa sobrescritas acidentais. Registros buscados se comportam diferente de “drawer aberta?”, “aba atual” ou “campos sujos”. Quando vivem juntos, um refetch pode pisar na UI, ou mudanças de UI podem mutar dados em cache.

Pular a limpeza no ciclo de vida deixa estado vazar. Filtros de uma vista podem afetar outra, e rascunhos podem permanecer após sair da página. Na próxima vez que alguém abrir outro registro, verá seleções antigas e vai achar que o app está quebrado.

Chaves ruins para rascunhos são um silencioso destruidor de confiança. Se você guarda rascunhos sob uma chave única como draft:editUser, editar Usuário A e depois Usuário B sobrescreve o mesmo rascunho.

Uma regra simples previne a maior parte disso: mantenha o estado o mais próximo possível de onde é usado, e só eleve quando duas partes independentes realmente precisarem compartilhá-lo. Quando compartilhar, defina propriedade (quem pode mudar) e identidade (como é indexado).

Um checklist rápido antes de escolher local, provide/inject ou Pinia

A pergunta mais útil é: quem é o dono desse estado? Se você não consegue dizer em uma frase, o estado provavelmente está fazendo coisas demais e deve ser dividido.

Use estes cheques como filtro rápido:

• Você consegue nomear o dono (um componente, uma página ou o app inteiro)?
• Precisa sobreviver a mudanças de rota ou um reload? Se sim, planeje persistência em vez de esperar o navegador.
• Dois registros alguma vez serão editados ao mesmo tempo? Se sim, indexe estado por ID do registro.
• O estado é usado apenas por componentes sob um shell de página? Se sim, provide/inject costuma servir.
• Precisa inspecionar mudanças e entender quem mudou o quê? Se sim, Pinia costuma ser o lugar mais limpo para essa fatia.

Casamento de ferramenta, em termos simples:

Se o estado nasce e morre dentro de um componente (como um flag de dropdown aberto/fechado), mantenha local. Se vários componentes na mesma tela precisam de contexto compartilhado (barra de filtros + tabela + resumo), provide/inject compartilha sem tornar global. Se o estado deve ser compartilhado entre telas, sobreviver à navegação ou precisar de atualizações previsíveis e depuráveis, use Pinia e indexe por ID quando rascunhos estiverem envolvidos.

Se você estiver construindo uma UI admin em Vue 3 (incluindo uma gerada por ferramentas como AppMaster), esse checklist evita colocar tudo em uma store cedo demais.

Próximos passos: evoluindo o estado sem criar bagunça

A forma mais segura de melhorar o gerenciamento de estado em painéis admin é fazê-lo em passos pequenos e previsíveis. Comece com estado local para qualquer coisa que fique dentro de uma página. Quando vir reutilização real (lógica copiada, um terceiro componente precisando do mesmo estado), eleve um nível. Só então considere uma store compartilhada.

Um caminho que funciona para a maioria dos times:

• Mantenha estado apenas da página local primeiro (filtros, ordenação, paginação, painéis abertos/fechados).
• Use provide/inject quando vários componentes na mesma página precisarem de contexto compartilhado.
• Adicione uma store Pinia de cada vez para necessidades entre telas (draft manager, tab manager, workspace atual).
• Escreva regras de reset e siga-as (o que reseta na navegação, logout, Limpar filtros, Descartar alterações).

Regras de reset parecem pequenas, mas evitam a maioria dos momentos de “por que isso mudou?”. Decida, por exemplo, o que acontece com um rascunho quando alguém abre outro registro e volta: restaurar, avisar ou resetar. Depois torne esse comportamento consistente.

Se você introduzir uma store, mantenha-a moldada por feature. Uma store de rascunhos deve cuidar de criar, restaurar e limpar rascunhos, mas não deve também controlar filtros de tabela ou flags de layout de UI.

Se quiser prototipar um painel admin rapidamente, AppMaster (appmaster.io) pode gerar um app web Vue3 mais backend e lógica de negócio, e você ainda pode refinar o código gerado onde precisar de manipulação de estado personalizada. Um próximo passo prático é construir uma tela de ponta a ponta (por exemplo, um formulário de edição com recuperação de rascunho) e ver o que realmente precisa estar no Pinia versus o que pode ficar local.