avec la popularité croissante de TypeScript, je pense que cela doit se produire. De nombreux autres packages js commencent maintenant à inclure leurs propres saisies (officielles). Plutôt que de laisser le soin à la communauté

C'est quelque chose que nous envisageons. Il devrait être possible de créer un script de nœud pour le générer automatiquement à partir de notre dump API .

+1 👍 de moi aussi. Le référentiel DefinitelyTyped est obsolète, alors qu'après Highcharts v4.2.x, seules les propriétés sporadiques et accessoires ont été mises à jour. Mais la plupart des changements dans Highcarts ne sont tout simplement pas traités.

Ainsi, soit le référentiel DefinitelyTyped devrait être mis à jour, soit - plus pratique - le regrouper avec Highcharts serait même une solution beaucoup plus agréable.

L'avoir généré automatiquement semble être une excellente option, mais cela peut encore nécessiter un travail manuel de la part de l'écriture de tests pour le fichier .d.ts ? En outre, l'avoir généré automatiquement pourrait l'être.

Je serais prêt à travailler pour mettre à jour le référentiel DefinitelyTyped vers la version actuelle et faire un PR sur https://github.com/highcharts/highcharts si vous souhaitez y inclure le fichier manuel ?

/cc @ry8806 @TorsteinHonsi

^ J'ai créé un PR pour le référentiel DefinitelyTyped qui

Avoir des définitions officielles de type TypeScript serait très apprécié. Aide beaucoup lors de la saisie d'une configuration de graphique.

Nous voici à nouveau avec les définitions de type une version majeure derrière la réalité. :/

Compte tenu de la complexité de cette bibliothèque, je pense que la meilleure solution consiste à générer les définitions de type à partir du "vidage d'API" auquel @TorsteinHonsi a fait référence. Cependant, ce lien semble rompu. Y a-t-il un nouveau? Je serais prêt à essayer d'écrire un générateur.

Cependant, ce lien semble rompu. Y a-t-il un nouveau?

Oui, le nouveau est disponible sur https://api.highcharts.com/highcharts/tree.json. Cet arbre est généré à partir de nos commentaires JSDoc et du code source analysé.

@cvasseng Pour info .

@TorsteinHonsi Merci, je vais y jeter un œil. Utilisez-vous une version particulière de "jsdoc" (Google Closure, JSDoc 3 ?) Le vidage JSON se produit-il quelque part dans cette base de code que je peux consulter pour référence ? La raison pour laquelle je pose la question est qu'il existe des convertisseurs JSDoc vers TSDef qui pourraient fonctionner...

Nous utilisons JSDoc 3, mais fortement étendu pour pouvoir décrire notre structure d'options déclaratives.

@TorsteinHonsi En regardant le JSON, j'ai quelques questions... vous n'avez par hasard pas de documentation de schéma sur ce format ? C'est ce que j'ai collecté . Comment désignez-vous les options qui sont transmises à Highcharts.setOptions() vs Highcharts.chart() (par exemple) ? Existe-t-il également un vidage d'API pour les classes et les espaces de noms ?

@cvasseng

Salut @aaronbeall , nous n'avons pas de documentation complète sur le schéma pour le moment, mais il semble que vous ayez tout compris dans votre définition.

Les options pour Highcharts.setOptions() , et la série sont toutes deux traitées comme des cas spéciaux en dehors du schéma lui-même où nous l'utilisons, mais nous devrions changer au moins global et lang pour être en dehors de la structure des options principales.

En remarque, l'ancien format de vidage était disponible sur https://api.highcharts.com/dump.json , nous l'avons maintenant ramené à sa position d'origine sur https://api.highcharts.com/highcharts/ option/dump.json.

