Я думаю, что с ростом популярности TypeScript это должно произойти. Многие другие пакеты js теперь начинают включать свои собственные (официальные) типы. Вместо того, чтобы оставлять это на усмотрение сообщества

Это то, что мы рассматриваем. Должна быть возможность создать скрипт узла для его автоматической генерации из дампа нашего

+1 👍 от меня тоже. DefinitelyTyped репо устарел, где после Highcharts v4.2.x только были обновлены спорадические и случайные свойства. Но большинство изменений в Highcarts просто не обрабатываются.

Таким образом, следует либо обновить репозиторий с определенным типом, либо, что более удобно, связать его с Highcharts, это было бы гораздо более приятным решением.

Автоматическая генерация - это отличный вариант, но это может потребовать ручного труда со стороны написания тестов для файла .d.ts? Кроме того, его автоматическая генерация может быть.

Я был бы готов поработать над обновлением репозитория DefininiteTyped до текущей версии и сделать PR на https://github.com/highcharts/highcharts, если вы хотите включить туда ручной файл?

/ cc @ ry8806 @TorsteinHonsi

^ Я создал PR для репозитория ОпределенноТипед, который

Было бы очень полезно иметь официальные определения типов TypeScript. Очень помогает при вводе конфигурации диаграммы.

Здесь мы снова с определениями типов - основной версией реальности. : /

Учитывая сложность этой библиотеки, я думаю, что лучшим решением является создание определений типов из "дампа API", на который ссылается @TorsteinHonsi . Однако эта ссылка, похоже, не работает. Есть новый? Я хотел бы попробовать написать генератор.

Однако эта ссылка, похоже, не работает. Есть новый?

Да, новый доступен по адресу https://api.highcharts.com/highcharts/tree.json. Это дерево создается из комментариев JSDoc и проанализированного исходного кода.

@cvasseng К вашему сведению.

@TorsteinHonsi Спасибо, я посмотрю на это. Используете ли вы особую разновидность «jsdoc» (Google Closure, JSDoc 3?). Возникает ли дамп JSON где-нибудь в этой кодовой базе, которую я могу посмотреть для справки? Причина, по которой я спрашиваю, заключается в том, что существуют существующие преобразователи JSDoc-to-TSDef, которые могут работать ...

Мы используем JSDoc 3, но он сильно расширен, чтобы иметь возможность описывать нашу декларативную структуру опций.

@TorsteinHonsi Глядя на JSON, у меня есть несколько вопросов ... у вас случайно нет документации по схеме для этого формата? Это то, что я собрал . Как вы определяете параметры, которые передаются в Highcharts.setOptions() vs Highcharts.chart() (например)? Есть ли дамп API для классов и пространств имен?

@cvasseng

Привет, @aaronbeall , в настоящее время у нас нет подробной документации по схеме, но похоже, что у вас есть все в своем определении.

Параметры для Highcharts.setOptions() и серии обрабатываются как особые случаи за пределами самой схемы, в которой мы ее используем, но мы должны изменить как минимум global и lang на вне основной структуры опций.

Кстати, старый формат дампа был доступен на https://api.highcharts.com/dump.json , теперь мы вернули его в исходное положение на https://api.highcharts.com/highcharts/ вариант / dump.json.

Спасибо @cvasseng. Я начинаю возиться с этим ... данных много, у меня есть работа, чтобы просто все это понять. :) Я заметил, что некоторые поля не имеют типа и не имеют значения по умолчанию, из которого можно вывести тип, например boost.seriesThreshold , но тип отображается в документации . Это особый случай, или я что-то упустил? Также существует ли какая-либо схема API для пространств имен / классов, или это обрабатывается отдельно? Должна ли декларативная модель сделать их устаревшими?

(У меня будут еще вопросы, есть ли лучшее место, чтобы обсудить это? Gitter? Я в порядке, но, вероятно, это создает довольно много шума для некоторых людей.)

Тип для boost.seriesThreshold самом деле выглядит неправильным в tree.json (и в действующей документации) - это должно быть число, а не строка. Если посмотреть на фактический доклет, из которого он был сгенерирован, тип в нем отсутствует. Скорее всего, так будет и в любых других местах, где отсутствуют типы. Мы работаем над добавлением дополнительных тестов и проверок в проход генерации, чтобы автоматически находить их при изменении доклетов, чтобы этого не происходило.

