@vitarx/plugin-vite 1.0.1 → 1.0.2-alpha.0

package/dist/utils/jsx-helpers.js

@@ -1,5 +1,6 @@
 /**
  * JSX 相关工具函数
+ * 提供 JSX 元素的各种操作和判断方法
  * @module utils/jsx-helpers
  */
 import * as t from '@babel/types';
@@ -9,22 +10,30 @@ import { createError } from '../error.js';
 import { isWhitespaceJSXText } from './ast-guards.js';
 /**
  * 获取 JSX 元素的名称
+ * @param node - JSX 元素节点
+ * @returns 元素名称（Identifier）或 null（MemberExpression）
  */
 export function getJSXElementName(node) {
     const nameNode = node.openingElement.name;
+    // 只处理简单标识符，MemberExpression 返回 null
     return nameNode.type === 'JSXIdentifier' ? nameNode.name : null;
 }
 /**
  * 将 JSX 元素名称节点转换为 createView 的类型表达式
  * JSXIdentifier → Identifier（组件）或 StringLiteral（原生元素）
  * JSXMemberExpression → MemberExpression（如 Obj.Key → Obj.Key）
+ * @param node - JSX 元素节点
+ * @returns 类型表达式或 null
  */
 export function resolveJSXElementType(node) {
     const nameNode = node.openingElement.name;
+    // 处理简单标识符（如 <div> 或 <Component>）
     if (nameNode.type === 'JSXIdentifier') {
         const name = nameNode.name;
+        // 原生元素转为字符串，组件转为标识符
         return isNativeElement(name) ? t.stringLiteral(name) : t.identifier(name);
     }
+    // 处理成员表达式（如 <Obj.Key>）
     if (nameNode.type === 'JSXMemberExpression') {
         return jsxMemberExprToMemberExpr(nameNode);
     }
@@ -33,8 +42,11 @@ export function resolveJSXElementType(node) {
 /**
  * 递归转换 JSXMemberExpression 为 MemberExpression
  * Obj.Key → Obj.Key, A.B.C → A.B.C
+ * @param node - JSXMemberExpression 节点
+ * @returns MemberExpression 节点
  */
 function jsxMemberExprToMemberExpr(node) {
+    // 递归处理对象部分
     const object = node.object.type === 'JSXMemberExpression'
         ? jsxMemberExprToMemberExpr(node.object)
         : t.identifier(node.object.name);
@@ -42,18 +54,27 @@ function jsxMemberExprToMemberExpr(node) {
 }
 /**
  * 判断名称是否为纯编译组件
+ * 纯编译组件在编译时完全展开，不会生成运行时调用
+ * @param name - 元素名称
+ * @returns 是否为纯编译组件
  */
 export function isPureCompileComponent(name) {
     return PURE_COMPILE_COMPONENTS.includes(name);
 }
 /**
  * 判断名称是否为组件（首字母大写）
+ * 遵循 React/Vue 的组件命名约定
+ * @param name - 元素名称
+ * @returns 是否为组件
  */
 export function isComponent(name) {
     return name.length > 0 && name[0] === name[0].toUpperCase();
 }
 /**
  * 判断名称是否为原生元素
+ * 原生元素使用小写字母开头
+ * @param name - 元素名称
+ * @returns 是否为原生元素
  */
 export function isNativeElement(name) {
     return !isComponent(name);

package/dist/utils/pattern-helpers.d.ts

@@ -7,14 +7,14 @@ import type { LVal, ObjectPattern } from '@babel/types';
 /**
  * 从绑定模式中收集变量名
  * 支持标识符、对象模式、数组模式
- * @param pattern - 绑定模式
- * @param variables - 变量名集合
+ * @param pattern - 绑定模式节点
+ * @param variables - 存储变量名的集合
  */
 export declare function collectPatternBindings(pattern: LVal, variables: Set<string>): void;
 /**
  * 从对象解构模式中收集变量名
  * 专门用于 toRefs 解构场景
- * @param pattern - 对象模式
- * @param variables - 变量名集合
+ * @param pattern - 对象模式节点
+ * @param variables - 存储变量名的集合
  */
 export declare function collectObjectPatternBindings(pattern: ObjectPattern, variables: Set<string>): void;

package/dist/utils/pattern-helpers.js

@@ -1,26 +1,32 @@
 /**
  * 从绑定模式中收集变量名
  * 支持标识符、对象模式、数组模式
- * @param pattern - 绑定模式
- * @param variables - 变量名集合
+ * @param pattern - 绑定模式节点
+ * @param variables - 存储变量名的集合
  */
 export function collectPatternBindings(pattern, variables) {
+    // 处理简单标识符
     if (pattern.type === 'Identifier') {
         variables.add(pattern.name);
     }
     else if (pattern.type === 'ObjectPattern') {
+        // 处理对象解构模式
         for (const prop of pattern.properties) {
             if (prop.type === 'RestElement') {
+                // 处理剩余运算符（...rest）
                 collectPatternBindings(prop.argument, variables);
             }
             else {
+                // 处理普通属性，递归收集 value
                 collectPatternBindings(prop.value, variables);
             }
         }
     }
     else if (pattern.type === 'ArrayPattern') {
+        // 处理数组解构模式
         for (const elem of pattern.elements) {
             if (elem) {
+                // 递归处理每个非空元素
                 collectPatternBindings(elem, variables);
             }
         }
@@ -29,18 +35,21 @@ export function collectPatternBindings(pattern, variables) {
 /**
  * 从对象解构模式中收集变量名
  * 专门用于 toRefs 解构场景
- * @param pattern - 对象模式
- * @param variables - 变量名集合
+ * @param pattern - 对象模式节点
+ * @param variables - 存储变量名的集合
  */
 export function collectObjectPatternBindings(pattern, variables) {
     for (const prop of pattern.properties) {
         if (prop.type === 'RestElement') {
+            // 处理剩余运算符
             collectPatternBindings(prop.argument, variables);
         }
         else if (prop.value.type === 'Identifier') {
+            // 处理简单标识符属性
             variables.add(prop.value.name);
         }
         else if (prop.value.type === 'ObjectPattern') {
+            // 处理嵌套对象解构，递归收集
             collectObjectPatternBindings(prop.value, variables);
         }
     }

package/dist/utils/vif-helpers.d.ts

@@ -15,14 +15,22 @@ export interface VIfChainInfo {
 }
 /**
  * 验证 v-if 链的合法性
+ * 检查语法错误，如顺序不当、v-else 不是最后一个等
+ * @param children - v-if 链的元素数组
  */
 export declare function validateVIfChain(children: t.JSXElement[]): void;
 /**
  * 从 JSX 元素数组收集 v-if 链信息
+ * 要求所有元素都属于 v-if 链（之前已验证）
+ * @param nodes - JSX 元素数组
+ * @returns v-if 链信息对象
  */
 export declare function collectVIfChainInfo(nodes: t.JSXElement[]): VIfChainInfo;
 /**
  * 收集 Fragment 中的 v-if 链
+ * 从 Fragment 的子元素中识别多个独立的 v-if 链
+ * @param children - Fragment 的子节点数组
+ * @returns v-if 链信息数组
  */
 export declare function collectFragmentVIfChains(children: t.Node[]): Array<VIfChainInfo & {
     endIndex: number;

package/dist/utils/vif-helpers.js

@@ -10,24 +10,31 @@ import { isWhitespaceJSXText } from './ast-guards.js';
 import { getDirectiveValue, hasDirective, isVElse, isVElseIf, isVIf, isVIfChain } from './jsx-helpers.js';
 /**
  * 验证 v-if 链的合法性
+ * 检查语法错误，如顺序不当、v-else 不是最后一个等
+ * @param children - v-if 链的元素数组
  */
 export function validateVIfChain(children) {
     if (children.length === 0)
         return;
+    // 第一个元素必须有 v-if 指令
     if (!hasDirective(children[0], 'v-if')) {
         throw createError('E008', children[0], 'First element must have v-if directive');
     }
+    // 验证后续元素
     for (let i = 1; i < children.length; i++) {
         const child = children[i];
         const prevChild = children[i - 1];
         const hasVElseIf = hasDirective(child, 'v-else-if');
         const hasVElse = hasDirective(child, 'v-else');
+        // 后续元素必须是 v-else-if 或 v-else
         if (!hasVElseIf && !hasVElse) {
             throw createError('E008', child, 'Elements after v-if must have v-else-if or v-else directive');
         }
+        // v-else 必须是最后一个元素
         if (hasVElse && i !== children.length - 1) {
             throw createError('E008', child, 'v-else must be the last element');
         }
+        // v-else-if 不能接在 v-else 后面
         if (hasVElseIf && hasDirective(prevChild, 'v-else')) {
             throw createError('E008', child, 'v-else-if cannot follow v-else');
         }
@@ -35,54 +42,72 @@ export function validateVIfChain(children) {
 }
 /**
  * 从 JSX 元素数组收集 v-if 链信息
+ * 要求所有元素都属于 v-if 链（之前已验证）
+ * @param nodes - JSX 元素数组
+ * @returns v-if 链信息对象
  */
 export function collectVIfChainInfo(nodes) {
     const conditions = [];
+    // 遍历每个节点，收集对应的条件
     for (const node of nodes) {
         const vIfValue = getDirectiveValue(node, 'v-if');
         if (vIfValue) {
+            // v-if 直接使用其条件表达式
             conditions.push(vIfValue);
             continue;
         }
         const vElseIfValue = getDirectiveValue(node, 'v-else-if');
         if (vElseIfValue) {
+            // v-else-if 直接使用其条件表达式
             conditions.push(vElseIfValue);
             continue;
         }
         if (hasDirective(node, 'v-else')) {
+            // v-else 使用 true 作为条件（默认情况）
             conditions.push(t.booleanLiteral(true));
             continue;
         }
+        // 理论上不会走到这里，因为之前已验证
         throw createError('E008', node, 'Element missing v-if/v-else-if/v-else directive');
     }
     return { nodes, conditions, startIndex: 0, endIndex: nodes.length - 1 };
 }
 /**
  * 收集 Fragment 中的 v-if 链
+ * 从 Fragment 的子元素中识别多个独立的 v-if 链
+ * @param children - Fragment 的子节点数组
+ * @returns v-if 链信息数组
  */
 export function collectFragmentVIfChains(children) {
     const chains = [];
     let i = 0;
+    // 遍历所有子节点
     while (i < children.length) {
         const child = children[i];
+        // 跳过文本节点
         if (isJSXText(child)) {
             i++;
             continue;
         }
+        // 跳过非 JSXElement 节点
         if (!isJSXElement(child)) {
             i++;
             continue;
         }
+        // 跳过不属于 v-if 链的元素
         if (!isVIfChain(child)) {
             i++;
             continue;
         }
+        // 处理 v-if 开头的链
         if (isVIf(child)) {
             const chain = collectSingleChainFromFragment(children, i);
             chains.push(chain);
+            // 跳到链结束的下一个位置
             i = chain.endIndex + 1;
         }
         else if (isVElseIf(child) || isVElse(child)) {
+            // v-else-if 或 v-else 不能单独出现
             throw createError(isVElse(child) ? 'E003' : 'E004', child);
         }
         else {
@@ -93,33 +118,44 @@ export function collectFragmentVIfChains(children) {
 }
 /**
  * 从 Fragment 收集单个 v-if 链
+ * 从 v-if 开始，收集后续连续的 v-else-if 和 v-else
+ * @param children - Fragment 的子节点数组
+ * @param startIndex - v-if 起始索引
+ * @returns 单个 v-if 链信息
  */
 function collectSingleChainFromFragment(children, startIndex) {
     const nodes = [children[startIndex]];
     const conditions = [getDirectiveValue(nodes[0], 'v-if')];
     let j = startIndex + 1;
+    // 继续收集后续的 v-else-if 和 v-else
     while (j < children.length) {
         const nextChild = children[j];
+        // 跳过空白文本节点（允许链元素间有空白）
         if (isJSXText(nextChild) && isWhitespaceJSXText(nextChild)) {
             j++;
             continue;
         }
+        // 遇到非 JSXElement，链结束
         if (!isJSXElement(nextChild))
             break;
+        // 遇到不属于 v-if 链的元素，链结束
         if (!isVIfChain(nextChild))
             break;
         if (isVElseIf(nextChild)) {
+            // 收集 v-else-if
             nodes.push(nextChild);
             conditions.push(getDirectiveValue(nextChild, 'v-else-if'));
             j++;
         }
         else if (isVElse(nextChild)) {
+            // 收集 v-else 并结束链
             nodes.push(nextChild);
             conditions.push(t.booleanLiteral(true));
             j++;
             break;
         }
         else {
+            // 其他情况，链结束
             break;
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitarx/plugin-vite",
-  "version": "1.0.1",
+  "version": "1.0.2-alpha.0",
   "description": "The official plugin for Vitarx support in Vite.",
   "author": "ZhuChongLin <8210856@qq.com>",
   "license": "MIT",