Merci @cvasseng. Je commence à bricoler avec ça... il y a beaucoup de données, j'ai du pain sur la planche pour tout comprendre. :) J'ai remarqué que certains champs n'ont pas de type et pas de valeur par défaut pour en déduire le type, comme boost.seriesThreshold , mais le type apparaît dans la documentation . Sont-ils traités comme un cas particulier ou est-ce que j'ai raté quelque chose ? Existe-t-il également un schéma d'API pour les espaces de noms/classes, ou est-il géré séparément ? Le modèle déclaratif vise-t-il à les rendre obsolètes ?

(J'aurai d'autres questions, y a-t-il un meilleur endroit pour en discuter ? Gitter ? Je vais bien ici, mais cela crée probablement pas mal de bruit pour certaines personnes.)

Le type de boost.seriesThreshold semble en fait être faux dans tree.json (et dans les documents en direct) - c'est censé être un nombre, pas une chaîne. En regardant le doclet réel à partir duquel il a été généré, le type est manquant. C'est probablement le cas pour tous les autres endroits où les types manquent également. Nous travaillons sur l'ajout de tests et de contrôles supplémentaires à la passe de génération pour les trouver automatiquement lorsque les doclets changent pour éviter que cela ne se produise.

Nous n'avons pas de schéma pour les espaces de noms/classes, mais ceux-ci sont gérés par vanilla JSDoc 3, il est donc possible d'ajouter un plugin existant pour générer automatiquement des définitions de script dactylographié pour eux. La configuration de cette partie peut être trouvée ici : https://github.com/highcharts/highcharts-docstrap

Et discuter de cela ici fonctionne très bien. :) De cette façon, nous avons un lieu public central pour cela, afin que d'autres puissent le suivre aussi.

Au cas où cela serait utile, type propriété default propriété, elle est donc affectée à any . Je pourrais écrire un fichier de correctif pour ces types, ou existe-t-il un meilleur moyen ?

Il existe également une clé vierge dans le JSON de niveau supérieur et dans mapNavigation.buttons .

J'ai fait quelques progrès à ce sujet aujourd'hui, vous pouvez voir ce qui est actuellement généré ici . Il reste beaucoup de travail pour faire cette haute qualité. Je vais pousser vers un repo demain. À un niveau élevé, certains problèmes que j'ai rencontrés :

• Je ne sais pas comment organiser la sortie. À l'heure actuelle, il y a 559 symboles, qui incluent des éléments importants comme Highcharts.Options et Series jusqu'à de petits objets très spécifiques comme PlotOptionsBbTopLine . Pour éviter les conflits de noms, il convertit le nom complet en PascalCase, ex de plotOptions.bb.topLine . J'essaie toujours de trouver comment améliorer cela. Essayer de comparer avec le @types/highcharts actuel est un peu difficile, le plus souvent, les choses n'existent tout simplement pas là-bas.
• Je ne suis pas sûr de comprendre la relation entre highcharts/highstocks/highmaps. (Je n'ai utilisé que Highcharts personnellement.) Le vidage de l'API contient-il toutes les données de tous les produits ? Comment doit-il être divisé? Je vais devoir mieux comprendre comment utiliser réellement highstock et highmaps dans un projet...
• La façon dont les objets s'étendent les uns les autres est parfaitement logique, mais j'ai du mal à trouver comment le convertir en types sensibles. Pour le moment, les objets sont fusionnés à l'aide & types d'intersection extends provoquait de nombreuses erreurs concernant l'extension incompatible. Actuellement, il n'y a pas de gestion de excludes , j'ai commencé à jouer avec le type Omit mais cela a soulevé beaucoup d'erreurs sur les champs omis n'existant pas dans le type. Je pense que c'est parce que, dans certains cas, une propriété d'objet hérite indirectement du parent, de sorte qu'elle n'a pas réellement les champs qui devraient être omis, contrairement à la propriété de l'objet parent. plotOptions.mfi.params est un exemple, il exclut index mais il n'a pas de propriété index ou extends un objet qui en a, mais le parent plotOptions.mfi étend plotOptions.sma qui a une propriété enfant plotOptions.sma.params qui a le index qui est fusionné sur le parent avec plotOptions.mfi.params . Ouais, je cherche toujours comment gérer ça. :) On dirait que j'ai besoin d'évaluer l'arbre entièrement fusionné et de déterminer les types à partir de là...
• Beaucoup de types génériques Array , Object et Function ... probablement tous bien documentés dans les descriptions mais cela ne semble pas être exprimé dans les types. Peut-être qu'un correctif judicieux du type data résoudra ce problème. Mon préféré est Array.<Array.<Mixed>> -- aucune idée de ce que c'est encore. :)