У нас нет схемы для пространств имен / классов, но они обрабатываются ванильным JSDoc 3, поэтому можно добавить существующий плагин для автоматической генерации определений машинописного текста для них. Настройку для этой части можно найти здесь: https://github.com/highcharts/highcharts-docstrap

И обсуждение этого здесь отлично работает. :) Таким образом, у нас есть центральное общественное место для этого, чтобы другие тоже могли за ним последовать.

Если это полезно, это дамп всех полей (в highcharts / tree.json), которые, похоже, не имеют типа. Быстрое сканирование предполагаемых типов из значений по умолчанию (строка, число, логическое значение) мне кажется правильным, но те, которые говорят «Невозможно определить тип», означают, что я не нашел свойство type или default свойство, поэтому оно присвоено any . Я мог бы написать файл патча для этих типов, или есть лучший способ?

Также есть пустой ключ в JSON верхнего уровня и в mapNavigation.buttons .

Сегодня я добился некоторого прогресса в этом, вы можете увидеть, что в настоящее время создано здесь . Осталось много работы, чтобы добиться такого высокого качества. Перейду на репо завтра. На высоком уровне я столкнулся с некоторыми проблемами:

• Не знаю, как организовать вывод. Прямо сейчас существует 559 символов, которые включают важные вещи, такие как Highcharts.Options и Series вплоть до очень специфических маленьких объектов, таких как PlotOptionsBbTopLine . Чтобы избежать конфликтов имен, он преобразует полное имя в PascalCase, например, из plotOptions.bb.topLine . Все еще пытаюсь понять, как это исправить. Пытаться сравнить с текущим @types/highcharts немного сложно, чаще всего там просто не существует вещей.
• Я не уверен, что понимаю взаимосвязь highcharts / highstocks / highmaps. (Я лично использовал только Highcharts.) Содержит ли дамп API все данные обо всех продуктах? Как его разделить? Мне нужно лучше понять, как на самом деле использовать highstock и highmaps в проекте ...
• То, как объекты расширяют друг друга, имеет смысл, но мне сложно придумать, как преобразовать его в разумные типы. В настоящий момент объекты объединяются с использованием типов пересечения & потому что extends вызывало много ошибок о несовместимых расширениях. В настоящее время нет обработки excludes , я начал играть с типом Omit но это вызвало много ошибок о пропущенных полях, не существующих в типе. Я думаю, это связано с тем, что в некоторых случаях свойство объекта наследуется косвенно от родительского объекта, поэтому на самом деле у него нет полей, которые следует опускать, в отличие от свойства родительского объекта. plotOptions.mfi.params является примером этого, он исключает index но не имеет свойства index или extends объекта, который имеет, но родительский plotOptions.mfi расширяет plotOptions.sma которого есть дочернее свойство plotOptions.sma.params которое имеет index которое объединено с родительским элементом с plotOptions.mfi.params . Ага, все еще пытаюсь с этим справиться. :) Похоже, мне нужно оценить полностью объединенное дерево и определить оттуда типы ...
• Множество общих типов Array , Object и Function ... вероятно, все хорошо задокументированы в описаниях, но, похоже, не выражены в типах. Возможно, это исправит какое-нибудь разумное исправление данных типа. Мой любимый - Array.<Array.<Mixed>> - пока не знаю, что это такое. :)

Некоторые другие специфические вещи:

• Что такое типы Color , CSSObject и Mixed ? Color кажется отформатированным string , CSSObject - это объект стандартного стиля или что-то особенное?
• series.bellcurve.data и series.histogram.data оба расширяются, создавая циклические ссылки. Думаю, это просто опечатка, наверное, они предназначены для расширения чего-то другого?

Кроме того, некоторые из ваших недостающих типов не отсутствуют в API, например https://api.highcharts.com/highstock/plotOptions.bb.topLine.styles.lineColor. Если я правильно помню, мы делаем угадывание типов в генераторе api-docs , но это можно переместить в сценарий highcharts.jsdoc.js чтобы он стал частью tree.json.

