DEV Community: Adryanne Kelly

Flutter - Conceitos que parecem iguais mas são diferentes

Adryanne Kelly — Wed, 13 Aug 2025 18:18:58 +0000

Um guia prático para evitar confusões comuns

Durante o desenvolvimento Flutter, é comum encontrar conceitos que aparentam ter a mesma função, mas possuem diferenças importantes que podem impactar performance e comportamento da aplicação. Neste artigo, vou te explicar alguns deles para que você não erre mais na hora de escolher qual usar no seu projeto.

Tópicos

Expanded vs Flexible
MediaQuery.sizeOf vs MediaQuery.of(context).size
const vs final
SingleChildScrollView vs ListView

1. Expanded vs Flexible

Ambos são usados para controlar como widgets ocupam espaço em layouts flexíveis, mas têm comportamentos distintos.

Expanded

Expanded(
  child: Container(color: Colors.blue, height: 50),
)

Com o Expanded o widget irá ocupar TODO o espaço que estiver disponível, ignorando o tamanho que você setou pra ele.

Flexible

Flexible(
  child: Container(color: Colors.blue, height: 50),
)

Ao contrário do Expanded, o Flexible não força o widget a ocupar todo o espaço. Em vez disso, ele mantém o tamanho natural se tiver espaço suficiente, se adapta (encolhe) automaticamente se não houver espaço, e pode crescer além do tamanho natural apenas se usar a propriedade flex ou se houver múltiplos widgets flexíveis dividindo o espaço.

Exemplo Comparativo:

Row(
    children: [ 
        Container(width: 100, height: 50, color: Colors.red),
        // Mantém 150px ou encolhe se necessário
        Flexible(child: Container(width: 150, color: Colors.blue, height: 50)), 
        // Ocupa todo espaço restante 
        Expanded(child: Container(color: Colors.green, height: 50)), 
    ], 
)

2. MediaQuery.of(context).size vs MediaQuery.sizeOf(context)

Ambos retornam o tamanho da tela, mas diferem em performance e funcionalidade.

MediaQuery.of(context).size

final screenSize = MediaQuery.of(context).size;
final width = screenSize.width;
final height = screenSize.height;

Esta forma de pegar o tamanho da tela é bem menos eficiente, pois carrega todas as informações que tem dentro do MediaQuery (informações de orientação, display, acessibilidade, etc), por isso, o ideal é só usar dessa forma quando você precisa de outras informações além do tamanho.

MediaQuery.sizeOf(context)

final screenSize = MediaQuery.sizeOf(context);
final width = screenSize.width;
final height = screenSize.height;

Esta é a forma mais recomendada e eficiente de pegar o tamanho da sua tela, é um método mais otimizado para casos onde são necessários apenas o tamanho, sem carregar todo o restante das informações.

Além de ser mais eficiente em termos de processamento, o MediaQuery.sizeOf(context) também evita rebuilds desnecessários do widget quando outras propriedades do MediaQuery mudam (como orientação ou brilho da tela).

O MediaQuery.sizeOf(context) só está disponível a partir da versão 3.10 do Flutter

Quando usar cada um:

// Para apenas tamanho da tela
final size = MediaQuery.sizeOf(context);

// Quando precisa de outras informações
final mediaQuery = MediaQuery.of(context);
final size = mediaQuery.size;
final padding = mediaQuery.padding;
final brightness = mediaQuery.platformBrightness;

3. const vs final

Ambos criam variáveis imutáveis, mas diferem em quando o valor é determinado.

const - Valor conhecido em tempo de compilação

const pi = 3.14159;
const appName = "Meu App";
const defaultColors = [Colors.red, Colors.blue];

Com o const, o valor da variável já é conhecido na hora que você escreve o código. É como se o Flutter já soubesse exatamente o que vai ser armazenado antes mesmo de rodar o app. O const é mais eficiente pois cria um único objeto na memória que é reutilizado.

final - Valor determinado em tempo de execução

final now = DateTime.now();
final userName = getUserName();
final randomNumber = Random().nextInt(100);

Com o final, o valor só é definido quando o código está rodando. É útil quando você precisa calcular algo ou buscar informações que só existem na hora da execução. O valor pode vir de funções, cálculos ou operações que só acontecem quando o app roda. Cada instância final cria seu próprio espaço na memória.

Exemplo prático:

class UserProfile {
  static const defaultAvatar = "assets/default_avatar.png"; // Sempre o mesmo
  final String userId; // Diferente para cada usuário
  final DateTime createdAt; // Definido na criação do objeto

  UserProfile({required this.userId}) : createdAt = DateTime.now();
}

4. SingleChildScrollView vs ListView

Ambos permitem rolagem, mas diferem significativamente em performance e uso de memória.

SingleChildScrollView - Para conteúdo limitado

SingleChildScrollView(
  child: Column(
    children: [
      Container(height: 200, color: Colors.red),
      Container(height: 200, color: Colors.blue),
      Container(height: 200, color: Colors.green),
    ],
  ),
)

O SingleChildScrollView carrega todo o conteúdo na memória de uma só vez, mesmo as partes que não estão visíveis na tela. É adequado quando você tem poucos widgets ou conteúdo pequeno, sendo simples de implementar mas podendo consumir muita memória se usado com muito conteúdo.

ListView - Para listas grandes

ListView.builder(
  itemCount: 1000,
  itemBuilder: (context, index) {
    return ListTile(
      title: Text('Item $index'),
      subtitle: Text('Descrição do item $index'),
    );
  },
)

O ListView é muito mais inteligente pois carrega apenas os widgets que estão visíveis na tela (lazy loading). Conforme você rola, ele vai criando os novos itens e destruindo os que saem de vista, sendo extremamente eficiente para listas grandes e gerenciando a memória automaticamente.

Em resumo...

Situação	Opção Recomendada	Motivo
Layout flexível que pode não ocupar todo espaço	Flexible	Respeita tamanho natural
Layout que deve ocupar todo espaço disponível	Expanded	Força expansão
Apenas obter tamanho da tela	MediaQuery.sizeOf	Mais performático
Valores conhecidos no código	const	Melhor performance
Valores calculados em runtime	final	Flexibilidade necessária
Lista com poucos itens	SingleChildScrollView	Simplicidade
Lista com muitos itens	ListView	Eficiência de memória

Extra: Agora sabe uma coisa que até parece diferente mas é igual?

Resposta: Navigator.pop(context) e Navigator.of(context).pop()

Isso mesmo, os dois fazem exatamente a mesma coisa na prática! O Navigator.pop(context) é apenas um atalho para Navigator.of(context).pop(). O ideal é usar Navigator.pop(context) diretamente quando você só vai fazer uma operação, mas se você vai usar o navigator em vários lugares, aí sim faz sentido armazenar o Navigator.of(context) em uma variável:

final navigator = Navigator.of(context); 

navigator.pop(); 
navigator.pushNamed('/home'); 
navigator.pushReplacementNamed('/profile');

Dessa forma você evita ficar repetindo Navigator.of(context) várias vezes no mesmo código.

Conclusão

Entender essas diferenças permite escolhas mais conscientes que resultam em código mais performático, manutenível e adequado para cada situação específica. A regra geral é sempre optar pela solução mais simples que atende aos requisitos, evoluindo para alternativas mais complexas apenas quando necessário.
Espero que tenha gostado do conteúdo, qualquer dúvida é só deixar sua pergunta, até a próxima :)

BLoC - Mais que um package, um padrão

Adryanne Kelly — Mon, 06 Jan 2025 12:49:19 +0000

Sabia que o BLoC é muito mais do que só um package do Flutter? Pois é, ele também é um padrão poderoso que pode transformar a forma como você organiza seu código e resolve sua lógica de negócios. Vou te mostrar de um jeito simples o que é o BLoC, como ele funciona, como aplicar no seu projeto e, também, os prós e contras de usar esse padrão. Então, pega um cafézinho e vem comigo descobrir tudo sobre esse tal de BLoC! 🚀

Tópicos

O que é o BLoC?
Principais conceitos
Como o BLoC funciona?
- Exemplo básico sem package
- Exemplo básico usando flutter_bloc
Quais as vantagens e desvantagens?
Conclusão
Referências

O que é o BLoC?

