Controle de anexos no Power Apps Canvas: guia do preview

O Canvas ganhou, em preview público, um controle de anexos moderno com upload por arrastar e soltar, filtro de tipos de arquivo, validação e eventos disparados ao adicionar ou remover um arquivo. É a base para uma tela de recebimento de comprovantes e contratos que recusa o formato errado na entrada e registra cada movimento em um fluxo do Power Automate. Ao final deste tutorial, você terá essa tela funcionando em um ambiente de teste, com a validação em duas camadas e o registro de cada arquivo adicionado ou removido.

Um aviso antes de começar: o recurso está em preview, não em produção. Nome de propriedade, comportamento e disponibilidade podem mudar antes da disponibilidade geral. O tutorial foi desenhado em torno disso.

O que muda por estar em preview

Recursos em preview não têm o compromisso de suporte de um recurso em disponibilidade geral e podem ser alterados ou retirados. Para um controle de anexos isso pesa mais do que para um controle visual, porque ele toca em documento de cliente, comprovante e contrato. Um comportamento que mude entre builds pode deixar o app aceitando o que não devia, ou recusando o que devia aceitar.

Por isso, a ordem dos passos abaixo começa pelo isolamento do teste, e não pelo controle. Também há uma limitação de honestidade técnica: os nomes exatos das propriedades de arquivo e de evento do controle moderno ainda variam entre builds do preview. Onde o nome exato for incerto, o tutorial usa um identificador de substituição que força erro de compilação, para que nada passe despercebido. Você confirma o nome real no IntelliSense do seu studio.

Pré-requisitos para usar o controle de anexos Power Apps em preview

• Licença: Power Apps (plano por usuário ou por aplicativo) ou o plano de desenvolvedor, para o ambiente de teste. O fluxo precisa de Power Automate; se gravar em SharePoint, o conector é padrão. Se gravar em Dataverse, o conector é premium e exige licença correspondente para quem executa.
• Papéis: Administrador do Power Platform para criar o ambiente sandbox (ou permissão delegada para isso no tenant), e a função Environment Maker nesse ambiente para criar o app e o fluxo.
• Ambiente: um ambiente do tipo Sandbox, separado do que hospeda o app em produção.
• Destino do registro: uma lista SharePoint de teste chamada Registro de Recebimentos, com as colunas Title (nome do arquivo), TipoDocumento (texto), TamanhoKB (número), IdProcesso (texto), Acao (texto) e Usuario (texto).
• Disponibilidade: recursos em preview chegam de forma gradual, por região e por tenant. Se o controle não aparecer no seu studio, pode não ter chegado ainda, e não é erro de configuração.

Passo a passo

São seis etapas. O desenho abaixo mostra a sequência e destaca a primeira, que é a que mais evita prejuízo.

O passo 1 vem antes de qualquer configuração: ligar o preview em um app de produção é a armadilha que o restante do tutorial evita.

Passo 1: isole o teste antes de ligar qualquer coisa

Este é o passo que a pauta mais exige respeitar: não ative o controle em um app de produção. A chave de preview do studio é por aplicativo, então uma cópia do app recebe a chave sem afetar o original. Mas a cópia precisa viver em um ambiente de teste, porque quem abre um app publicado em produção usa a versão publicada, com o que ela contiver.

1. Acesse o Power Platform admin center e vá em Ambientes > Novo. Escolha o tipo Sandbox e dê um nome que não se confunda com o de produção, por exemplo "Homologacao-Recebimentos".
2. Em make.powerapps.com, selecione esse ambiente no seletor no canto superior direito.
3. Se já existe um app em produção que vai receber o controle, leve-o para o sandbox: exporte a solução que o contém e importe no ambiente de teste, ou use Salvar como para uma cópia nomeada de forma inequívoca. Para um app novo, crie-o direto no sandbox.

O racional é simples. Se o preview mudar de comportamento, o prejuízo fica no ambiente que existe para isso.

Passo 2: habilite os controles modernos no app

Abra o app de teste no Power Apps Studio e entre em Configurações > Atualizações. Procure, nas guias de recursos em preview (a organização das guias muda entre versões do studio), a opção de controles modernos e temas e, se houver uma opção específica para o controle de anexos, ative-a também. Salve e, se o studio pedir, recarregue o app.

Se o controle não aparecer em seguida, volte à ressalva dos pré-requisitos: o recurso pode ainda não estar liberado no seu tenant.

Passo 3: insira o controle e prepare a tela

Crie uma tela chamada scrRecebimento. Em Inserir, procure pelo controle de anexos na seção de controles modernos. Não confunda com o controle clássico Attachments, que vive dentro do cartão de dados de um formulário e tem outra lógica de propriedades. Renomeie o controle novo para ctrlAnexos.

