CanvaPH

Uma biblioteca modular e intuitiva para criação e manipulação de imagens usando canvas. Desenvolvida para facilitar a geração de gráficos, cards, leaderboards e elementos visuais de forma programática.

Visão Geral

O canvaph-lib oferece uma interface fluente e chainable para criação de imagens, suportando desde elementos básicos como formas e texto até recursos avançados como gradientes, efeitos e composição de imagens.

Instalação

npm install canvaph-lib

OU

yarn add canvaph-lib

Começo Rápido

const canvaPh = require("canvaph-lib");

// Exemplo básico
const imagem = new canvaPh({ width: 800, height: 400 })
    .fundo({ cor: "#2f3136" })
    .texto({
        texto: "Bem-vindo ao CanvaPH",
        x: 400, y: 200,
        fonte: "bold 32px Arial",
        cor: "#ffffff",
        alinhamento: "center"
    })
    .salvar("exemplo.png");

Características Principais

• Sintaxe intuitiva: Métodos encadeáveis e nomenclatura em português
• Multiplataforma: Compatível com Node.js, Termux e ambientes mobile
• Rica em recursos: Suporte a imagens, gradientes, efeitos e transformações
• Performance otimizada: Geração eficiente de imagens via API
• Extensível: Arquitetura modular para customizações

Documentação da API

Configuração Inicial

const canvas = new canvaPh({
    width: 800,      // Largura do canvas
    height: 400,     // Altura do canvas  
    quality: 0.9     // Qualidade de saída (0.1 - 1.0)
});

Métodos de Fundo

// Cor sólida
.fundo({ cor: "#2f3136" })

// Imagem de fundo
.fundo({ image: "https://exemplo.com/fundo.jpg" })

// Gradiente
.fundo({
    gradiente: {
        cores: ["#7289da", "#ffffff", "#a4b3ff"],
        direcao: "vertical" // horizontal, vertical, diagonal
    }
})

Elementos Gráficos

Retângulos

.rect({
    x: 50, y: 50,
    largura: 300, altura: 200,
    cor: "#212121",
    raio: 10,           // Cantos arredondados
    borda: {
        cor: "#7289da",
        largura: 2
    },
    opacidade: 0.8      // Transparência (0-1)
})

Círculos

.circle({
    x: 100, y: 100,
    raio: 50,
    cor: "#7289da",
    borda: {
        cor: "#ffffff", 
        largura: 3
    }
})

Linhas

.line({
    x1: 50, y1: 50,
    x2: 200, y2: 200, 
    cor: "#ffffff",
    largura: 2,
    tracejado: [5, 5]   // Padrão tracejado
})

Manipulação de Imagens

// Imagem retangular
.image({
    url: "https://exemplo.com/imagem.jpg",
    x: 100, y: 100,
    largura: 200, altura: 150,
    raio: 8,            // Cantos arredondados
    opacidade: 0.9
})

// Avatar circular (shortcut)
.avatar({
    url: "https://exemplo.com/avatar.jpg", 
    x: 50, y: 50,
    tamanho: 100
})

Tipografia

Texto Básico

.texto({
    texto: "Texto exemplo",
    x: 100, y: 150,
    fonte: "bold 24px Arial",
    cor: "#ffffff",
    alinhamento: "left", // left, center, right
    sombra: {
        cor: "rgba(0,0,0,0.5)",
        blur: 10
    }
})

Textos Pré-formatados

// Título
.titulo({
    texto: "Título Principal",
    x: 400, y: 100,
    cor: "#ffffff"
})

// Parágrafo com quebra de linha
.paragrafo({
    texto: "Texto longo com quebra automática de linha...",
    x: 100, y: 200,
    maxLargura: 500
})

Efeitos e Estilos

// Sombra
.sombra({
    cor: "rgba(0,0,0,0.3)",
    blur: 15,
    offsetX: 0,
    offsetY: 5
})

// Desfoque
.desfoque(8) // Intensidade

// Efeitos customizados
.efeito({
    nome: "brilho",
    config: { intensidade: 0.5 }
})

Agrupamento e Organização

.grupo("cabecalho", (ctx) => {
    ctx.rect({
        x: 0, y: 0,
        largura: 800, altura: 80, 
        cor: "#2a2d31"
    })
    .texto({
        texto: "Cabeçalho",
        x: 400, y: 45,
        fonte: "bold 28px Arial",
        cor: "#ffffff",
        alinhamento: "center"
    });
})

Exemplos de Uso

Profile Card