O BLoC (Business Logic Component) não é apenas um package ou uma biblioteca, mas também um dos padrões de gerenciamento de estado mais populares no ecossistema Flutter. Ele ajuda a organizar nosso código ao separar a lógica de negócios da interface do usuário (UI), tornando nossa aplicação mais limpa, legível e fácil de escalar e, consequentemente, mais eficiente e manutenível.

Principais conceitos

Eventos: São ações ou intenções que vem da interface do usuário que indicam que algo deve ser feito. Por exemplo: ao preencher um formulário de cadastro, quando você aperta o botão de enviar os dados, o evento de registerUser é disparado.

Estados: Os estados mostram como a lógica de negócios está em um dado momento e são enviados pelo BLoC. Ex: RegisterUserInitial, RegisterUserLoading, RegisterUserSuccess. Você pode ver mais sobre estados no artigo Entendendo State Pattern

Sink: É o “porta de entrada” dos eventos. A UI manda os eventos pelo sink e o BLoC processa tudo.

Streams: As streams são como canais de comunicação entre a UI e o BLoC. Elas permitem que os eventos sejam enviados e os estados sejam recebidos de forma assíncrona.

BlocProvider: É responsável por fornecer e disponibilizar uma instância do BLoC para a árvore de widgets da aplicação, garantindo que eles tenham acesso à lógica e possam usá-la de forma fácil e organizada.

BlocBuilder: É o widget que atualiza a UI sempre que um novo estado chega, garantindo que a interface esteja sempre em sintonia com a lógica do aplicativo.

BlocListener: É o widget que fica de olho nas mudanças de estado e executa ações em resposta, como exibir um alerta ou iniciar uma animação, sem alterar a UI diretamente.

Como o BLoC funciona?

O BLoC trabalha como um mediador entre a interface do usuário e a lógica da nossa aplicação. O fluxo funciona assim:

Dispara o eventos: A interface envia ações (como cliques e interações) para o BLoC, transformando-as em eventos.

Processa os dados: O BLoC recebe esses eventos, executa a lógica necessária (validações, chamadas a API, etc) e decide o próximo passo.

Gera um novo estado: Após processar os dados, o BLoC gera novos estados que representam qual a condição atual da aplicação.

Atualiza a Interface: A UI escuta essas mudanças de estado e se ajusta automaticamente para refletir os novos dados ou comportamentos.

Tá mas como é isso na prática? Vamos lá.

Exemplo básico sem package

Primeiro, vamos ver como é o uso do BLoC puro, sem a utilização de package:

Classe de estado:

É onde ficarão os estados do nosso contador, no caso só precisamos de um.

class CounterState {
    final int counterValue;

    CounterState(this.counterValue);
}

Classe de evento:

É onde estarão os eventos referentes ao nosso contador que podem ser chamados pela tela, nesse caso o de incremento.

abstract class CounterEvent {}

class IncrementEvent extends CounterEvent {}

CounterBloc:

Nessa classe, o BLoC é implementado usando Stream e Sink. Quando o botão na tela é pressionado, a função increment() é chamada. Ela adiciona o evento IncrementEvent no controlador de eventos (_eventController). O BLoC escuta esses através da stream no construtor e chama a função _mapEventToState. Essa função verifica qual é o evento. Se for um IncrementEvent, o contador é aumentado e um novo estado, com o valor atualizado, é enviado para o controlador de estados (_stateController), que é usado para mostrar o novo valor do contador na tela.

import 'dart:async';
import 'counter_event.dart';
import 'counter_state.dart';

class CounterBloc {
    final _stateController = StreamController<CounterState>(); // Controlador para o estado do contador.
    final _eventController = StreamController<CounterEvent>(); // Controlador para eventos.

    int _counter = 0; // Valor atual do contador.

    CounterBloc() {
        // Escuta os eventos e processa as mudanças de estado.
        _eventController.stream.listen(_mapEventToState);
        // Adiciona o estado inicial ao fluxo.
        _stateController.add(CounterState(_counter));
    }

    // Saída do estado do contador.
    Stream<CounterState> get state => _stateController.stream;

    // Método para adicionar o evento de incremento.
    void increment() {
        _eventController.sink.add(IncrementEvent());
    }

    // Identifica o evento e atualiza o estado do contador.
    void _mapEventToState(CounterEvent event) {
        if (event is IncrementEvent) {
            _counter++;
            _stateController.add(CounterState(_counter));
        }
    }

    // Fecha os controladores ao descartar a página para liberar recursos.
    void dispose() {
        _stateController.close();
        _eventController.close();
    }
}

HomePage:

Essa é a nossa tela onde o evento de incremento do contador será chamado. Aqui usamos um StreamBuilder para observar as mudanças no estado do contador. Sempre que o estado é atualizado, o StreamBuilder reconstrói a interface para exibir o novo valor do contador.

import 'package:counter_sem_bloc/app/features/home/bloc/counter_state.dart';
import 'package:flutter/material.dart';
import '../bloc/counter_bloc.dart';

class HomePage extends StatefulWidget {
    const HomePage({super.key});

    @override
    _HomePageState createState() => _HomePageState();
}


class _HomePageState extends State<HomePage> {
    final CounterBloc _counterBloc = CounterBloc(); // Instancia o BLoC.

    @override
    void dispose() {
        _counterBloc.dispose(); // Libera recursos do BLoC ao descartar a página.
        super.dispose();
    }

    @override
    Widget build(BuildContext context) {
        return Scaffold(
            appBar: AppBar(
                title: const Text('Contador BLoC - Sem Package', style: TextStyle(color: Colors.white, fontSize: 16)),
            ),
            body: Center(
                child: StreamBuilder<CounterState>(
                    stream: _counterBloc.state, // Escuta as mudanças no estado do contador.
                    initialData: CounterState(0), // Valor inicial do contador.
                    builder: (context, snapshot) {
                        return Column(
                            mainAxisAlignment: MainAxisAlignment.center,
                            children: [
                                const Text(
                                    'Pressione o botão para incrementar o contador.',
                                    style: TextStyle(fontSize: 16),
                                ),
                                const SizedBox(height: 20),
                                Text(
                                    '${snapshot.data?.counterValue}', // Exibe o valor atual do contador.
                                    style: const TextStyle(fontSize: 36, fontWeight: FontWeight.bold),
                                ),
                            ],
                        );
                    },
                ),
            ),
            floatingActionButton: FloatingActionButton(
                onPressed: _counterBloc.increment, // Chama o método para incrementar o contador.
                tooltip: 'Incrementar',
                child: const Icon(Icons.add),
            ),
        );
    }
}

Exemplo básico usando flutter_bloc

Agora vamos ver como o BLoC é implementado usando o package flutter_bloc:

As classes de evento e estado são praticamente iguais ao do exemplo acima:

Classe de estado:

Como dito anteriormente, essa é a classe onde vai conter os estados do contador.

import 'package:equatable/equatable.dart';

class CounterState extends Equatable {
    final int counterValue;

    const CounterState(this.counterValue);

    @override
    List<Object> get props => [counterValue];
}

Nessa classe, também fazemos o uso de um outro package chamado equatable que no BLoC, é usado para comparar estados e eventos. Assim, o BLoC só muda algo na tela se o estado ou evento realmente for diferente, evitando atualizar sem necessidade.

O equatable serve para o Dart entender quando dois objetos são iguais olhando o que tem dentro deles (os valores). Sem ele, o Dart só compara se os objetos estão no mesmo lugar da memória. Por exemplo:

final user1 = User('Alice', 25); 
final user2 = User('Alice', 25);

print(user1 == user2); // false, porque são objetos diferentes na memória.
// mas usando o equatable o resultado será [true], pois consultará
// também os valores dentro desses objetos

Classe de evento:

Também da mesma forma do exemplo anterior, essa classe vai ter os eventos referentes ao contador que no nosso caso é o evento de incremento:

import 'package:equatable/equatable.dart';

abstract class CounterEvent extends Equatable {
    const CounterEvent();

    @override
    List<Object> get props => [];
}

class IncrementCounterEvent extends CounterEvent {}

CounterBloc:

Ao clicar no botão de incrementar, o evento IncrementCounterEvent é adicionado ao CounterBloc, que escuta o evento e incrementa o valor do contador, assim o CounterBloc emite um novo estado com o valor do contador incrementado e o widget é reconstruído exibindo o novo valor do contador

