Uma galeria
em Power Apps é um controle que repete automaticamente um mesmo modelo visual —
chamado de template — uma vez para cada linha de uma fonte de dados, permitindo
exibir listas inteiras sem a necessidade de criar manualmente um controle para
cada registro. Combinada com propriedades condicionais como DisplayMode e TemplateFill, a galeria pode reagir dinamicamente ao contexto do
aplicativo, alternando entre modo de leitura e edição, e destacando visualmente
o item selecionado pelo usuário.
Pré-requisito: você precisa ter concluído o tutorial anterior, com o Painel_MenuCadastros e o BtDiretores_Cad já configurados, incluindo a limpeza de variáveis e a
definição de varGlobal_Acao.
Botões de Painéis: Alternando entre Painéis
📌 Neste Tutorial você vai aprender
1. Construindo o Painel e a Galeria de Diretores
O que Você Vai Aprender Neste Tutorial
Você vai
aprender o que é uma galeria dentro do Power Apps, como ela se estrutura
internamente através de um template repetido, e vai construir, na prática, o Painel_Diretores e a galDiretorCad — a primeira galeria conectada a uma lista real de dados
dentro deste curso. Nossa primeira galeria não é uma galeria sofisticada, mas
em todos os componentes deste aplicativo existem códigos avançados que fogem
das regras de um simples controle. Nossa galeria é simples por ser uma galeria
de Título e Subtítulo, mas é uma galeria completa — depois de construí-la, você
será capaz de construir qualquer outra galeria deste sistema.
Por que Este Tutorial é Importante e sua Conexão com o Anterior
No tutorial
anterior, você criou o BtDiretores_Cad, o botão responsável por definir varGlobal_Acao como "Lista de Diretores" e limpar as variáveis de dados antes disso. Mas, até agora,
nenhum painel reage a essa mudança de variável — o botão existe, mas aponta
para um vazio. Este tutorial preenche exatamente essa lacuna: é aqui que o Painel_Diretores, com sua galeria, finalmente aparece quando o usuário toca
naquele botão.
2. Galerias: O que São, Para que Servem e Como se Estruturam
Uma galeria
é um controle que pega uma fonte de dados — uma tabela, uma coleção, o
resultado de um filtro — e repete, automaticamente, um mesmo modelo visual uma
vez para cada linha dessa fonte. Você desenha o layout de uma única linha —
onde vai o título, onde vai a data, onde vai qualquer outra informação — e a
galeria se encarrega de multiplicar esse layout para todos os registros
existentes, sem que você precise desenhar cartão por cartão manualmente.
Pense nela
como um molde de biscoito: você desenha a forma uma vez, e a galeria carimba
essa forma automaticamente para cada pedaço de massa — cada linha de dado — que
existir na fonte.
Toda galeria
tem, tecnicamente, duas grandes partes. A primeira é o próprio controle
Gallery — o container externo, responsável por propriedades como a fonte de
dados (Items),
a altura de cada linha (TemplateSize), a possibilidade de rolagem e navegação, e o comportamento
geral de seleção. A segunda é o template — o conjunto de controles
filhos que vivem dentro de cada linha, geralmente rótulos e retângulos
decorativos, que se repetem automaticamente para cada registro, usando a
palavra reservada ThisItem para acessar os dados daquela linha específica.
Como o Sistema de Controle de Bens Organiza o Painel de Diretores
No nosso
sistema, este painel será dividido em três partes, empilhadas verticalmente: a
parte superior, reservada para um sub-painel de controles — que ainda não vamos
construir neste tutorial —, logo abaixo a galeria que estamos construindo
agora, e mais abaixo o formulário de cadastro, que também fica para um tutorial
futuro.
Vale
destacar, desde já, a escolha de cor de preenchimento (Fill) deste painel: ela é única dentro do sistema, servindo
justamente para destacar visualmente esta área e reforçar sua identidade —
quando o usuário vê esse tom específico, ele já reconhece que está dentro do
contexto de Cadastro de Diretores, mesmo antes de ler qualquer texto.
A galeria em
si é transparente — ela não tem cor de fundo própria, deixando a cor do Painel_Diretores aparecer por trás dela. Isso é proposital: a galeria existe
para mostrar dados, não para competir visualmente com o painel que a contém.
3. Criando o Painel_Diretores e a Galeria galDiretorCad
Selecione a Area_TrabalhoCad na árvore lateral, confirme que ela está realmente
selecionada, e vá ao menu Inserir, categoria Layout, escolhendo Contentor.
Renomeie o novo container para Painel_Diretores.
Painel_Diretores:
Control: GroupContainer@1.5.0 (Contentor de Grupo)
Variant (Variante): ManualLayout (Layout Manual)
Properties (Propriedades):
BorderColor (Cor da Borda): RGBA(30; 14; 91; 1)
BorderThickness (Espessura da Borda): 2
Fill (Preencher): RGBA(232; 244; 217; 1)
Height (Altura): 935
RadiusBottomLeft/BottomRight/TopLeft/TopRight (Raio dos Cantos): 15 em cada
Visible (Visível): varGlobal_Acao = "Lista de Diretores" || varGlobal_Acao = "Cadastro de Diretor"
Width (Largura): Parent.Width
Y: 65
Com o Painel_Diretores selecionado na árvore, vá ao menu Inserir, categoria
Layout, e escolha Galeria. Quando o Power Apps oferecer os modelos de
layout, escolha o formato de Título e Subtítulo (BrowseLayout_Vertical_TwoTextVariant), que já traz dois rótulos prontos dentro do template.
Renomeie a galeria para galDiretorCad.
galDiretorCad:
Control: Gallery@2.15.0 (Galeria)
Variant (Variante): BrowseLayout_Vertical_TwoTextVariant_ver5.0
Properties (Propriedades):
BorderColor (Cor da Borda): RGBA(30; 14; 91; 1)
BorderThickness (Espessura da Borda): 2
DisplayMode (Modo de Exibição):
If(
varGlobal_Tarefa = "Novo Diretor" || varGlobal_Tarefa = "Editar Diretor";
DisplayMode.View;
DisplayMode.Edit
)
Height (Altura): 300
Items (Itens): tblGestaoDiretoria
OnSelect (Ao Selecionar):
Set(varGlobal_RegistroAtual; ThisItem);;
Set(varGlobal_Tarefa; "Ver Diretor");;
ViewForm(FormDiretorCad)
ShowNavigation (Mostrar Navegação): true
ShowScrollbar (Mostrar Barra de Rolagem): false
TemplateFill (Preenchimento do Modelo): If(ThisItem.IsSelected; RGBA(255; 255; 255; 1); RGBA(0; 0; 0; 0))
TemplateSize (Tamanho do Modelo): 50
Y: 52
Dentro do
template dessa galeria, você vai encontrar quatro controles filhos, já
parcialmente prontos pelo layout escolhido, mas que precisam de ajustes:
Control: Label@2.5.1 (Rótulo)
Properties (Propriedades):
BorderColor (Cor da Borda): RGBA(0; 18; 107; 1)
BorderThickness (Espessura da Borda): 1
Color (Cor): RGBA(50; 49; 48; 1)
Font (Fonte): Font.'Open Sans'
FontWeight (Peso da Fonte): If(ThisItem.IsSelected; FontWeight.Bold; FontWeight.Normal)
Height (Altura): 36
OnSelect (Ao Selecionar): Select(Parent)
PaddingBottom/Left/Right (Preenchimento): 0 / 10 / 0
Size (Tamanho): 13
Text (Texto): ThisItem.Direcao.DisplayName
VerticalAlign (Alinhamento Vertical): VerticalAlign.Top
Width (Largura): 370
X: 10
Y: 5
Control: Label@2.5.1 (Rótulo)
Properties (Propriedades):
BorderColor (Cor da Borda): RGBA(0; 18; 107; 1)
BorderThickness (Espessura da Borda): 1
Font (Fonte): Font.'Open Sans'
FontWeight (Peso da Fonte): If(ThisItem.IsSelected; FontWeight.Semibold; FontWeight.Normal)
Height (Altura): 36
OnSelect (Ao Selecionar): Select(Parent)
PaddingBottom/Left/Right (Preenchimento): 0 / 10 / 0
Size (Tamanho): 11
Text (Texto): ThisItem.DataInicio
VerticalAlign (Alinhamento Vertical): VerticalAlign.Top
Width (Largura): 247
X: 380
Y: 5
Control: Rectangle@2.3.0 (Retângulo)
Properties (Propriedades):
BorderColor (Cor da Borda): RGBA(92; 74; 168; 1)
Fill (Preencher): RGBA(255; 255; 255; 1)
Height (Altura): 4
OnSelect (Ao Selecionar): Select(Parent)
Width (Largura): Parent.TemplateWidth
Y: Parent.TemplateHeight - Self.Height
Control: Rectangle@2.3.0 (Retângulo)
Properties (Propriedades):
BorderColor (Cor da Borda): RGBA(92; 74; 168; 1)
Fill (Preencher): RGBA(92; 74; 168; 1)
Height (Altura): Parent.TemplateHeight - Separator5_7.Height
OnSelect (Ao Selecionar): Select(Parent)
Visible (Visível): ThisItem.IsSelected
Width (Largura): 4
4. DisplayMode, TemplateFill e os Controles Internos da Galeria
Como esta é
a primeira galeria completa deste curso, vamos abrir cada propriedade
importante com cuidado — a partir daqui, você já vai reconhecer esse mesmo
padrão em todas as galerias seguintes do sistema.
A Propriedade Visible do Painel: Duas Condições de Acesso
Visible:
varGlobal_Acao = "Lista de Diretores" || varGlobal_Acao =
"Cadastro de Diretor"
O Painel_Diretores fica visível em duas situações diferentes, unidas pelo
operador ||
(OU): quando varGlobal_Acao for "Lista de Diretores" — o estado que o BtDiretores_Cad já define — ou quando for "Cadastro
de Diretor", um estado que ainda vai ser usado
por um botão de criação, num tutorial futuro. Isso significa que o mesmo painel
serve tanto para visualizar a lista quanto para o momento de cadastro, sem
precisar de dois painéis separados fazendo praticamente a mesma coisa.
A Propriedade Items: Conectando a Galeria à Lista Real
Items:
tblGestaoDiretoria
Essa é a
propriedade mais importante da galeria: ela define de onde vêm os dados que
serão exibidos, linha por linha. tblGestaoDiretoria é a lista do SharePoint que você já conectou no tutorial
anterior — cada linha dessa lista vira, automaticamente, uma linha visível
dentro da galeria, sem nenhum código adicional de repetição.
DisplayMode: Quando a Galeria Pode e Não Pode ser Tocada
If(
varGlobal_Tarefa = "Novo Diretor" || varGlobal_Tarefa = "Editar Diretor";
DisplayMode.View;
DisplayMode.Edit
)
Aqui aparece
uma nuance importante sobre DisplayMode que ainda não tinha sido explorada em profundidade:
diferente do que você viu em botões, onde DisplayMode.Disabled significa "travado, sem reação nenhuma ao toque",
uma galeria também pode assumir o valor DisplayMode.View — que significa "visível e legível, mas sem permitir
seleção de um novo item". A diferença entre Disabled e View
é sutil, mas relevante: Disabled costuma vir acompanhado de uma aparência visualmente
"apagada"; View
mantém a aparência normal da galeria, apenas impedindo que o usuário troque a
seleção atual enquanto o formulário estiver em modo de criação ou edição.
A condição
testada aqui — varGlobal_Tarefa = "Novo
Diretor" || varGlobal_Tarefa = "Editar Diretor" — trava a galeria exatamente nos dois momentos em que seria
perigoso permitir uma nova seleção: enquanto o usuário está criando um Diretor
novo, ou editando um já existente. Se a galeria continuasse totalmente livre
nesses dois momentos, o usuário poderia, por engano, tocar em outro Diretor no
meio da edição, perdendo o que estava sendo digitado ou confundindo qual
registro está realmente sendo alterado.
O OnSelect: Guardando o Registro e Abrindo a Visualização
Set(varGlobal_RegistroAtual; ThisItem);;
Set(varGlobal_Tarefa; "Ver Diretor");;
ViewForm(FormDiretorCad)
Quando o
usuário toca numa linha da galeria, três coisas acontecem em sequência.
Primeiro, Set(varGlobal_RegistroAtual;
ThisItem) guarda o registro inteiro daquele
Diretor específico — todos os seus campos, não só o nome — numa variável global
nova, varGlobal_RegistroAtual, que vai servir de referência para o formulário que ainda
vamos construir. Segundo, Set(varGlobal_Tarefa;
"Ver Diretor") atualiza a micro-orientação do
sistema, avisando que agora o usuário está visualizando um registro específico.
Terceiro, ViewForm(FormDiretorCad) abre o formulário de Diretores — ainda não construído, mas
já referenciado aqui — em modo de visualização, mostrando os dados daquele
registro sem permitir edição imediata.
TemplateFill: O Destaque Visual do Item Selecionado
TemplateFill:
If(ThisItem.IsSelected; RGBA(255; 255; 255; 1); RGBA(0; 0; 0; 0))
Essa
propriedade controla a cor de fundo de cada linha da galeria, de forma
independente para cada item. ThisItem.IsSelected é uma propriedade especial, própria de galerias, que
responde à pergunta "esta linha específica é a que está selecionada
agora?" Se for verdadeiro, o fundo daquele cartão vira branco puro,
criando contraste imediato contra o fundo verde claro do restante da galeria.
Se for falso, o fundo fica totalmente transparente — repare no quarto argumento
0 dentro do segundo RGBA, o canal Alfa que você já aprendeu no tutorial anterior,
definindo opacidade zero — deixando a cor de fundo do Painel_Diretores aparecer por trás, sem destaque nenhum.
Os Controles Internos: lblTitulo_Diretor, lblData_Diretor e os Retângulos
Decorativos
O lblTitulo_Diretor mostra ThisItem.Direcao.DisplayName — o nome de exibição da pessoa cadastrada como Diretor
naquele registro específico. Repare no FontWeight:
If(ThisItem.IsSelected; FontWeight.Bold; FontWeight.Normal) — o texto fica em negrito automaticamente quando aquela
linha está selecionada, reforçando ainda mais o destaque já criado pelo TemplateFill.
O lblData_Diretor mostra ThisItem.DataInicio — a data em que aquele Diretor assumiu, informação que se
conecta diretamente com a lógica de varDiretoriaAtual que você vai usar mais adiante no sistema, para identificar
quem está em exercício no momento presente.
O Separator5_7 é um retângulo fino, posicionado sempre no rodapé de cada
cartão através da fórmula Y:
Parent.TemplateHeight - Self.Height
— uma posição relativa, que se ajusta automaticamente à altura real de cada
linha, sem depender de um número fixo. O Rectangle5_6 é a barra lateral de destaque, visível apenas quando ThisItem.IsSelected for verdadeiro — o mesmo padrão de destaque duplo (cor de
fundo mais barra lateral) que reforça, de duas formas diferentes ao mesmo
tempo, qual item está selecionado.
Em todos os
quatro controles internos, repare na propriedade OnSelect:
Select(Parent). Ela garante que, ao tocar em
qualquer parte visível do cartão — o título, a data, ou até uma área
aparentemente vazia —, o toque sempre propague a seleção para a linha inteira
da galeria, e não fique "preso" apenas ao controle específico que foi
tocado.
5. O que Você Aprendeu e os Cuidados para Não Errar
Você
entendeu o que é uma galeria dentro do Power Apps e como ela se estrutura
através de um template repetido, construiu o Painel_Diretores e a galDiretorCad, conectada diretamente à lista tblGestaoDiretoria, e aprendeu, em profundidade, o funcionamento de DisplayMode.View como estado intermediário entre travado e livre, além do
mecanismo de destaque visual criado por TemplateFill combinado com ThisItem.IsSelected.
Atenção Técnica
Sempre
inclua OnSelect: Select(Parent) em todo controle novo que for adicionado dentro do template
de uma galeria — sem essa linha, aquele ponto específico do cartão fica
"surdo" ao toque do usuário, mesmo que visualmente pareça parte do
mesmo item.
Erro Comum
O erro mais
comum ao configurar o DisplayMode de uma galeria é confundir DisplayMode.View com DisplayMode.Disabled, presumindo que os dois têm o mesmo efeito visual. O
resultado observável, quando essa confusão acontece, é uma galeria que parece
"travada" com aparência apagada, quando na verdade a intenção era
mantê-la com aparência normal, apenas impedindo uma nova seleção.
O Que Vem a Seguir
No próximo
tutorial vamos criar o Painel_MenusDiretores e o Título_GaleriaDiretores — o sub-painel de controles que vai ocupar a parte superior
do Painel_Diretores,
ainda reservada e vazia até este momento.
Nenhum comentário:
Postar um comentário