Adicione também:

• Uma lista suspensa ddTipoDocumento com os valores "Comprovante" e "Contrato".
• Um botão btnEnviar.
• Uma variável varIdProcesso, preenchida com o identificador do processo ao qual os documentos pertencem.

No OnVisible da tela, crie uma coleção vazia que guardará apenas os arquivos aprovados na validação:

// OnVisible da scrRecebimento
// Cria o esquema da coleção e a esvazia em seguida
ClearCollect(colValidos; {nome: ""; kb: 0});;
Clear(colValidos)

As fórmulas deste tutorial usam o separador do Power Fx em português do Brasil: ponto e vírgula entre argumentos e ;; para encadear ações. Se o seu studio estiver configurado em inglês, troque ; por , e ;; por ;.

Passo 4: configure o filtro de tipos aceitos

Selecione ctrlAnexos e, no painel de propriedades, localize o campo de tipos de arquivo aceitos. Preencha com as extensões permitidas. O formato exato (com ou sem ponto, separador) aparece na dica do próprio campo no seu build; siga-o. Uma referência de política para esta tela:

Se a propriedade aceitar fórmula (a maioria das propriedades de controle no Canvas aceita), você pode fazer o filtro depender do tipo escolhido na lista suspensa, em vez de fixar um valor:

// Propriedade de tipos aceitos do ctrlAnexos
// Ajuste o formato do texto ao que a dica do campo indicar
If(
    ddTipoDocumento.Selected.Value = "Contrato";
    ".pdf";
    ".pdf,.png,.jpg,.jpeg"
)

Dois cuidados que não dependem do build. Primeiro, teste o filtro pelos dois caminhos de entrada, o seletor de arquivos e o arrastar e soltar. Não presuma que o comportamento seja idêntico. Segundo, o filtro de extensão é uma conveniência de interface, não uma garantia de segurança: um arquivo executável renomeado para .pdf passa por ele. Por isso o passo seguinte repete a validação na fórmula, e o fluxo do passo 6 deve conferir também o que chegar a ele.

Passo 5: programe os eventos de adicionar e remover

Na aba Avançado do controle, localize as propriedades de evento correspondentes a adicionar e a remover arquivo. É nelas que a automação se conecta. A fórmula do evento de adicionar valida extensão e tamanho, recusa o que estiver fora da política e, se estiver correto, guarda o arquivo na coleção e avisa o fluxo.

Os identificadores AJUSTAR_NOME e AJUSTAR_TAMANHO abaixo são propositais: representam as propriedades pelas quais o controle expõe o arquivo no seu build. Digite ctrlAnexos. ou use o IntelliSense dentro do evento para encontrar os nomes reais e substitua. Enquanto não o fizer, o studio sinaliza erro, o que impede a publicação de uma fórmula incompleta.

// Evento de adicionar arquivo do ctrlAnexos
Set(varNome; ctrlAnexos.AJUSTAR_NOME);;
// Confirme a unidade do tamanho no seu build (bytes é o caso comum)
Set(varTamanhoKB; ctrlAnexos.AJUSTAR_TAMANHO / 1024);;
Set(varExt; Lower(Last(Split(varNome; ".")).Result));;

If(
    !(varExt in ["pdf"; "png"; "jpg"; "jpeg"]) || varTamanhoKB > 5120;
    Notify(
        "Arquivo recusado: use PDF, PNG ou JPG de até 5 MB.";
        NotificationType.Error
    );
    Collect(colValidos; {nome: varNome; kb: varTamanhoKB});;
    RegistrarAnexo.Run(
        varNome;
        ddTipoDocumento.Selected.Value;
        varTamanhoKB;
        varIdProcesso;
        "adicionado";
        User().Email
    )
)

A coleção colValidos é o que sustenta o envio: só o que passou pela validação entra nela. Para o contrato, ajuste as extensões e o limite de tamanho da condição de acordo com a tabela do passo 4.

O evento de remover mantém a coleção sincronizada e registra a retirada:

// Evento de remover arquivo do ctrlAnexos
Set(varNome; ctrlAnexos.AJUSTAR_NOME_REMOVIDO);;
Remove(colValidos; LookUp(colValidos; nome = varNome));;
RegistrarAnexo.Run(
    varNome;
    ddTipoDocumento.Selected.Value;
    0;
    varIdProcesso;
    "removido";
    User().Email
)

Para impedir envio sem anexo válido, use a coleção na propriedade DisplayMode do botão:

// DisplayMode do btnEnviar
If(
    CountRows(colValidos) = 0;
    DisplayMode.Disabled;
    DisplayMode.Edit
)

