Libraries - Dart Tutorial

Cada archivo Dart es una biblioteca por naturaleza, incluso sin escribir la directiva library;

Regla de privacidad: Los identificadores que empiezan por guion bajo _ son privados de la biblioteca, solo visibles dentro de la misma biblioteca, inaccesibles entre archivos/bibliotecas distintas;

No existen las palabras clave public/protected/private; los permisos de acceso se distinguen únicamente mediante el guion bajo;

Las bibliotecas se pueden empaquetar como package y gestionarse mediante pub;

Ventaja: Facilita el Tree Shaking (podado de árbol), que elimina el código muerto sin usar.

import

Se usa la palabra clave import para importar otras bibliotecas.

import sirve para introducir las API de otras bibliotecas

Hay tres tipos de URI:

dart:xxx: Bibliotecas estándar integradas de Dart (dart:core, dart:async, dart:js_interop)
package:xxx: Bibliotecas de terceros gestionadas por pub
Rutas de archivo relativas: Archivos .dart personalizados locales

// Bibliotecas estándar integradas
import 'dart:js_interop';
import 'dart:math';

// Paquetes de terceros
import 'package:test/test.dart';

// Biblioteca de archivo local
import './utils.dart';Lenguaje del código: JavaScript (javascript)

Alias de biblioteca

Cuando dos bibliotecas tienen clases/funciones con el mismo nombre, usa as alias para separarlas y evitar conflictos.

Ejemplo

En el archivo lib1.dart

class Element {}Lenguaje del código: JavaScript (javascript)

lib2.dart tiene la misma clase

class Element {}Lenguaje del código: JavaScript (javascript)

Archivo principal main.dart

// Importación directa, espacio de nombres por defecto
import 'lib1.dart';
// Asignar alias lib2
import 'lib2.dart' as lib2;

void main() {
  Element e1 = Element(); // Element de lib1
  lib2.Element e2 = lib2.Element(); // Element de lib2
}Lenguaje del código: JavaScript (javascript)

Para evitar confusiones, asignamos el alias lib2 a lib2.dart, así que al acceder a sus clases solo hay que añadir el prefijo del alias.

Importación selectiva show / hide

show: Solo importa los nombres indicados, oculta todo lo demás

// Solo importa foo, el resto de variables/clases no están disponibles
import 'lib1.dart' show foo;

void main() {
  foo();
  // bar(); // Error, no se importó mediante show, no accesible
}Lenguaje del código: JavaScript (javascript)

hide: Importa todo, excepto los nombres indicados

// Importa todo, solo oculta foo
import 'lib2.dart' hide foo;

void main() {
  bar();
  // foo(); // Error, ocultado por hide
}Lenguaje del código: JavaScript (javascript)

Carga diferida deferred as

Solo válido para la plataforma Web

Reducir el tamaño de carga inicial de la página web;
Para ventanas emergentes poco frecuentes, pantallas opcionales;
Descargar fragmentos de código dinámicamente bajo demanda.

Sintaxis de importación: import ruta deferred as espacioDeNombres
Llamar a espacioDeNombres.loadLibrary() devuelve un Future, usa await para esperar que termine la carga
Llamar varias veces a loadLibrary() para la misma biblioteca solo la carga una vez
Limitación: Las constantes y tipos dentro de la biblioteca diferida no se pueden usar directamente antes de cargarla

Ejemplo completo

hello.dart (biblioteca diferida)

void printGreeting() {
  print("Hello from deferred library wellcome to foxdevelop.com");
}
Lenguaje del código: JavaScript (javascript)

main.dart

// Importación diferida, alias hello
import 'hello.dart' deferred as hello;

Future&lt;void> greet() async {
  // Cargar la biblioteca dinámicamente
  await hello.loadLibrary();
  // Solo se pueden llamar métodos internos tras finalizar la carga
  hello.printGreeting();
}

void main() async {
  await greet();
}
Lenguaje del código: JavaScript (javascript)

Resultado de ejecución:

Hello from deferred library wellcome to foxdevelop.com
Lenguaje del código: JavaScript (javascript)

Coloca ambos archivos en la misma carpeta