Quelques autres choses spécifiques :

• Quels sont les types Color , CSSObject et Mixed ? Color semble être un string formaté, CSSObject est un objet de style standard ou quelque chose de spécial ?
• series.bellcurve.data et series.histogram.data s'étendent tous les deux, créant des références circulaires. Je pense que c'est juste une faute de frappe, ils sont probablement destinés à étendre autre chose?

De plus, certains de vos types manquants ne manquent pas dans l'API, par exemple https://api.highcharts.com/highstock/plotOptions.bb.topLine.styles.lineColor. Si je me souviens bien, nous tapons deviner dans le générateur api-docs , mais cela pourrait être déplacé vers le script highcharts.jsdoc.js afin qu'il fasse partie de tree.json.

@cvasseng Quel est le statut de nos définitions officielles de TypeScript ?

Téléchargé un repo pour jouer avec ça , pas d'ajouts aujourd'hui cependant.

Si je me souviens bien, nous tapons deviner dans le générateur api-docs

Je serais curieux de comprendre comment fonctionne le générateur de api-docs . Il fait un bon travail pour donner un sens au vidage de l'API. Je trouve des choses que je ne sais pas comment gérer. Par exemple, series.bullet.data.targetOptions étend series.bullet.targetOptions , mais une définition pour series.bullet.targetOptions n'existe pas... mais les propriétés apparaissent très bien dans la documentation . Je suppose que c'est parce que series.bullet étend plotOptions.bullet qui a plotOptions.bullet.targetOptions , donc series.bullet.targetOptions résout en plotOptions.bullet.targetOptions ?

Edit: Petit progrès ce soir, ma vérification véridique de la valeur par défaut supprimait toutes les valeurs littérales false , a corrigé cela et beaucoup plus de choses sont déduites comme un booléen. Cependant, je ne suis pas sûr que booléen soit le type correct à déduire à certains endroits. Je vérifie également le values pour les types littéraux (cette information est superbe à avoir !). Quoi qu'il en soit, le vidage des types manquants est mis à jour.

A fait quelques progrès après avoir réfléchi à la façon dont l'arbre étend les objets :