A gravação do conteúdo do arquivo em si (biblioteca do SharePoint, coluna de arquivo do Dataverse) é uma etapa separada, ligada ao botão de envio, e depende do destino que você escolheu. Este tutorial cobre a entrada controlada e o registro de cada evento.

Passo 6: crie o fluxo que recebe os eventos

1. Em make.powerautomate.com, no mesmo ambiente de teste, vá em Criar > Fluxo de nuvem instantâneo e escolha o gatilho Power Apps (V2). Nomeie o fluxo RegistrarAnexo.
2. No gatilho, adicione cinco entradas, na ordem exata em que o app as envia: nomeArquivo (Texto), tipoDocumento (Texto), tamanhoKB (Número), idProcesso (Texto), acao (Texto), e uma sexta, emailUsuario (Texto).
3. Adicione a ação SharePoint > Criar item apontando para a lista Registro de Recebimentos, mapeando cada entrada do gatilho para a coluna correspondente.
4. Salve o fluxo. No Power Apps Studio, abra o painel Power Automate na barra lateral e use Adicionar fluxo para vinculá-lo ao app. Sem esse vínculo, RegistrarAnexo.Run(...) não é reconhecido.

O racional de usar um único fluxo com o parâmetro acao é manter uma trilha única de auditoria, em que cada arquivo aparece com a ação e o horário na mesma lista. Como o fluxo não tem ação de resposta ao Power Apps, o app em geral não espera o resultado para seguir. Isso é desejável aqui, porque a interface não deve travar por causa de um registro de auditoria. Se quiser confirmar a gravação antes de liberar o envio, adicione a resposta e trate o retorno no app.

Como validar que deu certo

Teste no modo de execução do studio e, depois, no player em navegador, com arquivos de amostra e não com documentos reais. Use esta matriz:

Confirme também no lado do fluxo: em make.powerautomate.com, abra o Histórico de execuções do RegistrarAnexo. Cada arquivo aceito deve gerar uma execução com status Bem-sucedido e, na lista do SharePoint, uma linha com nome, tipo, tamanho, processo, ação e e-mail do usuário. Compare o número de execuções com o número de arquivos que você adicionou e removeu no teste. Se não bater, o evento correspondente não está disparando.

Erros comuns

• O controle não aparece em Inserir. Causa mais provável: o recurso ainda não foi liberado na região ou no tenant, ou a opção de controles modernos não foi ativada nas Atualizações do app. Confira o passo 2 antes de procurar defeito.
• "Name isn't valid. 'AJUSTAR_NOME' isn't recognized." (no studio em português, a mensagem aparece traduzida). Esperado: é o identificador de substituição do passo 5. Troque pelo nome real da propriedade mostrado no IntelliSense.
• "Unexpected characters. Characters are used in the formula in an unexpected way." Quase sempre é o separador errado: vírgula em um studio configurado em português, ou ponto e vírgula em um studio em inglês.
• "The input body for trigger 'manual' of type 'Request' did not match its schema definition." no histórico do fluxo. O app enviou um valor de tipo diferente do declarado na entrada, por exemplo texto onde o gatilho espera Número. Confira a ordem e os tipos dos parâmetros em RegistrarAnexo.Run.
• O arquivo recusado continua visível na lista do controle. O evento dispara depois que o arquivo já foi adicionado, e a notificação não o remove sozinha. Por isso o envio deve ler a coleção colValidos, e nunca a lista bruta do controle.
• Um arquivo renomeado passa na validação. A checagem é por extensão. Para documentos sensíveis, some a ela uma verificação do lado do servidor no fluxo e, quando houver gravação no SharePoint, o antivírus do próprio serviço (como o Safe Attachments, para quem tem o Microsoft Defender for Office 365).
• O app em produção quebrou depois de uma atualização do preview. É a consequência direta de ter ativado o controle sem ambiente de homologação. Reverta para a versão publicada anterior pelo histórico do app e refaça o teste no sandbox.

Antes de levar isso a produção

O caminho recomendado é manter o app com o controle só em homologação, documentar os nomes de propriedade que você usou e rever a matriz de testes a cada atualização do studio. Para entrar em produção, espere a disponibilidade geral do controle. Se o negócio não puder esperar, o controle clássico de anexos, em formulário, continua sendo a alternativa suportada para o mesmo cenário.

Quando o desenho estiver estável, vale discutir onde os documentos devem ficar, quem pode lê-los e como o registro dos eventos alimenta a auditoria. Essa é a parte em que a Trinapse costuma apoiar quem leva a digitalização de comprovantes e contratos do protótipo para a operação.