# @estruyf/vscode 中文文档

规范地址：https://npmcn.com/package/%40estruyf/vscode/

版本：1\.2\.1
npm 元数据更新时间：2026-08-21T08:48:13.169Z
中文译文更新时间：2026-11-14T03:02:17.882Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40estruyf/vscode
原文对照：https://npmcn.com/package/%40estruyf/vscode/?lang=original
项目主页：https://github.com/estruyf/vscode-helpers
源码仓库：https://github.com/estruyf/vscode-helpers

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：76 kB，70 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2021-09-04T14:52:40.930Z
- 最新版本发布：2026-08-21T08:48:12.856Z
- 近 30 天下载量：2453（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 1 个）

## 中文简介

一套用于简化Visual Studio代码扩展开发的公用功能和辅助器.

## 安装

```sh
npm install @estruyf/vscode
```

也可以使用：`pnpm add @estruyf/vscode`、`yarn add @estruyf/vscode`、`bun add @estruyf/vscode`

## README

# Visual Studio代码扩展助手

这个 `@estruyf/vscode` 软件包包含几个帮助者,使Visual Studio代码扩展开发更加容易.

## 安装

使用 npm

```bash
npm i @estruyf/vscode
```

## 帮助者

### 配置

配置帮助器, 以方便获取您的扩展名的设置 .

```typescript
import { Configuration } from "@estruyf/vscode";

const config = Configuration.get("section");

const mdConfig = Configuration.getForLanguage<string>("markdown");

const setting = Configuration.getSetting<string>("section", "setting");

await Configuration.updateSetting<string>("section", "setting", value);

await Configuration.updateSettingForLanguage<string>(
  "markdown",
  "setting",
  value
);
```

### 编辑器

```typescript
import { EditorHelper } from "@estruyf/vscode";

// Show a file in the editor
EditorHelper.showFile(filepath);

// Read a file's content
const content = await EditorHelper.readFile(uri);

// Write content to a file
await EditorHelper.writeFile(uri, "Hello World");

// Check if a file exists
const exists = await EditorHelper.fileExists(uri);
```

### 网页视图

#### 信件处理器

这个 `messageHandler` 是一个帮助者,可以更容易地从您的扩展中发送和请求数据。 它基于 `postMessage` 财务报告和审定财务报表 `onDidReceiveMessage`,但允许您使用自动同步/等待发送和接收数据.

这个 `messageHandler` 可以向扩展发送两类消息:

1.  `messageHandler.send`:这是一个单向消息,您会向扩展发送数据,但不要期望得到响应.
2.  `messageHandler.request`:这是一个双向消息,您会向扩展发送数据,并期望得到响应.

使用它只需要做以下几点:

**网页视图**

```typescript
import { messageHandler } from "@estruyf/vscode/dist/client";

// Sends a message with id: "GET_DATA"
messageHandler.request<any>("GET_DATA").then((data: any) => {
  // Do something with the returned data
  console.log(data);
});

// Sends a message with id: "POST_DATA" - no data is expected back
messageHandler.send("POST_DATA", { dummy: "Nothing to report..." });
```

**延长**

```typescript
import { MessageHandlerData } from "@estruyf/vscode";

panel.webview.onDidReceiveMessage(
  (message) => {
    const { command, requestId, payload } = message;

    if (command === "GET_DATA") {
      // Do something with the payload

      // Send a response back to the webview
      panel.webview.postMessage({
        command,
        requestId, // The requestId is used to identify the response
        payload: `Hello from the extension!`,
      } as MessageHandlerData<string>);
    } else if (command === "POST_DATA") {
      // Do something with the payload
    }
  },
  undefined,
  context.subscriptions
);
```

##### 错误

如果您想将错误发回网页视图, 您可以使用 `error` 属性代替 `payload` 属性和通过错误数据.

**延长**

```typescript
panel.webview.postMessage({
  command,
  requestId, // The requestId is used to identify the response
  error: `Something went wrong!`,
} as MessageHandlerData<string>);
```

