vscode-window-messages 是 VS Code 扩展开发中关于窗口消息 API 的使用指南,适用于需要调用 showInformationMessage、showWarningMessage、showErrorMessage 的场景。以下按用途、主要能力、使用方式、适用场景和限制整理。
用途
本规范提供在 VS Code 扩展中弹出信息、警告、错误消息的最佳实践,帮助开发者统一消息提示的实现方式,避免使用旧版接口,并保证消息内容的国际化与返回值的正确处理。
主要能力
直接使用 VS Code 原生 API
应直接使用 vscode.window.show*Message,不要在新代码中使用旧版 NotificationService。示例:
import * as vscode from 'vscode';
import { nls } from '../messages/messages';
// 正确
await vscode.window.showInformationMessage(nls.localize('retrieve_canceled'));
await vscode.window.showErrorMessage(nls.localize('retrieve_failed', String(error)));
// 错误
await notificationService.showInformationMessage(nls.localize('retrieve_canceled'));
使用 nls.localize 进行国际化
所有消息字符串和按钮标签必须使用 nls.localize(),这一要求由 no-vscode-message-literals ESLint 规则强制执行。即使按钮标签是命令标题,也应使用 nls.localize();直接导入 package.nls.json 会剥离本地化上下文,只有清单中的 %key% 才会读取对应语言环境的 JSON 文件,使用 nls.localize() 可通过 i18n.ja.ts 保留日语等语言环境。
正确示例:
await vscode.window.showInformationMessage(nls.localize('retrieve_canceled'));
await vscode.window.showErrorMessage(nls.localize('retrieve_failed', String(error)));
await vscode.window.showInformationMessage(`${nls.localize('prefix')} ${nls.localize('suffix')}`);
const answer = await vscode.window.showWarningMessage(
nls.localize('confirm_delete'),
nls.localize('yes_button'),
nls.localize('no_button')
);
错误示例:
await vscode.window.showInformationMessage('Operation successful');
await vscode.window.showInformationMessage(`Operation ${status} successful`);
await vscode.window.showWarningMessage(nls.localize('confirm_delete'), 'Yes', 'No');
新增消息的步骤:在包内的 i18n.ts 中添加键值;使用 nls.localize('your_message_key', ...args)。
处理返回值
方法返回被点击的按钮,若被关闭则返回 undefined。返回类型:字符串按钮为 Thenable<string | undefined>;MessageItem 按钮为 Thenable<MessageItem | undefined>。
// 正确 - 字符串按钮
const selection = await vscode.window.showWarningMessage(
nls.localize('unsaved_changes'),
nls.localize('save_button'),
nls.localize('discard_button')
);
if (selection === nls.localize('save_button')) {
await saveFile();
}
// 正确 - MessageItem 按钮
const item = await vscode.window.showWarningMessage(
nls.localize('unsaved_changes'),
{ modal: true },
{ title: nls.localize('save_button') },
{ title: nls.localize('discard_button') }
);
if (item?.title === nls.localize('save_button')) {
await saveFile();
}
// 正确 - 即发即弃
void vscode.window.showInformationMessage(nls.localize('operation_completed'));
// 错误
vscode.window.showInformationMessage(nls.localize('operation_completed')); // 缺少 void
与 Effect 集成
需要用户响应时使用 Effect.promise() 等待用户响应,阻塞执行直到用户回应:
import { Effect } from 'effect';
const selection =
yield *
Effect.promise(() =>
vscode.window.showWarningMessage(nls.localize('confirm_action'), nls.localize('yes'), nls.localize('no'))
);
if (selection === nls.localize('yes')) {
yield * performAction();
}
yield * Effect.promise(() => vscode.window.showErrorMessage(nls.localize('critical_error')));
不需要用户响应时(即发即弃)使用 Effect.sync() 进行非阻塞消息,执行会立即继续:
yield *
Effect.sync(() => {
void vscode.window.showInformationMessage(nls.localize('background_task_started'));
});
yield * performBackgroundTask();
不应在不需要等待时使用 Effect.promise() 造成阻塞;也不应在 Effect.gen 中直接调用,例如 await vscode.window.showErrorMessage('Error') 会产生类型错误。
消息类型选择
showInformationMessage:成功、信息、非关键提示。 showWarningMessage:警告、可恢复错误、需要用户决策。 showErrorMessage:错误、失败、关键问题。
await vscode.window.showInformationMessage(nls.localize('retrieve_completed'));
await vscode.window.showWarningMessage(nls.localize('unsaved_changes'));
await vscode.window.showErrorMessage(nls.localize('retrieve_failed', errorMessage));
// 带 detail 的模态框(detail 仅在模态时显示)
await vscode.window.showWarningMessage(
nls.localize('destructive_action_warning'),
{ modal: true, detail: nls.localize('destructive_action_detail') },
nls.localize('confirm')
);
注意:VS Code 会自动为模态对话框添加 Cancel 按钮,当 modal: true 时不要显式添加 nls.localize('cancel_button') 作为条目。关闭对话框(通过 Cancel 或 ESC)返回 undefined。
MessageOptions 与 MessageItem
MessageOptions:modal?: boolean 表示系统模态对话框,会阻塞交互;detail?: string 为额外文本(仅模态可用)。
按钮类型可为字符串或 MessageItem 对象:
// 字符串按钮(优先)
const result = await vscode.window.showWarningMessage(
nls.localize('confirm_action'),
nls.localize('yes'),
nls.localize('no')
);
// result: string | undefined
// MessageItem(用于模态 ESC 处理)
const result = await vscode.window.showWarningMessage(
nls.localize('confirm_action'),
{ modal: true },
{ title: nls.localize('yes'), isCloseAffordance: false },
{ title: nls.localize('no'), isCloseAffordance: true }
);
// result: MessageItem | undefined
isCloseAffordance: true 表示该按钮处理 ESC,仅模态可用。模态会自动添加 Cancel,可用此项控制哪个自定义按钮处理 ESC。
常见模式
条件消息(即发即弃):
if (hasErrors) {
void vscode.window.showErrorMessage(nls.localize('operation_completed_with_errors'));
} else {
void vscode.window.showInformationMessage(nls.localize('operation_completed_successfully'));
}
需要响应的用户确认:
import { Effect } from 'effect';
const confirm =
yield *
Effect.promise(() =>
vscode.window.showWarningMessage(
nls.localize('confirm_destructive_action'),
nls.localize('proceed_button')
)
);
if (confirm === nls.localize('proceed_button')) {
yield * performDestructiveAction();
}
ESLint 规则
no-vscode-message-literals 强制要求:第一个参数不能是字符串字面量;不能使用模板字面量,除非其中包含 nls.localize() 调用;适用于 showInformationMessage、showWarningMessage、showErrorMessage。提交前运行 npm run lint。
适用场景
适用于使用 VS Code 扩展 API 弹出信息、警告、错误提示,并需要国际化、用户确认、返回值处理,或与 Effect 库结合使用的开发场景。
限制
资料未提供其他限制说明;具体 API 行为以 VS Code 官方为准。