SuperAPI AI 工具集

vscode-window-messages

编程与开发

查看项目

更新于 10-16 10:15

技能介绍

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 官方为准。