Lista Aninhada

Organize opções em níveis hierárquicos

A Lista Aninhada é uma lista organizada em formato de árvore, onde cada opção pode conter sub-opções em quantos níveis forem necessários. O usuário navega pelos níveis expandindo as opções até chegar à desejada.

Use este tipo de lista quando as opções possuem relação hierárquica entre si — como códigos CNAE, categorias de produto com subcategorias, estruturas organizacionais por departamento/setor/equipe ou classificações fiscais com divisões e subdivisões.

Assim como a Lista Padrão, a Lista Aninhada é criada no nível do workspace e pode ser vinculada a campos de seleção em qualquer categoria.

Quando usar este tipo de lista

Utilize a Lista Aninhada quando precisar de uma estrutura de opções com níveis e subdivisões.

É ideal para:

• Códigos CNAE e classificações fiscais com divisões e subdivisões
• Categorias de produto com subcategorias e famílias
• Estruturas organizacionais (departamento → setor → equipe)
• Classificações geográficas (país → região → estado → cidade)
• Qualquer conjunto de dados com relação hierárquica natural

Estrutura de uma opção

Cada opção da lista possui:

• Nome — o texto exibido para o usuário (até 200 caracteres). Ex: "Cultivo de Soja".
• Descrição (opcional) — texto complementar exibido abaixo do nome da opção (até 300 caracteres).
• Ajuda (opcional) — texto de orientação exibido como tooltip ao passar o mouse sobre a opção no formulário (até 300 caracteres).
• Referência — número único gerado automaticamente pelo sistema para identificar a opção. Não pode ser editado. É utilizado em automações, fórmulas e integrações. A referência aparece como uma badge colorida ao lado do nome da opção, com cor diferente para cada nível de profundidade.

Como funciona

A lista suporta profundidade ilimitada de níveis. O sistema identifica visualmente cada nível por cores diferentes na badge de referência:

• Nível 1 (verde) — Principal. Ex: "Agricultura, Pecuária e Pesca".
• Nível 2 (azul) — Subcategoria. Ex: "Produção Agrícola".
• Nível 3 (laranja) — Detalhamento. Ex: "Cultivo de Cereais e Grãos".
• Nível 4+ (vermelho) — Específico. Ex: "Cultivo de Soja".

Cada opção exibe um contador (badge numérica) indicando quantas sub-opções diretas ela contém. O usuário clica na seta à esquerda para expandir e ver os níveis inferiores.

No formulário, a lista aninhada aparece como um dropdown com setas para expandir os níveis. O usuário clica na seta de uma opção para ver suas sub-opções e vai navegando até encontrar a desejada.

Se o campo de seleção onde a lista está vinculada tiver a Caixa de Busca ativada (disponível nos campos Lista de Seleção Única e Lista de Seleção Múltipla), o usuário pode digitar para buscar diretamente — a busca percorre todos os níveis de uma vez, sem precisar expandir manualmente.

Não há limite de quantidade de opções ou níveis por lista.

Configurações específicas

Seleção restrita

Isso é útil quando os níveis superiores servem apenas para organização e navegação, e a seleção válida é sempre a mais específica. Por exemplo, em uma classificação CNAE, o usuário deve selecionar o código mais detalhado (ex: "111110 — Cultivo de Soja"), não a categoria genérica ("11 — Agricultura").

Essa configuração funciona inclusive com campos de Seleção Múltipla — o usuário pode selecionar várias opções de último nível ao mesmo tempo, mas continua impedido de selecionar opções intermediárias.

Como criar uma lista aninhada

Gerenciando opções

Ao passar o mouse sobre qualquer opção da lista, três ações ficam disponíveis:

• + (verde) — adiciona uma sub-opção dentro daquela opção (nível inferior).
• Lápis (azul) — abre o modal de edição com Nome, Descrição, Ajuda e a referência da opção. O nome pode ser editado; a referência não.
• Lixeira (vermelho) — exclui a opção e todas as suas sub-opções.

Na barra superior da seção "Lista Aninhada", dois controles adicionais estão disponíveis:

• Expandir/Colapsar — expande toda a árvore para visualizar todos os níveis, ou colapsa para exibir apenas o nível 1.
• + (ao lado da busca) — adiciona sempre uma nova opção de nível 1.

Importação e exportação

Para listas grandes com muitos níveis (como tabelas de classificação oficiais), a importação em lote é mais prática do que adicionar opções manualmente.

Clique no botão de Importar para abrir o modal de importação. O processo funciona em dois passos:

1. Baixe o modelo Excel — clique em Baixar Modelo (Excel) para obter o arquivo XLSX com a estrutura correta.

2. Preencha e faça o upload — o arquivo deve seguir esta estrutura de colunas:

Regra das chaves

A chave é um número que define a qual nível a opção pertence e quem é seu pai. A regra é:

• A quantidade de dígitos determina o nível de profundidade (2 dígitos = nível 1, 3 dígitos = nível 2, 4 dígitos = nível 3, e assim por diante).
• A chave do filho deve começar com a chave do pai. É assim que o sistema sabe qual opção está dentro de qual.

Exemplo:

O botão de Exportar gera um arquivo XLSX com a mesma estrutura, permitindo editar externamente e reimportar.

Comportamento dos dados

Algumas alterações na lista afetam diretamente os itens que a utilizam:

• Alterar o nome de uma opção reflete imediatamente em todos os formulários e itens existentes.
• Alterar a referência não é possível; o número é gerado automaticamente e imutável.
• Excluir uma opção remove a referência nos itens que a utilizavam; eles exibirão um ID interno.
• Excluir uma opção-pai exclui todas as suas sub-opções em cascata; todos os itens que utilizavam qualquer opção daquele ramo perderão a referência.
• Reordenar opções não é possível por arrasto; a ordem é definida pela estrutura hierárquica e chaves de importação.
• Importar opções substitui toda a lista atual; itens que utilizavam opções removidas perderão a referência.

Boas práticas

• Planeje a estrutura hierárquica antes de criar a lista; reorganizar exige exclusão e recriação de opções.
• Utilize importação via Excel para listas grandes com muitos níveis (ex: CNAE completo) em vez de adicionar manualmente.
• Ative Selecionar Apenas Opções de Último Nível quando os níveis superiores forem apenas para navegação.
• Exporte a lista antes de realizar importações em massa como backup de segurança.
• Mantenha a consistência na nomenclatura das chaves para facilitar futuras importações.
• Utilize o campo Descrição para adicionar contexto sobre a opção sem poluir o nome exibido.

Exemplo prático

Uma lista de classificação de atividades econômicas com 5 níveis de profundidade:

Com a opção Selecionar Apenas Opções de Último Nível ativada, o usuário navega pela árvore expandindo os níveis até chegar a "111110 — Cultivo de Soja (específico)", que é a única opção selecionável. Os níveis superiores servem apenas para navegação e organização.