@cvasseng Каков статус наших официальных определений TypeScript?

Загрузил репо, чтобы поиграть с этим , но сегодня никаких добавлений.

Если я правильно помню, мы делаем угадывание типа в генераторе api-docs

Мне было бы любопытно понять, как работает генератор api-docs . Он хорошо разбирается в дампе API. Я нахожу вещи, с которыми не знаю, как с ними справиться. Например, series.bullet.data.targetOptions расширяет series.bullet.targetOptions , но определение для series.bullet.targetOptions не существует ... однако свойства хорошо представлены в документации . Я предполагаю, что это потому, что series.bullet расширяет plotOptions.bullet котором есть plotOptions.bullet.targetOptions , поэтому series.bullet.targetOptions преобразуется в plotOptions.bullet.targetOptions ?

Изменить: небольшой прогресс сегодня вечером, моя правдивая проверка для значения по умолчанию отбрасывала все буквальные значения false , исправила это, и многие другие вещи выводятся как логические. Однако не уверен, что логическое значение является правильным типом для вывода в некоторых местах. Я также проверяю values предмет литеральных типов (эта информация просто великолепна!). В любом случае дамп недостающих типов обновляется.

Достигнут некоторый прогресс после размышлений о том, как дерево расширяет объекты:

• Придумал способ разрешить все определения, которые объединяются по заданному пути . (Это напрягло мой мозг ... Я полагаю, генератор документов делает что-то подобное?)
• Затем я уменьшаю все дерево, удаляя избыточные defs в путях, которые затеняют другие defs, объединенные с другими частями дерева, что удаляет около 100 избыточных defs объектов и сотни избыточных свойств. (Многие из этих "избыточных" defs, казалось, были там, чтобы предоставлять дополнения к документации, такие как описание или значения по умолчанию, но не помогли defs типов ... звучит правильно?)
• После этого только несколько определений в сокращенном дереве фактически содержали отсутствующие типы, которые нельзя вывести, и я исправляю их здесь (эти изменения, вероятно, будут хороши в самом jsdoc). Все, что осталось, можно вывести ( см. Последний дамп «недостающих типов» ), хотя я не проверял, что предполагаемый тип всегда верен. Также все еще существует проблема с расплывчатыми типами, такими как object , array и function .
• Вот дамп того, как изменяется дерево def перед выводом определений типа TS. Это дает нам сгенерированный результат, который начинает выглядеть многообещающим.

Что дальше

• Работайте с исключенными полями, и я думаю, что у меня есть стратегия, использующая Omit<> и выполняющая переход для добавления явного extends ко всем объектам, имеющим excludes (используя метод, упомянутый в первый маркер) и вернуться к использованию интерфейсов со всеми необязательными свойствами. Я думаю, это сработает, если мы можем быть уверены, что все свойства будут необязательными? Есть ли требуемые свойства?
• Некоторые другие детали : улучшения типов, очистка и тесты.
• Я заберу это после праздников. Хотел бы получить обратную связь, если вы думаете, что это даже идет в правильном направлении или нет.

Вопросов

• Что означает "memberof": "yaxis" в доклете tooltipValueFormat ?
• Одно из значений context - это PlotLineOrBand но я не вижу этого в документах классов, является ли это подклассом Series ?
• plotOptions.series.states имеет имя типа доклета "plotOptions.series.states" - означает ли это что-то особенное?

@aaronbeall есть ли у тебя какие-нибудь успехи? Я также немного погрузился в генерацию шрифтов для высоких диаграмм.

Один из основных недостатков состоит в том, что сгенерированный tree.json не содержит всех типизаций highcharts, таких как статические методы в пространстве имен highcharts. После обрезки допустимых символов остается 703 символа. Но после этого выводимых символов в tree.json будет около 100. Многие из них игнорируются.

@ scott-ho Это было немного из-за того, что я ушел из проекта, используя Highcharts в новом году, но я вернулся к нему сейчас и скоро вернусь в этот проект.

