con la creciente popularidad de TypeScript, creo que esto debe suceder. Muchos otros paquetes js están comenzando a incluir sus propios tipos (oficiales) ahora. En lugar de dejarlo en manos de la comunidad DefinitelyTyped

Esto es algo que estamos considerando. Debería ser posible hacer un script de nodo para generarlo automáticamente desde nuestro volcado de API .

+1 👍 de mí también. El repositorio DefinitelyTyped está desactualizado, donde después de Highcharts v4.2.x solo se actualizaron las propiedades esporádicas e incidentales. Pero la mayoría de los cambios en Highcarts simplemente no se procesan.

Por lo tanto, el repositorio DefinitelyTyped debería actualizarse o, lo que es más conveniente, tenerlo incluido con Highcharts sería incluso una solución mucho mejor.

Tenerlo generado automáticamente suena como una gran opción, pero esto aún podría requerir trabajo manual por parte de la escritura de pruebas para el archivo .d.ts. Además, tenerlo autogenerado podría serlo.

Estaría dispuesto a trabajar un poco para actualizar el repositorio DefinitelyTyped a la versión actual, y hacer un PR en https://github.com/highcharts/highcharts si desea incluir el archivo manual allí.

/ cc @ ry8806 @TorsteinHonsi

^ He creado un PR para el repositorio DefinitelyTyped que implementa Highcharts v5.0.10 . Si alguien está interesado, este podría ser un buen lugar para trabajar más adelante (una vez y si se fusiona). Al menos por el momento, hasta que el archivo de definición de TypeScript se implemente junto con el propio Highcharts.

Sería muy apreciado tener definiciones oficiales de tipos de TypeScript. Ayuda mucho al escribir una configuración de gráfico.

Aquí estamos de nuevo con las definiciones de tipo, una versión mayor detrás de la realidad. : /

Dada la complejidad de esta biblioteca, creo que la mejor solución es generar las definiciones de tipo a partir del "volcado de API" al que se refirió @TorsteinHonsi . Sin embargo, ese vínculo parece estar roto. ¿Hay uno nuevo? Estaría dispuesto a intentar escribir un generador.

Sin embargo, ese vínculo parece estar roto. ¿Hay uno nuevo?

Sí, el nuevo está disponible en https://api.highcharts.com/highcharts/tree.json. Este árbol se genera a partir de nuestros comentarios JSDoc y código fuente analizado.

@cvasseng FYI.

@TorsteinHonsi Gracias.

Estamos usando JSDoc 3, pero muy extendido para poder describir nuestra estructura de opciones declarativas.

@TorsteinHonsi Mirando el JSON tengo algunas preguntas ... ¿por casualidad no tiene una documentación de esquema en este formato? Esto es lo que he recopilado . ¿Cómo se designan las opciones que se pasan a Highcharts.setOptions() frente a Highcharts.chart() (por ejemplo)? ¿Existe también un volcado de API para las clases y espacios de nombres?

@cvasseng

Hola @aaronbeall , no tenemos ninguna documentación completa sobre el esquema en este momento, pero parece que lo tienes todo en tu definición.

Las opciones para Highcharts.setOptions() y la serie se manejan como casos especiales fuera del esquema en sí donde lo usamos, pero debemos cambiar al menos global y lang para que sean fuera de la estructura de opciones principal.

Como nota al margen, el formato de volcado anterior estaba disponible en https://api.highcharts.com/dump.json , ahora lo hemos movido de nuevo a la posición original en https://api.highcharts.com/highcharts/ opción / dump.json.

Gracias @cvasseng. Estoy empezando a jugar con esto ... hay muchos datos, tengo mucho trabajo para mí solo para entenderlo todo. :) Me di cuenta de que algunos campos no tienen tipo ni valores predeterminados para inferir el tipo, como boost.seriesThreshold , pero el tipo aparece en los documentos . ¿Se tratan como un caso especial o me falta algo? Además, ¿hay algún esquema de API para los espacios de nombres / clases, o se maneja por separado? ¿El modelo declarativo está destinado a hacerlos obsoletos?

(Tendré más preguntas, ¿hay un mejor lugar para discutir esto? ¿Gitter? Estoy bien aquí, pero probablemente esté creando bastante ruido para algunas personas).

El tipo de boost.seriesThreshold realidad parece incorrecto en tree.json (y en los documentos en vivo); se supone que es un número, no una cadena. Al observar el doclet real a partir del cual se generó, falta el tipo. Es probable que este sea el caso de cualquier otro lugar donde también falten tipos. Estamos trabajando para agregar más pruebas y controles al pase de generación para encontrarlos automáticamente cuando los doclets cambien para evitar que esto suceda.

