Librerías e imports

Las directivas import y library pueden ayudarte a crear una base de código modular y compartible. Las bibliotecas no solo proporcionan APIs, sino que también son una unidad de privacidad: los identificadores que comienzan con un guion bajo (_) son visibles solo dentro de la biblioteca. Cada archivo Dart (junto con sus partes) es una bibliotecaBibliotecaUna única unidad de compilación en Dart, compuesta por un archivo Dart principal y sus partes. Más información, incluso si no usa una directiva library.

Las bibliotecas se pueden distribuir utilizando paquetes.

Dart utiliza guiones bajos en lugar de palabras clave de modificación de acceso como public, protected o private. Aunque las palabras clave de modificación de acceso de otros lenguajes ofrecen un control más detallado, el uso de guiones bajos en Dart y la privacidad basada en bibliotecas proporcionan un mecanismo de configuración sencillo, ayudan a habilitar una implementación eficiente del acceso dinámico y mejoran el tree shaking (eliminación de código muerto).

Usa import para especificar cómo se utiliza un espacio de nombres de una biblioteca en el ámbito de otra biblioteca.

Por ejemplo, las aplicaciones web de Dart generalmente usan la biblioteca dart:js_interop , la cual pueden importar así:

import 'dart:js_interop';

El único argumento requerido para import es un URI que especifica la biblioteca. Para las bibliotecas incorporadas, el URI tiene el esquema especial dart:. Para otras bibliotecas, puedes usar una ruta del sistema de archivos o el esquema package: . El esquema package: especifica bibliotecas proporcionadas por un gestor de paquetes como la herramienta pub. Por ejemplo:

import 'package:test/test.dart';

Si importas dos bibliotecas que tienen identificadores en conflicto, puedes especificar un prefijo para una o ambas bibliotecas. Por ejemplo, si library1 y library2 tienen ambas una clase Element, podrías tener un código como este:

import 'package:lib1/lib1.dart';
import 'package:lib2/lib2.dart' as lib2;
​
// Uses Element from lib1.
Element element1 = Element();
​
// Uses Element from lib2.
lib2.Element element2 = lib2.Element();

Los prefijos de importación con el nombre de comodín (wildcard) _ no son vinculantes, pero proporcionarán acceso a las extensiones no privadas en esa biblioteca.

Si deseas utilizar solo una parte de una biblioteca, puedes importar selectivamente la biblioteca. Por ejemplo:

// Import only foo.
import 'package:lib1/lib1.dart' show foo;
​
// Import all names EXCEPT foo.
import 'package:lib2/lib2.dart' hide foo;

La carga diferida (Deferred loading) (también llamada carga perezosa (lazy loading)) permite que una aplicación web cargue una biblioteca bajo demanda, si y cuando la biblioteca sea necesaria. Usa la carga diferida cuando desees cubrir una o más de las siguientes necesidades.

• Reducir el tiempo de inicio inicial de una aplicación web.
• Realizar pruebas A/B; por ejemplo, probar implementaciones alternativas de un algoritmo.
• Cargar funcionalidad poco utilizada, como pantallas y diálogos opcionales.

Eso no significa que Dart cargue todos los componentes diferidos al momento de inicio. La aplicación web puede descargar los componentes diferidos a través de la web cuando sea necesario.

La herramienta dart no admite la carga diferida para objetivos que no sean la web. Si estás desarrollando una aplicación de Flutter, consulta su implementación de carga diferida en la guía de Flutter sobre componentes diferidos (deferred components).

Para cargar una biblioteca de forma perezosa, primero impórtala usando deferred as.

import 'package:greetings/hello.dart' deferred as hello;

Cuando necesites la biblioteca, invoca loadLibrary() usando el identificador de la biblioteca.

Future<void> greet() async {
  await hello.loadLibrary();
  hello.printGreeting();
}

En el código anterior, la palabra clave await pausa la ejecución hasta que se carga la biblioteca. Para obtener más información sobre async y await, consulta la programación asíncrona.

Puedes invocar loadLibrary() varias veces en una biblioteca sin problemas. La biblioteca se carga solo una vez.

Ten en cuenta lo siguiente al utilizar la carga diferida (deferred loading):

• Las constantes de una biblioteca diferida no son constantes en el archivo que la importa. Recuerda que estas constantes no existen hasta que se carga la biblioteca diferida.
• No puedes usar tipos de una biblioteca diferida en el archivo que la importa. En su lugar, considera mover los tipos de interfaz a una biblioteca importada tanto por la biblioteca diferida como por el archivo importador.
• Dart inserta implícitamente loadLibrary() en el espacio de nombres que defines usando deferred as namespace. La función loadLibrary() devuelve un Future.

Para especificar comentarios de documentación (doc comments) a nivel de biblioteca o anotaciones de metadatos, adjúntalos a una declaración library al principio del archivo.

/// A really great test library.
@TestOn('browser')
library;

Consulta Crear paquetes (Create Packages) para obtener consejos sobre cómo implementar un paquete, incluyendo:

• Cómo organizar el código fuente de la biblioteca.
• Cómo usar la directiva export.
• Cuándo usar la directiva part.
• Cómo usar importaciones y exportaciones condicionales para implementar una biblioteca que admita múltiples plataformas.