import 'package:counter_using_flutter_bloc/app/bloc/counter_event.dart';
import 'package:counter_using_flutter_bloc/app/bloc/counter_state.dart';
import 'package:flutter_bloc/flutter_bloc.dart';

class CounterBloc extends Bloc<CounterEvent, CounterState> {
    CounterBloc() : super(const CounterState(0)) {// Inicia o estado do contador com o valor 0
        on<IncrementCounterEvent>((event, emit) { // Escuta o evento IncrementCounterEvent
            emit(CounterState(state.counterValue + 1)); // Emite um novo estado com o valor do contador incrementado
        });
    }
}

E por último nossa HomePage que é onde o evento vai ser chamado e assim a tela vai atualizar o estado do contador através do BlocBuilder:

import 'package:counter_using_flutter_bloc/app/bloc/counter_bloc.dart';
import 'package:counter_using_flutter_bloc/app/bloc/counter_event.dart';
import 'package:counter_using_flutter_bloc/app/bloc/counter_state.dart';
import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';


class HomePage extends StatefulWidget {
    const HomePage({super.key, required this.title});

    final String title;

    @override
    State<HomePage> createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {

    @override
    Widget build(BuildContext context) {
        return Scaffold(
            appBar: AppBar(
                backgroundColor: Theme.of(context).colorScheme.inversePrimary,
                title: Text(widget.title, style: Theme.of(context).textTheme.bodyLarge),
            ),
            body: Center(
                // Escuta o estado do CounterBloc e reconstrói o widget quando o estado muda
                child: BlocBuilder<CounterBloc, CounterState>(
                    builder: (context, state) {
                        return Column(
                            mainAxisAlignment: MainAxisAlignment.center,
                            children: <Widget>[
                                const Text(
                                    'Pressione o botão para incrementar o contador.',
                                ),
                                Text(
                                    '${state.counterValue}', // Exibe o valor do contador
                                    style: Theme.of(context).textTheme.headlineMedium,
                                ),
                            ],
                        );
                    },
                ),
            ),
            floatingActionButton: FloatingActionButton(
                onPressed: () {
                    // Adiciona o evento IncrementCounterEvent ao CounterBloc
                    context.read<CounterBloc>().add(IncrementCounterEvent());
                },
                tooltip: 'Increment',
                child: const Icon(Icons.add),
            ),
        );
    }
}

Opa, mas precisamos de mais um detalhe! Temos que inserir a instancia do nosso bloc dentro da árvore de widgets para que possamos acessá-la na nossa HomePage. Como fazemos isso? É simples, vamos adicionar um BlocProvider como "pai" da nossa HomePage, assim poderemos obter a instância a partir de qualquer parte da tela.

import 'package:counter_using_flutter_bloc/app/bloc/counter_bloc.dart';
import 'package:counter_using_flutter_bloc/app/pages/home_page.dart';
import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';


class AppWidget extends StatelessWidget {
const AppWidget({super.key});

    @override
    Widget build(BuildContext context) {
        return MaterialApp(
            title: 'Exemplo de uso do Flutter Bloc',
            theme: ThemeData(
                colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
                useMaterial3: true,
            ),
            debugShowCheckedModeBanner: false,
            home: BlocProvider( // Adiciona a instância do CounterBloc ao widget da página
                create: (context) => CounterBloc(),
                child: const HomePage(title: 'Contador usando Flutter Bloc'),
            ),
        );
    }
}

Caso quiséssemos acessar a instância do bloc em qualquer parte da aplicação, colocaríamos o BlocProvider como "pai" do MaterialApp.

Assim, ambos os exemplos funcionam da mesma forma, mas com abordagens diferentes. No primeiro, mostramos como o BLoC funciona por trás dos panos, implementando sua lógica de maneira pura, sem uso pacotes. Já no segundo, utilizamos o package flutter_bloc, que abstrai boa parte da implementação, tornando o código mais simples, organizado e enxuto.

Quais as vantagens e desvantagens?

Vantagens

Separação de responsabilidades	Mantém a lógica de negócios separada da interface do usuário, deixando o código mais organizado e fácil de trabalhar.
Testabilidade	Isolar a lógica de negócios facilita a criação de testes unitários, garantindo a qualidade do código.
Escalabilidade	Organiza o código de forma a suportar o crescimento do app sem se perder em complexidade.
Padronização	Garante uma abordagem padronizada no desenvolvimento, o que é vantajoso para equipes grandes
Reutilização de código	Permite usar a mesma lógica de negócios em diferentes partes do app ou até em outros projetos

Desvantagens

Curva de aprendizado	Pode ser intimidador para iniciantes por usar conceitos como streams, sinks e gerenciamento de estados.
Complexidade desnecessária para apps simples	Em projetos pequenos, o uso do BLoC pode parecer exagerado, adicionando mais código e estrutura do que o necessário.
Mais verboso	Comparado a outros métodos de gerenciamento de estado, como `Provider` ou `setState`, o BLoC pode exigir mais código boilerplate.

"Ain mas num sei o que significa boilerplate" Então agora vai saber:

Boilerplate é um termo usado em desenvolvimento de software para se referir a códigos ou estruturas que precisam ser repetidos em vários lugares ou projetos, muitas vezes sem muitas alterações.

Conclusão

O BLoC é um padrão poderoso que promove o desacoplamento, a escalabilidade e a testabilidade nas aplicações Flutter. Apesar da sua implementação manual ser mais trabalhosa, o uso de pacotes como flutter_bloc torna o processo bem mais simples e direto. Usando o BLoC, podemos ter uma interface do usuário mais reativa e alinhada com os princípios de boas práticas de desenvolvimento, permitindo que criemos aplicações mais robustas e fáceis de manter a longo prazo.
Espero que tenham gostado do artigo. Abaixo vou deixar alguns links de materiais relacionados que podem ajudar e complementar esse conteúdo, além do exemplo de implementação que usei. Qualquer dúvida é só chamar :3
Até a próxima.

Referências

Criando aplicação multi-idioma no Flutter

Adryanne Kelly — Fri, 21 Jun 2024 11:28:53 +0000

Neste artigo, vou guiá-lo passo a passo sobre como implementar um seletor de idioma moderno e funcional em sua aplicação Flutter. Vamos explorar como criar um toggle de idioma de forma intuitiva e fácil de usar, garantindo que seus usuários possam alternar entre diferentes idiomas de forma suave e sem complicações. Vamos começar?

Tópicos

Introdução
Passo a passo
- Passo 1: Criando nosso projeto Flutter
- Passo 2: Adicionando o flutter_localizations, intl e provider
- Passo 3: Gerando arquivos de tradução
- Passo 4: Configurando as linguagens na nossa aplicação
- Passo 5: Adicionando traduções na nossa aplicação
- Passo 6: Fazendo toggle de idiomas
Conclusão
Referências

Introdução

Se você está desenvolvendo uma aplicação que visa um público global, ou simplesmente deseja oferecer suporte a múltiplos idiomas, um seletor de idioma é essencial.
A alternância entre idiomas é importante pois oferece uma experiencia melhor para o usuário, permitindo que ele escolha um idioma de sua preferência de maneira rápida e fácil.
Neste artigo, você vai aprender de maneira rápida como fazer sua aplicação ter suporte a diferentes idiomas.
Lembrando que neste artigo faremos a alternância entre 2 idiomas, mas a partir disso você pode fazer com quantos idiomas desejar. Então, mão na massa!

Passo a passo

Passo 1: Criando nosso projeto Flutter

Para criar nosso projeto Flutter, vamos simplesmente rodar o seguinte comando

flutter create internationalization_example

Aqui batizamos o nome do nosso projeto como "internationalization_example". Você pode colocar o nome que preferir.

Passo 2: Adicionando flutter_localizations, intl e provider

Agora, vamos adicionar os packages que precisamos para o nosso toggle de idiomas. Para isso, dentro do nosso projeto flutter vamos rodar os seguintes comandos:

Adicionando flutter_localizations: Este pacote será para adicionar suporte a outros idiomas já que por padrão o Flutter suporta somente o Inglês.

flutter pub add flutter_localization

Adicionando o intl: Este pacote oferece recursos de internacionalização e localização, incluindo tradução de mensagens, plurais e gêneros, formatação e análise de data/número e texto bidirecional.

flutter pub add intl:any

Adicionando o provider: Utilizaremos este para injeção de dependência que vamos precisar mais pra frente.

flutter pub add provider

⚠️ Agora uma pequena alteração:
No nosso arquivo pubspec.yaml, precisaremos alterar a forma de declaração do nosso flutter_localization como mostrado abaixo e após isso dar um ctrl + s para reinstalar as nossas dependências:

dependencies:
    flutter:
        sdk: flutter
+   flutter_localizations:
+       sdk: flutter
    # The following adds the Cupertino Icons font to your application.
    # Use with the CupertinoIcons class for iOS style icons.
    cupertino_icons: ^1.0.6
-   flutter_localization: ^0.2.0
    intl: any
    provider: ^6.1.2

Passo 3: Gerando arquivos de tradução

Dentro da pasta lib vamos criar uma pasta chamada l10n e dentro criar um arquivo chamado app_en.arb para os textos em inglês (en é a sigla da linguagem desejada, você pode colocar a sigla da linguagem que quiser) e um chamado app_pt.arb para textos em português.

Vamos escrever nossas traduções da seguinte forma:

// app_en.arb
{
    "helloWorld": "Hello World!",
    "counterMsg": "You have pushed the button this many times:"
}

// app_pt.arb
{
    "helloWorld": "Olá mundo",
    "counterMsg": "Você apertou o botão essa quantidade de vezes:"
}

Lembrando que as chaves das traduções devem ser exatamente iguais nos dois arquivos.

Você deverá fazer isso para todos os textos que deseja traduzir na sua aplicação. "Ah mas eu tenho um montão de textos nela!". Então... boa sorte. 👍

Curiosidade: A sigla l10n é assim porque na palavra localization tem 10 letras entre a letra L e a letra N.

Criados os nossos arquivos, para ativar a nossa geração dos arquivos de tradução, vamos no nosso arquivo pubspec.yaml novamente e habilitar a flag generate como no exemplo abaixo:

flutter:
    # The following line ensures that the Material Icons font is
    # included with your application, so that you can use the icons in
    # the material Icons class.
    uses-material-design: true
    generate: true

Agora, para gerar nossos arquivos, rodamos o seguinte comando:

flutter gen-l10n

Estes arquivos gerados ficarão localizados em dart_tool/flutter_gen/gen_l10n.

Não mexa nesses arquivos. Toda alteração nas traduções deve ser feita somente nos arquivos .arb

Passo 4: Configurando as linguagens na nossa aplicação

Agora configuraremos nosso MyApp, afinal, é a partir dele que a mágica acontece.

O MyApp é onde fica o nosso MaterialApp que nada mais é que a raiz de um aplicativo Flutter, que fornece uma estrutura base para navegação, estilização e internacionalização.

Dito isso, vamos adicionar as nossas configurações de internacionalização:

import 'package:flutter/material.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:internationalization_flutter_example/app/my_home_page.dart';


class MyApp extends StatelessWidget {
    const MyApp({super.key});