No tenemos un esquema para espacios de nombres / clases, pero esos son manejados por vanilla JSDoc 3, por lo que es posible agregar un complemento existente para generar automáticamente definiciones de mecanografiado para ellos. La configuración para esa parte se puede encontrar aquí: https://github.com/highcharts/highcharts-docstrap

Y discutir esto aquí funciona bien. :) De esa forma tenemos un lugar público central para ello, para que otros también puedan seguirlo.

En caso de que sea útil, este es un volcado de todos los campos (en highcharts / tree.json) que no parecen tener un tipo. Un análisis rápido de los tipos inferidos de los valores predeterminados (cadena, número, booleano) me parece correcto, pero los que dicen "No se puede determinar el tipo" significan que no encontré una propiedad type o una propiedad default propiedad, por lo que se asigna a any . Podría escribir un archivo de parche para esos tipos, ¿o hay una mejor manera?

También hay una clave en blanco en el JSON de nivel superior y en mapNavigation.buttons .

Hice algunos avances en esto hoy, puedes ver lo que se ha generado actualmente aquí . Queda mucho trabajo por hacer para lograr esta alta calidad. Empujaré a un repositorio mañana. En un nivel alto, me encontré con algunos problemas:

• No estoy seguro de cómo organizar la salida. En este momento hay 559 símbolos, que incluyen cosas importantes como Highcharts.Options y Series hasta pequeños objetos muy específicos como PlotOptionsBbTopLine . Para evitar conflictos de nombres, convierte el nombre completo a PascalCase, ex de plotOptions.bb.topLine . Todavía estoy tratando de averiguar cómo mejorar esto. Tratar de comparar con el actual @types/highcharts es un poco difícil, la mayoría de las veces las cosas simplemente no existen allí.
• No estoy seguro de entender la relación entre highcharts / highstocks / highmaps. (Solo he usado Highcharts personalmente). ¿El volcado de API contiene todos los datos de todos los productos? ¿Cómo debería dividirse? Tendré que entender mejor cómo usar realmente highstock y highmaps en un proyecto ...
• La forma en que los objetos se extienden entre sí tiene mucho sentido, pero me cuesta trabajo averiguar cómo convertirlos en tipos sensibles. Por el momento, los objetos se combinan utilizando los tipos de intersección & porque extends generaba muchos errores sobre la extensión incompatible. Actualmente no hay manejo de excludes , comencé a jugar con el tipo Omit pero eso generó muchos errores sobre los campos omitidos que no existen en el tipo. Creo que esto se debe a que, en algunos casos, una propiedad de objeto se hereda indirectamente del padre, por lo que en realidad no tiene los campos que deben omitirse, la propiedad del objeto padre sí. plotOptions.mfi.params es un ejemplo de esto, excluye index pero no tiene una propiedad index o extends un objeto que la tenga, pero el padre plotOptions.mfi extiende plotOptions.sma que tiene una propiedad secundaria plotOptions.sma.params que tiene la propiedad index que se fusiona en el padre con plotOptions.mfi.params . Sí, sigo pensando cómo lidiar con esto. :) Parece que necesito evaluar el árbol completamente fusionado y calcular los tipos a partir de ahí ...
• Muchos tipos genéricos Array , Object y Function ... probablemente todos bien documentados en las descripciones, pero no parece estar expresado en los tipos. Tal vez algún parche sensato del tipo de datos solucione este problema. Mi favorito es Array.<Array.<Mixed>> , todavía no tengo idea de qué es. :)

Algunas otras cosas específicas:

• ¿Cuáles son los tipos Color , CSSObject y Mixed ? Color parece ser un string formateado, CSSObject es un objeto de estilo estándar , o algo especial?
• series.bellcurve.data y series.histogram.data ambos se extienden, creando referencias circulares. Creo que esto es solo un error tipográfico, ¿probablemente pretenden extender algo más?

Además, algunos de los tipos que faltan no faltan en la API, por ejemplo, https://api.highcharts.com/highstock/plotOptions.bb.topLine.styles.lineColor. Si mal no recuerdo, escribimos adivinando en el generador api-docs , pero esto podría trasladarse al script highcharts.jsdoc.js para que sea parte de tree.json.

@cvasseng ¿Cuál es el estado de nuestras definiciones oficiales de TypeScript?

