登录
📘 全面解析：JavaScript 时间格式化 API 实战指南
2025年11月11日 07:31
——从 toUTCString() 到 Intl.DateTimeFormat 的深度理解 时间与日期，是前端开发中最容易“踩坑”的部分。不同浏览器、不同区域、甚至不同系统语言，都会造成输出不一致。
本文将深入剖析 Vue 单文件组件（SFC）编译器中的 defineEmits 处理逻辑，来自 compiler-sfc 模块的源码实现。
本文涵盖从概念、原理到实践的全链路分析，辅以详细注释与代码逐行解析。
一、概念：defineEmits 的定位与作用
在 Vue 3 的 <script setup> 中，defineEmits() 用于声明组件可以触发的事件。
例如：
const emit = defineEmits(['submit', 'cancel'])
emit('submit')
其核心目标是：
- 类型层面：提供 TypeScript 类型约束（确保事件名称正确）。
-
运行时层面：生成可用的
emits配置，供 Vue 组件选项使用。
在编译阶段，Vue 会分析 defineEmits() 的调用，提取其中的事件定义或类型信息，并生成最终的运行时代码。
二、原理：编译器的处理流程总览
defineEmits 的编译处理分为三个核心步骤：
-
检测与记录调用：
processDefineEmits- 识别
defineEmits()调用语句； - 检查重复定义；
- 区分运行时参数和类型参数；
- 保存到上下文（
ScriptCompileContext）。
- 识别
-
提取运行时声明：
extractRuntimeEmits- 若使用 TypeScript 类型参数（
defineEmits<{...}>()），提取其中的事件名称。
- 若使用 TypeScript 类型参数（
-
生成最终运行时代码：
genRuntimeEmits- 合并类型定义与
v-model的事件（如update:modelValue）； - 生成最终字符串代码片段。
- 合并类型定义与
三、源码逐行解析与注释
1. processDefineEmits
export function processDefineEmits(
ctx: ScriptCompileContext,
node: Node,
declId?: LVal,
): boolean {
if (!isCallOf(node, DEFINE_EMITS)) {
return false
}
说明：
通过isCallOf()检查当前 AST 节点是否为defineEmits()的调用，若不是则跳过。
if (ctx.hasDefineEmitCall) {
ctx.error(`duplicate ${DEFINE_EMITS}() call`, node)
}
说明：
Vue 组件中只能调用一次defineEmits，此处用于防止重复定义。
ctx.hasDefineEmitCall = true
ctx.emitsRuntimeDecl = node.arguments[0]
说明：
记录运行时参数（如['click', 'submit']）。
if (node.typeParameters) {
if (ctx.emitsRuntimeDecl) {
ctx.error(`${DEFINE_EMITS}() cannot accept both type and non-type arguments`, node)
}
ctx.emitsTypeDecl = node.typeParameters.params[0]
}
说明：
处理类型参数（如defineEmits<{ change: (value: string) => void }>()）。
同时检查不能混用类型参数与运行时参数。
ctx.emitDecl = declId
return true
}
说明：
保存声明标识符（如const emit = defineEmits(...)），供后续生成使用。
2. genRuntimeEmits
export function genRuntimeEmits(ctx: ScriptCompileContext): string | undefined {
let emitsDecl = ''
if (ctx.emitsRuntimeDecl) {
emitsDecl = ctx.getString(ctx.emitsRuntimeDecl).trim()
} else if (ctx.emitsTypeDecl) {
const typeDeclaredEmits = extractRuntimeEmits(ctx)
emitsDecl = typeDeclaredEmits.size
? `[${Array.from(typeDeclaredEmits)
.map(k => JSON.stringify(k))
.join(', ')}]`
: ``
}
说明：
这里根据上下文选择不同模式：
- 运行时参数：直接输出字符串。
- 类型参数：调用
extractRuntimeEmits从类型信息中提取事件名。
if (ctx.hasDefineModelCall) {
let modelEmitsDecl = `[${Object.keys(ctx.modelDecls)
.map(n => JSON.stringify(`update:${n}`))
.join(', ')}]`
emitsDecl = emitsDecl
? `/*@__PURE__*/${ctx.helper('mergeModels')}(${emitsDecl}, ${modelEmitsDecl})`
: modelEmitsDecl
}
return emitsDecl
}
说明：
若组件同时使用defineModel()，需合并update:modelValue事件。
生成形如：/*@__PURE__*/_mergeModels(["submit"], ["update:modelValue"])
3. extractRuntimeEmits
export function extractRuntimeEmits(ctx: TypeResolveContext): Set<string> {
const emits = new Set<string>()
const node = ctx.emitsTypeDecl!
说明：
当使用类型参数时，从类型 AST 中提取所有事件名称。
if (node.type === 'TSFunctionType') {
extractEventNames(ctx, node.parameters[0], emits)
return emits
}
说明：
若defineEmits是函数类型（如defineEmits<(e: 'click' | 'submit')>()），从参数中提取字符串字面量。
const { props, calls } = resolveTypeElements(ctx, node)
let hasProperty = false
for (const key in props) {
emits.add(key)
hasProperty = true
}
说明：
如果是对象类型{ change: (val: number) => void }，将键名作为事件名。
if (calls) {
if (hasProperty) {
ctx.error(`defineEmits() type cannot mixed call signature and property syntax.`, node)
}
for (const call of calls) {
extractEventNames(ctx, call.parameters[0], emits)
}
}
return emits
}
说明：
若类型中混合了函数签名与对象属性，会报错。
Vue 要求两者互斥，以保证一致性。
4. extractEventNames
function extractEventNames(
ctx: TypeResolveContext,
eventName: ArrayPattern | Identifier | ObjectPattern | RestElement,
emits: Set<string>,
) {
if (
eventName.type === 'Identifier' &&
eventName.typeAnnotation &&
eventName.typeAnnotation.type === 'TSTypeAnnotation'
) {
const types = resolveUnionType(ctx, eventName.typeAnnotation.typeAnnotation)
说明：
此函数用于处理联合类型，如：defineEmits<(e: 'a' | 'b' | 'c')>()
for (const type of types) {
if (type.type === 'TSLiteralType') {
if (
type.literal.type !== 'UnaryExpression' &&
type.literal.type !== 'TemplateLiteral'
) {
emits.add(String(type.literal.value))
}
}
}
}
}
说明：
从联合类型中提取所有字面量值，并存入事件集合。
四、对比分析：类型模式 vs 运行时模式
| 模式类型 | 示例 | 优点 | 缺点 |
|---|---|---|---|
| 运行时参数 | defineEmits(['click', 'change']) |
简单直观 | 无类型约束 |
| 类型参数 | defineEmits<{ change: (v: number) => void }>() |
完整类型推导 | 仅 TS 支持 |
| 函数签名参数 | `defineEmits<(e: 'a' | 'b')>()` | 可枚举事件字面量 |
Vue 的编译器在生成代码时，会自动兼容这些模式。
五、实践示例：从源码到生成代码
输入源代码：
const emit = defineEmits<{ submit: (data: any) => void, cancel: () => void }>()
编译器生成的运行时代码：
export default {
emits: ["submit", "cancel"]
}
如果存在 defineModel('value')：
export default {
emits: /*@__PURE__*/_mergeModels(["submit", "cancel"], ["update:value"])
}
六、拓展：与 defineProps、defineModel 的关系
-
defineProps：声明组件输入接口； -
defineEmits：声明组件输出事件； -
defineModel：语法糖，自动生成props+emits的绑定关系。
genRuntimeEmits 之所以会检测 hasDefineModelCall，正是为了保证双向绑定事件正确注入。
七、潜在问题与限制
-
混用类型与运行时参数报错
编译时强制互斥，否则抛出错误。 -
函数签名与对象类型混合报错
例如：defineEmits<{ submit: () => void (e: 'cancel'): void }>()这种混用是不被允许的。
-
无法动态计算事件名
所有事件名称必须为字面量常量，否则类型提取失败。
八、总结
processDefineEmits 是 Vue SFC 编译过程中负责 事件定义提取 的关键函数。
它结合类型系统与运行时声明，生成统一的 emits 数组，保证组件在类型安全与运行时行为之间的平衡。
核心价值：
- 静态分析事件声明；
- 支持 TypeScript 类型提取；
- 自动合并
v-model相关事件。
本文部分内容借助 AI 辅助生成，并由作者整理审核。