Из моего последнего сообщения я пошел по пути преобразования type в interface и использования extends вместо & (это была моя стратегия для правильной поддержки tree.json использование excludes определенных полей), и столкнулись с проблемами: TS не позволит интерфейсу расширять другой интерфейс, который имеет общее имя поля, которое является типом объекта, который не имеет общего 1 объект. Вот абстрактный пример. Я забыл точные примеры этого, с которыми я столкнулся, но их было много из-за того, что tree.json свободно расширяет объекты (в некоторых случаях цепочки расширений превышают 5) и свободно исключает поля в любой момент. Это заставило меня подумать, что мой предыдущий подход с использованием типов пересечений & может быть лучшим маршрутом. В основном это приведет к тому, что некоторые свойства, которые «исключены», на самом деле не будут отображаться в подсказке типа (потому что они объединены из чего-то более высокого в дереве, что не может быть исключено из текущего узла), но я не могу придумайте лучший способ сделать это. Документы обходят эту проблему, потому что они отображают свойства из одной точки, но структурно мы не можем описать типы таким образом, не отказавшись от extends и создав тонну в основном повторяющихся определений типов.

После обрезки допустимых символов остается 703 символа. Но после этого выводимых символов в tree.json будет около 100. Многие из них игнорируются.

Какой метод обрезки вы имеете в виду? С этим было сложнее всего справиться ...

Да, я также заметил, что классы / пространства имен не описаны в tree.json (это в основном описывает декларативные параметры инициализации, как я это понимаю), но @cvasseng сказал, что это ванильный jsdoc3, поэтому, надеюсь, мы можем использовать стандартный конвертер для этого.

pruning ссылается на эту строку .

Весь сбор данных для tree.json внутри метода publish .

Я думаю, что внутри него могло быть неправильное использование jsdoc api.

Мы могли бы придумать лучший способ сгенерировать новую версию tree.json на основе исходного вывода jsdoc.

Сегодня я потратил некоторое время, чтобы узнать, что представляют собой tree.json . Затем я наконец понял, что tree.json содержит только типы параметров диаграммы. См. Здесь https://api.highcharts.com/highcharts/.

Логика сбора и генерации типов написана здесь - https://github.com/highcharts/highcharts/blob/master/tools/jsdoc/plugins/highcharts.jsdoc.js.

Возможно, нам придется самостоятельно сгенерировать полную версию типов и сделать что-то похожее на https://github.com/englercj/tsd-jsdoc.

Есть ли для этого расчетное время прибытия? Определения в DefininiteTyped довольно ужасны.

Думали ли вы поговорить с командой TypeScript о недостающих функциях, которые вам нужны? Я уверен, что они прислушаются к потребностям проекта размером с Highcharts, и у них довольно быстрый цикл выпуска.

@aaronbeall Вы смотрели сопоставленные типы ?

Вот ссылка с исправлением для вашего примера

@cvasseng @TorsteinHonsi

Думали ли вы поговорить с командой TypeScript о недостающих функциях, которые вам нужны?

@JannesMeyer К сожалению, нет Omit<> работает, чтобы разобрать вещи ... но проблемы для меня больше связаны с тем, как определить способ определения структуры данных Highcharts в пригодном для использования , полные, эргономичные определения типов. Похоже, что определения должны быть минимально определены (т.е. не переопределять одно и то же свойство для похожих объектов повсюду), но ничего не упускать. Наличие опции, отображаемой в автозавершении типа, которую Highcharts фактически не использует в данном контексте, является меньшей проблемой, чем отсутствие чего-то, что должно быть там. Также существует проблема отсутствия схемы документа, что приводит к универсальным типам object или any ... где-то кто-то должен записать тип, генерация типов не может сделать это за вас.

Да, в этом есть смысл. Похоже, что команде Highcharts следует принять TypeScript немного больше, чем сейчас. Может быть, было бы даже возможно генерировать документы из определений типов вместо того, чтобы создавать их из jsdoc?

@JannesMeyer #

Я слежу за этой публикацией, и будет очень полезно, если будет доступен файл декларации.
Я использовал DefenentyTyped для нашего проекта React / Typescript. Однако застрял на доступности. не понимал, что часть доступности не будет работать с DefenitoTyped. Я связался со службой поддержки Highcharts по поводу моей проблемы, но мне пока не повезло.
В нашей команде мы активно используем Highcharts / Highmaps. Поэтому мы вложили в это деньги. Пожалуйста, подумайте о приоритетах этого проекта.

