# Visão geral ## O que é PocketBlocks? **Openblocks + PocketBase = PocketBlocks.** PocketBlocks é uma integração entre Openblocks e PocketBase. Tradicionalmente, construir um aplicativo interno requer interações complexas de front-end e back-end com centenas ou milhares de linhas de código, sem mencionar o trabalho de empacotamento, integração e implantação. PocketBlocks reduz significativamente o trabalho que você precisa fazer para construir um aplicativo. No PocketBlocks, tudo o que você precisa fazer é arrastar e soltar componentes pré-construídos ou autopersonalizados na tela What-You-See-Is-What-You-Get (WYSIWYG). PocketBlocks ajuda você a construir um aplicativo rapidamente e se concentrar na logíca do negócio. ## Por que escolher PocketBlocks? * **Código aberto**: Torna suas ideias mais viáveis. * **Alta escalabilidade**: Permite executar JavaScript em praticamente qualquer lugar onde você gostaria de personalizar seus processos de negócios e componentes de UI. * **Design limpo**: Segue os princípios do Ant Design e suporta exibição em telas de diferentes tamanhos. Temos vários componentes de UI, com base nos quais você pode construir livremente painel de controle, painel de administração e sistema de gerenciamento de conteúdo (CMS). ## Como construir um aplicativo no PocketBlocks? Construir um aplicativo interno leva basicamente 4 passos: 1. Conecte-se rapidamente à sua API Pocketbase usando o SDK. 2. Use componentes de UI pré-construídos ou personalizados pelo usuário para construir a UI do seu aplicativo. 3. Configure [manipuladores de eventos](/portugues-brasil/construcao-de-aplicativos/event-handlers) para acionar funções javascript, controlar componentes ou outras ações em reação às interações do usuário. 4. Visualize e compartilhe seu aplicativo com outras pessoas. # Instalação Neste artigo, você vai aprender como hospedar PocketBlocks em seu próprio servidor: ### Manualmente * Baixe o binário do seu sistema operacional e arquitetura na [Página de Lançamento](https://github.com/pedrozadotdev/pocketblocks/releases); * Execute o comando `./pocketblocks serve` no terminal; * Acesse o [Aplicativo do PocketBlocks](http://localhost:8090) e crie o primeiro usuário administrador. ### Docker * Salve o arquivo [docker-compose.yml](https://raw.githubusercontent.com/pedrozadotdev/pocketblocks/main/docker-compose.yml); * Execute o comando `docker compose up -d` no terminal; * Acesse o [Aplicativo do PocketBlocks](http://localhost:8080) e crie o primeiro usuário administrador. ### Fly.io * Salve o arquivo [fly.toml](https://raw.githubusercontent.com/pedrozadotdev/pocketblocks/main/fly.toml); * Edite o campo `app-name`; * Execute o comando `flyctl launch` no terminal; * Execute o comando `flyctl vol create data` no terminal; * Execute o comando `flyctl deploy` no terminal; * Acesse `https://.fly.dev` e crie o primeiro usuário administrador. {% hint style="info" %} Lembre-se de que PocketBlocks usa o Openblocks como frontend. O diretório `pb_public` já está configurado, mas você pode usar o diretório `pbl_public` e todos os arquivos desse diretório serão servidos no caminho `/pbl/`. {% endhint %} # Criando um novo aplicativo ## Criando um novo aplicativo da web Clique em **Novo > Aplicativo** no canto superior direito da página inicial do Pocketblocks e vá para o editor do aplicativo. Você pode renomear o aplicativo no canto superior esquerdo do editor.
{% hint style="info" %} Apenas **administradores** do espaço de trabalho podem criar aplicativos. {% endhint %} ## Exportando e importando um aplicativo ### Exportando um aplicativo Clique no nome do seu aplicativo e selecione **Exportar para JSON**, o aplicativo será exportado para um arquivo JSON.
### Importando um aplicativo Você pode importar um aplicativo existente em formato JSON clicando em **Novo > Importar**.
# Editor de aplicativo Dê uma rápida olhada no editor de aplicativos antes de começar No PocketBlocks, o editor de aplicativos é onde você monta componentes, cria funções javascript para interagir com os dados do PocketBase e publica seus aplicativos. É composto por cinco áreas: 1. Barra de ferramentas 2. Canvas 3. Navegador de dados 4. Editor de consultas 5. Painel de componentes e propriedades
## Barra de ferramentas A barra de ferramentas é composta por uma barra superior e uma barra lateral esquerda.
Na barra superior, você pode configurar seu aplicativo da seguinte forma: * Alterar o nome do aplicativo * Exportar para um arquivo JSON * Controlar a visibilidade de outras áreas * Compartilhe seu aplicativo * Visualize e implante seu aplicativo * Verifique as versões do histórico Na barra lateral esquerda, algumas opções estão disponíveis como segue: * Mostrar ou ocultar o **Navegador de dados** * Defina o tamanho da tela e o tema do aplicativo * Gerenciar scripts e estilos CSS * Iniciar tutorial para editor de aplicativos * Mostrar atalhos de teclado ## Canvas O Canvas no centro do editor é onde você projeta e vê a UI geral. Arraste e solte componentes na tela, vincule-os a manipuladores de dados e eventos e monte-os para criar um aplicativo poderoso e agradável.
Confira [Design UI do aplicativo](/portugues-brasil/construcao-de-aplicativos/design-app-ui) para práticas de layout de UI. ## Navegador de dados O navegador de dados no painel esquerdo contém as seções **Consultas**, **Componentes** e **Globais**. Aqui você pode inspecionar os dados em uma estrutura em árvore. Por exemplo, para verificar os dados retornados de uma consulta ou componente específico, encontre seu item na seção pertencente e clique empara expandir.
## Editor de consultas O editor de consultas na parte inferior consiste em duas seções: lista de consultas (com as guias **Consultas** e **Metadados**) à esquerda e configurações de consulta (com **Geral**, **Notificação** e **Guias Avançadas**) à direita. Crie consultas para interagir com a API Pocketbase aqui.
Você pode acessar o SDK do Pocketbase através do objeto **window\.pb**. ## Painel de componentes e propriedades O painel de componentes e propriedades está localizado à direita da janela. Arraste os componentes para a tela a partir da guia **Inserir** e edite as propriedades dos componentes na guia **Propriedades**. ![](https://3319212993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fbz5pg8HuItSzRC8Qjkc6%2Fuploads%2Fgit-blob-1950caf7abe4060c084dafe558fb7223b5e001de%2F07.png?alt=media) ![](https://3319212993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fbz5pg8HuItSzRC8Qjkc6%2Fuploads%2Fgit-blob-d374ffcb88b8da7e78dedd864e152a2d04216b68%2F08.png?alt=media) Quando um componente é selecionado na tela, a guia **Propriedades** será ativada automaticamente e exibirá as propriedades desse componente. # Manipuladores de eventos No PocketBlocks, os manipuladores de eventos são responsáveis ​​por coletar e processar eventos de componentes e consultas e executar ações subsequentes. Por exemplo, para um componente **Botão**, você pode adicionar um manipulador de eventos para acionar a ação **Executar consulta** em resposta ao evento **Clique** do botão.
Defina manipuladores de eventos com sabedoria para fornecer uma experiência de usuário (UX) reativa e responsiva. Por exemplo, acionar uma consulta **retorna todos os dados** após o término da consulta de **inserção de dados** permite a atualização automática da tabela. {% hint style="info" %} Você pode adicionar quantos manipuladores de eventos desejar para um único componente ou consulta, e esses manipuladores de eventos serão executados simultaneamente. {% endhint %} ## Eventos ### Eventos de componentes Componentes diferentes têm eventos diferentes. Por exemplo, os componentes **Botão** possuem apenas um evento **Clique**.
Os componentes **Input** têm eventos **Mudar**, **Foco**, **Desfoque** e **Enviar**.
### Consultar eventos A execução de uma consulta pode resultar em sucesso ou falha, portanto, as consultas têm dois eventos: **Sucesso** ou **Falha**. Você pode adicionar manipuladores de eventos a consultas no Editor de consultas.
## Ações Existem várias ações de manipulador de eventos disponíveis no PocketBlocks para lidar com diferentes cenários. Defina-os na lista suspensa **Ação** em um manipulador de eventos. ![](https://3319212993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fbz5pg8HuItSzRC8Qjkc6%2Fuploads%2Fgit-blob-63ca9265154af55596c732d0699d0e6dcc4277e4%2F05.png?alt=media) {% hint style="info" %} Consulte [avançado](#advanced) nesta página para conhecer as configurações avançadas. {% endhint %} ### Executar consulta Acione a consulta selecionada. ![](https://3319212993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fbz5pg8HuItSzRC8Qjkc6%2Fuploads%2Fgit-blob-ee3b546ad05eb64467eb8e6af4a02554090132da%2F06.png?alt=media) ### Controlando Componentes Para controlar um componente, selecione um componente na lista suspensa **Componente** e chame um de seus métodos na lista suspensa **Método**. ![](https://3319212993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fbz5pg8HuItSzRC8Qjkc6%2Fuploads%2Fgit-blob-17a7ccc19efe32d1b5fc72dcb18ed0cc20cd437e%2F07.png?alt=media) ### Definir estado temporário Armazene dados em um [estado temporário](/portugues-brasil/construcao-de-aplicativos/write-javascript/temporary-state). ### Vá para um aplicativo Navegue até um aplicativo PocketBlocks com consulta opcional ou parâmetros de hash. | Parâmetro | Função | | -------------------------- | ---------------------------------------------------------------------------------------------- | |

