--- title: Composições slug: studio/composicoes docTags: createdAt: 2026-04-28T18:37:55.353Z --- # Composições Composições são componentes de UI que podem ser aninhados em telas, permitindo construir bibliotecas de componentes e manter a consistência entre suas aplicações. *** ## 1 - O que é uma Composição? Uma composição é basicamente um fragmento de tela reutilizável. Ele contém: - Uma coleção de elementos (botões, comandos, contêineres, etc.) - Estilos responsivos para diferentes pontos de interrupção (celular, tablet, desktop) - Propriedades que podem ser sobrescrevidas por instância - Suporte para aninhamento de outras composições (até 5 níveis de profundidade) :::hint{type="info"} 📌 As composições são expandidas no lado do servidor durante a prévia, garantindo um comportamento consistente entre o estúdio web e os aplicativos móveis. ::: *** ## 2 - Criando uma Composição 1. Clique no botão "+" no painel Composições na barra lateral esquerda 2. Nomeie sua composição (por exemplo, "UserCard", "ProductItem") 3. Adicione elementos por meio de arrastar e soltar a partir da paleta 4. Configure propriedades e estilos para cada elemento 5. O save ocorre automaticamente após 2 segundos de inatividade ![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/_8lqmUOqa3bDqix4U9eYg-20260602-200509.gif) ```javascript // Example composition structure { uuid: "comp-123", name: "UserCard", category: "ui", elements: [ { type: "Flex", properties: { direction: "column" }, children: [ { type: "Text", properties: { text: "Username" } }, { type: "Button", properties: { label: "View Profile" } } ] } ], styles: { default: { padding: "16px" }, sm: { padding: "12px" }, md: { padding: "16px" }, lg: { padding: "20px" } } } ``` *** ## 3 - Uso de Composições em Telas Uma vez criadas, as composições aparecem na paleta Componentes, na seção "Composições". 1. Navegue até uma tela no seu projeto 2. Encontre sua composição na paleta 3. Arraste para a tela 4. A composição é inserida como um elemento `CompositionInstance ` ```javascript // CompositionInstance structure { type: "CompositionInstance", uuid: "instance-456", properties: { compositionId: "comp-123", overrides: { // Per-instance style overrides "element-789": { styles: { default: { backgroundColor: "blue" } } } } } } ``` *** ## 4 - Modo de Edição O sistema opera em dois modos de edição: | **Modo** | **Descrição** | | ---------------------- | ----------------------------------------------------------------------------- | | **Modo Tela** | Modo padrão. Edite o layout da tela e adicione composições às telas. | | **Modo de composição** | Editar o conteúdo da composição. Ativado clicando em uma composição na lista. | :::hint{type="info"} ❗ Ao editar uma composição, as alterações se aplicam a **todas as instâncias** dessa composição em todas as telas. ::: *** ## 5 - Composições Aninhadas Composições podem ser aninhadas dentro de outras composições com até 5 níveis de profundidade. ```javascript // Example: UserCard composition contains Avatar composition UserCard (Level 1) └── Flex ├── Avatar (Level 2) <- Another composition │ └── Image └── Text ``` **Regras de Nidificação\:** - Profundidade máxima de nidificação: 5 níveis - Referências circulares são impedidas (Composição A não pode conter Composição B se B já contém A) - Avisos visuais aparecem na paleta para composições com profundidade >= 4 *** ## 6 - Substituições de Estilo Cada instância de composição pode ter estilos personalizados por elemento. :::hint{type="warning"} ⚠️ As sobrescrituras de estilo são aplicadas por instância e não afetam outras instâncias da mesma composição. ::: Exemplo de estrutura de substituição: ```javascript { type: "CompositionInstance", properties: { compositionId: "user-card", overrides: { "button-123": { styles: { default: { backgroundColor: "#007bff" }, sm: { fontSize: "14px" } } } } } } ``` *** ## 7 - Expansão no Lado do Servidor :::hint{type="warning"} 🔥 **Breaking Change (dezembro de 2025):** Visualização móvel não recebe mais telas via . Agora ele busca dados diretamente do servidor `.postMessage` **Impacto:** - A primeira carga adiciona \~200ms de latência (depois armazenada no cache) - Requer conexão ativa com servidor - Permite composições em visualização móvel - Melhor consistência de dados ::: O servidor expande automaticamente as composições durante a prévia: 1. Solicitações de aplicativos móveis /projects/\:id/preview 2. Servidor carrega todas as telas e composições 3. Para cada tela, expande recursivamente os elementosCompositionInstance 4. Retorna dados expandidos com UUIDs únicos por instância ```javascript // Before expansion { type: "CompositionInstance", properties: { compositionId: "comp-123" } } // After expansion (server-side) { type: "Flex", uuid: "instance-456-element-789", // Prefixed with instance UUID properties: { direction: "column" }, children: [...] } ``` *** ## 8 - Validação e Segurança O sistema inclui várias salvaguardas: **Detecção de Referência Circular** ```javascript // This is prevented: Composition A contains Composition B Composition B contains Composition A // ❌ Error: "Circular reference detected" ``` **Validação da Profundidade de Aninhamento** - Profundidade máxima: 5 níveis - Aviso em profundidade >= 4 - Blocos adicionando composições que excedem o limite **Detecção de Composição Órfã** - Detecta composições deletadas ainda referenciadas nas telas - Mostra faixa de aviso com contagem - Atualiza automaticamente a cada 30 segundos *** ## 9 - Encadernações e Eventos As ligações (eventos e propriedades) funcionam corretamente com instâncias de composição: 1. O servidor duplica vinculações para cada elemento expandido 2. Gera IDs de vinculação únicos: `{instanceUuid}-{originalBindingId} ` 3. UUIDs de elementos são rastreados no mapeamento: `{instanceUuid}-{elementUuid} ` ```javascript // Original binding in composition { id: "binding-1", elementId: "button-123", eventType: "click", functionId: "func-456" } // Expanded binding in instance { id: "instance-789-binding-1", elementId: "instance-789-button-123", eventType: "click", functionId: "func-456" } ``` *** ## 10 - Melhores Práticas | **Prática** | **Descrição** | | ---------------------------------------- | ---------------------------------------------------------------------- | | **Modular Design** | Mantenha as composições pequenas e focadas em responsabilidades únicas | | **Convenção de nomeação** | Use nomes descritivos: , ,`serCardProductListNavigationMenu` | | **Evite nidificações profundas** | Fique dentro de 2-3 níveis para melhor desempenho | | **Instâncias de Teste** | Verifique todos os casos após editar uma redação | | **Usar categorias** | Organize composições por categoria (ui, layout, formas) | *** ## problemas **Composição Não Aparece na Visualização do Celular** 1. Verifique se a composição existe no banco de dados 2. Verifique está correto `CompositionInstance` `compositionId ` 3. Certifique-se de que o celular esteja buscando do servidor (não usando dados em cache) 4. Verifique os logs do servidor para erros de expansão **Avisos de Chave Duplicada** - Não deve ocorrer após as atualizações de dezembro de 2025 - Atualmente, UUIDs são precedidos por UUID de instância **Fixações Não Funcionando** - Verifique se a duplicação de binding do lado do servidor está funcionando - Verifique se os UUIDs dos elementos correspondem na tabela de ligações - Confirme que o ID da função é válido *** ## 12 - Endpoints de API | **Método** | **Endpoint** | **Descrição** | | --------------------------------------- | ----------------------------------------- | ----------------------------------------------- | | OBTER | `/projects/:id/compositions` | Liste todas as composições de um projeto | | OBTER | `/projects/:id/compositions/:uuid` | Obtenha uma composição individual | | POSTAR | `/projects/:id/compositions` | Crie nova composição | | PATCH | `/projects/:id/compositions/:uuid` | Composição atualizada | | DELETE | `/projects/:id/compositions/:uuid` | Excluir composição | | OBTER | `/projects/:id/preview` | Obtenha dados expandidos do projeto para prévia | *** ## 13 - Esquema de Banco de Dados ```javascript CREATE TABLE lowcode_studio.compositions ( uuid UUID PRIMARY KEY, project_id TEXT NOT NULL, name VARCHAR(255) NOT NULL, category VARCHAR(100), description TEXT, icon VARCHAR(50), elements JSONB NOT NULL DEFAULT '[]', properties JSONB, styles JSONB, order INTEGER DEFAULT 0, created_at BIGINT DEFAULT extract(epoch from now()) * 1000, updated_at BIGINT, deleted_at BIGINT ); CREATE INDEX idx_compositions_project ON lowcode_studio.compositions(project_id); ``` *** ## 14 - Arquitetura Técnica **Lado do Cliente (Web Studio)** - React Query para busca de composição - Sinais de Preact para estado reativo - Edição de modo duplo (tela vs composição) - Salvamento automático com dequique de 2 segundos **Lado do Servidor (API)** - Estrutura Deno + Hono - Drizzle ORM com PostgreSQL - Expansão de composição recursiva - Mapeamento UUID para duplicação de ligações **Prévia Móvel** - Buscas a partir do endpoint `/projects/:id/preview` - Recebe dados de composição totalmente expandidos - Renderizações usando lowcode-engine-tauri *** ## 15 - Migração a partir de versões anteriores Projetos criados antes das composições são totalmente compatíveis: - JSONs de projetos antigos importam sem problemas - O sistema lida com elegância com dados de composição ausentes - Sem mudanças significativas para projetos existentes - Somente novos projetos podem criar composições *** ## 16 - Considerações de Desempenho **Web Studio** - Composições carregam sob demanda - Tempo de 5 minutos para armazenamento de composição - Invalidação automática do cache em atualizações **Prévia Móvel** - Carga inicial: \~200ms de sobrecarga para expansão - Carregamentos subsequentes: armazenados em cache pelo React Query - A expansão acontece uma vez por sessão de pré-visualização **Recomendações** - Mantenha as composições abaixo de 50 elementos - Limite o aninhamento a 3 níveis para desempenho ideal - Use categorias de composição para uma melhor organização - Limpeza regular de composições não utilizadas *** ## 17 - Segurança - Suporte a múltiplas inquilinações via isolamento de esquema de banco de dados - Autenticação baseada em token para endpoints de API - Validação do lado do servidor de todos os dados de composição - Proteção contra ataques circulares de referência - Prevenção de injeção SQL via Drizzle ORM *** ## 18 - Melhorias Futuras **Melhorias planejadas\:** - Variantes de composição (temas claro/escuro) - Biblioteca de modelos de composição - Composições de importação/exportação entre projetos - Histórico de versões das composições - Análise de composição (acompanhamento de uso) - Ferramenta de diferença de composição visual - Mercado de composições *** ## 19 - Suporte e Recursos **Para ajuda adicional\:** - Verifique os logs do servidor para erros de expansão - Use o DevTools do navegador para inspecionar os dados de composição - Verifique o esquema do banco de dados com `deno task db:check ` - Consulte o guia de implementação em `docs/en-us/platform/compositions.md ` :::hint{type="warning"} 💡 Ative o registro de depuração definindo variáveis de ambiente para ver logs detalhados de expansão de composição. `DEBUG=true` ::: ![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/-4_SDcjt_aznvASbRyZ46-20260601-191750.gif)