    @override
    Widget build(BuildContext context) {
        return MaterialApp(
            title: 'Flutter Demo',
            theme: ThemeData(
                colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
                useMaterial3: true,
            ),
            // Delegações de internacionalização globais 
            localizationsDelegates: const [
                AppLocalizations.delegate,
                GlobalMaterialLocalizations.delegate,
                GlobalWidgetsLocalizations.delegate,
                GlobalCupertinoLocalizations.delegate,
            ],
            // linguagens que nossa aplicação irá suportar
            supportedLocales: const [
                Locale('en'),
                Locale('pt'),
            ],
            // idioma atual da nossa aplicação
            locale: const Locale('pt'),
            home: const MyHomePage(title: 'Flutter Demo Home Page'),
        );
    }
}

Passo 5: Adicionando traduções na nossa aplicação

Para adicionar as traduções nas páginas da nossa aplicação, vamos substituir os textos presentes na aplicação pelas chaves correspondentes do arquivo gerado com o comando flutter gen-l10n como no exemplo abaixo:

import 'package:flutter_gen/gen_l10n/app_localizations.dart';
...

appBar: AppBar(
    // adicionando texto da chave helloWorld
    title: Text(AppLocalizations.of(context)!.helloWorld),
),

Nota: a cada mudança nos arquivos .arb é necessário rodar novamente o comando flutter gen-l10n para que as mudanças persistam nos arquivos de tradução gerados.

Passo 6: Fazendo toggle de idiomas

Agora, por fim, vamos fazer nosso toggle de idiomas!! Para isso vamos criar uma controller que vai estender de ChangeNotifier (vamos usar o ChangeNotifier para que a nossa tela fique escutando qualquer alteração na nossa classe)

Nesta classe vamos criar uma variável booleana (vou chamá-la de isEnglish) que recebe por padrão true

Criada a variável, criaremos agora uma função void que toda vez que for chamada o valor da variável mudará para sua negação (isso significa que se ela for true se tornará false e vice-versa) e logo após notificamos essa alteração usando notifyListeners();.

Nossa controller ficará da seguinte forma:

import 'package:flutter/material.dart';

class LanguageController extends ChangeNotifier {
    bool isEnglish = true;

  void toggleLanguage() {
    isEnglish = !isEnglish;
    notifyListeners();
  }
}

Agora voltando ao nosso MyApp, vamos injetar o nosso controller que é a nossa dependência:


class MyApp extends StatelessWidget {
    const MyApp({super.key});

    @override
    Widget build(BuildContext context) {
        // adicionamos o ChangeNotifierProvider para fornecer o LanguageController
        return ChangeNotifierProvider(
            // criamos uma instância de LanguageController
            create: (context) => LanguageController(),
            builder: (context, child) {
                // acessamos o LanguageController por meio do Provider
                final languageController = Provider.of<LanguageController>(context);
                return MaterialApp(
                    title: 'Flutter Demo',
                    theme: ThemeData(
                        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
                        useMaterial3: true,
                    ),
                    localizationsDelegates: const [
                        AppLocalizations.delegate,
                        GlobalMaterialLocalizations.delegate,
                        GlobalWidgetsLocalizations.delegate,
                        GlobalCupertinoLocalizations.delegate,
                    ],
                    supportedLocales: const [
                        Locale('en'),
                        Locale('pt'),
                    ],
                    // acessamos o atributo isEnglish do LanguageController para definir o idioma
                    // se false, o idioma será português (pt), caso contrário, será inglês (en)
                    locale: languageController.isEnglish ? const Locale('en') : const Locale('pt'),
                    home: const MyHomePage(title: 'Flutter Demo Home Page'),
                );
            },
        );
    }
}

O ChangeNotifierProvider é uma classe do pacote provider no Flutter, que é usado para fornecer uma instância de um ChangeNotifier aos widgets descendentes na árvore de widgets. Sendo assim, o método create é chamado para criar uma instância de LanguageController para que possamos acessar os dados ou regras de negócio presentes nele.

Agora, na nossa tela, vamos adicionar o nosso botão para mudar o idioma da nossa aplicação:

class MyHomePage extends StatefulWidget {
    const MyHomePage({super.key, required this.title});
    final String title;