Заранее спасибо!

Хочу сразу сообщить, что этот вопрос стал приоритетным.

Команда Highcharts ( @sophiebremer и @oysteinmoseng ) фактически присоединилась ко мне к сеансу отладки и помогла мне решить эту проблему, загрузив файлы Js напрямую. Я очень ценю время и решение, которое они предоставили, чтобы разблокировать меня в данный момент. Ожидайте появления файла декларации TS с Highcharts как окончательного решения. :)

Спасибо @sophiebremer, уделяя этому приоритетное внимание. Это будет очень полезно для проектов, использующих Typescript.

Примечание: я отредактировал комментарий, чтобы обеспечить лучший контекст, а также поблагодарить людей из команды Highcharts.

Мы интенсивно используем Highstock в большой команде, работающей с angular / typescript. Для нас было бы здорово иметь определения машинописного текста, мы думали, что определения из Определенного Типа были справочными, но они полностью устарели для Highstock ..

Эти определения машинописного текста действительно очень нужны нам!
Приветствуется любое ETA :)

Сейчас мы работаем над качеством и стараемся уменьшить количество генерируемых интерфейсов в дереве опций Highcharts. После этого мы начнем публичную бета-фазу.

Наше расчетное время прибытия - это 3-й квартал 2018 года для бета-тестирования.

@sophiebremer Это отличные новости! У вас есть генератор DTS или вы используете существующий инструмент преобразования?

Мы используем нестандартный. Мы попробовали подход этого запроса на перенос https://github.com/highcharts/highcharts/pull/8307, используя dts-dom внизу, но это не сработало.

Есть новости по этому поводу? Похоже, что @types/highcharts больше не обновляется.

Мы все еще работаем над этим в первоочередном порядке. К сожалению, сейчас я не могу опубликовать превью декларации. Есть еще типы, которые нужно объединить или ввести. "Highcharts.d.ts" будет огромным файлом, содержащим более 200 000 строк объявлений и комментариев.

@sophiebremer, как вы создаете этот файл? Вручную?

@ Скотт-Хо
Хотя файлы объявлений создаются автоматически, исправление и обновление доклетов в исходном коде выполняется вручную.

Всем привет! Я опубликовал превью объявлений Highcharts в моем личном репозитории. Вы можете протестировать его с помощью npm i https://github.com/sophiebremer/highcharts-declarations-alpha.git или загрузить объявление с https://github.com/sophiebremer/highcharts-declarations-alpha/blob/master/highcharts.d.ts и поместить его прямо в ./node_modules/highcharts/ . Сообщите нам, работает ли декларация у вас или у вас возникли проблемы. Спасибо!

Известные вопросы:

• тип закрепления в свойстве options.series не работает. Обходной путь прямо сейчас - привести объект к типу вашей серии, например { data: [0, 1, 2]} as Highcharts.SeriesLineOptions
• параметры стиля не везде относятся к типу CSSObject

Функции ChartEventsOptions, такие как выбор, похоже, не принимают параметр функции события

Пара других проблем, которые я обнаружил

• Невозможно импортировать модули экспорта и автономного экспорта. Мне пришлось изменить export = factory, чтобы экспортировать factory по умолчанию и использовать его как импорт по умолчанию

• Модуль отсутствующих аннотаций

• PlotSeriesEventsOptions click необходимо изменить как click ?: (e: PointerEventObject) => boolean;

Спасибо за отзыв, @muperi !
Некоторые комментарии к вашему второму посту:

• Обычные модули не экспортируют по умолчанию. Проверьте настройки ES6 в tsconfig.
• Лишь у нескольких модулей есть объявления. Мы, конечно, добавим больше в ближайшие пару месяцев.
• Мы займемся этим вопросом.

Функции ChartEventsOptions, такие как выбор, похоже, не принимают параметр функции события

Исправление является частью highcharts / highcharts # 9110 и будет включено в следующее обновление https://github.com/highcharts/highcharts-declarations-beta.

Пожалуйста, добавьте дополнительные проблемы с файлами объявлений в этот репозиторий: https://github.com/highcharts/highcharts-declarations-beta.

Спасибо.