Bibliotecas Libraries

Cada arquivo Dart é uma biblioteca por padrão, mesmo sem escrever a diretiva library;

Regra de privacidade: Identificadores iniciados por sublinhado _ são privados da biblioteca, visíveis apenas dentro da mesma biblioteca, inacessíveis entre arquivos/bibliotecas diferentes;

Não existem as palavras-chave public/protected/private; as permissões de acesso são diferenciadas apenas pelo sublinhado;

Bibliotecas podem ser empacotadas em package e gerenciadas via pub;

Vantagem: Habilita o Tree Shaking para remover código morto não utilizado.

import

Use a palavra-chave import para carregar outras bibliotecas.

import serve para importar APIs de outras bibliotecas

Três tipos de URI:

1. dart:xxx: Bibliotecas padrão nativas do Dart (dart:core, dart:async, dart:js_interop)
2. package:xxx: Bibliotecas de terceiros gerenciadas pelo pub
3. Caminhos relativos de arquivo: Arquivos .dart customizados locais

// Bibliotecas padrão nativas
import 'dart:js_interop';
import 'dart:math';

// Pacotes de terceiros
import 'package:test/test.dart';

// Biblioteca de arquivo local
import './utils.dart';Code language: JavaScript (javascript)

Alias de biblioteca

Quando duas bibliotecas possuem classes/funções com o mesmo nome, use as alias para separar e evitar conflitos de nomes.

Exemplo

No arquivo lib1.dart

class Element {}Code language: JavaScript (javascript)

lib2.dart contém a mesma classe

class Element {}Code language: JavaScript (javascript)

Arquivo principal main.dart

// Importação direta, namespace padrão
import 'lib1.dart';
// Definir alias lib2
import 'lib2.dart' as lib2;

void main() {
  Element e1 = Element(); // Element da lib1
  lib2.Element e2 = lib2.Element(); // Element da lib2
}Code language: JavaScript (javascript)

Para evitar confusões, atribuímos o alias lib2 ao lib2.dart, então ao acessar suas classes basta adicionar o prefixo do alias.

Importação seletiva show / hide

show: Importa apenas os nomes especificados, oculta todo o resto

// Apenas importa foo, outras variáveis/classes ficam indisponíveis
import 'lib1.dart' show foo;

void main() {
  foo();
  // bar(); // Erro, não importado via show, sem acesso
}Code language: JavaScript (javascript)

hide: Importa tudo, exceto os nomes indicados

// Importa tudo, apenas oculta foo
import 'lib2.dart' hide foo;

void main() {
  bar();
  // foo(); // Erro, bloqueado por hide
}Code language: JavaScript (javascript)

Carregamento adiado deferred as

Válido apenas para a plataforma Web

• Reduzir o tamanho do carregamento inicial da página web;
• Para popups de baixa frequência, telas opcionais;
• Baixar fragmentos de código dinamicamente sob demanda.

1. Sintaxe de importação: import caminho deferred as namespace
2. Chamar namespace.loadLibrary() retorna um Future, use await para aguardar o término do carregamento
3. Múltiplas chamadas de loadLibrary() para a mesma biblioteca executam apenas um carregamento
4. Limitação: Constantes e tipos dentro da biblioteca adiada não podem ser usados diretamente antes do carregamento

Exemplo completo

hello.dart (biblioteca de carregamento adiado)

void printGreeting() {
  print("Hello from deferred library wellcome to foxdevelop.com");
}
Code language: JavaScript (javascript)

main.dart

// Importação adiada, alias hello
import 'hello.dart' deferred as hello;

Future<void> greet() async {
  // Carregar biblioteca dinamicamente
  await hello.loadLibrary();
  // Apenas após o carregamento é possível chamar métodos internos
  hello.printGreeting();
}

void main() async {
  await greet();
}
Code language: JavaScript (javascript)

Saída de execução:

Hello from deferred library wellcome to foxdevelop.com
Code language: JavaScript (javascript)

Coloque os dois arquivos na mesma pasta

E se o hello.dart estiver em outro diretório, por exemplo a pasta lib de nível superior?