• A proposé une méthode pour résoudre toutes les defs qui sont fusionnées à un chemin donné . (Cela m'a étiré le cerveau... J'imagine que le générateur de documents fait quelque chose comme ça ?)
• Ensuite, je réduis l'ensemble de l'arbre en supprimant les définitions redondantes sur les chemins qui masquent d'autres définitions fusionnées à partir d'autres parties de l'arbre, ce qui supprime environ 100 définitions d'objet redondantes et des centaines de propriétés redondantes. (Beaucoup de ces définitions « redondantes » semblaient être là pour fournir des ajouts à la documentation, comme une description ou des valeurs par défaut, mais n'ont pas aidé les définitions de type...
• Après cela, seules quelques définitions dans l'arborescence réduite manquaient en fait de types qui ne peuvent pas être déduits, que je corrige ici (ces modifications seraient probablement bonnes dans le jsdoc lui-même). Ce qui reste peut être déduit ( voir le dernier dump "types manquants" ), bien que je n'aie pas validé le type déduit est toujours correct. Il y a aussi toujours le problème des types vagues comme object , array et function .
• Voici un dump de la façon dont l'arbre de def est modifié avant de sortir les defs de type TS. Cela nous donne cette sortie générée qui commence à sembler prometteuse.

Et après

• Traiter les champs exclus, que je pense avoir une stratégie utilisant Omit<> et faire une passe pour ajouter explicite extends à tous les objets qui ont excludes (en utilisant la méthode mentionnée dans le première puce) et revenir à utiliser des interfaces avec toutes les propriétés facultatives. Je pense que cela fonctionnera, tant que nous pouvons être sûrs que les propriétés seront toutes facultatives ? Y a-t-il des propriétés requises?
• Quelques autres détails : améliorations de type, nettoyage et tests
• Je reprendrai ça après les vacances. J'aimerais avoir des commentaires si vous pensez que cela va même dans la bonne direction ou non.

Des questions

• Que signifie "memberof": "yaxis" dans tooltipValueFormat doclet ?
• L'une des valeurs de context est PlotLineOrBand mais je ne vois pas cela dans la documentation des classes, est-ce une sous-classe de Series ?
• plotOptions.series.states a le nom de type de doclet "plotOptions.series.states" -- cela signifie-t-il quelque chose de spécial ?

@aaronbeall avez-vous des progrès? J'ai aussi plongé un peu dans la génération de type pour les highcharts.

Un défaut majeur est que le tree.json généré ne contient pas toutes les saisies de highcharts, comme les méthodes statiques sur l'espace de noms highcharts. Il y a 703 symboles après un élagage de symboles valide. Mais après cela, les symboles de sortie dans tree.json sont d'environ 100. C'est beaucoup d'entre eux ignorés.

@scott-ho Cela fait un petit moment parce que j'ai quitté le projet en utilisant Highcharts au cours de la nouvelle année, mais je suis de retour maintenant et je reviendrai bientôt dans ce projet.

Depuis mon dernier message, j'ai décidé de convertir type en interface et d'utiliser extends au lieu de & (c'était ma stratégie pour bien prendre en charge le tree.json utilisation de excludes de champs spécifiques), et a rencontré des problèmes : TS n'autorisera pas une interface à étendre une autre interface qui partage un nom de champ qui est un type d'objet qui ne partage pas au moins 1 propriété. Voici un exemple abstrait. J'oublie les exemples exacts que j'ai rencontrés, mais il y en avait beaucoup, à cause de la façon dont tree.json étend librement les objets (dans certains cas, les chaînes d'extension dépassent 5) et exclut librement les champs à tout moment. Cela m'a amené à penser que mon approche précédente consistant à utiliser des types d'intersection & pourrait être le meilleur itinéraire. Fondamentalement, cela entraînera que certaines propriétés "exclues" n'apparaissent pas réellement exclues dans l'indication de type (car elles sont fusionnées à partir de quelque chose d'étendu plus haut dans l'arbre qui ne peut pas être omis du nœud actuel), mais je ne peux pas pensez à une meilleure façon de le faire. Les documents contournent ce problème car ils restituent les propriétés à partir d'un seul point, mais structurellement, nous ne pouvons pas décrire les types de cette façon sans abandonner extends et créer une tonne de définitions de types principalement en double.

Il y a 703 symboles après un élagage de symboles valide. Mais après cela, les symboles de sortie dans tree.json sont d'environ 100. C'est beaucoup d'entre eux ignorés.

De quelle méthode de taille parles-tu ? Cela a été la partie la plus difficile à gérer...

Oui, j'ai également remarqué que les classes/espaces de noms ne sont pas décrits dans tree.json (cela décrit essentiellement les options d'initialisation déclaratives telles que je les comprends), mais @cvasseng a dit qu'il s'agit de vanilla jsdoc3 donc j'espère que nous pourrons utiliser un standard convertisseur pour ça.

pruning est référencé à partir de cette ligne .

Toute la collecte de données pour tree.json réside dans la méthode publish .