Subí un repositorio para jugar con esto , aunque no hay adiciones hoy.

Si mal no recuerdo, escribimos adivinando en el generador api-docs

Tendría curiosidad por saber cómo funciona el generador api-docs . Hace un buen trabajo al darle sentido al volcado de API. Estoy encontrando cosas que no estoy seguro de cómo manejar. Por ejemplo, series.bullet.data.targetOptions extiende series.bullet.targetOptions , pero no existe una definición para series.bullet.targetOptions ... sin embargo, las propiedades aparecen en los documentos sin problemas . Supongo que es porque series.bullet extiende plotOptions.bullet que tiene plotOptions.bullet.targetOptions , entonces series.bullet.targetOptions resuelve en plotOptions.bullet.targetOptions ?

Editar: Un pequeño progreso esta noche, mi verificación de veracidad para el valor predeterminado fue descartar todos los valores literales false , se corrigió eso y muchas más cosas se infieren como un booleano. Sin embargo, no estoy seguro de que boolean sea el tipo correcto para inferir en algunos lugares. También verifico el values para ver los tipos literales (¡esa información es excelente!). De todos modos, se actualiza el volcado de tipos que faltan .

Hice algunos avances después de pensar en cómo el árbol extiende los objetos:

• Se me ocurrió un método para resolver todas las definiciones que se fusionan en una ruta determinada . (Esto estiró mi cerebro ... ¿Me imagino que el generador de documentos hace algo como esto?)
• Luego reduzco todo el árbol eliminando defs redundantes en las rutas que sombrean otras defs fusionadas de otras partes del árbol, lo que elimina alrededor de 100 defs de objetos redundantes y cientos de propiedades redundantes. (Muchas de esas definiciones "redundantes" parecían estar allí para proporcionar adiciones a los documentos, como la descripción o los valores predeterminados, pero no ayudaron a las definiciones de tipo ... ¿suena bien?)
• Después de eso, solo algunas definiciones en el árbol reducido en realidad faltaban tipos que no se pueden inferir, que parcheo aquí (esos cambios probablemente serían buenos en el propio jsdoc). Lo que queda se puede inferir ( ver el último volcado de "tipos perdidos" ), aunque no he validado que el tipo inferido sea siempre correcto. También existe el problema de los tipos vagos como object , array y function .
• Aquí hay un volcado de cómo se cambia el árbol de def antes de generar defs de tipo TS. Esto nos da esta salida generada que comienza a parecer prometedora.

Que sigue

• Tratar los campos excluidos, que creo que tengo una estrategia usando Omit<> y haciendo un pase para agregar explícitamente extends a todos los objetos que tienen excludes (usando el método mencionado en el primera viñeta) y volver a utilizar interfaces con todas las propiedades opcionales. Creo que esto funcionará, siempre y cuando podamos estar seguros de que todas las propiedades serán opcionales. ¿Hay propiedades requeridas?
• Algunos otros detalles : mejoras de tipo, limpieza y pruebas
• Volveré a recoger esto después de las vacaciones. Me encantaría recibir comentarios si ustedes piensan que esto va en la dirección correcta o no.

Preguntas

• ¿Qué significa "memberof": "yaxis" en tooltipValueFormat doclet?
• Uno de los valores de context es PlotLineOrBand pero no veo eso en los documentos de las clases, ¿es esta una subclase de Series ?
• plotOptions.series.states tiene un nombre de tipo doclet "plotOptions.series.states" - ¿eso significa algo especial?

@aaronbeall ¿tienes algún progreso? También me he sumergido un poco en la generación de tipos para highcharts.

Un defecto importante es que el tree.json generado no contiene todos los tipos de highcharts, como los métodos estáticos en el espacio de nombres de highcharts. Hay 703 símbolos después de la poda de símbolos válida. Pero después de eso, los símbolos de salida dentro de tree.json son aproximadamente 100. Muchos de ellos se ignoran.

@ scott-ho Ha pasado un poco porque me mudé del proyecto usando Highcharts en el nuevo año, pero estoy de vuelta ahora y volveré a este proyecto pronto.

