Hay cuatro aspectos diferentes de las enumeraciones en TypeScript que debe conocer. Primero, algunas definiciones:
"objeto de búsqueda"
Si escribe esta enumeración:
enum Foo { X, Y }
TypeScript emitirá el siguiente objeto:
var Foo;
(function (Foo) {
Foo[Foo["X"] = 0] = "X";
Foo[Foo["Y"] = 1] = "Y";
})(Foo || (Foo = {}));
Me referiré a esto como el objeto de búsqueda . Su propósito es doble: servir como un mapeo de cadenas a números , por ejemplo, al escribir Foo.Xo Foo['X'], y servir como un mapeo de números a cadenas . Ese mapeo inverso es útil para fines de depuración o registro; a menudo tendrá el valor 0o 1y querrá obtener la cadena correspondiente "X"o "Y".
"declarar" o " ambiente "
En TypeScript, puede "declarar" cosas que el compilador debería conocer, pero no emitir código. Esto es útil cuando tiene bibliotecas como jQuery que definen algún objeto (por ejemplo $) sobre el que desea escribir información, pero no necesita ningún código creado por el compilador. La especificación y otra documentación se refiere a declaraciones hechas de esta manera como en un contexto "ambiental"; Es importante tener en cuenta que todas las declaraciones de un .d.tsarchivo son "ambientales" (ya sea que requieran un declaremodificador explícito o lo tengan implícito, según el tipo de declaración).
"alineado"
Por razones de rendimiento y tamaño del código, a menudo es preferible tener una referencia a un miembro enum reemplazado por su equivalente numérico cuando se compila:
enum Foo { X = 4 }
var y = Foo.X; // emits "var y = 4";
La especificación llama a esta sustitución , yo la llamaré inlining porque suena mejor. A veces se quiere no querrá que los miembros de enumeración estén incluidos, por ejemplo, porque el valor de enumeración podría cambiar en una versión futura de la API.
Enums, ¿cómo funcionan?
Analicemos esto por cada aspecto de una enumeración. Desafortunadamente, cada una de estas cuatro secciones hará referencia a términos de todas las demás, por lo que probablemente necesitará leer todo esto más de una vez.
calculado vs no calculado (constante)
Los miembros de enumeración pueden calcularse o no. La especificación llama constantes a los miembros no calculados , pero los llamaré no calculados para evitar confusiones con const .
Un miembro de enumeración calculado es aquel cuyo valor no se conoce en tiempo de compilación. Las referencias a los miembros calculados no se pueden insertar, por supuesto. Por el contrario, un miembro de enumeración no calculado es una vez cuyo valor se conoce en tiempo de compilación. Las referencias a miembros no calculados siempre están alineadas.
¿Qué miembros de enumeración se calculan y cuáles no? Primero, todos los miembros de una constenumeración son constantes (es decir, no calculados), como su nombre lo indica. Para una enumeración no constante, depende de si estás mirando un ambiente enumeración (declarar) o una enumeración no ambiental.
Un miembro de a declare enum(es decir, ambiente enum) es constante si y solo si tiene un inicializador. De lo contrario, se calcula. Tenga en cuenta que en a declare enum, solo se permiten inicializadores numéricos. Ejemplo:
declare enum Foo {
X, // Computed
Y = 2, // Non-computed
Z, // Computed! Not 3! Careful!
Q = 1 + 1 // Error
}
Por último, los miembros de enumeraciones no constantes no declaradas siempre se consideran calculadas. Sin embargo, sus expresiones de inicialización se reducen a constantes si son computables en tiempo de compilación. Esto significa que los miembros de enumeración que no son constantes nunca están alineados (este comportamiento cambió en TypeScript 1.5, consulte "Cambios en TypeScript" en la parte inferior)
const vs no const
constante
Una declaración de enumeración puede tener el constmodificador. Si una enumeración es const, todas las referencias a sus miembros en línea.
const enum Foo { A = 4 }
var x = Foo.A; // emitted as "var x = 4;", always
las enumeraciones const no producen un objeto de búsqueda cuando se compilan. Por esta razón, es un error hacer referencia Fooen el código anterior, excepto como parte de una referencia de miembro. Ningún Fooobjeto estará presente en tiempo de ejecución.
no constante
Si una declaración de enumeración no tiene el constmodificador, las referencias a sus miembros están en línea solo si el miembro no está calculado. Una enumeración no constante y no declarada producirá un objeto de búsqueda.
declarar (ambiente) vs no declarar
Un prefacio importante es que declareen TypeScript tiene un significado muy específico: este objeto existe en otro lugar . Es para describir objetos existentes . Usar declarepara definir objetos que en realidad no existen puede tener malas consecuencias; los exploraremos más tarde.
declarar
A declare enumno emitirá un objeto de búsqueda. Las referencias a sus miembros están en línea si esos miembros se calculan (consulte más arriba sobre calculados frente a no calculados).
Es importante señalar que otras formas de referencia a un declare enum están permitidos, por ejemplo, este código es no un error de compilación, pero se fallará en tiempo de ejecución:
// Note: Assume no other file has actually created a Foo var at runtime
declare enum Foo { Bar }
var s = 'Bar';
var b = Foo[s]; // Fails
Este error se incluye en la categoría de "No mientas al compilador". Si no tiene un objeto nombrado Fooen tiempo de ejecución, ¡no escriba declare enum Foo!
A declare const enumno es diferente de a const enum, excepto en el caso de --preserveConstEnums (ver más abajo).
no declarar
Una enumeración no declarada produce un objeto de búsqueda si no lo es const. Inlining se describe arriba.
--preserveConstEnums bandera
Esta bandera tiene exactamente un efecto: las enumeraciones const no declaradas emitirán un objeto de búsqueda. Inlining no se ve afectado. Esto es útil para depurar.
Errores comunes
El error más común es usar a declare enumcuando sería más apropiado enumo regular const enum. Una forma común es esta:
module MyModule {
// Claiming this enum exists with 'declare', but it doesn't...
export declare enum Lies {
Foo = 0,
Bar = 1
}
var x = Lies.Foo; // Depend on inlining
}
module SomeOtherCode {
// x ends up as 'undefined' at runtime
import x = MyModule.Lies;
// Try to use lookup object, which ought to exist
// runtime error, canot read property 0 of undefined
console.log(x[x.Foo]);
}
Recuerda la regla de oro: nunca declarecosas que en realidad no existen . Úselo const enumsi siempre desea alinear o enumsi desea el objeto de búsqueda.
Cambios en TypeScript
Entre TypeScript 1.4 y 1.5, hubo un cambio en el comportamiento (ver https://github.com/Microsoft/TypeScript/issues/2183 ) para hacer que todos los miembros de enumeraciones no constantes no declaradas se traten como computados, incluso si se inicializan explícitamente con un literal. Esto "deshace al bebé", por así decirlo, hace que el comportamiento de alineación sea más predecible y separa más claramente el concepto de const enumregular enum. Antes de este cambio, los miembros no calculados de enumeraciones no constantes se insertaron de forma más agresiva.