Je pense qu'il pourrait y avoir une mauvaise utilisation de l'API jsdoc à l'intérieur.

Nous pourrions trouver un meilleur moyen de générer une nouvelle version de tree.json basée sur la sortie originale de jsdoc.

Aujourd'hui, j'ai mis du temps à découvrir ce que représentent les tree.json . Ensuite, j'ai finalement compris que tree.json n'héberge que les types d'options de graphique. Voir ici https://api.highcharts.com/highcharts/.

La logique de collecte et de génération des types est écrite ici - https://github.com/highcharts/highcharts/blob/master/tools/jsdoc/plugins/highcharts.jsdoc.js.

Nous devrons peut-être générer nous-mêmes la version complète des types et faire quelque chose de similaire à https://github.com/englercj/tsd-jsdoc.

Y a-t-il un ETA pour cela? Les définitions dans DefinitelyTyped sont assez horribles.

Avez-vous envisagé de parler à l'équipe TypeScript des fonctionnalités manquantes dont vous avez besoin ? Je suis sûr qu'ils écouteraient les besoins d'un projet de la taille de Highcharts et qu'ils ont un cycle de publication plutôt rapide.

@aaronbeall Avez-vous regardé les types mappés ?

Voici un lien avec un correctif pour votre exemple

@cvasseng @TorsteinHonsi

Avez-vous envisagé de parler à l'équipe TypeScript des fonctionnalités manquantes dont vous avez besoin ?

@JannesMeyer Malheureusement, pas de Omit<> fonctionne pour séparer les choses... , des définitions de types complètes et ergonomiques. Il semble que les définitions devraient être définies au minimum (c'est-à-dire ne pas redéfinir la même propriété sur des objets similaires partout) mais sans rien manquer. Avoir une option qui s'affiche dans la saisie semi-automatique que Highcharts n'utilise pas réellement dans un contexte donné est moins un problème que de manquer quelque chose qui devrait être là. Il y a aussi le problème de l'absence de schéma de documentation qui entraîne des types génériques object ou any ... quelque part, quelqu'un doit écrire le type, la génération de type ne peut pas le faire pour vous.

Ouais, ça a du sens. Il semble que l'équipe Highcharts devrait adopter TypeScript un peu plus qu'elle ne le fait actuellement. Peut-être serait-il même possible de générer les documents à partir de définitions de types au lieu de les générer à partir de jsdoc ?

@JannesMeyer #8307 est en passe de générer les types complets de Highcharts. La révision est exigeante. Une fois l'amélioration de la documentation fusionnée, une anthère PR sera émise pour générer automatiquement les types complets basés sur la notation jsdoc.

J'ai suivi ce post, et il sera vraiment utile si le fichier de déclaration est disponible.
J'utilise DefenitelyTyped pour notre projet React/Typescript. Cependant, je suis resté coincé avec l'accessibilité. Je ne savais pas que la partie accessibilité ne fonctionnerait pas avec DefenitelyTyped. J'ai contacté l'équipe d'assistance de Highcharts pour mon problème, mais sans succès pour le moment.
Dans notre équipe, nous utilisons fortement Highcharts/Highmaps. Nous y avons donc investi. Merci de réfléchir à la priorité de ce projet.

Merci d'avance!

Je voudrais juste informer que cette question est devenue une priorité élevée.

L'équipe Highcharts ( @sophiebremer et @oysteinmoseng ) s'est en fait jointe à une session de débogage avec moi et m'a aidé à résoudre ce problème en chargeant directement les fichiers Js. J'apprécie vraiment le temps et la solution qu'ils ont fournis pour me débloquer en ce moment. Attendez-vous au fichier de déclaration TS avec Highcharts comme solution ultime. :)

Merci @sophiebremer d'en avoir fait une priorité. Cela sera très utile pour les projets qui utilisent Typescript.

Remarque : j'ai modifié le commentaire pour fournir un meilleur contexte et également remercier les personnes de l'équipe Highcharts.

Nous utilisons intensivement Highstock dans une grande équipe frontend travaillant avec angulaire / tapuscrit. Ce serait génial pour nous d'avoir des définitions dactylographiées, nous pensions que les définitions de DefinitelyTyped étaient la référence, mais c'est complètement obsolète pour Highstock..

Ces définitions tapuscrites sont vraiment un grand besoin pour nous !
Tout ETA est le bienvenu :)