    @override
    State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
    @override
    Widget build(BuildContext context) {
        // acessamos o LanguageController por meio do Provider
        final languageController = Provider.of<LanguageController>(context);

        return Scaffold(
            appBar: AppBar(
                backgroundColor: Theme.of(context).colorScheme.inversePrimary,
                title: Text(AppLocalizations.of(context)!.helloWorld),
            ),
            body: Center(
                child: Column(
                    mainAxisAlignment: MainAxisAlignment.center,
                    children: <Widget>[
                        Text(
                            AppLocalizations.of(context)!.counterMsg,
                        ),
                        Text(
                            '2',
                            style: Theme.of(context).textTheme.headlineMedium,
                        ),
                    ],
                ),
            ),
            floatingActionButton: FloatingActionButton(
                // chamando nossa função do LanguageController
                onPressed: languageController.toggleLanguage,
                tooltip: 'Toggle Language',
                child: const Icon(Icons.language),
            ),
        );
    }
}

Ao fim disso, nosso toggle de idiomas já está funcionando, basta clicar no botão flutuante e o idioma da nossa aplicação mudará assim como demonstrado abaixo:

E pronto, agora você pode alternar entre os idiomas que quiser na sua aplicação!

Conclusão

Implementar uma alternância entre idiomas é uma excelente maneira de tornar sua aplicação acessível a usuários de diversos países. Com estes seis passos, você pode implementar essa funcionalidade de forma fácil e eficiente. Abaixo, disponibilizo o repositório de exemplo e links úteis para auxiliá-lo. Em caso de dúvidas, sinta-se a vontade para entrar em contato. Obrigado por ler até aqui. Espero que tenha gostado e até a próxima!

Referências

Meus agradecimentos a @clintonrocha98, @cherryramatis e @redrodrigoc vocês são demais 💜

Entendendo State Pattern - Flutter

Adryanne Kelly — Thu, 02 May 2024 12:09:50 +0000

No universo Flutter, encontramos diversas formas de lidar com gerência de estado e de aplicar as melhores práticas da linguagem em determinados contextos, nesse artigo vou lhe apresentar mais uma forma para essa coleção! Vamos conhecer um pouco sobre o State Pattern, que promete obedecer os princípios de responsabilidade única e composição de uma forma mais organizada, limpa e de fácil manutenção.

Tópicos

O que é o State Pattern?
Quando devo usar StatePattern?
State Pattern na prática
Conclusão
Referências

O que é o State Pattern?

No site de design patterns in Dart, podemos encontrar a seguinte definição, que é uma maneira simples e direta de dizer do que se trata o nosso State Pattern:

O State pattern é utilizado na programação para encapsular comportamentos diferentes para o mesmo objeto, com base no seu estado interno. Esta pode ser uma forma mais limpa de um objeto alterar o seu comportamento em tempo de execução sem recorrer a declarações condicionais, melhorando assim a manutenção.

Isso quer dizer que cada estado do nosso objeto estará separado por classes, que serão extensões/variações de uma classe de estado principal de um determinado objeto.

Mas como assim?

Imagine que você tem um objeto Agua, para representar o estado desta Agua você cria um EstadoDaAgua, logo as variações de estado de Agua poderiam ser Solido, Liquido e Gasoso, ou seja:

abstract class EstadoDaAgua {
    //
}

class Solido extends EstadoDaAgua {
    //
}

class Liquido extends EstadoDaAgua {
    //
}

class Gasoso extends EstadoDaAgua {
    //
}

O State Pattern é usado inclusive no padrão BLoC. Se você usa padrão BLoC, obrigatoriamente já estará usando State Pattern.

Quando devo usar State Pattern?

Quando seu objeto se comporta diferente dependendo do seu estado.
Quando o número de estados é grande e o código do estado muda frequentemente.
Quando sua classe tiver uma quantidade massiva de condicionais que alteram a forma como a classe se comporta de acordo com os valores dos campos que ela contém.
Quando tiver muito código duplicado de estados e transições semelhantes.

State Pattern na prática

Agora, vamos ver um exemplo de uso de State Pattern na prática. Observando a classe abaixo, percebemos que o estado está sendo definido a partir de variáveis usando ChangeNotifier:

class CategoryStore extends ChangeNotifier {
    List<String> categories = [];
    bool isLoading = false;
    String error = '';
    IApiDatasource apiDatasource = ApiDatasource();

    void getCategories() async {
        isLoading = true;
        await apiDatasource.getCategories().then((response) {
            response.fold(
                (left) => error = left.message;
                (right) => categories = right;
            )
        });
        isLoading = false;
        notifyListeners();
    }
}

O método fold() utilizado no exemplo pertence ao Either Type, um elemento da programação funcional utilizado para representar um valor que tem qualquer um dos dois tipos especificados. O Either é comumente usado para representar um valor de sucesso ou um valor de falha, assim como exemplificado acima onde left representa o valor de erro e o right o valor de sucesso.

A classe acima contém uma função que inicia com o carregamento (isLoading) e, durante esse processo, ela aguarda que os dados provenientes de uma API sejam armazenados na variável categories. Quando o carregamento é concluído, a função recebe o valor falso.

Poderíamos organizar esse código usando State Pattern da seguinte forma:

Classe de Estados

Declaramos os estados com suas respectivas classes.

abstract class CategoryState {}

class CategoryInitial extends CategoryState {}

class CategoryLoading extends CategoryState {}

class CategoryLoaded extends CategoryState {
    final List<String> categories;
    CategoryLoaded(this.categories);
}

class CategoryError extends CategoryState {
    final String message;
    CategoryError(this.message);
}

Classe de Store

Na função getCategories() descartamos a variável isLoading e utilizaremos a variável value (variável que representa o estado no ValueNotifier, que por sua vez é do tipo CategoryState) setando a classe CategoryLoading para receber nosso estado.

Depois disso, no método fold() se minha requisição deu erro ,value receberá o estado de Error com a mensagem (left) e se estiver dado tudo certo receberá o Loaded com seus dados carregados na variável right e assim, acabamos por descartar as variáveis categories e èrror

class CategoryStore extends ValueNotifier<CategoryState> {
    CategoryStore() : super(CategoryInitial());

    IApiDatasource apiDatasource = ApiDatasource();

    void getCategories() async {
        value = CategoryLoading(); 
        await apiDatasource.getCategories().then((response) {
            response.fold(
                (left) => value = CategoryError(left.message);
                (right) => value = CategoryLoaded(right);
            )
        });
    }
}

value é um get de Value Notifier, onde contém o estado atual da nossa classe Store

Exemplo em página


class HomePage extends StatefulWidget {
  const HomePage({super.key});

  @override
  State<HomePage> createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
    //Instancia de CategoryStore criada 
    CategoryStore store = CategoryStore();

    // iniciando função ao carregar a página
    @override
    void initState() {
        store.getCategories();
        super.initState();
    }

    @override
    void dispose() {
        // TODO: implement dispose
        super.dispose();
        store.dispose();
    }

     @override
      Widget build(BuildContext context) {
        return Scaffold(
        body: Expanded(
            // "Escutando a store"
            child: ValueListenableBuilder(
                valueListenable: store,
                builder: (context, value, child) {
                    //se o value receber erro retorna a mensagem
                    if (value is CharacterError) {
                        return Center(
                            child: Text(
                              'Erro ao carregar categorias: ${value.message}',
                            ),
                        );
                    }
                    // se o value receber sucesso/loaded retorna a lista
                    // de categorias
                    if (value is CharacterLoaded) {
                         return ListView.builder(
                            controller: store.scroll,
                            itemCount: value.categories.length,
                            itemBuilder: (context, index) {
                                final category = value.categories[index];
                                return Text(category);
                            }
                        );
                    }
                    // em estado de loading ou inicial ficará carregando
                    return const Center(child: CircularProgressIndicator());
                }
            ),
        );
    }
}

E pronto, já implementamos nosso State Pattern! E como vantagem: seguimos o Princípio de Responsabilidade Única e Open/Closed e simplificamos o código eliminando condicionais que poderiam deixar o nosso código poluído.

Conclusão

Muito obrigada por ter lido até aqui, como este é um artigo sobre o State Pattern, acabei por não falar muito sobre o ValueNotifier e outras coisas que escolhi utilizar no exemplo, porém vou estar deixando abaixo alguns links que podem ajudar a entender, além de também um vídeo do meu sensei @redrodrigoc explicando direitinho como o State Pattern funciona, vale a pena dar uma olhada. Espero que tenham gostado, até a próxima! 💙

Referências

Meus agradecimentos ao @redrodrigoc e a @cherryramatis por todo apoio e ajuda com este artigo 💙

Autopreenchimento de campos no FilamentPHP usando API

Adryanne Kelly — Mon, 01 Apr 2024 19:28:04 +0000

Neste artigo, vou mostrar como você pode consumir API e utilizá-la para autopreenchimento de campos no Filament, tornando assim seu formulário mais automatizado e dinâmico de forma simples e fácil. Vamos aprender, como exemplo, a autopreencher campos de endereço a partir do CEP digitado. Partiu?

Tópicos

Introdução
Passo a Passo
- Passo 1: Criando projeto Laravel e adicionando o FilamentPHP
- Passo 2: Criando as migrations e relacionamentos
- Passo 3: Criando nossa resource
- Passo 4: Adicionando funcionalidade de autopreenchimento com API
Conclusão
Referências

Introdução

E ai pessoal, este artigo não tem o intuito de ser clean code, mas sim de mostrar no geral como o autopreenchimento é feito para que a didática fique melhor, porém você pode organizar seu código da maneira que desejar. Neste exemplo, vou estar fazendo uso da API do ViaCep e vamos utilizá-la para autopreenchimento de campos de endereço, mas isso não se limita só a ela, sinta-se livre para usar a API que preferir. Vamos começar!

Passo a passo

Neste exemplo, estamos utilizando as seguintes versões de nossas ferramentas:

Laravel v11.x
PHP v8.2
FilamentPHP v3.2

❗ Importante: O uso de outras versões pode mudar a forma como o procedimento abaixo é feito.

Passo 1: Criando projeto Laravel e adicionando o FilamentPHP

Para criar nosso projeto Laravel, podemos utilizar o seguinte comando:

composer create-project laravel/laravel example-app

Onde example-app é o nome do nosso projeto. Feito isso, dentro da pasta do projeto vamos usar os seguintes comandos, sendo o primeiro para adicionar o FilamentPHP e o outro para instalar os painéis do Filament:

composer require filament/filament:"^3.2" -W
 
php artisan filament:install --panels

Passo 2: Criando nossos models, migrations e relacionamentos

Agora vamos rodar o seguinte comando para criar o nosso Model, onde Address é o nome do nosso model e a flag -m fará com que a Migration seja criada junto com o Model:

php artisan make:model Address -m

Dentro da nossa Migration vamos adicionar os campos que vamos utilizar na nossa tabela. Levando em conta que vamos utilizar a API do ViaCep, os campos deverão ficar mais ou menos dessa forma:


<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    /**
    * Run the migrations.
    */
    public function up(): void
    {
        Schema::create('addresses', function (Blueprint $table) {
            $table->id();
            $table->foreignId('user_id')->constrained()->cascadeOnDelete();
            $table->string('postal_code')->nullable();
            $table->string('address')->nullable();
            $table->string('number')->nullable();
            $table->string('complement')->nullable();
            $table->string('neighborhood')->nullable();
            $table->string('city')->nullable();
            $table->string('uf')->nullable();
            $table->timestamps();
        });
    }

