опубликовано вчераvuese1.0, это мой новый проект с открытым исходным кодом для анализа Vue SFC и создания документов уценки, здесь:GitHub.com/HC имеет Сунь Ян/….
В этой статье не будет описываться, как им пользоваться, что касается того, как им пользоваться, вы можете ознакомиться с ним.readme, здесь в основном речь идет об идее реализации.
1. Мотивация
У вас или вашей команды может быть собственная библиотека компонентов (или просто компонент).Обычно при разработке компонента вам нужно вручную писать уценочные документы, чтобы другие могли понять, как используется компонент. Проблема здесь в том, что если компонент постоянно обновляется, вам приходится вручную поддерживать соответствующую документацию, чтобы она соответствовала функциональности компонента. На самом деле, этот процесс немного отвратительный🤢, так что есть способ лучше? На основе этого я разработалvuese.
2. Идеи
мы знаемvueИнтерфейс, предоставляемый компонентом, представляет собой не что иное, какprops,events,slots(илиscopedSlots) и частьmethods. Итак, можем ли мы реализовать инструмент, который поможет нам проанализировать компонент vue и извлечь эту информацию? Затем документация генерируется автоматически, поэтому независимо от того, как изменяется компонент, нам не нужно поддерживать документацию вручную, просто используйте инструмент для ее повторного создания.
3. Основные идеи
дляvueкомпоненты, если не учитыватьstyleи пользовательский блок, то он состоит из двух частей, а именно: шаблонной иscriptкусок. даже при использованииrenderЕсли функция заменяет шаблон, то остается только одинscript.
заprops,methodsони могут быть толькоscirptОпределяется внутри блока, например:
props: {
name: String
}
methods: {
clear () {/*...*/}
}
Для слотов это можно определить либо в блоке скрипта, либо в шаблоне, например:
<!-- 在模板中定义 -->
<div>
<slot name="header" />
</div>
// 在 script 块内定义了 slots
render (h) {
return h('div', this.$slots.header)
}
Вышеуказанные два способа записи эквивалентны, поэтому при извлеченииslotsинформация, которую необходимо учитывать в шаблонеslots, но и совместимыscriptвнутри блокаslots.
А в функциональных компонентах все следующее должно обрабатываться как слоты:
// ctx.slots()
render (h, ctx) {
return h('div', ctx.slots().xxx)
}
// ctx.children
render (h, ctx) {
return h('div', ctx.children)
}
Это то, что мы извлекаемslotsинформацию необходимо учитывать.
Точно так же дляeventsОн также может отображаться в шаблоне, но также и вscriptблокировать следующим образом:
<!-- 模板中的 events -->
<div @click="$emit('onclear')"></div>
// 定义在 script 中的事件
methods: {
someMethod () {
this.$meit('onclear')
}
}
Итак, извлечениеeventsИнформация также должна учитывать как шаблон, так иscriptкусок.
Для шаблонов мы по умолчаниюhtmlсинтаксис, дляscriptблокировать по умолчаниюjs. Первое, что мы должны сделать, этоhtmlиjsДобывается и анализируется отдельно.К счастью, плечи великанов толстые, и уже есть@vue/component-compiler-utilsмодули иvue-template-compilerмодуль. где мы используем@vue/component-compiler-utilsМодуль анализирует vue SFC и получает исходный код html (шаблон) и JavaScript (блок скрипта) соответственно. Для источника html мы снова можем использоватьvue-template-compilerМодуль разбирает его в соответствующий шаблонAST, то, написавtraverseфункция, чтобы проанализировать его, прочитатьslotsсвязанный контент.
И дляJavaScriptДля обработки исходного кода я решил использоватьbabel7, написалbabelСтуденты-плагины, возможно, догадались об идее реализации. Мы передаем исходный код@babel/traversмодуля обработки, а затем, написав некоторыеhelperчтобы помочь нам определить, что действительно нужно обработать, как показано в следующем фрагменте исходного кода:
const mainTraveres = {
ObjectProperty(path: any) {
// Processing name
if (isVueOption(path, 'name')) {
if (onName) onName(path.node.value.value)
}
// Processing props
if (isVueOption(path, 'props')) {
// 一些逻辑
}
// more...
}
}
вisVueOptionФункция написана намиhelperфункция, которая поможет нам определить, является ли свойство объектаVueЕсли это определенный атрибут в объекте option, мы можем его дополнительно обработать.Обработка js в основном та же идея.Для получения дополнительной информации вы можете просмотреть исходный код:GitHub.com/HC имеет Сунь Ян/…
В-четвертых, генерируйте цели
После предыдущего шага мы можем написатьparserмодуль, разбираем и собираем нужный нам контент, после того, как у нас будет нужный нам контент, мы можем написатьRenderМодули — это, по сути, процесс генерации кода, а что касается сгенерированного контента, то это зависит от цели, которую вы хотите.vueseВстроенныйRenderбудет сгенерировано для вас на основе этой информацииmarkdownфайл или создать интеграциюdocuteдокументация. Но на самом деле, пока ваш мозг достаточно большой, вы можете генерировать что угодно.parserМодуль написан более совершенно, дляvueАнализ компонентов достаточно подробен, чтобы мы могли получитьvueВся информация о компоненте, а затем создание TS-совместимого компонента на этапе генерации кода Разве это не плагин, который преобразует компонент vue, написанный не на js, в ts-совместимый компонент vue? (Примечание: позже приятель предложил лучший способ добиться этого. Чтобы избежать смущения, я могу только сказать, что это тоже идея...)
Возвращаясь к встроенному модулю Render vuese, результатом Render является ресурс уценки, который, по сути, представляет собой процесс объединения строк.Подробности можно просмотреть в исходном коде.GitHub.com/HC имеет Сунь Ян/…, не сложно.
На самом деле vuese предоставляет массу полезной информации и функций, не отраженных в документации, которые будут постепенно добавляться в будущем. Например, файл уценки, сгенерированный с помощью vuese, выглядит примерно так:
Вы могли заметить, что приведенный выше файл уценки содержит много вещей, таких как:
<!-- @vuese:CompName:props:start -->
<!-- @vuese:CompName:props:end -->
аннотации, такие какvueseКуда следует поместить сгенерированный код уценки при создании документа?Если у компонента нет соответствующего документа уценки, он будет сгенерирован заново, в противном случае он будет обновлен на основе существующего документа. Целью этого является рассмотрение реальных сценариев использования, поскольку документация компонента может содержать не только содержимое, показанное на рисунке выше, но и демоверсии, написанные самими разработчиками, и другие описания. Таким образом, когда мы генерируем документ, мы не перезаписываем контент, написанный самим разработчиком, а вставляем сгенерированный контент в указанное место.
5. Планирование
На данный момент реализованы следующие функции Vuese:
Кроме того, система плагинов в настоящее время не поддерживается, что также планируется в будущем. И мы применили его для обслуживания документации внутренней библиотеки компонентов в нашей команде, а также планируем обратить внимание на vue3.0 и быть совместимым с ним. НаконецvueseВ только что выпущенной версии есть много недостатков, но с последующими обновлениями и итерациями она будет становиться все лучше и лучше, и заинтересованные студенты могут строить вместе.
Другие планы: мопс поддержки шаблонов, система плагинов, что еще? ? ? ? ? ?