Stencil 项目中引入 @Event 装饰器后构建报错，通常源于 Event 类型与原生 Web Event 接口冲突；通过显式使用 globalThis.Event 可彻底解决该问题。
stencil 项目中引入 `@event` 装饰器后构建报错，通常源于 `event` 类型与原生 web `event` 接口冲突；通过显式使用 `globalthis.event` 可彻底解决该问题。
在 Stencil 中，@Event 装饰器用于声明自定义事件并触发跨框架通信（如向 Angular 应用传递数据），但其类型系统与浏览器原生 Event 接口存在命名空间冲突——尤其当代码中同时引用了 Event（如 secondMethod(event: Event)）和 @Event 装饰器时，TypeScript 无法准确推断类型上下文，导致构建阶段静默失败（常见表现为 Promise<void> 红色波浪线、无明确错误信息）。
该问题并非 Stencil 独有，而是 TypeScript 在全局类型合并场景下的典型歧义行为。官方文档及多个 GitHub issue（#4681、#3037）均确认此为已知限制，并推荐标准化规避方案：始终为原生 DOM 事件参数显式指定 globalThis.Event 类型，以明确区分于 Stencil 的 @Event 装饰器。
✅ 正确写法如下：
import { Component, Method, Host, h, Prop, Event, EventEmitter } from '@stencil/core';
@Component({
tag: 'my-component',
styleUrl: 'my-component.css',
shadow: false,
})
export class MyComponent {
@Prop() value: string;
@Event({ eventName: 'a-click' })
onClick: EventEmitter<string>;
@Method()
async handleClick(): Promise<void> {
this.onClick.emit('hello world');
}
// ✅ 关键修复：使用 globalThis.Event 明确声明原生事件类型
@Method()
async secondMethod(event: globalThis.Event): Promise<void> {
const target = event.target as HTMLInputElement;
const id = target.id; // 安全访问 input 元素属性
// 处理 checkbox 选中状态等逻辑
}
render() {
return (
<div>
<input type="checkbox" id="my-checkbox" onInput={(e) => this.secondMethod(e)} />
<button onClick={() => this.handleClick()}>Trigger Custom Event</button>
</div>
);
}
}⚠️ 注意事项：
- 不要使用 import { Event } from '@stencil/core' 或 declare const Event: any 等非常规方式覆盖类型，这会破坏类型安全；
- 若需在事件载荷中传递原生事件对象（如 emit({ ev: event })），请确保 EventEmitter 泛型中也使用 globalThis.Event，例如：
@Event() customEvent: EventEmitter<{ data: string; ev: globalThis.Event }>; - 升级至 Stencil v4+ 后该问题仍存在，因此该修复具有长期适用性。
总结：类型冲突的本质是 TypeScript 的模块作用域与全局作用域交汇导致的歧义。通过 globalThis.Event 显式锚定原生事件类型，既符合 Web 标准，又完全兼容 Stencil 的装饰器机制，是当前最稳定、最推荐的实践方案。