    /**
    * Reverse the migrations.
    */
    public function down(): void
    {
        Schema::dropIfExists('addresses');
    }
};

Adicionado os campos na Migration, podemos rodar um php artisan migrate para que nossas tabelas sejam criadas no banco de dados.
E também, para criar um usuário para acessar nosso painel, usamos php artisan make:filament-user, digite um nome, um email e uma senha e use-os para fazer seu login no painel.

Agora vamos trabalhar nossos Models. Primeiro, precisamos adicionar os campos da nossa tabela na variável $fillable, como mostrado abaixo:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class Address extends Model
{
    use HasFactory;

    protected $fillable = [
        'user_id',
        'postal_code',
        'address',
        'number',
        'complement',
        'neighborhood',
        'city',
        'uf',
    ];
}

Após isso, ainda dentro do nosso Model precisamos criar nossos relacionamentos. Considerando que um usuário terá somente um endereço e que um endereço está relacionado somente a um usuário, podemos adicionar uma relação do tipo hasOne:

Address.php

public function users()
{
    return $this->hasOne(User::class);
}

User.php

public function addresses()
{
    return $this->hasOne(Address::class);
}

Passo 3: Criando nossa resource

Vamos agora criar nossa resource de User, para isso utilizamos o seguinte comando:

php artisan make:filament-resource User --view --generate

// onde --view gera uma página de visualização e
// -- generate gerará nosso formulário e tabela automaticamente

Com isso, será criada sua resource em àpp/Filament/Resources já com seus campos e sua tabela gerada. Você perceberá também que nossos campos de endereço não estão nessa Resource, pois ele faz parte de outro Model e sendo assim "como vamos adicionar os campos de endereço na resource de User, se eles pertencem a outro Model?" Vamos lá, lembram da nossa relação? Então, vamos fazer o seguinte:

Podemos chamar nossa relação para dentro de um Fieldset através da flag ->relationship() como mostrado no exemplo de layout abaixo:


<?php

namespace App\Filament\Resources;

use App\Filament\Resources\UserResource\Pages;
use App\Models\User;
use Exception;
use Filament\Forms;
use Filament\Forms\Components\Actions\Action;
use Filament\Forms\Components\Fieldset;
use Filament\Forms\Form;
use Filament\Forms\Set;
use Filament\Notifications\Notification;
use Filament\Resources\Resource;
use Filament\Tables;
use Filament\Tables\Table;
use Illuminate\Support\Facades\Http;

class UserResource extends Resource
{
    protected static ?string $model = User::class;
    protected static ?string $navigationIcon = 'heroicon-o-users';

    public static function form(Form $form): Form
    {
        return $form
        ->schema([
            Forms\Components\TextInput::make('name')
                ->required()
                ->maxLength(255),
            Forms\Components\TextInput::make('email')
                ->email()
                ->required()
                ->maxLength(255),
            Forms\Components\DateTimePicker::make('email_verified_at'),
            Forms\Components\TextInput::make('password')
                ->password()
                ->required()
                ->maxLength(255),
            Fieldset::make('address')->label('Address')
                ->relationship('addresses') // chamando nosso relacionamento
                ->schema([
                    Forms\Components\TextInput::make('postal_code')
                        ->maxLength(255),
                    Forms\Components\TextInput::make('address')
                        ->maxLength(255),
                    Forms\Components\TextInput::make('number')
                        ->maxLength(255),
                    Forms\Components\TextInput::make('complement')
                        ->maxLength(255),
                    Forms\Components\TextInput::make('neighborhood')
                        ->maxLength(255),
                    Forms\Components\TextInput::make('city')
                        ->maxLength(255),
                    Forms\Components\TextInput::make('uf')
                        ->maxLength(255),
            ]),
        ]);
    }