¿Y si hello.dart está en otro directorio, por ejemplo la carpeta lib del nivel superior?

Ejemplo de ruta: D:\dartdemo\firstdart\lib

El archivo main.dart está en D:\dartdemo\firstdart\bin

firstdart/
├─ bin/
│  └─ firstdart.dart       // Punto de entrada del programa
└─ lib/
   └─ hello.dart      // Biblioteca de carga diferidaLenguaje del código: JavaScript (javascript)

Entonces se importa así

// ../ representa el directorio padre
import '../lib/hello.dart' deferred as hello;Lenguaje del código: JavaScript (javascript)

Declaración superior de biblioteca library

Se escribe al principio del archivo, para añadir comentarios de documentación de biblioteca y anotaciones a nivel de biblioteca (por ejemplo, restricciones de plataforma de prueba).

/// Biblioteca de herramientas de prueba exclusiva para navegador
@TestOn('browser')
library;
Lenguaje del código: JavaScript (javascript)

export

Exportar (encapsular API unificada pública)

Muy usado al crear paquetes de herramientas: agrupa varias subbibliotecas y expone un único punto de importación externo.

Estructura de archivos

src/math.dart

int add(int a, int b) => a + b;
int sub(int a, int b) => a - b;
Lenguaje del código: PHP (php)

src/string.dart

String upper(String s) => s.toUpperCase();
Lenguaje del código: JavaScript (javascript)

utils.dart (punto de exportación unificado)

export 'src/math.dart';
export 'src/string.dart';
// Ocultar herramientas internas privadas
export 'src/internal.dart' hide helper;
Lenguaje del código: JavaScript (javascript)

utils.dart no se puede ejecutar solo: es solo un archivo de agrupación de exportaciones, no tiene la función de entrada main(), no se puede ejecutar dart run lib/utils.dart;

Función de export

Agrupar las API de varios subarchivos src;
El usuario solo necesita importar el archivo utils.dart para disponer de todos los métodos expuestos;
hide xxx oculta las herramientas internas, encapsula la implementación interna y controla las API visibles al exterior.

Uso en main.dart

import 'utils.dart';

void main() {
  print(add(1,2));
  print(upper("dart"));
}
Lenguaje del código: JavaScript (javascript)

Nota

export/import solo realizan importación y exportación a nivel de código fuente; si distribuyes archivos .dart fuente, otros podrán ver todo el código fuente;

Para ocultar el código fuente, debes no publicar los archivos fuente .dart, solo distribuir instantáneas binarias compiladas (Snapshot).

Un Snapshot es un archivo binario compilado de Dart; otros no pueden revertirlo para obtener código fuente legible completo, solo pueden llamar a las API expuestas.

Este tema se explica en otros cursos.

part

Dividir una única biblioteca en varios archivos

Separar una misma biblioteca en varios archivos que comparten identificadores privados con guion bajo; es obligatorio emparejar part 'xxx.dart' / part of 'archivo_principal.dart'

main_lib.dart (archivo principal de biblioteca)

library; // Declara que este archivo es una biblioteca
part 'logic.dart'; // Fusionar logic.dart con el archivo actual, ambos pertenecen a la misma biblioteca

int _secret = 999; // Variable privada de biblioteca
Lenguaje del código: JavaScript (javascript)

logic.dart (archivo fragmentado)

part of 'main_lib.dart'; // Declara que este archivo pertenece a la biblioteca main_lib.dart, no es una biblioteca independiente.

void printSecret() {
  // Se puede acceder a _secret del archivo principal, los privados de la misma biblioteca se comparten mutuamente
  print(_secret);
}
Lenguaje del código: JavaScript (javascript)

Llamada

import 'main_lib.dart'; // Importar la biblioteca principal, NO importar los archivos fragmentados

void main() {
  printSecret(); // Muestra 999
}
Lenguaje del código: JavaScript (javascript)

Importaciones condicionales

Cambiar automáticamente los archivos de implementación según la plataforma

import 'platform_stub.dart'
    if (dart.library.io) 'platform_mobile.dart'
    if (dart.library.js_interop) 'platform_web.dart';
Lenguaje del código: JavaScript (javascript)

Previous: metadatos

Next: Clase class