**网页视图**

```typescript
messageHandler
  .request<string>("GET_DATA_ERROR")
  .then((msg) => {
    setMessage(msg);
  })
  .catch((err) => {
    setError(err);
  });
```

#### 通讯员

信使可以用来向您的扩展发送消息,也可以收听您扩展发送的消息.

```typescript
import { Messenger } from "@estruyf/vscode/dist/client";

// Get the VS Code API in your webview
Messenger.getVsCodeAPI();

// Listen to messages from your extension.
const listener = (message: MessageEvent<EventData<T>>) => {
  const event = message.data;
  console.log(event.command, event.payload);
};

Messenger.listen<T>(listener);

// Remove a listener
Messenger.unlisten(listener);

// Send a message to your extension
Messenger.send("command", payload);
```

#### 网页视图帮助器

```typescript
import { WebviewHelper } from "@estruyf/vscode";

// Generate a random string for your webview
WebviewHelper.getNonce();
```

### 公用事业

#### 主题公用事业

```typescript
import { getThemes, getTheme } from "@estruyf/vscode";

// Get all contributed themes
const themes = getThemes();

// Get the currently active theme or a specific theme by name
const theme = await getTheme();
const specificTheme = await getTheme("Dark+ (default dark)");
```

#### 路径工具

```typescript
import { parseWinPath } from "@estruyf/vscode";

// Convert Windows path to POSIX path
const posixPath = parseWinPath("C:\\Users\\Name\\file.txt"); // "C:/Users/Name/file.txt"
```

#### 工作空间

```typescript
import { bringToFront } from "@estruyf/vscode";
import { Uri } from "vscode";

// Bring a workspace folder to the front in VS Code
await bringToFront(Uri.file("/path/to/workspace"));
```

### 扩展元数据

#### 扩展信息

这个 `ExtensionInfo` 类为您的扩展提供元数据和状态管理.

```typescript
import { ExtensionInfo } from "@estruyf/vscode";

const extInfo = ExtensionInfo.getInstance(context);
const name = extInfo.name;
const version = extInfo.version;
const isUpdated = extInfo.isUpdated();
extInfo.updateVersion();
```

### 团队设置

#### 团队安排

这个 `TeamSettings` 类帮助管理基于团队的配置文件和设置.

```typescript
import { TeamSettings } from "@estruyf/vscode";

// Initialize team settings
TeamSettings.init("team-settings.json", "myExtension");

// Get a team setting
const value = TeamSettings.get<string>("settingKey");

// Update a team setting
await TeamSettings.update<string>("settingKey", "newValue");

// Listen for config changes
TeamSettings.onConfigChange((global) => {
  // Handle config change
});
```

## 许可证

[MIT 许可证](https://npmcn.com/package/%40estruyf/vscode/LICENSE)

[![Visitors](https://api.visitorbadge.io/api/visitors?path=https%3A%2F%2Fgithub.com%2Festruyf%2Fvscode-helpers&countColor=%23263759)](https://visitorbadge.io/status?path=https%3A%2F%2Fgithub.com%2Festruyf%2Fvscode-helpers)

## 常见问题

### @estruyf/vscode 是什么？

一套用于简化Visual Studio代码扩展开发的公用功能和辅助器\.

### 如何安装 @estruyf/vscode？

在项目目录运行 npm install @estruyf/vscode，或使用 pnpm add / yarn add / bun add。

### @estruyf/vscode 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @estruyf/vscode 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @estruyf/vscode 可以商用吗？

@estruyf/vscode 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @estruyf/vscode 的下载量有多少？

根据 npm 官方下载统计，@estruyf/vscode 在 2026/10/14 – 2026/11/12 这 30 天内被下载 2,453 次，日均约 82 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @estruyf/vscode 还在维护吗？

最新版本 1\.2\.1 发布于 2026/08/21（2 个月前）；至今共发布 18 个版本，其中过去 12 个月发布了 1 个；首次发布于 2021/09/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。