处理事件、Props 和指令

VTJ 引擎提供了一个复杂的系统，用于解析、管理和生成 Vue 组件的事件、属性和指令。该架构支持 Vue 源代码和 DSL 模式之间的无缝双向转换，同时支持静态和动态绑定，并具备完整的类型安全和代码保留能力。

架构概览

事件、属性和指令处理系统跨越三个核心层：数据模型、解析与转换和代码生成。这种分层方法确保了你在将 Vue 代码转换为 DSL 或从 DSL 生成 Vue 代码时的一致性。

该架构通过定义 DSL 格式的协议接口维护单一事实来源，而模型类则提供具有自动 DSL 序列化功能的运行时操作能力。

属性管理

VTJ 中的属性支持静态值和动态 JavaScript 表达式，并对 style 和 class 属性进行特殊处理，以在代码转换期间保持视觉保真度。

数据模型结构

PropModel 类封装了属性定义，并具有智能默认值跟踪功能：

class PropModel {
  name: string;
  value?: JSONValue | JSExpression | JSFunction;
  defaultValue?: JSONValue | JSExpression | JSFunction;
  isUnset: boolean; // 跟踪值是否与默认值匹配
}

isUnset 标志对于 DSL 序列化至关重要——与默认值匹配的属性将从生成的模式中排除，从而保持 DSL 文件最小化。静态值直接作为 JSON 值存储，而动态绑定则使用格式为 { type: 'JSExpression', value: string } 的 JSExpression。

从 Vue 模板解析属性

模板解析器处理两类属性：

属性类型	示例	解析策略
静态	type="text"	直接字符串提取
动态 (v-bind)	:type="fieldType"	包装为 JSExpression
样式属性	style="color: red"	解析为 JSON 对象
类属性	class="btn primary"	保留为字符串数组

对于类属性，解析器采用复杂的正则表达式匹配来从类名中提取生成的 CSS 选择器（模式：word_5+characters），并将它们映射到解析的 CSS 规则中的样式定义。这实现了作用域样式的双向转换。

从 DSL 生成 Vue 属性

代码生成器通过类型感知转换处理属性绑定：

function bindProp(name, value, computedKeys) {
  // 样式：仅动态表达式
  if (name === "style" && isJSCode(value)) {
    return `:style="${parseValue(value)}"`;
  }

  // 静态字符串
  if (typeof value === "string") {
    return `${name}="${value}"`;
  }

  // 动态绑定
  if (isJSCode(value)) {
    return `:${name}="${parseValue(value)}"`;
  }

  // 对象字面量
  if (isPlainObject(value)) {
    return `:${name}='{${parsePlainObjectValue(value)}}'`;
  }
}

特殊处理将复杂的样式对象转换为作用域 CSS 类。系统生成唯一的类名（componentName_nodeId）并将样式提取到单独的 CSS 规则中，防止内联样式膨胀，同时保持设计保真度。

事件处理

VTJ 提供全面的事件解析，通过双向转换过程保留事件处理程序、内联逻辑和 Vue 事件修饰符。

事件数据模型

事件建模时完整保留了处理程序：

interface NodeEvent {
  name: string; // 事件名称（例如，'click'）
  handler: JSFunction; // 处理程序函数代码
  modifiers?: Record<string, boolean>; // 事件修饰符
}

class EventModel {
  name: string;
  handler: JSFunction;
  modifiers: NodeModifiers;
}

处理程序存储对组件 methods 对象中定义的命名方法的引用，或用于立即事件处理的内联箭头函数。修饰符存储为 Vue 内置修饰符（.prevent, .stop, .once, .capture, .passive, .self, .right, .middle, .left）的布尔标志。

从 Vue 模板解析事件

事件解析器处理 v-on 指令（简写 @）并提取命名处理程序和内联逻辑：

// 使用修饰符解析 v-on
<input @click.stop="handleSubmit" />

// 解析内联逻辑
<button @click="loading = !loading">Toggle</button>

// 解析 $event 使用
<input @input="handleInput($event)" />

解析器通过正则表达式模式匹配识别命名处理程序（处理程序名称以 _5+characters 唯一后缀结尾）。对于内联逻辑，它在必要时将代码包装在箭头函数语法中，处理简单赋值和复杂表达式。

从 DSL 生成 Vue 事件

事件生成重构原始 Vue 事件绑定语法：

function bindEvent(name, value, binder, nodeContext, isExp) {
  const { handler, modifiers } = value;
  const modifierStr = Object.entries(modifiers || {})
    .filter(([, v]) => v)
    .map(([k]) => `.${k}`)
    .join("");

  return `@${name}${modifierStr}="${handler.value}"`;
}

系统跟踪事件上下文依赖项，将处理程序名称添加到上下文集中以进行依赖分析和热重载场景。这使渲染器能够理解组件更新时需要重新生成哪些处理程序。

💡 Vue 模板中内联定义的事件处理程序在解析期间会自动转换为箭头函数，以保留作用域。例如，@click="count++" 变为 ($event) => { count++ }，以确保处理程序在正确的上下文中执行。

指令处理

VTJ 支持 Vue 内置指令和自定义指令，完全保留参数、修饰符和迭代元数据。

指令数据模型

指令建模以捕获所有 Vue 指令功能：

interface NodeDirective {
  id?: string; // 唯一标识符
  name: string | JSExpression; // 指令名称
  arg?: string | JSExpression; // 指令参数
  modifiers?: NodeModifiers; // 修饰符标志
  value?: JSExpression; // 表达式值
  iterator?: {
    // v-for 迭代数据
    item: string;
    index: string;
  };
}