Consulta de URL

|

Anexar ?key1=value1\&key2=value2... ao URL do aplicativo a ser aberto.

| | Hash de URL | Anexe `#key1=value1&key2=value2...` ao URL do aplicativo a ser aberto. | #### **Caso de uso** No aplicativo **Lista de usuários**, clique em **Ver informações** para navegar até o aplicativo **Informações do usuário** e as informações detalhadas do usuário na linha selecionada serão exibidas. 1. O aplicativo **Lista de usuários** passa `{{currentRow.id}}` na linha da tabela como um parâmetro de consulta de URL para o aplicativo **Informações do usuário**.
2. O campo URL da variável global do aplicativo **Informações do usuário** resolverá automaticamente o URL solicitado pelo aplicativo. Neste caso, o valor de `url.query` é `{"id":3}`, então a consulta recuperará as informações do usuário correspondentes via `{{url.query.id}}`. Veja a figura abaixo.
### Ir para URL Navegue para um URL externo. ![](https://3319212993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fbz5pg8HuItSzRC8Qjkc6%2Fuploads%2Fgit-blob-9ff1a09dcd1e1f951297e5555de3bb360e42dec8%2F10.png?alt=media) ### Mostrar notificação Mostre uma notificação flutuante de mensagem informativa, de sucesso, de aviso ou de erro. ![](https://3319212993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fbz5pg8HuItSzRC8Qjkc6%2Fuploads%2Fgit-blob-6b25995fa580812164f243f112aba47dfd1e1d40%2F11.png?alt=media) ### Copiar para área de transferência Copie um valor para a área de transferência. ![](https://3319212993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fbz5pg8HuItSzRC8Qjkc6%2Fuploads%2Fgit-blob-702abbe61107557fc62a6d2ae4bab49a9a0211c7%2F12.png?alt=media) ### Exportar dados Exporte dados em um determinado tipo de arquivo (TXT, JSON, CSV e Excel). ![](https://3319212993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fbz5pg8HuItSzRC8Qjkc6%2Fuploads%2Fgit-blob-365ce2d597f8b986b037e15bbdd43433c9764a00%2F13.png?alt=media) ## Avançado ### Execute apenas quando A ação só pode ser acionada sob uma condição especificada. Configure a condição de execução de um manipulador de eventos na opção **Executar somente quando** e, em seguida, o manipulador de eventos será executado somente quando esta condição for avaliada como `true`. ### Debounce e throttle **Debounce** e **Throttle** reduzem a frequência de acionamento da ação. #### **Debounce** Debounce atrasa uma ação. Uma vez definido o tempo de debounce, a ação não será executada imediatamente após o evento até que o tempo de debounce passe. Se o evento ocorrer novamente antes do término do tempo, o tempo de debounce será cronometrado novamente. Por exemplo, um componente de entrada aciona uma consulta quando o usuário altera o texto. Se a execução da consulta for cara e você não quiser executá-la depois que cada caractere for digitado, você poderá atrasar a execução da consulta definindo o tempo de rejeição. Então a consulta só será executada depois que o usuário terminar de digitar. #### **Throttle** Throttle permite que uma ação aconteça apenas uma vez durante um período de tempo especificado. Por padrão, cada evento desencadeia uma ação, mas às vezes executar uma ação pode custar caro. Por exemplo, você define um identificador de evento para acionar a ação **Executar consulta** para atualizar dados em resposta ao evento **Clique**, mas acha que essa consulta é muito cara para ser executada, então você pode definir um tempo de aceleração para permitir que a consulta seja executada apenas uma vez em um determinado período. # Escrevendo JavaScript # Escrevendo JavaScript por {{ }} Ao construir aplicativos no PocketBlocks, você pode usar JavaScript (JS) para acessar e transformar dados de objetos, incluindo componentes, consultas e parâmetros globais. Ao escrever JavaScript dentro da caixa de entrada da propriedade do componente, configurações de coluna da tabela, etc., lembre-se sempre de colocar todo o seu código JS entre chaves duplas, como `{{'olá, ' + usuarioAtual.nome}}`. ## Acessando dados Os objetos têm nomes globalmente exclusivos, como `entrada1`, `consulta1` e `tabela1`. Você pode consultar as propriedades dos objetos em seu aplicativo por código JS. ### Acessando dados em um objeto PocketBlocks oferece suporte para acessar os dados em um objeto usando notação de ponto (`nomeDoObjecto.nomeDaChave`). Por exemplo, `{{informacoesDoUsuario.selectedRow.nome}}` acessa o valor `nome` na linha atualmente selecionada da **Tabela** `informacoesDoUsuario`. Ao escrever JS em `{{ }}` para acessar valores em um objeto, adicione um `.` após o nome do objeto para acionar um menu de sugestão automática caso você não tenha certeza sobre as propriedades ou métodos integrados dos objetos. **Exemplo** Este GIF mostra como a notação de ponto aciona um menu de sugestão automática e exibe as propriedades de `tabela1`.
### Acessando dados em um array Você pode acessar os valores em um array por índice. O índice sempre começa em 0, então você pode usar `array[0]` para acessar o primeiro elemento do array. **Exemplo** A propriedade **Data** do componente **Tabela** é uma matriz de objetos. Este GIF mostra como acessar o valor de `primeiro_nome` no primeiro elemento do array **data** em `tabela1`.
## Transformando dados Você pode aproveitar funções JS integradas e bibliotecas de terceiros em `{{ }}` para transformar dados, como operações `filter()`, `map()` e `reduce()`. **Exemplos** Colocando texto em caixa baixa. ```javascript { { entrada1.value.toLowerCase(); } } ``` Alterar formato de data ```javascript { { moment(tabela1.selectedRow.coluna).format("DD/MM/YYYY"); } } ``` Retornar o nome dos resultados da consulta. ```javascript {{consulta1.data.map(i => i.nome)}}. ``` ## Restrições O código JS em `{{ }}` deve ser um código de linha única, como `.map()` ou `.reduce()` combinado com uma função de seta ou um operador ternário. **Exemplos** ```javascript { { consulta1.data.id.length; } } // ✅ para referenciar um valor { { consulta1.data.map((linha) => linha.id); } } // ✅ .map() + função arrow { { num1 > num2 ? num1 : num2; } } // ✅ ternário ``` Os seguintes exemplos de código JS são ilegais em `{{ }}`. ```javascript { { // ❌ você não pode escrever código como este em {{ }} const lista = consulta1.data; const listaFiltrada = lista.filter((isso) => isso.valor > 10); return listaFiltrada; } } ``` Se você deseja orquestrar múltiplas linhas de JavaScript, PocketBlocks oferece suporte para escrever esse código em [transformadores](/portugues-brasil/construcao-de-aplicativos/write-javascript/transformers). ```javascript // códigos dentro de um transformador if (seletor.value === "1") { return "Opção 1"; } if (seletor.value === "2") { return "Opção 2"; } return "Opção 3"; ``` ## Ver dados Os dados das consultas podem ser complicados e aninhados em casos reais. A visualização de dados fornece a estrutura detalhada dos dados em objetos e ajuda a entendê-los melhor. Antes de acessar ou transformar dados, pode ser necessário primeiro visualizar os dados e sua estrutura. PocketBlocks oferece três maneiras de visualizar dados. ### Ver resultado da consulta Depois de executar uma consulta dentro do editor de consultas, clique no botão **Executar**. O resultado da consulta é exibido no formato mostrado abaixo.
### Visualizando dados no navegador de dados O navegador de dados localizado no painel esquerdo exibe todos os dados dentro do seu aplicativo. Você pode clicar no nó para expandir e visualizar a estrutura de dados.
### Visualizando em tempo real Ao configurar propriedades ou escrever código JS dentro de um editor, você pode visualizar o resultado avaliado em tempo real em uma caixa abaixo do seu editor.
# Consulta JavaScript Há casos em que você deseja orquestrar operações, por exemplo, após acionar duas consultas, deseja combinar e armazenar seus resultados em um estado temporário e, em seguida, abrir um modal. Este processo pode ser complicado ao encadear vários manipuladores de eventos e certamente não pode ser feito em uma linha de código em `{{ }}`. É aí que entra a consulta JavaScript (JS). Ela libera a capacidade de interagir com componentes e consultas escrevendo consultas JS complexas para realizar as seguintes operações: * Interagir com componentes da UI * Acionar consultas * Acessar bibliotecas JS de terceiros * Personalizar funções O exemplo a seguir é para você entender rapidamente o que é consulta JS e como ela funciona. ## Retorna dados Use a sintaxe `return` para retornar o resultado. Por exemplo, o código a seguir retorna `3`. ```javascript return Math.floor(3.4); ``` O resultado retornado também pode ser um objeto [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). Por exemplo, `query2.run()` retorna um objecto promise. ```javascript return query2.run(); ``` {% hint style="info" %} A instrução `return` não é necessária para cenários onde você deseja omitir resultados. {% endhint %} ## Acessando dados Use consultas JS para acessar dados em seu aplicativo. Observe que não há necessidade de usar a notação `{{ }}`. ```javascript var data = [input1.value, query1.data, fileUpload.files[0].name]; ``` ## Controlando Componentes Em consultas JS, você pode usar métodos expostos por componentes para interagir com componentes de UI em seu aplicativo. Tal operação não é suportada pelo código JS embutido em `{{}}`. ```javascript // defina o valor de input1 como "Olá" input1.setValue("Olá"); ``` {% hint style="warning" %} O método `input1.setValue()` (ou outros métodos componentes) é assíncrono e retorna um objeto [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). Acessando `input1.value` imediatamente após definir o valor de `input1` não retorna o valor atualizado. {% endhint %} ## Executando consulta ### `run()` método e retornos de chamada Execute o método `run()` para executar outras consultas, por exemplo: ```javascript return consultaPorNome.run(); // execute uma consulta e ela retornará uma Promise ``` O valor de retorno de `query.run()` é uma promise, então você pode anexar retornos de chamada para lidar com o resultado ou erro bem-sucedido. ```javascript return consultaPorNome.run().then( (data) => { // após a consulta ser executada com sucesso return "olá, " + data.user_fullname; }, (error) => { // após a consulta ser executada com falha // use a função de mensagem integrada para exibir uma mensagem de erro message.error("Ocorreu um erro ao buscar o usuário: " + error.message); } ); ``` ### Passando parâmetros Você pode passar parâmetros no método `run()` para dissociar a implementação da consulta de seus parâmetros. ```javascript query.run({ parametro1: valor1, parametro2: valor2, ... }); ``` ## Declarando uma função Você pode declarar funções dentro de uma consulta JS para melhor legibilidade. ```javascript // Se o primeiro número é um múltiplo do segundo número function eMultiplo(num1, num2) { return num1 % num2 === 0; } // Chame a biblioteca do moment para retornar a data atual function dataAtual() { return moment().format("DD/MM/YYYY"); } ``` ## Adicionando scripts pré-carregados PocketBlocks oferece suporte à importação de bibliotecas JS de terceiros e à adição de código JS predefinido, como a adição de métodos ou variáveis ​​globais para reutilização em **nível de aplicativo** ou **nível de espaço de trabalho**. Você pode encontrar as configurações no nível do aplicativo em ⚙️ > **Outros** > **Scripts e estilo**.
Para nível de espaço de trabalho, acesse ⚙️ **Configurações** > **Avançado**.
Na guia **JavaScript**, você pode adicionar código JavaScript pré-carregado para definir métodos e variáveis ​​globais e reutilizá-los em seu aplicativo. Para importar bibliotecas, consulte [Usando biblioteca de terceiros](/portugues-brasil/construcao-de-aplicativos/write-javascript/use-third-party-libraries).
## Restrições Por motivos de segurança, diversas variáveis ​​globais e funções de **window** estão desabilitadas no PocketBlocks. Por favor, reporte ao nosso [GitHub](https://github.com/pedrozadotdev/pocketblocks) se você encontrar algum problema. # Transformadores Os transformadores são projetados para transformação de dados e reutilização de seu código JavaScript multilinha. Os dados de consultas ou componentes podem não atender às suas necessidades em cenários de negócios. Além disso, você pode usar o mesmo bloco de código várias vezes em um aplicativo. Nesses casos, um transformador é o que você precisa. Comparado com o código embutido em `{{ }}`, o transformador suporta blocos de código multilinha. E, diferentemente da consulta JavaScript, o transformador foi projetado para realizar operações somente leitura, o que significa que você não pode acionar uma consulta ou atualizar um estado temporário dentro de um transformador. ## Começando Clique em **+ Novo > Transfromer** em um editor de consultas para criar um transformador.
Em seguida, escreva seu código JS no transformador. Você pode clicar em **Visualizar** para obter o valor de retorno e acessá-lo por `nomeDoTransformador.value` em seu aplicativo. No exemplo a seguir, `transformador1` usa os dados de classificação por estrelas em `avaliacao1` para calcular uma pontuação.
{% hint style="warning" %} `{{ }}` não é permitido dentro de um transformador ou consulta JS. `{{ }}` é usado apenas para fins de expressão JS de linha única, enquanto um transformador ou consulta JS é para múltiplas linhas de código JS. {% endhint %} ## Casos de uso ### Transformação de data e hora Use o método `moment().format()` para transformar formatos de data/hora. O exemplo a seguir converte o valor de data/hora de `tempo_inicial` retornado por `consulta1` para o formato `DD/MM/YYYY`. ```javascript return consulta1.data.map((isso) => { return { ...isso, tempo_inicial: moment(it.tempo_inicial).format("DD/MM/YYYY"), }; }); ``` ### Classificando dados da consulta Use o método `_.orderBy()` fornecido por [lodash](https://lodash.com/) para classificar os dados. O exemplo a seguir retorna `consulta1.data` classificado pela coluna `quantidade` em ordem crescente. ```javascript return _.orderBy(consulta1.data, "quantidade", "asc"); ``` ### Juntando duas consultas O código de exemplo abaixo mostra como unir os resultados da consulta de `usuarios` e `pedidos` usando o ID do usuário. ```javascript const usuarios = consultarUsuarios.data; const pedidos = consultarPedidos.data; return usuarios.map((usuario) => ({ ...usuario, pedidos: pedidos.find((pedido) => pedido.clienteId === usuario.id), })); ``` ## Operações somente leitura Somente operações somente leitura são permitidas dentro de um transformador. Isso significa que você não pode definir valores de componentes ou estados temporários, nem acionar consultas. Para essas operações, use consultas JavaScript. Por exemplo, você não pode chamar o método `setText()` de um componente de texto em um transformador.
Em vez disso, chame o método `setText()` em uma consulta JavaScript não reporta nenhum erro.
Em outro exemplo, o transformer`ordernador1` visa classificar os dados de `consultarUsuarios` por `primeiro_nome`, mas o método `sort()` pode alterar os dados originais, então ocorre um erro.
Neste caso, use o método `_.orderBy()` fornecido por [lodash](https://lodash.com/).
# Estado temporário Você pode usar o estado temporário para armazenar e fazer referência a dados locais em um aplicativo. Cada vez que você carrega ou atualiza um aplicativo, o valor do estado temporário é redefinido. ## Cenários de casos de uso Os estados temporários podem ajudar nos seguintes cenários: * Para rastrear os valores temporários de uma variável quando o usuário interage com seu aplicativo. * Para armazenar seus dados apenas em operação sem persistir em um banco de dados. * Para funcionar como uma propriedade temporária quando propriedades integradas no PocketBlocks (como `{{tabela.selectedRow}}` e `{{seletor.value}}`) não suportam seu caso de uso.

Para armazenar e acessar dados em aplicativos no seu espaço de trabalho, use o localStorage.

## Crie um estado temporário Clique em **+ Novo** e selecione **Estado temporário** no editor de consultas.
Você pode renomear o estado temporário e definir um valor inicial.
## Definindo valores de estado O estado temporário oferece métodos `setValue()` e `setIn()` para definir ou alterar seu valor, que podem ser chamados em consultas JavaScript. Use `setValue()` para alterar o valor diretamente. ```javascript //state.setValue(value: any) state.setValue(3); state.setValue(input1.value); ``` Quando o valor inicial de um estado temporário é um objeto, use `setIn()` para alterar o valor em um caminho especificado. ```javascript // valor inicial de estado2 da seguinte forma: { garota: { nome: "Lucia", idade: 18, cidade: { nome: "Nova Iorque" } } garoto: { nome: "Bob", idade: 21, cidade: { nome: "Los Angeles" } } } //Para alterar o valor em um caminho especificado //estado.setIn(caminho, qualquerValor) //caminho: uma matriz de chaves ou índices. Somente o último item do caminho será alterado. estado2.setIn(['garota','cidade'],{nome:'Seatle'}) estado2.setIn(['garoto','idade'],18) // Para definir o valor da matriz de valor, você pode usar // valor inicial = ["olá", "mundo"] estado2.setIn([1],"fulano") // isso resultará em ["olá", "fulano"] ``` Você também pode chamar esses dois métodos em [manipuladores de eventos](/portugues-brasil/construcao-de-aplicativos/event-handlers). Selecione **Definir estado temporário** como ação e escolha o método sob demanda.
## Exemplo: Incremento de um contador Neste exemplo, o contador rastreia o número de cliques no botão. Cada vez que o usuário clica no botão, o número no componente de texto aumenta em um.
Crie um contador de incremento nas seguintes etapas: 1. Adicione um componente de botão `botao1` e um componente de texto `texto1`. 2. Crie um estado temporário `estado1`, defina seu valor inicial como `0`. Vincule `{{estado1.value}}` como o texto de exibição de `texto1`.
3. Adicione um manipulador de eventos para `botao1`. Selecione a ação **Definir estado temporário** e o método **setValue**, e então defina `{{estado1.value+1}}` como o valor.
4. Clique no botão, você pode ver que o valor de `texto1` aumenta em um cada vez que você clica.
Você também pode obter o mesmo resultado usando consultas JavaScript: 1. Adicione uma nova consulta e selecione **Executar código JavaScript**. 2. Escreva a consulta JavaScript com este código e configure-a para ser invocada manualmente:\ `estado1.setValue(estado1.value + 1)` 3. Adicione um manipulador de eventos `botao1` para executar `consulta1`.
Agora clique no botão **Incrementar contador**, você deverá ver o mesmo resultado acima. # Respondedor de dados Ao construir um aplicativo, você pode definir eventos para os componentes para ouvir as alterações de determinados dados. Por exemplo, para um componente **Tabela**, os eventos integrados para a alteração da propriedade `selectedRow` incluem "Alteração de seleção de linha", "Alteração de filtro", "Alteração de classificação" e "Alteração de página". No entanto, faltam eventos semelhantes para algumas alterações de dados, como alterações de estados temporários, transformadores ou resultados de consultas. Os respondedores de dados são projetados para esses casos e permitem ouvir e responder a qualquer alteração nos dados. {% hint style="info" %} Os eventos para respondedores de dados são mais gerais do que os eventos que escutam alterações de dados, como alteração de conteúdo, alteração de seleção de linha, etc. {% endhint %} ## Ouça as alterações de dados No editor de consultas, clique em **+ Novo** e selecione **Respondedor de dados** para criar um novo respondedor de dados.
Você pode definir os dados que o respondedor de dados escuta. Ele suporta todos os tipos de formatos de dados, incluindo número, string, array e objeto JS. No exemplo a seguir, qualquer alteração de valor no componente **Texto** aciona uma notificação global.
Se os dados estiverem em formato de array ou objeto JS, a alteração dos dados de qualquer subelemento acionará o evento configurado. Por exemplo, os dados de `dataResponder2` são um objeto JS, que escuta dois componentes **Entrada de Texto** no aplicativo. A alteração de dados de qualquer componente aciona a mesma notificação global.
## Respondendo ações Para obter informações detalhadas, vá para [Manipuladores de eventos](/portugues-brasil/construcao-de-aplicativos/event-handlers) > [Ações](/portugues-brasil/construcao-de-aplicativos/event-handlers#actions). # Funções JavaScript integradas ## utils - funções utilitárias ### utils.openUrl() Abra um URL. ```javascript // Sintaxe utils.openUrl( url: string, options?: { newTab: boolean = true } ) ``` | Parâmetros | Descrição | | -------------- | -------------------------------------------------------------------------------------------------------------------------------- | |

url

| Obrigatório. Um valor **Texto** que especifica o URL a ser aberto. Deve começar com *http\://* or *https\://*. | | newTab | Opcional. **Booleano** valor que, quando **True**, especifica que o URL será aberto em uma nova guia. O valor padrão é **True**. | ```javascript // Exemplo: Abre google.com em uma nova aba. utils.openUrl("https://www.google.com", { newTab: true }); ``` ### utils.openApp() Abra um aplicativo PocketBlocks. ```javascript // Sintaxe utils.openApp( applicationId: string, options?: { queryParams?: {"chave":"valor"}, hashParams?: {"chave":"valor"}, newTab: true } ) ``` | Parâmetro | Descrição | | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |

appId

|

Obrigatório. Um valor Texto que especifica o ID do aplicativo a ser aberto.

| | queryParams: {'chave1':'valor1',chave2:'valor2',...} | Opcional. Um **Objeto** que especifica parâmetros de consulta a serem transmitidos ao aplicativo. Os parâmetros de consulta são adicionados ao URL do aplicativo na forma de ?*chave1=valor1\&chave2=valor2&...* | |

hashParams：{'chave1':'valor1',chave2:'valor2',...}

| Opcional. Um **Object** que especifica parâmetros de hash a serem transmitidos ao aplicativo. Os parâmetros hash são adicionados ao URL do aplicativo na forma de *#chave1=valor1\&chave2=valor2&...* | | newTab | Opcional. Um valor **Booleano** que, quando **True**, especifica o URL deve ser aberto em uma nova guia. O valor padrão é **True**. | ```javascript // Exemplo: Abre um aplicativo PocketBlocks em uma nova guia. utils.openApp("632bddc33bb9722fb888f6c0", { newTab: true }); // Exemplo: Abre um aplicativo PocketBlocks e passa o parâmetro "id". utils.openApp("632bddc33bb9722fb888f6c0", { queryParams: { id: tabela1.selectedRow.id }, }); ``` ### utils.downloadFile() Baixa um arquivo contendo os dados especificados. ```javascript // Sintaxe utils.downloadFile(data: any, fileName: string, options?: { fileType?: string, dataType?: "url" | "base64" } ) ``` | Parâmetro | Descrição | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | data | Obrigatório. Um **Texto** ou **Objeto** que especifica os dados para download de consultas, componentes, transformadores, etc. | | fileName | Obrigatório. Um valor **Texto** que especifica o nome do arquivo para download. | | fileType | Opcional. Um valor **Texto** que especifica o tipo de arquivo para download. Todos os [tipos MIME](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) são suportados. | | dataType | Opcional. Um valor **Texto** que especifica o tipo de dados: "url" ou "base64". | ```javascript // Exemplo: baixe os dados base64 de um componente de arquivo como um arquivo PNG denominado dados-do-usuario. utils.downloadFile(file1.value[0], "dados-do-usuario", { fileType: "png", dataType: "base64", }); // Exemplo: Faça download dos resultados de consulta1 como um arquivo XLXS denominado dados-do-usuario. utils.downloadFile(consulta1.data, "dados-do-usuario", { fileType: "xlsx" }); // ou desta forma: utils.downloadFile(consulta1.data, "dados-do-usuario.xlsx"); // Exemplo: Faça download dos resultados de consulta1 como um arquivo PDF denominado dados-do-usuario. utils.downloadFile(consulta1.data, "dados-do-usuario", { fileType: "pdf", dataType: "base64", }); ``` ### utils.copyToClipboard() Copie um texto para a área de transferência. ```javascript // Sintaxe utils.copyToClipboard( text: string ) ``` | Parâmetro | Descrição | | --------- | ------------------------------------------------------------------------ | | text | Obrigatório. Um valor **Texto** que especifica o conteúdo a ser copiado. | ```javascript // Exemplo: Copie o conteúdo do componente de entrada para a área de transferência. utils.copyToClipboard(input1.value); ``` ## message – notificação global Use métodos `message` para enviar uma notificação de alerta global, que é exibida na parte superior da tela e dura 3 segundos por padrão. Cada um dos quatro métodos a seguir oferece suporte a um estilo de exibição exclusivo. ```javascript // message.info( text: string, options?: {duration: number = 3 } ) message.info("Por favor confirme suas informações", { duration: 10 }); // message.success( text: string, options?: {duration: number = 3 } ) message.success("A consulta foi executada com sucesso", { duration: 10 }); // message.warn( text: string, options?: {duration: number = 3 } ) message.warn("Aviso", { duration: 10 }); // message.error( text: string, options?: {duration: number = 3 } ) message.error("Consulta foi executada com erro", { duration: 10 }); ```
## localStorage Use métodos `localStorage` para armazenar e gerenciar dados de pares de valores-chave localmente, que não são redefinidos quando o aplicativo é atualizado e podem ser acessados ​​em qualquer aplicativo dentro do espaço de trabalho usando `localStorage.values`. | Método | Descrição | | ---------------------------------- | ------------------------------------- | | setItem(*key: string, value: any*) | Armazena um par de chave valor. | | removeItem(*key: string*) | Remove um par de chave valor. | | clear() | Limpa todos os dados no localStorage. | ### localStorage.values Você pode acessar qualquer par de chave valor no armazenamento local usando `localStorage.valores.` em consultas JavaScript.
Inspecione os dados em localStorage em **Globals** no navegador de dados.
### localStorage.setItem() Armazena um par de chave valor. ```javascript // Sintaxe localStorage.setItem(key: string, value: any) // Exemplo localStorage.setItem("pedido", seletor1.value) ``` ### localStorage.removeItem() Remove um par de chave valor. ```javascript // Sintaxe localStorage.removeItem(key: string) // Exemplo localStorage.removeItem("pedido") ``` ### localStorage.clear() Limpa todos os dados no localStorage. # Uso de bibliotecas de terceiros Todo desenvolvedor aprende um dos princípios mais importantes da engenharia de software no início de sua carreira: DRY (Don’t Repeat Yourself). O uso de bibliotecas de terceiros pode economizar seu tempo, pois você não precisa desenvolver a funcionalidade que a biblioteca oferece. PocketBlocks fornece algumas bibliotecas integradas de terceiros para usos comuns, e você pode importar manualmente outras bibliotecas sob demanda. ## Bibliotecas integradas PocketBlocks fornece algumas bibliotecas JavaScript integradas para uso. | Biblioteca | Documentação | Versão | | ------------------------ | ---------------------------------------------------------- | -------------------------- | | lodash | | 4.17.21 | | moment | | 2.29.3 | | uuid | | 8.3.2（Support v1/v3/v4/v5） | | numbro | | 2.3.6 | | papaparse(Papa) | | 5.3.2 | | PocketBase SDK(pb) | | 0.21.3 | | TanStack QueryClient(qc) | | 5.44.0 | ## Importando manualmente bibliotecas de terceiros PocketBlocks suporta a configuração de JavaScript pré-carregado e bibliotecas que podem estar no **nível do aplicativo** ou no **nível do espaço de trabalho**. * **Bibliotecas em nível de aplicativo** são carregadas somente no aplicativo onde definido. Além disso, o aplicativo A não pode usar bibliotecas configuradas para o aplicativo B. * **Bibliotecas no nível do espaço de trabalho** serão carregadas quando você abrir qualquer aplicativo no seu espaço de trabalho. Todos os aplicativos podem acessar essas bibliotecas. Pode haver um certo impacto no desempenho do aplicativo, especialmente quando você tem funções JavaScript complexas que não estão sendo usadas em todos os aplicativos. **Dicas que você deve saber antes de configurar bibliotecas:** * Bibliotecas externas são carregadas e executadas no navegador. * Bibliotecas somente NodeJS não são suportadas. * URLs de bibliotecas externas precisam oferecer suporte a vários domínios. * A exportação da biblioteca deve ser configurada diretamente no objeto window, variáveis ​​globais como `var xxx = xxx` não têm efeito. * As bibliotecas externas são executadas em um ambiente sandbox restrito e as seguintes variáveis ​​globais não estão disponíveis: `parent` `document` `location` `chrome` `setTimeout` `fetch` `setInterval` `clearInterval` `setImmediate` `XMLHttpRequest` `importScripts` `Navigator` `MutationObserver` Agora vamos pegar **cowsay** como exemplo e importá-lo no nível do aplicativo e no nível do espaço de trabalho. * Página do GitHub: * Link da Biblioteca: ### No nível do aplicativo Navegue até a página de configurações e clique no sinal de mais **+** na guia **Biblioteca JavaScript**. Cole o link **cowsay** e clique em **Adicionar novo**.
Crie uma consulta JS e insira o código.
Você pode obter o mesmo resultado chamando o método `cowsay.say()` no valor do componente de texto.
Observe que a biblioteca cowsay é importada no nível do aplicativo e você não pode usá-la em nenhum outro aplicativo em seu espaço de trabalho. ### No nível do espaço de trabalho Vá para a página inicial do PocketBlocks, selecione **Configurações** > **Avançado** e clique em **Adicionar** na guia **Biblioteca JavaScript**. Cole o link da biblioteca JS de terceiros e clique em **Adicionar novo** para adicioná-la ao seu espaço de trabalho. As bibliotecas instaladas podem ser acessadas de qualquer aplicativo em seu espaço de trabalho.
# Guias de Componentes # Lista de opções Um menu suspenso garante uma entrada fácil e sem erros do usuário, oferecendo uma lista de opções possíveis. PocketBlocks suporta a implementação de listas de opções usando componentes como **Seletor** e **Seletor Mútiplo**. Você pode configurar uma lista de opções manualmente ou mapeando dados de suas fontes de dados.
## Propriedades Cada lista de opções possui quatro propriedades. * **Rótulo**: o texto da opção exibido aos usuários * **Valor**: o identificador exclusivo da opção * **Desativado**: desativa a opção (o valor padrão é `false`) * **Oculto**: oculta a opção (o valor padrão é `false`)
{% hint style="warning" %} Quando mais de uma opção em uma lista utiliza o mesmo valor, apenas a primeira opção é válida e, portanto, exibida. {% endhint %} ## Modo manual Em **Básico** > **Manual**, clique em **+ Adicionar** para criar uma nova opção. Selecione uma opção para configurá-lo manualmente. Você pode clicar em `···` para **Duplicar** ou **Excluir** uma opção e arrastar `⋮⋮` para organizar sua posição.
Verifique o valor da opção selecionada em **Componentes** no navegador de dados. Por exemplo, quando **Nova York** é selecionado, você pode encontrar o valor da string `"1"` para **localizacaoSelecionada**.
O modo manual é recomendado para estes cenários: * Gerenciável e enumerável manualmente. * Usado por apenas um componente. * Os dados não vêm de fontes de dados. ## Modo mapeado Quando você tiver dados da lista de opções provenientes de fontes de dados, transformadores ou estado temporário, poderá usar o **Modo Mapeado**. Em **Básico** > **Mapeado**, insira sua matriz de fonte de dados na caixa **Dados** usando código JavaScript (JS). Uma lista de opções será mapeada automaticamente a partir deste array. Por exemplo, acesse informações da universidade via `{{universidade.dado}}`. Cada item na matriz de resultados contém `pais`, `paginas_web`, `codigo` e `nome`.
Você pode referenciar o valor de qualquer campo de uma opção através de `item` e seu índice `i`, começando em 0. No exemplo a seguir, o **Rótulo** de cada opção é o `nome` da universidade, o **Valor** é `web_page`, e aqueles que contêm um parêntese de abertura `(` em seus nomes estão desativados. O valor padrão é definido como `paginas_web` do primeiro item usando `{{universidade.dado[0] .paginas_web}}`. Observe que o valor padrão de uma lista de opções deve ser um elemento do array **Valor**, mas não do array **Rótulo**.
Verifique o valor da opção selecionada em **Componentes** no navegador de dados. Por exemplo, quando "Ahi Evran University" é selecionado, seu valor de string `[\"http://www.ahievran.edu.tr/\"]` é exibido.
# Exibição em lista O componente Exibição em lista serve para você exibir linhas de dados. Funciona como um contêiner: você pode inserir outros componentes nele e vincular dados a esses componentes. O componente **Exibição em lista** exibe linhas de dados. Semelhante a Formulário, Modal e Drawer, também é um componente semelhante a um contêiner que pode conter outros componentes ou módulos. Para dados de exibição em lista, primeiro vincule os dados a um componente **Exibição em lista** e configure as regras de nomenclatura para os itens. Em seguida, você projeta a exibição da primeira linha arrastando e soltando os componentes, e esse layout será aplicado a todos os itens desse componente. A seguir está uma demonstração da **Exibição em lista**, exibindo parte dos MELHORES LIVROS DE 2021 de[Goodreads](https://www.goodreads.com/choiceawards/best-books-2021):
Arraste e solte o **Exibição em lista** na tela. Cada item contém uma **Imagem**, um **Texto** e um componente de **Avaliação**. Você pode atualizar a exibição de todo o componente **Exibição em lista** configurando o layout da primeira entrada. Clique no componente **Imagem** para ver a fonte da imagem padrão.
O componente **Exibição em lista** recupera dados de uma matriz JSON de objetos e exibe um componente **Imagem**, **Texto** e **Avaliação** para cada entrada. Você também pode passar os resultados da consulta para uma **Exibição em lista**.
## Vinculando dados Os dados de um componente **Exibição em lista** aceitam dois tipos de valores: número e matriz. * Número: os números são processados ​​como contagem de linhas e nenhum dado válido é passado para o componente **Exibição em lista**. * Array: O comprimento de um array é passado como contagem de linhas e cada entrada no array é processada como um objeto JS no formato JSON, correspondendo a uma linha no componente **Exibição em lista**. Por exemplo, os dados a seguir contêm duas linhas de dados, cada uma contendo quatro campos: `avaliacao`, `titulo`, `url` e `cover`. ```json [ { "avaliacao": "9.2", "titulo": "The Shawshank Redemption", "url": "https://www.imdb.com/title/tt0111161/", "cover": "https://m.media-amazon.com/images/M/MV5BMDFkYTc0MGEtZmNhMC00ZDIzLWFmNTEtODM1ZmRlYWMwMWFmXkEyXkFqcGdeQXVyMTMxODk2OTU@._V1_UY67_CR0,0,45,67_AL_.jpg" }, { "avaliacao": "9.2", "titulo": "The Godfather", "url": "https://www.imdb.com/title/tt0068646/", "cover": "https://m.media-amazon.com/images/M/MV5BM2MyNjYxNmUtYTAwNi00MTYxLWJmNWYtYzZlODY3ZTk3OTFlXkEyXkFqcGdeQXVyNzkwMjQ5NzM@._V1_UY67_CR1,0,45,67_AL_.jpg" } ] ``` Você pode visualizar os dados detalhados sobre o componente **Exibição em lista**, seus itens, propriedades, etc., no navegador de dados.
## Exibir dados em componentes internos Depois de vincular dados válidos ao componente **Exibição em lista** e projetar seus componentes internos, você pode adicionar dados a esses componentes. **Exibição em lista** suporta variáveis ​​locais `currentItem` e `i`. Observe que você só precisa alterar os dados da primeira linha, e as mesmas configurações são aplicadas às outras linhas automaticamente. {% hint style="info" %} Você pode vincular um endereço URL estático ao componente **Imagem** para exibição de imagens; e como esse endereço URL é estático, a mesma imagem aparece em todas as linhas. {% endhint %}
## Nomeando os itens Você pode definir os nomes dos índices dos itens e os nomes dos dados dos itens. Isto é útil ao incorporar uma lista em outra lista. Por exemplo, você pode definir o índice de uma lista como `i` e o aninhado interno `j` para evitar conflito de nomenclatura.
### Nome do índice do item Por padrão, o índice do item é denominado `i`, referindo-se ao índice dos dados da lista e começando do zero. Além de usar `i` como números, você também pode usar `i` para acessar dinamicamente os dados dos resultados da consulta. Por exemplo, para acessar o campo `nome_do_livro` da tabela `ficcao` no componente **Texto**, escreva o seguinte código. ```javascript { { getAllFictions.data[i].nome_do_livro; } } ``` Em seguida, você poderá ver os nomes dos livros de ficção exibidos no **Exibição em lista** por ordem de índice.
### Nome dos dados do item Por padrão, você pode referenciar o valor de cada item em uma lista usando a variável `currentItem`. Por exemplo, para exibir um número de série mais o nome do livro, escreva o seguinte código no valor `texto1`. ```javascript {{i+1}}. {{currentItem.nome_do_livro}} ```
{% hint style="info" %} Erros de dependência circular ocorrem quando você faz referência aos dados de uma linha por `listView.items[i]` de um componente dentro de um componente **Exibição em lista**. Recomenda-se usar tal referência somente fora da lista. {% endhint %} ## Paginação ### Pulo rápido Alterne "Mostrar pulo rápido" ou defina seu valor como `true` para permitir que seus usuários acessem rapidamente a página especificada.
### Tamanho da página Você pode configurar se deseja permitir que seus usuários personalizem quantos itens serão exibidos em uma única página ativando ou desativando o "Mostrar botão de alteração de tamanho" ou definindo seu valor em JS. Quando desativado, você pode definir o tamanho de página padrão.
Se ativado, você poderá configurar vários tamanhos de página para serem selecionados pelos usuários.
### Contagem total de linhas Por padrão, a contagem total de linhas de um componente **Exibição em lista** é o número de itens de dados atuais. Você também pode inserir um valor de uma consulta. Por exemplo, `{{consulta1.data[0].countador}}`. ## Referenciar itens fora da lista **Exibição em lista** oferece suporte à exposição de dados de componentes internos com o campo **Itens**. Você pode inspecionar o **Navegador de dados** no painel esquerdo.
Por exemplo, arraste um componente **Entrada de Texto** para **Exibição em lista** e, em seguida, você poderá referenciar o valor do componente **Avaliação** em componentes fora do **Exibição em lista** pelo código a seguir. ```javascript { { listView1.items[0].rating1.value; } } ```
# Menu lateral No PocketBlocks, **Drawer** é uma barra lateral sobreposta para exibir informações ou realizar operações, sem interromper o fluxo de trabalho na janela principal. O exemplo a seguir cria um carrinho de compras usando uma gaveta.
## Layout Quando inserida pela operação de arrastar e soltar, um **Drawer** flutua no lado direito (por padrão) da janela principal. Em seguida, você pode adicionar componentes ao **Drawer** de acordo com suas necessidades. No modo de edição de um **Drawer**, outros componentes na tela não são editáveis.
{% hint style="info" %} Quando um Drawer é fechado, você pode reabri-lo clicando no rótulo correspondente na guia **Modais** no painel esquerdo. {% endhint %} ### Posição Na aba **Propriedades**, você pode definir a posição do Drawer. A posição padrão é o lado direito da janela principal.
### Redimensionando Na aba **Propriedades**, você pode definir a largura do drawer em pixels ou porcentagem. Observe que a altura de um drawer é igual à da janela principal e não é personalizável.
## Eventos Você pode fazer referência a um drawer no código JS em qualquer lugar do seu aplicativo ou chamá-lo por meio de uma ação de "componente de controle" em **Propriedades** > **Interação** > **Manipuladores de eventos**. As seções a seguir orientam você sobre como abrir e fechar um drawer clicando em um botão em um aplicativo de compras online. ### Acionando openDrawer Normalmente, em um aplicativo, você aciona a abertura de um drawer por meio de um evento como clicar em um botão. Por exemplo, abrir um drawer para exibir o carrinho de compras é implementado nas etapas a seguir. 1. Adicione um botão e renomeie-o como `irParaCarro`. 2. Defina o manipulador de eventos do botão. Selecione "Componente de controle" como **Ação** e selecione o componente "carrinho" e o método "openDrawer". Todas essas configurações são salvas automaticamente.
3. Clique no botão `irParaCarro` e o drawer vinculado(carrinho) será aberto. ### Acionando o fechamento do drawer Acionar "closeDrawer" é semelhante a acionar "openDrawer". Ao configurar o manipulador de eventos, selecione o método "closeDrawer". Por exemplo, fechar um drawer que exibe o carrinho de compras é implementado nas etapas a seguir. 1. Adicione um botão e renomeie-o como `voltarShopping`. 2. Defina o manipulador de eventos do botão. Selecione "Componente de controle" como **Ação** e selecione o componente "carrinho" e o método "closeDrawer". Todas essas configurações são salvas automaticamente.
3. Clique no botão “Continuar Comprando” e o drawer vinculado (carrinho) é fechado. # Imagem Use o componente **Imagem** para apresentar informações nos seus aplicativos de maneira vívida. PocketBlocks suporta a adição de uma imagem via URL e dados codificados em base64. ## URL Arraste o componente **Image** para a tela ou para um **Container**. Clique no componente **Imagem** e a guia **Propriedades** será exibida à direita. Você pode definir o URL para exibir uma imagem.
## Dados codificados em Base64 Você também pode inserir uma imagem por meio de dados codificados em base64. Certifique-se de que a fonte da imagem codificada comece com `data:image/FORMATODAIMAGEM;base64,` ou simplesmente `data:image;base64,`. {% hint style="warning" %} Não esqueça da vírgula no final do prefixo: `data:image/FORMATODAIMAGEM;base64`**`,`** `OS_DADOS_DA_SUA_IMAGEM_EM_BASE64` `data:image;base64`**`,`**`OS_DADOS_DA_SUA_IMAGEM_EM_BASE64` {% endhint %}
### Demo: carreguando e exibindo uma imagem Um caso de uso comum para exibição de imagens base64 seria combinar um componente **Upload de arquivo** com um componente **Imagem**.
Aqui está o código JS que concatena o prefixo com os dados codificados em base64 do arquivo enviado por meio de `arquivo1.value[0]`. ```javascript { { "data:image/jpeg;base64," + arquivo1.value[0]; } } ``` ## Definindo visualização de clique para uma imagem Ative **Suporte a visualização de clique** na guia **Propriedades** para permitir que os usuários visualizem a imagem em tamanho real. Passe o mouse sobre a imagem e você verá **👁 Visualização**. Então, você pode clicar para visualizar.
## Definindo o estilo de uma imagem Em **Propriedades** > **Estilo**, altere a cor da borda e defina o **Raio da borda** em pixels ou em porcentagem.
# Gráficos Tabelas e gráficos são representações visuais de dados usados ​​para simplificar informações complexas e torná-las mais fáceis de entender. Eles podem ajudar a destacar insights importantes e fornecer um resumo rápido de dados que, de outra forma, seriam difíceis de interpretar. Os gráficos vêm em diferentes formatos, como gráficos de barras, gráficos de linhas, gráficos de pizza, gráficos de dispersão e muito mais, cada um adequado para diferentes tipos de dados e finalidades analíticas. PocketBlocks permite inserir vários formatos de tabelas e gráficos em seus aplicativos para satisfazer suas necessidades em diferentes casos de uso.
## Modo UI ### Formato de dados No modo UI, o componente **Gráfico** oferece suporte à apresentação de dados armazenados como uma matriz de objetos JS. Cada campo de objeto corresponde a uma coluna em formato tabular. Os objetos na matriz a seguir contêm três campos: `data`, `fruta` e `contador`. ```json [ { "data": "2022-03-01", "fruta": "apple", "contador": 4 }, { "data": "2022-03-01", "fruta": "banana", "contador": 6 }, { "data": "2022-04-01", "fruta": "grape", "contador": 10 }, { "data": "2022-04-01", "fruta": "apple", "contador": 3 }, { "data": "2022-04-01", "fruta": "banana", "contador": 2 } ] ``` Você também pode usar o código JS em `{{}}` para fazer referência a dados de outros componentes ou consultas ou para transformar dados para atender a necessidades específicas. Por exemplo, o resultado da consulta `colsulta1` é o seguinte. ```json { "data": [ "2022-03-01", "2022-03-01", "2022-04-01", "2022-04-01", "2022-04-01" ], "fruta": ["apple", "banana", "grape", "apple", "banana"], "contador": [4, 6, 10, 3, 2] } ``` Você pode transformá-lo usando o transformador `transformador1` com o seguinte código JS. ```javascript let datas = query1.data.data; let frutas = query1.data.fruta; let contadores = query1.data.contador; let resultado = []; for (let i = 0; i < datas.length; i++) { resultado.push({ date: datas[i], fruta: frutas[i], count: contadores[i] }); } return resultado; ``` Em seguida, referencie o valor do transformador `{{transformador1.value}}` como dados para o gráfico.
### Tipo de Gráfico PocketBlocks oferece suporte a quatro tipos de gráficos: gráfico de barras, gráfico de linhas, gráfico de dispersão e gráfico de pizza. Você pode selecionar o tipo de gráfico em **Propriedades** > **Dados** > **Tipo de gráfico**. Você também pode personalizar o layout e o estilo do seu gráfico na guia **Propriedades**.
### Eixo X Gráficos de barras, gráficos de linhas e gráficos de pizza mapeiam valores para variáveis ​​categóricas. Assim, nesses gráficos, o eixo X geralmente mostra dados não numéricos – por exemplo, data ou departamento.
Por padrão, o PocketBlocks detecta automaticamente os dados do eixo X e seu tipo. Você também pode selecionar manualmente um entre "Eixo de categoria", "Eixo de valor", "Eixo de tempo" ou "Eixo de registro". Para obter informações detalhadas, consulte [tipo de eixo X](https://echarts.apache.org/en/option.html#xAxis.type).
### Série de gráficos Na maioria dos tipos de gráficos, a **Série de gráficos** (eixo Y) apresenta valores numéricos para as categorias no eixo X. Por padrão, PocketBlocks preenche todos os campos numéricos no eixo Y. Você pode ocultar campos desnecessários em **Propriedades** > **Série de gráficos**.
## Echarts em JSON Além dos gráficos integrados, você também pode plotar seus dados com o [Apache ECharts](https://echarts.apache.org/en/index.html), uma biblioteca de visualização JS de código aberto. Você só precisa preencher o campo **Configuração** > **Opção** no formato JSON. Para informações detalhadas, consulte a [documentação do ECharts](https://echarts.apache.org/en/option.html#title) e os [exemplos do ECharts](https://echarts.apache.org/examples/en/index.html).
Se precisar de mais opções de configuração para gráficos, crie uma issue no [Github](https://github.com/pedrozadotdev/pocketblocks/issues). # Carregamento de arquivo ## Fundamentos Você pode personalizar as propriedades dos componentes de upload de arquivo no painel direito, como texto exibido, tipos de arquivo e tipo de upload.
### Tipo de arquivo Você pode inserir uma série de strings para restringir os tipos de arquivos a serem carregados. O valor padrão do tipo de arquivo está vazio, o que significa que nenhuma limitação é predefinida. Cada valor de string em uma matriz de tipo de arquivo especificada deve ser um [especificador de tipo de arquivo exclusivo](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#unique_file_type_specifiers) em um dos os seguintes formatos. * Uma extensão de nome de arquivo válida que não diferencia maiúsculas de minúsculas, começando com um caractere de ponto final ("."), como `.png`, `.txt` e `.pdf`. * Uma string válida em [formato MIME](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) sem extensão. * String `audio/*` indicando "qualquer arquivo de áudio". * String `video/*` indicando "qualquer arquivo de vídeo". * String `image/*` indicando "qualquer arquivo de imagem". Por exemplo, quando o valor do tipo de arquivo é `[".pdf", ".mp4", "image/*"]`, você pode fazer upload de arquivos PDF, arquivos MP4 e qualquer tipo de arquivo de imagem. ### Tipo de upload Você pode decidir se deseja fazer upload de um único arquivo, de vários arquivos ou de um diretório.
### Exibir arquivos enviados Ative ou desative **Mostrar lista de upload** para exibir ou ocultar a lista de arquivos enviados. Você também pode definir essa propriedade por meio do código JS. Por padrão, seu valor é “verdadeiro”. A lista de upload apresenta os nomes de todos os arquivos carregados em ordem cronológica. Você também pode acessar o nome dos arquivos enviados através da propriedade `files[index].name`. Ao passar o mouse sobre um arquivo, o ícone 🗑️ aparece e você pode clicar nele para excluir o arquivo correspondente.
### Analisar arquivos Alterne **Analisar arquivos** e o PocketBlocks tentará analisar a estrutura de dados do arquivo carregado em objetos, matrizes ou strings. Você pode acessar o resultado analisado através da propriedade `parsedValue`. PocketBlocks oferece suporte à análise de arquivos Excel, JSON e CSV. O resultado da análise de outros tipos de arquivos é `null`.
## Validação Na aba de validação, você pode configurar quantos arquivos podem ser carregados, bem como o tamanho mínimo e máximo de um único arquivo a ser carregado.
### Máximo de arquivos Quando o tipo de upload é "Múltiplo" ou "Diretório", você pode definir **Máximo de arquivos** para limitar o número máximo de arquivos a serem carregados. Se o número de arquivos a serem carregados exceder esse limite, os arquivos carregados mais recentemente substituirão os mais antigos. ### Tamanho do arquivo Você pode definir o tamanho mínimo e máximo dos arquivos para upload, usando unidades KB, MB, GB ou TB. A unidade padrão para tamanho de arquivo é byte. Quando o tamanho do arquivo enviado exceder o limite, você verá um alerta global.
### Acessando os arquivos enviados Os arquivos carregados por meio do componente de upload de arquivo são armazenados na memória cache do navegador em formato de string **codificado em base64**. Para armazenar esses arquivos em fontes de dados, você precisa criar consultas para conectar-se a bancos de dados ou APIs. Você pode visualizar as propriedades dos arquivos enviados no navegador de dados no painel esquerdo ou acessar os nomes das propriedades em `{{}}` ou Consultas JS via código JS. As propriedades comumente usadas são as seguintes. * `value`: Uma lista do conteúdo dos arquivos enviados, codificados em base64. * `files`: Uma lista de metadados dos arquivos enviados, incluindo `uid`, `name`, `type`, `size` e `lastModified`. * `parsedValue`: Uma lista do valor dos arquivos analisados.
# Componente customizado No PocketBlocks, você pode projetar componentes personalizados usando a biblioteca React.js para satisfazer necessidades específicas ao construir seu aplicativo. O componente personalizado pode ser estático ou dinâmico, mas requer codificação. ## Pré-requisitos * Bom entendimento de como construir um aplicativo em PocketBlocks. * Familiarizado com HTML/CSS/JS e a biblioteca React.js. ## Fundamentos Arraste um **componente personalizado** para a tela. Por padrão, PocketBlocks adiciona uma caixa de título, uma caixa de texto e dois botões, conforme mostrado abaixo. Você pode modificar **Dados** e **Código** no painel **Propriedades** para adaptá-los de acordo com suas necessidades. {% hint style="info" %} Clique na borda em vez da área interna para selecionar um **Componente personalizado** e exibir suas configurações de propriedade. {% endhint %}
### Dados **Dados** armazena informações em pares de valores-chave, fornecendo uma interface para o **componente personalizado** interagir com dados externos. Por exemplo, você pode referenciar dados do **componente personalizado** em outros componentes do seu aplicativo por meio de `nomeDoComponenteCustomizado.model` ou passar dados de outros componentes para o **componente personalizado**.
### Código Por padrão, PocketBlocks define o objeto `model` e duas funções `execultarConsulta` e `atualizarModel`.
* `executarConsulta` é uma função que aceita um nome de consulta em formato texto. Por exemplo, `executarConsulta(model.consulta)`. * `atualizarModel` é uma função que aceita um único argumento do tipo objeto. O argumento passado para `atualizarModel` será mesclado com os dados do **Componente customizado**. ## Implementação Todo o código do seu **componente personalizado**, incluindo HTML, CSS e JavaScript, é armazenado na caixa **Código** no painel **Propriedades**. Quando seu aplicativo for executado, o componente personalizado será incorporado em um elemento [iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe). Para facilitar a interação entre o **Componente personalizado** e outros componentes do seu aplicativo, o PocketBlocks oferece uma API para você por meio de objetos globais. A definição do tipo e a descrição dos objetos são as seguintes. ```typescript interface PBL { // Assine a alteração de dados // Quando os dados mudam, o manipulador será acionado // O valor retornado é a função de cancelamento de assinatura subscribe(handler: SubscribeHandler): () => void; // Função do componente React HOC que aceita um componente React // Retorna um novo componente que contém propriedades: runQuery, model, updateModel connect(Component: ComponentType): ComponentType; // Execute a consulta especificada runQuery(queryName: string): Promise; // Atualizar dados updateModel(patch: any): Promise; } interface SubscribeHandler { (data: IDataPayload): void; } interface IDataPayload { model: any; } ``` O exemplo a seguir é o mínimo de código que um componente personalizado requer para funcionar. ```javascript
``` ## Interação de dados ### Passando dados do aplicativo para o componente personalizado Por exemplo, para passar o texto em uma caixa de entrada para um componente personalizado, você pode usar a sintaxe `{{}}` para referenciar dados deste componente **Texto**. Observe que você também pode fazer referência a dados de consultas da mesma maneira.
Abaixo está o código para este exemplo. ```javascript
``` ### Passando dados do componente personalizado para o aplicativo Por exemplo, para exibir determinado texto do **Componente personalizado** em um componente **Input** no aplicativo, você pode definir o valor de `custom1.model.nome` como o valor padrão de `entrada1`. A notação de ponto `custom1.model.nome` acessa o nome do **componente personalizado**.
### Acionando consulta do componente personalizado Por exemplo, dada a tabela `usuarios` que exibe informações de todos os usuários, você deseja filtrar os dados com base no texto inserido em um **Componente personalizado**. Além disso, a operação de filtro é acionada clicando em um botão dentro do mesmo **Componente personalizado**.
De acordo com o requisito, o **componente personalizado** contém um componente **Input** e um componente **Botão**. Você também pode adicionar um componente **Texto** para fornecer contexto aos usuários do seu aplicativo. Quando um usuário insere na caixa de texto, por exemplo "Lor", e a seguir clica no botão de pesquisa, a tabela apresenta apenas as entradas em que o campo "Nome" que contém "Lor".
Para implementar esse **componente personalizado**, primeiro você cria a consulta `filtrarUsuario` para acessar os dados do componente personalizado e configura-o para ser executado por invocação manual. ```javascript return usuarios.value.filter((u) => u.name.includes(custom1.model.pesquisa || "") ); ``` Em seguida, você importa a biblioteca "antd" e utiliza os componentes **Button**, **Input**, **Card** e **Space**. Por fim, mais uma configuração para cada componente dentro do **Componente personalizado**: * Configure o método `updateModel` para executar e atualizar os dados do **Componente personalizado** quando o texto no componente **Input** for alterado. * Acionar a consulta `filtrarUsuario` pelo método `runQuery` quando o botão **Pesquisar** for clicado. ```javascript
``` # Uso de Markdown PocketBlocks oferece suporte ao uso da linguagem de marcação leve Markdown para formatar textos em seu aplicativo, como alterar o tamanho da fonte, inserir código e adicionar uma lista. Você também pode incorporar texto formatado em HTML no Markdown para obter mais opções de estilo. Use Markdown nos componentes **Texto** e **Tabela**. * **Texto**: Use Markdown para o texto de entrada.
* **Tabela**: Use Markdown para tipo de coluna.
## Noções básicas de Markdown Toda a sintaxe Markdown é válida no PocketBlocks. * **Títulos**: Use hashtag (#) antes do título. Mais hashtags, nível de título mais baixo. * **Parágrafos**: use uma linha em branco para separar os textos em parágrafos. * **Quebras de linha**: adicione pelo menos dois espaços em branco no final de uma linha e pressione **Enter** para iniciar uma nova linha. * **Ênfase**: Use um asterisco único (∗) antes e depois do texto para convertê-lo em texto *itálico*, asteriscos duplos (∗∗) para texto em **negrito** e asteriscos triplos (∗∗∗) para *\*\* itálico negrito \*\** texto. * **Blockquotes**: Use o colchete angular de fechamento (>) para criar uma blockquote. * **Listas**: use hífen (-), asterisco (∗) ou sinal de mais (+) seguido de um espaço em branco para criar uma lista não ordenada e use números seguidos de um ponto final (.) para criar uma lista ordenada. * **Código**: Use crases (\`) antes e depois do código para denotar `` `code` `` em texto simples, e três crases (\`\`\`) para apresentar ` ```bloco de código ` \`\` \`. * **Réguas horizontais**: Use pelo menos três asteriscos (∗∗∗), hífens (---) ou sublinhados (\_ \_ \_) no início de uma linha para criar uma régua horizontal. * **Links**: Use colchetes (\[]) para o texto de exibição e parênteses (()) para o endereço do link. Observe que não deve haver espaço entre eles. Por exemplo, `[PocketBlocks](https://github.com/pedrozadotdev/pocketblocks)`. * **Imagens**: Use um ponto de exclamação (!) para iniciar uma inserção de imagem e, em seguida, use colchetes (\[]) para o texto alternativo e parênteses (()) para o endereço do link ou caminho de origem. A legenda pode seguir os parênteses ou começar em uma nova linha. * **Caracteres de escape**: Use barra invertida (\\) para exibir os símbolos especiais que o Markdown usa. Por exemplo, para imprimir ` `` ` em texto simples, você deve usar `` \`\` `` em Markdown. Para obter mais informações, consulte [Guia de Markdown](https://www.markdownguide.org/basic-syntax/). ## Extensão GFM Você também pode usar extensões GitHub Flavored Markdown (GFM) para sintaxe adicional. * **Notas de rodapé**: use o acento circunflexo (^) e o número entre colchetes (\[]) para inserir notas de rodapé. Para obter mais informações, consulte [Notas de rodapé](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#footnotes). * **Linhas tachadas**: Use til duplo (\~\~) antes e depois do texto para adicionar linhas tachadas. Para obter mais informações, consulte [Estilização de texto](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#styling-text). * **Tabelas**: use hífens (-) separados pela barra vertical (|) para criar a linha de cabeçalho de uma tabela e continue usando a barra vertical para separar o conteúdo nas células. Para obter mais informações, consulte [Tabelas (extensão)](https://github.github.com/gfm/#tables-extension-). * **Listas de tarefas**: use um espaço em branco entre colchetes (\[ ]) no formato de lista para criar listas de tarefas. Para marcar uma tarefa concluída, substitua o espaço em branco pela letra *x*. Para obter mais informações, consulte [Listas de tarefas](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#task-lists). ## Suporte HTML No PocketBlocks, você pode usar a maioria das tags e propriedades HTML. Para obter mais informações, consulte [Incorporar HTML no Markdown](https://www.markdownguide.org/basic-syntax/#html). {% hint style="warning" %} Por motivos de segurança, algumas tags HTML, incluindo **iframe** e **script**, não são permitidas no PocketBlocks. {% endhint %} ### Apêndice: Tags HTML suportadas ```html