    public static function table(Table $table): Table
    {
        return $table
            ->columns([
                Tables\Columns\TextColumn::make('name')
                    ->searchable(),
                Tables\Columns\TextColumn::make('email')
                    ->searchable(),
                Tables\Columns\TextColumn::make('email_verified_at')
                    ->dateTime()
                    ->sortable(),
                Tables\Columns\TextColumn::make('created_at')
                    ->dateTime()
                    ->sortable()
                    ->toggleable(isToggledHiddenByDefault: true),
                Tables\Columns\TextColumn::make('updated_at')
                    ->dateTime()
                    ->sortable()
                    ->toggleable(isToggledHiddenByDefault: true),
            ])
            ->filters([
                //
            ])
            ->actions([
                Tables\Actions\ViewAction::make(),
                Tables\Actions\EditAction::make(),
            ])
            ->bulkActions([
                Tables\Actions\BulkActionGroup::make([
                    Tables\Actions\DeleteBulkAction::make(),
                ]),
            ]);
    }

// restante o código da resource...

}

O Fieldset não é o único componente de layout que aceita relações, em Managing relationships você pode ver os campos/componentes e os tipos de relações que são compatíveis com eles.

Você pode organizar esses campos e a sua tabela da maneira como preferir, dentro da documentação na aba de Layout (Layout de Formulário, Layout de Tabela), você encontra componentes e exemplos que você pode usar para organizar seus dados.

Passo 4: Adicionando funcionalidade de autopreenchimento com API

Enfim, vamos adicionar nossa funcionalidade, para isso vamos utilizar a flag ->suffixAction no nosso campo de CEP (postal_code), ela adicionará um botão no final do nosso campo que ao clicar disparará a ação que definirmos dentro dela:

Forms\Components\TextInput::make('postal_code')->mask('99999-999')
    ->suffixAction(
        Action::make('search')
            ->icon('heroicon-o-magnifying-glass')
            ->action()
    )
    ->maxLength(255),

Você pode escolher outro ícone pra sua Action no site Heroicons, lá você encontra todos os ícones suportados pelo Filament

E também usamos o método ->mask() para fazer a máscara do nosso CEP, a máscara já respeitará o uso de somente números no campo.

Ela ficará visualmente da seguinte forma:

Agora, dentro da nossa Action, dentro da flag ->action() vamos criar nossa função. Então, como parâmetros da nossa função vamos usar uma variável Set $set (para setar valores nos outros campos) e uma variável $state (usada no Filament para pegar o valor atual do campo).

Assim, a primeira coisa que vamos fazer é verificar se o valor atual do nosso campo está em branco e se estiver retornar uma mensagem para o usuário. No exemplo abaixo, estamos retornando uma notificação usando o Notification do Filament:

Forms\Components\TextInput::make('postal_code')->mask('99999-999')
    ->suffixAction(
        Action::make('search')
            ->icon('heroicon-o-magnifying-glass')
            ->action(function(Set $set, $state){
                if (blank($state)) {
                    Notification::make()
                        ->title('Postal Code is required')
                        ->danger()->send();
                        return;
                }
            })
    )
    ->maxLength(255),

Agora, dentro de um bloco try catch, podemos fazer nossa requisição. Dentro do try vamos adicionar uma variável $cepData que vai receber os dados que vierem da nossa requisição e dentro da URL da nossa requisição adicionamos nossa variável $state no endpoint para fazer a busca na API a partir do valor digitado no campo.

E dentro do catch fazemos nossa notificação ao usuário caso nossa requisição retorne algum erro.

Forms\Components\TextInput::make('postal_code')->mask('99999-999')
    ->suffixAction(
        Action::make('search')
            ->icon('heroicon-o-magnifying-glass')
            ->action(function(Set $set, $state){
                if (blank($state)) {
                    Notification::make()
                        ->title('Postal Code is required')
                        ->danger()->send();
                        return;
                }
                try {
                    $cepData = 
                        Http::get("https://viacep.com.br/ws/{$state}/json")
                        ->throw()->json();

                } catch (Exception $e) {
                    Notification::make()
                        ->title('Postal Code not found')
                        ->danger()->send();
                }
            })
    )
    ->maxLength(255),

Mas temos um detalhe, na API do ViaCep, ao enviarmos um CEP e ele não for encontrado ela irá retornar um array com uma chave de erro e não uma Exception (mostrado na imagem abaixo) e então não cairá no nosso bloco catch e o usuário não será notificado.

Para resolver isso, temos que forçar uma Exception para que nosso bloco catch "agarre" este erro e a notificação ao usuário seja enviada, fazemos isso da seguinte forma:

Forms\Components\TextInput::make('postal_code')->mask('99999-999')
    ->suffixAction(
        Action::make('search')
            ->icon('heroicon-o-magnifying-glass')
            ->action(function(Set $set, $state){
                if (blank($state)) {
                    Notification::make()
                        ->title('Postal Code is required')
                        ->danger()->send();
                        return;
                }
                try {
                    $cepData = 
                        Http::get("https://viacep.com.br/ws/{$state}/json")
                        ->throw()->json();

                    // forçando a Exception
                    if (in_array('erro', $cepData)) {
                        throw new Exception('Postal Code not found');
                    }

                } catch (Exception $e) {
                    Notification::make()
                        ->title('Postal Code not found')
                        ->danger()->send();
                }
            })
    )
    ->maxLength(255),

Agora, considerando que nossa variável $cepData, recebeu nossos dados da requisição, utilizamos a nossa variável $set para setar os valores que vieram da nossa requisição nos outros campos ou null caso não venha nada:

Forms\Components\TextInput::make('postal_code')->mask('99999-999')
    ->suffixAction(
        Action::make('search')
            ->icon('heroicon-o-magnifying-glass')
            ->action(function(Set $set, $state){
                if (blank($state)) {
                    Notification::make()
                        ->title('Postal Code is required')
                        ->danger()->send();
                        return;
                }
                try {
                    $cepData = 
                        Http::get("https://viacep.com.br/ws/{$state}/json")
                        ->throw()->json();

                    // forçando a Exception
                    if (in_array('erro', $cepData)) {
                        throw new Exception('Postal Code not found');
                    }

                } catch (Exception $e) {
                    Notification::make()
                        ->title('Postal Code not found')
                        ->danger()->send();
                }

                $set('address', $cepData['logradouro'] ?? null);
                $set('neighborhood', $cepData['bairro'] ?? null);
                $set('city', $cepData['localidade'] ?? null);
                $set('uf', $cepData['uf'] ?? null);
            })
    )
    ->maxLength(255),

Pronto! Agora nosso autopreenchimento já está funcionando. Abaixo mostro uma demonstração da nossa funcionalidade em ação.

Conclusão

Agora que você já aprendeu como fazer o autopreenchimento, pode usar isso nos seus projetos e tornar seus formulários menos cansativos de preencher e mais dinâmicos. Esta funcionalidade é até mesmo uma forma de facilitar a vida do usuário e reduzir erros de escrita na hora de preencher o formulário.
Abaixo vou estar disponibilizando o link do repositório do nosso exemplo, sinta-se livre para brincar como quiser. Espero que você tenha gostado e qualquer dúvida estou a disposição ^^
Até a próxima !!

Referências

Obrigada @clintonrocha98 mais uma vez pelos feedbacks! 💜

The power of FilamentPHP - EN

Adryanne Kelly — Mon, 25 Mar 2024 17:52:49 +0000

In this article, I'm going to introduce you to a powerful and incredibly easy-to-use tool and how it can make your web development much faster and more efficient with just a few commands. With it, you can create your complete project, with a beautiful and intuitive interface in very little time. Shall we go?

Topics

What is FilamentPHP?
What are the advantages of using FilamentPHP?
What do I need to use FilamentPHP?
Installing Filament
Demonstration of using FilamentPHP in practice
Conclusion
References

What is FilamentPHP?

FilamentPHP is a full-stack web development tool, also called TALLKit, as it brings together the 4 knights of TALLStack (Tailwind, Alpine.js, Laravel, Livewire).

With rich and clear documentation, using Filament's features holds no secrets, you can implement each of them in your project without much effort, thus being a great productivity ally, all this with a beautiful and intuitive interface that you can shape however you prefer.

In the current version (v3.2) Filament provide 8 modules available for use that are: PanelBuilder, Form Builder, Table Builder, Notifications, Actions, Widgets, Infolist Builder and Core Concepts. Each of them sustaining different needs of your application.

What are the advantages of using FilamentPHP?

Ease of use: With FilamentPHP several lines get simplified into a single one. You can easily implement features like filters and search fields in seconds. Just one command can assemble a ready to use form available for customization of your business logic.

Decoupling: Filament modules can also be used independently, without an need to install your entire ecosystem. So, if you want to use just the Form Builder or the Table Builder, you can install them without having to install everything else.

Productivity: With the various facilities that this tool offers, your development becomes much faster. A function that would typically take you hours to complete can now be done in just minutes.

Customizable: No boundaries here. Even if the focus here is on Filament being in manageable panels, we can also use it to create websites for example. With it we are free to use our imagination.

Open-source: That's right, on GitHub you can clone the Filament repository and add your contribution, in the project's readme you will find instructions on how to run the project on your device.

Free: We can't forget the best of all, right? The FilamentPHP is completely free

What do I need to use FilamentPHP?

To use FilamentPHP you need to meet the following requirements:

PHP 8.1+
Laravel v10.0+
Livewire v3.0+

These requirements refer to FilamentPHP v3.2, you can see the requirements for other versions by visiting the Installation tab within documentation. It's recommended to use the most current version, as it came with many more features than the previous ones and in even more simplified way. However, if you choose a lower version, be aware that some features may not be present or the way they are implemented has changed.

For development in FilamentPHP, it is very important that you have a good understanding of PHP + Laravel, as this way, in addition to making better use of the tool, by understanding this, you can decouple the functionalities more easily, thus enjoying all the advantages of using it.

Installing Filament

To install FilamentPHP, within your Laravel project, run the following command:

composer require filament/filament:"^3.2" -W

After that, run the following command. This will install the Panel:

php artisan filament:install --panels

And finally, to create your panel user, use the command:

php artisan make:filament-user

And that's it, now you can access your Filament panel, just run php artisan serve and access the URL localhost:8000/admin and log in with the email and password of the user you created.

Demonstration of using FilamentPHP in practice

In the video above, I demonstrate the creation of a resource using Filament. The Filament resource already comes with the complete and functional CRUD, with its form and tables already assembled.

To create this resource we can follow the following steps:

Firstly, before creating the resource, you will only need 3 things:

Your table in your Laravel project database must be created.
In your Model, the $fillable variable must contain all the fields in your table.
And obviously, have FilamentPHP installed in your project. (Step by step in the previous topic)

You can easily do this as follows:

Use the command below with the name of the model model you want (in this case, my models's name is Product) with the -m tag so that the migration is already be created together:

php artisan make:model Product -m

In the migration you just created, place the fields you want to add to your table, it should look something like this:

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    /**
    * Run the migrations.
    */
    public function up(): void 
    {
        Schema::create('products', function (Blueprint $table) {
            $table->id();
            $table->string('name');
            $table->longText('description');
            $table->decimal('price', 8, 2);
            $table->timestamps();
        });
    }

    /**
    * Reverse the migrations.
    */
    public function down(): void 
    {
        Schema::dropIfExists('products');
    }
};

After adding your fields, run php artisan migrate to create the table in your database.

After creating the table, declare the fields of your table in the variable $fillable within your Model as in the example below:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class Product extends Model
{
    use HasFactory;

    protected $fillable = [
        'name',
        'description',
        'price',

    ];
}

And that's it, now just run for the hug! To create your resource, you will only need the following command (where Product is the name of your model):

php artisan make:filament-resource Product --generate --view

// The --generate flag will generate your form
// The --view flag will create the view page
// You can also use the --simple flag so that your resource is based on modals, this is all explained clearly in the documentation

Conclusion

You can get a taste of FilamentPHP's features by visiting demo, it shows in a pratical way an example of how the components can be used and organized on screen in your project. Filament also has a community on Discord that is always ready to help you and answer your questions.

Furthermore, legend has it that version 4 comes later this year with even more new features.

"Oh, but you are advertising the tool", I think what is good needs to be shown, right?
So, let's go to Filament?

References

Thank you very much to @cherryramatis and @clintonrocha98 for all your help with this article, you are awesome 💜🩷

O poder do FilamentPHP

Adryanne Kelly — Tue, 06 Feb 2024 22:21:59 +0000

Neste artigo vou apresentar uma ferramenta poderosa, incrivelmente fácil de usar e como ela pode deixar seu desenvolvimento web muito mais rápido e eficiente com apenas alguns comandos. Com ela, você consegue montar seu projeto completo, com uma interface linda e intuitiva dentro de pouquíssimo tempo. Vamos lá?

Tópicos

O que é o FilamentPHP?
Quais as vantagens de usar FilamentPHP?
O que preciso para usar FilamentPHP?
Instalando o Filament
Demonstração de uso do FilamentPHP na prática
Conclusão
Referências

O que é o FilamentPHP?

O FilamentPHP é uma ferramenta para desenvolvimento web full-stack, também chamada de TALLkit, pois reúne os 4 cavaleiros da TALLStack (Tailwind, Alpine.js, Laravel, Livewire).

Com uma documentação rica e clara, usar os recursos do Filament não tem nenhum segredo, você consegue implementar cada um deles no seu projeto sem muito esforço, sendo assim, um grande aliado da produtividade, tudo isso com uma interface bonita e intuitiva que você pode moldar da forma como preferir.

O Filament na versão atual (v3.2) conta com 8 módulos pra você usar, são eles: Panel Builder, Form Builder, Table Builder, Notifications, Actions, Widgets, Infolist Builder e Core Concepts, cada um deles com suas respectivas funcionalidades.

Quais as vantagens de usar FilamentPHP?

Facilidade: Usando o FilamentPHP você vê várias linhas de código se tornarem uma só. Você consegue implementar facilmente recursos como filtros e campos de buscas em segundos. Basta um comando e o Filament consegue montar seu formulário prontinho só pra você moldar como quiser.

Desacoplamento: Os módulos do Filament também podem ser utilizados de forma independente, sem a necessidade da instalação de todo seu ecossistema. Então, se você quiser usar só o Form Builder ou o Table Builder, você pode instalá-los sem precisar instalar todo o restante.

Produtividade: Com as várias facilidades que essa ferramenta oferece, o seu desenvolvimento fica muito mais rápido, uma função que você normalmente demoraria umas horas pra fazer pode durar apenas minutos.

Customizável: Afinal, quem tem limite é estado, não é mesmo? Apesar de o foco do Filament ser em painéis administrativos, você pode utilizá-lo também para criar sites por exemplo, com ele você é livre pra usar sua imaginação.

Open-source: Isso mesmo, lá no Github você pode clonar o repositório do Filament e adicionar sua contribuição. No próprio readme do projeto você encontra orientações de como rodar o projeto na sua máquina.

Gratuito: Não podemos esquecer o melhor de tudo né? O FilamentPHP é totalmente gratuito.

O que preciso para usar FilamentPHP?

Para usar FilamentPHP você precisa ter os seguintes requisitos :

PHP 8.1+
Laravel v10.0+
Livewire v3.0+

Esses requisitos valem para o FilamentPHP v3.2, você pode ver os requisitos para as outras versões visitando a aba de Instalação lá dentro da documentação. É recomendado o uso da versão mais atual, pois ela veio com muito mais recursos que as anteriores e de forma ainda mais simplificada, porém, se você optar por uma versão mais baixa, saiba que alguns recursos podem não estar presentes ou mudaram a forma de implementação.

Para o desenvolvimento em Filament, é muito importante que você tenha uma boa noção de PHP + Laravel, pois assim além de a ferramenta ser melhor aproveitada, entendendo isso, você pode desacoplar as funcionalidades com mais facilidade, assim usufruindo de todas as vantagens de utilizá-lo.

Instalando o Filament

Para instalar o FilamentPHP, dentro do seu projeto Laravel rode o seguinte comando:

composer require filament/filament:"^3.2" -W

Depois disso, rode o comando a seguir. Este vai instalar o Painel:

php artisan filament:install --panels

E por último, para criar seu usuário do painel, utilize o comando:

php artisan make:filament-user

E pronto, agora você já pode acessar seu painel Filament, basta rodar um php artisan serve e acessar a URL localhost:8000/admin e logar com o e-mail e senha do usuário que você criou.

Demonstração de uso do FilamentPHP na prática

No vídeo acima, eu demonstro a criação de uma resource utilizando Filament. A resource já vem com o CRUD completo e funcional, com seu formulário e sua tabela já montados.

Para criar essa resource eu sigo os seguintes passos:

Primeiro, antes de criar a resource você precisará somente de 3 coisas

A sua tabela no banco de dados do seu projeto Laravel deve estar criada.
No seu Model, a sua variavel $fillable deve conter todos os campos existentes na sua tabela.
E obviamente, ter o FilamentPHP instalado no seu projeto. (Passo a passo no tópico anterior).

Você pode facilmente fazer isso da seguinte forma:

Use o comando abaixo com o nome do Model que você desejar (no caso o nome do meu Model é Product) com a flag -m para que a migration já seja criada junto:

php artisan make:model Product -m

Na Migration que você acabou de criar, coloque os campos que você desejar adicionar na sua tabela, ela deve ficar mais ou menos assim:

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    /**
    * Run the migrations.
    */
    public function up(): void 
    {
        Schema::create('products', function (Blueprint $table) {
            $table->id();
            $table->string('name');
            $table->longText('description');
            $table->decimal('price', 8, 2);
            $table->timestamps();
        });
    }