Exemplo de caminho: D:\dartdemo\firstdart\lib

O main.dart está em D:\dartdemo\firstdart\bin

firstdart/
├─ bin/
│  └─ firstdart.dart       // Ponto de entrada do programa
└─ lib/
   └─ hello.dart      // Biblioteca de carregamento adiadoCode language: JavaScript (javascript)

Nesse caso a importação fica assim

// ../ representa diretório pai
import '../lib/hello.dart' deferred as hello;Code language: JavaScript (javascript)

Declaração superior de biblioteca library

Escrito no topo absoluto do arquivo, usado para comentários de documentação da biblioteca e anotações de nível de biblioteca (ex: restrição de plataforma de teste).

/// Biblioteca de utilitários de teste exclusiva para navegador
@TestOn('browser')
library;
Code language: JavaScript (javascript)

export

Exportar (encapsular API pública unificada)

Muito utilizado no desenvolvimento de pacotes de ferramentas: agrupa várias subbibliotecas e expõe apenas um ponto de importação externo.

Estrutura de arquivos

src/math.dart

int add(int a, int b) => a + b;
int sub(int a, int b) => a - b;
Code language: PHP (php)

src/string.dart

String upper(String s) => s.toUpperCase();
Code language: JavaScript (javascript)

utils.dart (ponto de exportação unificado)

export 'src/math.dart';
export 'src/string.dart';
// Ocultar utilitários internos privados
export 'src/internal.dart' hide helper;
Code language: JavaScript (javascript)

utils.dart não pode ser executado isoladamente: é apenas um arquivo de agrupamento de exportações, não contém a função de entrada main(), não é possível rodar dart run lib/utils.dart;

Função do export

• Agrupar APIs de múltiplos subarquivos src;
• O desenvolvedor precisa importar apenas o arquivo utils.dart para acessar todos os métodos expostos;
• hide xxx oculta utilitários internos, encapsula detalhes de implementação e controla as APIs visíveis externamente.

Uso no main.dart

import 'utils.dart';

void main() {
  print(add(1,2));
  print(upper("dart"));
}
Code language: JavaScript (javascript)

Aviso importante

export/import apenas realizam importação e exportação em nível de código-fonte; distribuir arquivos .dart deixa todo o código fonte visível para terceiros;

Para ocultar o código fonte, você deve não publicar os arquivos .dart originais, apenas distribuir Snapshots binários compilados.

Um Snapshot é um arquivo binário compilado do Dart; não é possível reverter completamente para código fonte legível, apenas chamar as APIs públicas expostas.

Esse conteúdo é explicado em outros módulos do curso.

part

Dividir uma única biblioteca em múltiplos arquivos

Separar uma mesma biblioteca em vários arquivos que compartilham identificadores privados com sublinhado; obrigatório emparelhar part 'xxx.dart' / part of 'arquivo_principal.dart'

main_lib.dart (arquivo principal da biblioteca)

library; // Declara que esse arquivo é uma biblioteca
part 'logic.dart'; // Unir logic.dart ao arquivo atual, ambos pertencem à mesma biblioteca

int _secret = 999; // Variável privada da biblioteca
Code language: JavaScript (javascript)

logic.dart (arquivo fragmentado)

part of 'main_lib.dart'; // Declara que esse arquivo pertence à main_lib.dart, não é uma biblioteca independente.

void printSecret() {
  // Acessa _secret do arquivo principal, variáveis privadas são compartilhadas dentro da mesma biblioteca
  print(_secret);
}
Code language: JavaScript (javascript)

Forma de chamada

import 'main_lib.dart'; // Importar apenas a biblioteca principal, NÃO importar os arquivos fragmentados

void main() {
  printSecret(); // Saída 999
}
Code language: JavaScript (javascript)

Importações condicionais

Trocar automaticamente os arquivos de implementação conforme a plataforma de execução

import 'platform_stub.dart'
    if (dart.library.io) 'platform_mobile.dart'
    if (dart.library.js_interop) 'platform_web.dart';
Code language: JavaScript (javascript)