每个指令都有一个唯一的 ID（如果未提供则自动生成），用于在设计器操作和热重载期间进行跟踪。iterator 字段专门捕获 v-for 循环变量名称，用于生成具有作用域感知的代码。

内置指令解析

解析器分类并处理 Vue 的核心指令：

指令	DSL 名称	关键属性
v-if / v-else-if / v-else	vIf / vElseIf / vElse	条件表达式或布尔值
v-for	vFor	值表达式、迭代器
v-model	vModel	绑定参数、值表达式
v-show	vShow	布尔表达式
v-bind (无参数)	vBind	对象表达式
v-html	vHtml	HTML 内容表达式
自定义指令	原始名称	名称、参数、修饰符、值

对于条件指令（v-if/v-else-if/v-else），解析器跟踪分支关系并将条件与正确的分支节点关联。v-for 指令提取数据源表达式和迭代变量别名，用于生成具有作用域的变量。

从 DSL 生成 Vue 指令

代码生成器使用适当的 Vue 格式重构指令语法：

function parseDirectives(directives, computedKeys, output) {
  directives.forEach((item) => {
    const { name, arg, modifiers, value, iterator } = item;

    // v-if / v-else-if / v-else
    if (["vIf", "vElseIf", "vElse"].includes(name)) {
      output.push(`${name}="${value?.value || ""}"`);
    }

    // v-for
    else if (name === "vFor") {
      const { item, index } = iterator || {};
      output.push(`v-for="(${item}, ${index}) in ${value?.value}"`);
    }

    // 带参数的 v-model
    else if (name === "vModel") {
      const modStr = getModifiers(modifiers);
      output.push(`v-model${arg ? ":" + arg : ""}${modStr}="${value?.value}"`);
    }

    // 自定义指令
    else {
      const modStr = getModifiers(modifiers);
      output.push(
        `v-${name}${arg ? ":" + arg : ""}${modStr}="${value?.value}"`,
      );
    }
  });
}

系统通过 directivesRegister() 支持指令注册，允许正确映射和生成自定义指令。计算值替换确保在生成的代码中保持响应式依赖关系。

高级功能

修饰符支持

事件和指令都支持修饰符处理，并具有自动语法重构功能：

function getModifiers(modifiers = {}) {
  return Object.entries(modifiers)
    .filter(([, enabled]) => enabled)
    .map(([key]) => `.${key}`)
    .join("");
}

修饰符存储为布尔映射（{ prevent: true, stop: false }），并在代码生成期间转换为点表示法（.prevent）。

表达式跟踪

解析器通过模块级变量维护表达式、处理程序和指令的全局上下文跟踪：

let __handlers: Record<string, JSFunction> = {};
let __directives: Record<string, JSExpression> = {};
let __context: Record<string, Set<string>> = {};

这能够在模板解析期间进行跨文件引用解析和依赖项跟踪，对于准确的代码生成和热重载至关重要。

计算值替换

从 DSL 生成代码时，计算属性引用会自动替换为其正确的上下文：

function replaceComputedValue(value: string, computedKeys: string[]) {
  return computedKeys.reduce((result, key) => {
    return result.replace(new RegExp(`\\b${key}\\b`, "g"), `${key}.value`);
  }, value);
}

这确保了 refs 和计算属性在生成的 Vue 3 组合式 API 代码中正常工作。

双向转换工作流

处理事件、属性和指令的完整工作流遵循以下阶段：

解析器从 Vue 模板 AST 节点提取所有属性，按类型（属性/指令）分类，并将它们转换为适当的 DSL 模型格式。生成器执行逆操作，读取 DSL 模式并使用适当的间距、引号和修饰符位置重构语法正确的 Vue 模板代码。

与其他系统的集成

渲染器集成

渲染器使用模型类在运行时操作组件属性：

// 更新属性值
const prop = node.props["disabled"];
prop.setValue(false);

// 更新事件处理程序
const event = node.events["click"];
event.update({
  handler: { type: "JSFunction", value: "() => handleClick()" },
});

渲染器可以通过更新模型实例动态修改组件行为，并通过自动 DSL 序列化反映更改。

设计器集成

设计器 UI 使用这些模型进行属性面板和事件绑定编辑。EventModel.update() 和 DirectiveModel.update() 方法提供响应式更新，这些更新传播到设计器的预览和底层 DSL 模式。

最佳实践

事件处理程序组织

• 优先使用命名方法而不是内联处理程序，以提高可维护性
• 仅对简单的单行操作使用内联处理程序
• 利用事件修饰符（.prevent, .stop）代替手动方法调用

属性默认值

• 始终为可选属性指定默认值
• 序列化 DSL 时使用 isUnset 标志检测以排除冗余数据
• 如果不需要默认值，请考虑使用 undefined 而不是显式默认值

指令使用

• 使用 v-for 的迭代器功能显式命名循环变量
• 将 v-if/v-else-if/v-else 组合在 DSL directives 数组中以进行逻辑分组
• 通过提供者系统注册自定义指令，以实现一致的代码生成

代码转换

• 解析复杂组件时，在 parseTemplate() 中启用 handlers 和 directives 选项以保留上下文
• 为 Vue 3 组合式 API 生成代码时，使用计算键替换
• 为生成的 CSS 类选择器保持一致的命名约定

💡 集成自定义组件时，请确保在提供者的指令配置中注册所有自定义指令。这使解析器能够识别它们，并使生成器能够输出正确的语法，而无需回退到字符串插值。

参考资料

• 官方文档：https://vtj.pro/
• 在线平台：https://app.vtj.pro/
• 开源仓库：https://gitee.com/newgateway/vtj