Nous travaillons maintenant sur la qualité et essayons de réduire le nombre d'interfaces générées dans l'arborescence des options de Highcharts. Après cela, nous commencerons une phase bêta publique.

Notre ETA est pour l'instant le 3ème trimestre 2018 pour la Beta.

@sophiebremer C'est une excellente nouvelle ! Avez-vous un générateur DTS ou utilisez-vous un outil de conversion existant ?

Nous en utilisons un personnalisé. Nous avons essayé l'approche de cette pull request https://github.com/highcharts/highcharts/pull/8307 en utilisant dts-dom en dessous, mais cela n'a pas bien fonctionné.

Des nouvelles de celui-ci ? Il semble que @types/highcharts ne soit plus mis à jour.

Nous y travaillons toujours avec une haute priorité. Malheureusement, je ne peux pas publier un aperçu de la déclaration pour le moment. Il existe encore des types qu'il faut consolider ou introduire. Le "highcharts.d.ts" sera un énorme fichier avec plus de 200.000 lignes de déclarations et de commentaires.

@sophiebremer comment produisez-vous ce fichier ? Manuellement?

@scott-ho
Bien que les fichiers de déclaration soient générés automatiquement, la correction et la mise à jour des doclets dans le code source est un processus manuel.

Salut à tous! J'ai publié un aperçu des déclarations pour Highcharts dans mon référentiel personnel. Vous pouvez le tester par npm i https://github.com/sophiebremer/highcharts-declarations-alpha.git ou télécharger la déclaration depuis https://github.com/sophiebremer/highcharts-declarations-alpha/blob/master/highcharts.d.ts et la placer directement dans ./node_modules/highcharts/ . Veuillez nous faire savoir si la déclaration fonctionne pour vous ou si vous rencontrez des problèmes. Merci!

Problèmes connus:

• l'épinglage de type dans la propriété options.series ne fonctionne pas. La solution de contournement consiste actuellement à convertir l'objet en type de série comme { data: [0, 1, 2]} as Highcharts.SeriesLineOptions
• les options de style ne sont pas partout de type CSSObject

Les fonctions ChartEventsOptions comme la sélection ne semblent pas prendre en compte le paramètre de fonction d'événement

Quelques autres problèmes que j'ai trouvés

• Impossible d'importer les modules d'exportation hors ligne. J'ai dû changer export = factory pour exporter l'usine par défaut et l'utiliser comme importation par défaut

• Module d'annotations manquant

• Le clic PlotSeriesEventsOptions doit être modifié en tant que clic ? : (e:PointerEventObject) => booléen ;

Merci pour le retour, @muperi !
Quelques commentaires sur votre deuxième message :

• Les modules réguliers n'exportent pas par défaut. Veuillez vérifier votre tsconfig pour les paramètres ES6.
• Seuls quelques modules ont encore des déclarations. Nous allons bien sûr en ajouter d'autres au cours des prochains mois.
• Nous allons nous pencher sur cette question.

Les fonctions ChartEventsOptions comme la sélection ne semblent pas prendre en compte le paramètre de fonction d'événement

Le correctif fait partie de highcharts/highcharts#9110 et sera inclus dans la prochaine mise à jour de https://github.com/highcharts/highcharts-declarations-beta.

Veuillez ajouter d'autres problèmes avec les fichiers de déclaration à ce référentiel : https://github.com/highcharts/highcharts-declarations-beta.

Merci.