Desde mi última publicación, seguí la ruta de convertir type en interface y usar extends lugar de & (esta fue mi estrategia para respaldar adecuadamente el tree.json uso de excludes de campos específicos), y tuvo problemas: TS no permitirá que una interfaz extienda otra interfaz que comparte un nombre de campo que es un tipo de objeto que no comparte al menos 1 propiedad. He aquí un ejemplo abstracto. Olvidé los ejemplos exactos de esto con los que me encontré, pero había muchos, debido a la forma en que tree.json extiende libremente los objetos (en algunos casos, las cadenas de extensión excedieron 5) y excluye libremente los campos en cualquier punto. Esto me llevó a pensar que mi enfoque anterior de usar los tipos de intersección & podría ser la mejor ruta. Básicamente, eso dará como resultado que algunas propiedades que están "excluidas" no aparezcan realmente excluidas en la sugerencia de tipo (porque se fusionan desde algo extendido más arriba en el árbol que no se puede omitir del nodo actual), pero no puedo Piense en una mejor manera de hacerlo. Los documentos resuelven este problema porque representan las propiedades desde un solo punto, pero estructuralmente no podemos describir los tipos de esa manera sin deshacernos de extends y crear una tonelada de definiciones de tipos en su mayoría duplicadas.

Hay 703 símbolos después de la poda de símbolos válida. Pero después de eso, los símbolos de salida dentro de tree.json son aproximadamente 100. Muchos de ellos se ignoran.

¿A qué método de poda te refieres? Esta ha sido la parte más difícil de lidiar ...

Sí, también noté que las clases / espacios de nombres no se describen en tree.json (que básicamente describe las opciones de inicio declarativas tal como las entiendo), pero @cvasseng dijo que son vanilla jsdoc3, así que con suerte podemos usar un estándar convertidor para eso.

pruning se refiere desde esta línea .

Toda la recopilación de datos para tree.json vive dentro del método publish .

Creo que podría haber un mal uso de la api jsdoc en su interior.

Podríamos encontrar una mejor manera de generar una nueva versión de tree.json basada en la salida original de jsdoc.

Hoy, dediqué un tiempo a averiguar qué representan tree.json . Luego, finalmente me doy cuenta de que tree.json solo aloja los tipos de opciones de gráficos. Consulte aquí https://api.highcharts.com/highcharts/.

La recopilación de tipos y la lógica de generación se escribe aquí: https://github.com/highcharts/highcharts/blob/master/tools/jsdoc/plugins/highcharts.jsdoc.js.

Es posible que necesitemos generar la versión completa de los tipos nosotros mismos y hacer algo similar a https://github.com/englercj/tsd-jsdoc.

¿Hay alguna ETA para esto? Las definiciones en DefinitelyTyped son bastante horribles.

¿Consideró hablar con el equipo de TypeScript sobre las funciones faltantes que necesita? Estoy seguro de que escucharían las necesidades de un proyecto del tamaño de Highcharts y tienen un ciclo de lanzamiento bastante rápido.

@aaronbeall ¿Ha mirado los tipos asignados ?

Aquí hay un enlace con una solución para su ejemplo.

@cvasseng @TorsteinHonsi

¿Consideró hablar con el equipo de TypeScript sobre las funciones faltantes que necesita?

@JannesMeyer Desafortunadamente no hay Omit<> para separar las cosas ... pero los desafíos para mí son más sobre cómo resolver la forma en que la estructura de datos de Highcharts se define en usable , definiciones de tipo ergonómicas y completas. Parece que las definiciones deberían estar mínimamente definidas (es decir, no redefinir la misma propiedad en objetos similares en todo el lugar) pero sin perder nada. Tener una opción que aparece en la finalización de tipos que Highcharts no usa realmente en un contexto dado es menos un problema que perder algo que debería estar allí. También está el problema de la falta de un esquema de documento que da como resultado tipos genéricos object o any ... en algún lugar alguien tiene que escribir el tipo, la generación de tipos no puede hacer eso por usted.

Sí, eso tiene sentido. Parece que tal vez el equipo de Highcharts debería adoptar TypeScript un poco más de lo que lo hace actualmente. ¿Quizás incluso sería factible generar los documentos a partir de definiciones de tipo en lugar de generarlos desde jsdoc?

@JannesMeyer # 8307 está en camino de generar los tipos completos de Highcharts. La revisión requiere. Una vez que la mejora de los documentos se fusiona, se emitirá otro PR para generar automáticamente los tipos completos en función de la notación jsdoc.

He estado siguiendo esta publicación y será realmente útil si el archivo de declaración está disponible.
He estado usando DefenitelyTyped para nuestro proyecto React / Typescript. Sin embargo, me quedé atascado con la accesibilidad. no se dio cuenta de que la parte de accesibilidad no funcionará con DefenitelyTyped. Me he puesto en contacto con el equipo de soporte de Highcharts por mi problema, pero todavía no he tenido suerte.
En nuestro equipo usamos Highcharts / Highmaps en gran medida. Por eso, hemos invertido en ello. Por favor, piense en la prioridad de este proyecto.

