El repositorio de definiciones de TypeScript de alta calidad.
Vea también el sitio web definitelytyped.org, aunque la información en este README está más actualizada.
Vea el Manual de TypeScript.
Este es el método preferido. Solo está disponible para usuarios TypeScript 2.0+. Por ejemplo:
npm install --save-dev @types/node
Los types deberían ser incluidos automaticamente por el compilador. Vea más en el manual.
Para un paquete NPM "foo", Estos typings
estarán en "@types/foo".
Si no puedes encontrar tu paquete, búscalo en TypeSearch.
Si aún no puedes encontrarlo, comprueba si el paquete ya incluye los typings.
Esto es provisto usualmente en el campo "types"
o "typings"
en el package.json
,
o solo busca por cualquier archivo ".d.ts" en el paquete e incluyelo manualmente con un /// <reference path="" />
.
Estos pueden ser utilizados por TypeScript 1.0.
- Typings
NuGet(use las alternativas preferidas, la publicación DT type de nuget ha sido desactivada)- Descarguelo manualmente desde la
master
branch de este repositorio
Tal vez debas añadir manualmente las referencias.
¡DefinitelyTyped solo trabaja gracias a contribuidores como tú!
Antes de compartir tu mejora con el mundo, úselo usted mismo.
Para agregar nuevas funciones puedes usar el module augmentation.
También puedes editar directamente los types en node_modules/@types/foo/index.d.ts
, o copiarlos de ahí y seguir los pasos explicados a continuación.
Añade a tu tsconfig.json
:
"baseUrl": "types",
"typeRoots": ["types"],
(También puedes usar src/types
.)
Crea un types/foo/index.d.ts
que contenga declaraciones del módulo "foo".
Ahora deberías poder importar desde "foo"
a tu código y te enviara a un nuevo tipo de definición.
Entonces compila y ejecuta el código para asegurarte que el tipo de definición en realidad corresponde a lo que suceda en el momento de la ejecución.
Una vez que hayas probado tus definiciones con el código real, haz un PR
luego sigue las instrucciones para editar un paquete existente o
crear un nuevo paquete.
Una vez que hayas probado tu paquete, podrás compartirlo en DefinitelyTyped.
Primero, haz un fork en este repositorio, instala node, y luego ejecuta la npm install
.
cd types/my-package-to-edit
- Haz cambios. Recuerda editar las pruebas.
- También puede que quieras añadirte la sección "Definitions by" en el encabezado del paquete.
- Esto hará que seas notificado (a través de tu nombre de usuario en GitHub) cada vez que alguien haga un pull request o issue sobre el paquete.
- Haz esto añadiendo tu nombre al final de la línea, así como en
// Definitions by: Alice <https://github.com/alice>, Bob <https://github.com/bob>
. - O si hay más personas, puede ser multiline
// Definitions by: Alice <https://github.com/alice> // Bob <https://github.com/bob> // Steve <https://github.com/steve> // John <https://github.com/john>
- Si hay un
tslint.json
, ejecutanpm run lint package-name
. De lo contrario, ejecutatsc
en el directorio del paquete.
Cuando hagas un PR para editar un paquete existente, dt-bot
deberá @-mencionar a los autores previos.
Si no lo hace, puedes hacerlo en el comentario asociado con el PR.
Si eres el autor de la librería, o puedes hacer un pull request a la biblioteca, bundle types en vez de publicarlo en DefinitelyTyped.
Si estás agregando typings para un paquete NPM, crea un directorio con el mismo nombre.
Si el paquete al que le estás agregando typings no es para NPM, asegurate de que el nombre que escojas no genere problemas con el nombre del paquete en NPM.
(Puedes usar npm info foo
para verificar la existencia del paquete foo
.)
Tu paquete debería tener esta estructura:
Archivo | Propósito |
---|---|
index.d.ts | Este contiene los typings del paquete. |
foo-tests.ts | Este contiene una muestra del código con el que se realiza la prueba de escritura. Este código no es ejecutable, pero sí es type-checked. |
tsconfig.json | Este permite ejecutar tsc dentro del paquete. |
tslint.json | Permite linting. |
Generalas ejecutando npm install -g dts-gen
y dts-gen --dt --name my-package-name --template module
.
Ve todas las opciones en dts-gen.
También puedes configurar el tsconfig.json
para añadir nuevos archivos, para agregar un "target": "es6"
(necesitado por las funciones asíncronas), para agregar a la "lib"
, o para agregar la opción de compilación "jsx"
.
Los miembros de DefinitelyTyped frecuentemente monitorean nuevos PRs, pero ten en mente que la cantidad de PRs podrian ralentizar el proceso.
Para un buen paquete de ejemplo, vea base64-js.
- Primero, sigue el consejo del manual.
- Formatear: Ya sea utilizar todo en tabs, o siempre utiliza 4 espacios.
function sum(nums: number[]): number
: UtilizaReadonlyArray
si una funcion no escribe a sus parámetros.interface Foo { new(): Foo; }
: Este define el tipo de objeto que esten nuevos. Probablemente quierasdeclare class Foo { constructor(); }
.const Class: { new(): IClass; }
: Prefiere usar una declaración de claseclass Class { constructor(); }
En vez de una nueva constante.getMeAT<T>(): T
: Si un tipo de parámetro no aparece en los tipos de ningún parámetro, no tienes una función genérica, solo tienes un afirmación del tipo disfrazado. Prefiera utilizar una afirmación de tipo real, p.ej.getMeAT() as number
. Un ejemplo donde un tipo de parámetro es aceptable:function id<T>(value: T): T;
. Un ejemplo donde no es aceptable:function parseJson<T>(json: string): T;
. Una excepción:new Map<string, number>()
está bien.- Utilizando los tipos
Function
yObject
casi nunca es una buena idea. En 99% de los casos es posible especificar un tipo más especifico. Los ejemplos son(x: number) => number
para funciones y{ x: number, y: number }
para objetos. Si no hay certeza en lo absoluto del tipo,any
es la opción correcta, noObject
. Si el único hecho conocido sobre el tipo es que es un objecto, usa el tipoobject
, noObject
o{ [key: string]: any }
. var foo: string | any
: Cuando es usadoany
en un tipo de unión, el tipo resultante todavía esany
. Así que mientras la porciónstring
de este tipo de anotación puede verse útil, de hecho, no ofrece ningún typechecking adicional más que un simpleany
. Dependiendo de la intención, una alternativa aceptable puede serany
,string
, ostring | object
.
Cuando un paquete bundles sus propios tipos, estos tipos deberán ser removidos de DefinitelyTyped para evitar que generen confusión.
Se puede remover ejecutando npm run not-needed -- typingsPackageName asOfVersion sourceRepoURL [libraryName]
.
typingsPackageName
: Este es el nombre del directorio que tienes que eliminar.asOfVersion
: Un stub será publicado a@types/foo
con esta versión. Debería ser más grande que cualquier versión publicada actualmente.sourceRepoURL
: Esto debería señalar el repositorio que contiene los typings.libraryName
: Un nombre descriptivo de la librería, p.ej. "Angular 2" en vez de "angular2". (Si es omitido, será idéntico a "typingsPackageName".)
Cualquier otro paquete en DefinitelyTyped que referencie el paquete eliminado deberá ser actualizado para referenciar los tipos bundled. para hacer esto, añade package.json
con "dependencies": { "foo": "x.y.z" }
.
Si un paquete nunca estuvo en DefinitelyTyped, no será necesario añadirlo a notNeededPackages.json
.
Para realizar el lint a un paquete, solo añade tslint.json
al paquete que contiene { "extends": "dtslint/dt.json" }
. Todos los paquetes nuevos deberán pasar por el proceso de linted.
Si el tslint.json
deshabilita algunas reglas esto se debe a que aún no se ha acomodado. Por ejemplo:
{
"extends": "dtslint/dt.json",
"rules": {
// This package uses the Function type, and it will take effort to fix.
"ban-types": false
}
}
(Para indicar que la regla lint realmente no es utilizada, usa // tslint:disable rule-name
o mejor, //tslint:disable-next-line rule-name
.)
Para afirmar que una expresión es de un tipo dado, utilice $ExpectType
. Para afirmar que una expresión causa un error de compilación, utilice $ExpectError
.
// $ExpectType void
f(1);
// $ExpectError
f("one");
Para más detalles, vea el dtslint readme.
Realiza una prueba ejecutando npm run lint package-name
donde package-name
es el nombre de tu paquete.
Este script utiliza dtslint.
La master
branch es automaticamente publicada en el alcance de los @types
en NPM gracias a los types-publisher.
Esto depende, pero la mayoría de los pull requests serán merged en alrededor de una semana. PRs que hayan sido aprovados por un autor listado en el encabezado de las definiciones usualmente son merged más rápidamente; PRs para nuevas definiciones tomarán más tiempo ya que requieren más revisiones de los mantenedores. Cada PR es revisado por un miembro de TypeScript o DefinitelyTyped antes de ser merged, por favor se paciente debido a que factores humanos pueden causar retrasos. Revisa el PR Burndown Board para ver el progreso mientras los mantenedores trabajan on los PRs abiertos.
Los paquetes NPM deberán ser actualizados en unas cuantas horas. Si ha pasado más de 24 horas, menciona a @RyanCavanaugh y/o a @andy-ms en el PR para investigar.
Estoy escribiendo una definición que depende de otra definición. Debería utilizar <reference types="" />
o una import?
Si el modulo al cual te estás refiriendo es un módulo externo (utiliza export
), utilice una import.
Si el módulo al cual te refieres es un módulo ambiente (utiliza declare module
, o simplemente declara las globales), utilice <reference types="" />
.
Normalmente no lo necesitaras. Cuando publicas un paquete normalmente nosotros automáticamente crearemos un package.json
para eso.
Un package.json
puede ser incluido por el bien de especificar dependencias. Aquí tienen un ejemplo.
No aceptamos otros campos, tales como "description"
, para que sean definidos manualmente.
Además, si necesitas referencia a una versión anterior de typings, debes hacerlo añadiendo "dependencies": { "@types/foo": "x.y.z" }
al package.json.
Algunos paquetes no tienen tslint.json
, y algunos tsconfig.json
no contienen "noImplicitAny": true
, "noImplicitThis": true
, o "strictNullChecks": true
.
Entonces están equivocados. Puedes ayudar enviando un pull request para arreglarlos.
Aquí están las definiciones solicitadas actualmente.
Si las types son parte de los estándares web, estas deberán ser contribuidas a TSJS-lib-generator para que se hagan parte de la librería predeterminada lib.dom.d.ts
.
Un paquete utiliza export =
, pero prefiero utilizar las import predeterminadas. ¿Puedo cambiar export =
por export default
?
Si la import predeterminada trabaja en tu ambiente, considera hacer un cambio en la opción de compilación --allowSyntheticDefaultImports
opción compilar.
No cambies la type definition si es preciso.
Para un paquete NPM, export =
es exacto si node -p 'require("foo")'
es la export, y export default
es exacto si node -p 'require("foo").default'
es el export.
Entonces deberás añadir un comentario a la última línea de la definición en el encabezado (despues de // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
): // TypeScript Version: 2.1
.
Esto puede pertenecer a TSJS-Lib-Generator. Vea las guías allí.
Si el estándar sigue siendo un borrador, este pertenece aquí.
Utilice un nombre que empiece con dom-
e incluya un link al estándar como el "Project" con el link en el encabezado.
Cuando ya no sea un borrador, lo podremos eliminar desde DefinitelyType y hacer obsoleto el paquete @types
asociado.
Si planeas continuar actualizando la versión anterior del paquete, puedes crear una subcarpeta con la versión actual p.ej. v2
, y copia los archivos existentes. Si es así, necesitarás:
- Actualiza las rutas relativas en
tsconfig.json
al igual quetslint.json
. - Añadir reglas de mapeo de rutas para asegurart de que la prueba se está ejecutando contra la versión prevista.
Por ejemplo history v2 tsconfig.json
se ve así:
{
"compilerOptions": {
"baseUrl": "../../",
"typeRoots": ["../../"],
"paths": {
"history": [ "history/v2" ]
},
},
"files": [
"index.d.ts",
"history-tests.ts"
]
}
Si hay otros paquetes en DefinitelyTyped que son incompatibles con la nueva versión, necesitaras mapear las rutas a la versión anterior. También deberá hacer esto para los paquetes que dependen de paquetes que dependen de una version anterior.
Por ejemplo, react-router
depende de history@2
, así que react-router tsconfig.json
tiene una ruta mapeada a "history": [ "history/v2" ]
;
transitivo así mismo, react-router-bootstrap
(que depende de react-router
) también añade una ruta mapeada en su tsconfig.json.
Además, /// <reference types=".." />
no trabajara con rutas mapeadas, así que las dependencias deberán utilizar import
.
El manual de TypeScript contiene excelente información general para escribir definiciones, ademas este archivo de definiciones de ejemplo el cual muestra como crear una definición utilizando la sintaxis de módulo en ES6, asi como también especificando objetos que son disponibles en el alcance global. Esta técnica es demostrada practicamente en la definición para big.js, el cual es una librería que puede ser cargada globalmente a travéz de una etiqueta script en una página web, o importada via require o imports estilo ES6.
Para probar como puede ser usada tu definición cuando se refieren globalmente o como un módulo importado, crea una carpeta test
, y coloca dos archivos de prueba en él. nombra uno YourLibraryName-global.test.ts
y el otro YourLibraryName-module.test.ts
. El archivo de prueba global debe ejercer la definición de acuerdo como va a ser usado en un script cargado en una página web donde la librería estará disponible en el alcance global - en este escenario no debes de especificar la sentencia de import. El archivo módulo de prueba debe de ejercer la definición de acuerdo a como va a ser utilizado cuando sea importado (incluyendo las sentencias import
). Si especificas un propiedad files
en tu archivo tsconfig.json, asegurate de incluir ambos archivos de prueba. Un ejemplo práctico de esto es también disponible en la definición de big.js.
Por favor tenga en cuenta que no es necesario para ejercer plenamente la definición en cada archivo de prueba - Es suficiente con probar solo los elementos globalmente accesibles en la prueba de archivos globales y ejercer la definición en el módulo del archivo de prueba, o viceversa.
Types para un paquete scoped @foo/bar
deberán ir en types/foo__bar
. tenga en cuenta el doble guion bajo.
Cuando dts-gen
es utilizado como scaffold en un paquete scoped, las propiedades paths
deberán ser adaptadas manualmente en el paquete generado
tsconfig.json
para referenciar correctamente el paquete scoped:
{
"paths":{
"@foo/bar": ["foo__bar"]
}
}
GitHub no le hace support historial de archivos para archivos renombrados. Utilice git log --follow
en su lugar.
Algunos paquetes, como chai-http, exportan una función.
importar este módulo con un ES6 style import de forma import * as foo from "foo";
conduce al error:
error ts2497: El módulo 'foo' se resuelve en una entidad que no es un módulo y no se puede importar mediante esta construcción
Este error puede ser suprimido al unir la declaración de una función con un namespace vacío del mismo nombre pero esta práctica no es recomendable. Esto es un citado común Respuestas de Stack Overflow con respecto a este asunto.
Es más apropiado importar este módulo utilizando la sintaxis import foo = require("foo");
, o utilizando una importación predeterminada como import foo from "foo";
si usas la bandera --allowSyntheticDefaultImports
si la ejecución de tu módulo soporta un esquema de interoperación para módulos no ECMAScript como tal.
Este proyecto es licenciado bajo la licencia MIT.
Los derechos de autor de cada archivo de definición son respectivos de cada contribuidor listado al comienzo de cada archivo de definición.