    /**
    * Reverse the migrations.
    */
    public function down(): void 
    {
        Schema::dropIfExists('products');
    }
};

Depois de adicionar seus campos, rode um php artisan migrate para que seja criada a tabela no seu banco de dados.

Após criada a tabela, declare os campos da sua tabela na variável $fillable dentro do seu Model como no exemplo abaixo:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class Product extends Model
{
    use HasFactory;

    protected $fillable = [
        'name',
        'description',
        'price',

    ];
}

E pronto, agora é só correr pro abraço! Para criar sua resource, você só vai precisar do seguinte comando (onde Product é o nome do seu Model):

php artisan make:filament-resource Product --generate --view

// A flag --generate vai gerar seu formulário
// A flag --view vai criar a página de visualização
// Você pode ainda utilizar a flag --simple para que sua 
// resource seja baseada em modais, isso tudo ta explicado 
// direitinho na documentação

Conclusão

Você pode ter um gostinho das funcionalidades do FilamentPHP visitando a demo, lá mostra de forma prática um exemplo de como os componentes podem ser utilizados e organizados em tela no seu projeto. O Filament também tem uma comunidade no Discord que está sempre pronta pra te ajudar e tirar suas dúvidas.

Além disso, reza a lenda que a versão 4 vem ainda esse ano com ainda mais novidades.

"Ah mas você ta fazendo propaganda do negócio", acho que o que é bom tem ser mostrado né pessoal.
Eai, vamos pro Filament?

Referências

Meus agradecimentos a @cherryramatis,@clintonrocha98 e @redrodrigoc pelas dicas e sugestões para este artigo, vocês são demais 💜