¡Gracias por adelantado!

Solo me gustaría notificar que este tema se ha convertido en una alta prioridad.

El equipo de Highcharts ( @sophiebremer y @oysteinmoseng ) se unió a una sesión de depuración conmigo y me ayudó a resolver este problema cargando los archivos Js directamente. Realmente aprecio el tiempo y la solución que brindaron para desbloquearme en este momento. Espere el archivo de declaración de TS con Highcharts como solución definitiva. :)

Gracias @sophiebremer por darle prioridad a esto. Esto será muy útil para proyectos que utilizan Typecript.

Nota: He editado el comentario para proporcionar un mejor contexto y también agradecer a las personas del equipo de Highcharts.

Utilizamos Highstock de forma intensiva en un gran equipo de frontend que trabaja con angular / mecanografiado. Sería increíble para nosotros tener definiciones mecanografiadas, pensamos que las definiciones de DefinitelyTyped eran la referencia, pero está completamente desactualizado para Highstock.

¡Estas definiciones mecanografiadas son realmente una gran necesidad para nosotros!
Cualquier ETA es bienvenida :)

Ahora trabajamos en la calidad e intentamos reducir la cantidad de interfaces generadas en el árbol de opciones de Highcharts. Después de esto, comenzaremos una fase beta pública.

Nuestra ETA es por ahora el tercer trimestre de 2018 para la Beta.

@sophiebremer ¡ Qué buenas noticias! ¿Tiene un generador DTS o está utilizando una herramienta de conversión existente?

Usamos uno personalizado. Probamos el enfoque de esta solicitud de extracción https://github.com/highcharts/highcharts/pull/8307 usando dts-dom debajo, pero esto no funcionó bien.

¿Alguna noticia sobre este? Parece que @types/highcharts ya no se actualiza.

Todavía estamos trabajando en esto con alta prioridad. Lamentablemente, no puedo publicar una vista previa de la declaración en este momento. Todavía hay tipos que necesitan consolidarse o introducirse. El "highcharts.d.ts" será un archivo enorme con más de 200.000 líneas de declaraciones y comentarios.

@sophiebremer ¿cómo se produce ese archivo? ¿A mano?

@ scott-ho
Aunque los archivos de declaración se generan automáticamente, arreglar y actualizar los doclets en el código fuente es un proceso manual.

¡Hola a todos! Publiqué una vista previa de las declaraciones de Highcharts en mi repositorio personal. Puede probarlo con npm i https://github.com/sophiebremer/highcharts-declarations-alpha.git o descargar la declaración de https://github.com/sophiebremer/highcharts-declarations-alpha/blob/master/highcharts.d.ts y colocarlo directamente en ./node_modules/highcharts/ . Háganos saber si la declaración le funciona o si tiene problemas. ¡Gracias!

Problemas conocidos:

• el tipo de fijación en la propiedad options.series no funciona. La solución alternativa en este momento es convertir el objeto a su tipo de serie como { data: [0, 1, 2]} as Highcharts.SeriesLineOptions
• las opciones de estilo no están en todas partes del tipo CSSObject

Las funciones ChartEventsOptions como la selección no parecen tomar el parámetro de función de evento

Un par de otros problemas que encontré

• No se pueden importar los módulos de exportación y exportación fuera de línea. Tuve que cambiar export = factory para exportar la fábrica predeterminada y usarla como importación predeterminada

• Módulo de anotaciones faltantes

• ¿El clic de PlotSeriesEventsOptions debe modificarse como clic ?: (e: PointerEventObject) => boolean;

¡Gracias por los comentarios, @muperi !
Algunos comentarios sobre tu segunda publicación:

• Los módulos normales no exportan por defecto. Compruebe su tsconfig para conocer la configuración de ES6.
• Solo algunos módulos tienen declaraciones todavía. Por supuesto, agregaremos más en los próximos meses.
• Analizaremos este problema.

Las funciones ChartEventsOptions como la selección no parecen tomar el parámetro de función de evento

Fix es parte de highcharts / highcharts # 9110 y se incluirá en la próxima actualización de https://github.com/highcharts/highcharts-declarations-beta.

Agregue más problemas con los archivos de declaración a este repositorio: https://github.com/highcharts/highcharts-declarations-beta.

Gracias.