const profile = new canvaPh({ width: 378, height: 536 })
    .fundo({
        gradiente: {
            cores: ["#7289da", "#ffffff"],
            direcao: "vertical"
        }
    })
    .rect({
        x: 25, y: 150,
        largura: 328, altura: 370,
        cor: "#111214",
        raio: 15
    })
    .avatar({
        url: user.avatarURL,
        x: 40, y: 70,
        tamanho: 100
    })
    .texto({
        texto: user.username,
        x: 65, y: 235,
        fonte: "bold 20px Poppins", 
        cor: "#ffffff"
    })
    .salvar("profile_card.png");

Leaderboard

const leaderboard = new canvaPh({ width: 680, height: 450 })
    .fundo({ cor: "#36393f" });

users.forEach((user, index) => {
    const y = index * 75;
    
    leaderboard
        .rect({
            x: 10, y: y + 5,
            largura: 660, altura: 60,
            cor: "#2a2d31",
            raio: 10,
            opacidade: 0.9
        })
        .avatar({
            url: user.avatar,
            x: 20, y: y + 10,
            tamanho: 50
        })
        .texto({
            texto: user.tag,
            x: 85, y: y + 35,
            fonte: "bold 18px Arial",
            cor: "#ffffff"
        })
        .texto({
            texto: `Score: ${user.score}`,
            x: 520, y: y + 35,
            fonte: "16px Arial",
            cor: "#b9bbbe",
            alinhamento: "right"
        });
});

leaderboard.salvar("leaderboard.png");

Banner Promocional

const banner = new canvaPh({ width: 1000, height: 400 })
    .fundo({
        gradiente: {
            cores: ["#667eea", "#764ba2", "#f093fb"],
            direcao: "diagonal" 
        }
    })
    .rect({
        x: 50, y: 50,
        largura: 900, altura: 300,
        cor: "rgba(255,255,255,0.1)",
        raio: 20,
        borda: {
            cor: "rgba(255,255,255,0.3)",
            largura: 2
        }
    })
    .texto({
        texto: "PROMOÇÃO ESPECIAL",
        x: 500, y: 150,
        fonte: "bold 60px Arial",
        cor: "#ffffff",
        alinhamento: "center",
        sombra: {
            cor: "rgba(0,0,0,0.5)",
            blur: 20
        }
    })
    .salvar("banner_promocional.png");

Módulos Especializados

Profile Card Avançado

const { profile } = require("canvaph-lib");

const profileCard = new profile()
    .setUser("user-id-discord")
    .setBorder("#7289da")
    .setActivity({
        activity: userActivity,
        largeImage: activityImage
    })
    .build();

Sistema de Leaderboard

const { top } = require("canvaph-lib");

const leaderboard = new top()
    .setUsersData(users)
    .setScoreMessage("Pontuação:")
    .setColors({
        box: '#2a2d31',
        username: '#ffffff',
        score: '#b9bbbe', 
        firstRank: '#f7c716',
        secondRank: '#c0c0c0',
        thirdRank: '#cd7f32'
    })
    .setBackground("color", "#36393f")
    .build();

Configuração e Customização

Estilos Globais

const canvas = new canvaPh()
    .estilo({
        fonte: "Arial",
        corTexto: "#ffffff"
    })
    .qualidade(0.8)
    .tamanho(1200, 630); // Alterar dimensões

Exportação

// Salvar arquivo
const resultado = await canvas.salvar("imagem.png");

// Com API key customizada
const resultado = await canvas.salvar("imagem.png", "sua-api-key");

// Resultado retorna:
// { success: boolean, path: string, error?: string }

Solução de Problemas

Problemas Comuns

Imagens não carregam:

• Verifique se a URL é acessível publicamente
• Confirme o formato da imagem (PNG, JPG, WebP)
• Teste com uma URL conhecida para isolamento do problema

Texto não visível:

• Verifique contraste com o fundo
• Confirme posição dentro dos limites do canvas
• Teste com fonte e tamanho diferentes

Erros de renderização:

• Valide cores hexadecimais (#RRGGBB)
• Verifique valores numéricos dentro dos limites
• Confirme parâmetros obrigatórios

Debug

// Ativar logs detalhados
const canvas = new canvaPh()
    .comentario("Iniciando renderização...")
    .estatisticas(); // Exibe métricas de uso

Boas Práticas

1. Otimização: Use opacidade e efeitos com moderação
2. Performance: Combine operações similares
3. Manutenção: Use grupos para organizar elementos relacionados
4. Qualidade: Ajuste a qualidade conforme necessidade (0.7-0.9 para web)

Compatibilidade

• Node.js 16+
• Termux e ambientes mobile
• Navegadores modernos (com adaptações)
• APIs RESTful

Licença

MIT License - veja o arquivo LICENSE para detalhes.

Para mais exemplos e casos de uso avançados, consulte a documentação completa ou os exemplos no repositório.