Published on

一起来写 VS Code 插件：VS Code 版 CNode 已上线

一起来写 VS Code 插件：VS Code 版 CNode 已上线

前言

本篇是 VS Code 插件开发实战系列第三篇，前面两篇是

  1. 《一起来写 VS Code 插件：为你的团队提供常用代码片段》
  2. 《一起来写 VS Code 插件：实现一个翻译插件》

CNode  社区为国内最专业的 Node.js 开源技术社区，致力于 Node.js 的技术研究。本篇将通过实现 VS Code 版 CNode， 来带领大家一起熟悉 VSCode Webview 强大的功能。在开始之前，我们先参考 官网关于 webview 的介绍。Webview API 允许扩展在 visualstudio 代码中创建完全可定制的视图，可以将 webview 看作是 VS Code 中的 iframe。

我们可以通过网页将事件消息传递给我们的服务端(包括 NodeJS)， 服务端处理完后可以把消息数据传递给网页。因此我们能在 extensions 中开发出跟网页一样的内容，但实现远比网页更强大的功能。

效果

首先来看下实现的效果

nn.gif.gif

主要分为 2 部分，左侧是主题列表，右侧是主题详情。

初始化项目

首先通过脚手架初始化一个 typescript + webpack 的工程

image.png

配置左侧导航图标

 "icon": "icon.png",
  "activationEvents": [
    "onView:vs-sidebar-view"
  ],
  "contributes": {
    "viewsContainers": {
      "activitybar": [
        {
          "id": "vs-sidebar-view",
          "title": "CNODE 社区",
          "icon": "media/cnode_icon_64.png"
        }
      ]
    },
    "views": {
      "vs-sidebar-view": [
        {
          "type": "webview",
          "id": "vs-sidebar-view",
          "name": "Topic 列表",
          "icon": "media/cnode_icon_64.png",
          "contextualTitle": "Topic 列表"
        }
      ]
    }
  },
  ...

views 是配置视图列表,activitybar 是定义下显示在侧边导航上的视图。

注册一个侧边栏

在 extension.ts 中注册一个 与 package.json 对应的 vs-sidebar-view侧边栏 ID

import * as vscode from 'vscode'
import { SidebarProvider } from './SidebarProvider'

export function activate(context: vscode.ExtensionContext) {
  const sidebarPanel = new SidebarProvider(context.extensionUri)
  context.subscriptions.push(
    vscode.window.registerWebviewViewProvider('vs-sidebar-view', sidebarPanel)
  )
}

实现侧边栏

import * as vscode from "vscode";
import { getNonce } from "./getNonce";

export class SidebarProvider implements vscode.WebviewViewProvider {
  _view?: vscode.WebviewView;
  _doc?: vscode.TextDocument;
  constructor(private readonly _extensionUri: vscode.Uri) {}

  public resolveWebviewView(webviewView: vscode.WebviewView) {
    this._view = webviewView;

    webviewView.webview.options = {
      // 在 webview 允许脚本
      enableScripts: true,
      localResourceRoots: [this._extensionUri],
    };

    webviewView.webview.html = this._getHtmlForWebview(webviewView.webview);
  }

  public revive(panel: vscode.WebviewView) {
    this._view = panel;
  }

  private _getHtmlForWebview(webview: vscode.Webview) {
    const scriptUri = webview.asWebviewUri(
      vscode.Uri.joinPath(this._extensionUri, "build", "static/js/main.js")
    );
    const styleMainUri = webview.asWebviewUri(
      vscode.Uri.joinPath(this._extensionUri, "build", "main.css")
    );

    // Use a nonce to 只允许特定脚本运行.
    const nonce = getNonce();

    return `<!DOCTYPE html>
		<html lang="en">
		<head>
		<meta charset="UTF-8">
                <meta http-equiv="Content-Security-Policy" content="img-src https: data:; style-src 'unsafe-inline' ${webview.cspSource}; script-src 'nonce-${nonce}';">
		<meta name="viewport" content="width=device-width, initial-scale=1.0">
		<link href="${styleMainUri}" rel="stylesheet">
                <script nonce="${nonce}">
                  const tsvscode = acquireVsCodeApi(); //内置函数，可以访问 VS Code API 对象
                  const apiBaseUrl = 'https://cnodejs.org/'
                </script>
                </head>
              <body>
                  <div id="root"></div>
                  <script nonce="${nonce}" src="${scriptUri}"></script>
              </body>
	</html>`;
  }
}

上述代码采用面向对象的方式实现一个 SidebarProvider类，根据 vscode.WebviewViewProvider， 其实实现所有的 WebviewViewProvider 都是是这段代码，其他代码都是相同的，因为关于 webview 中的 HTML 我们都可以使用 js 来生成，这不正是我们的单页面应用开发吗？

上述代码中， Nonce是一个在加密通信只能使用一次的数字。在认证协议中，它往往是一个随机或伪随机数，以避免重放攻击。Nonce 也用于流密码以确保安全。如果需要使用相同的密钥加密一个以上的消息，就需要 Nonce 来确保不同的消息与该密钥加密的密钥流不同。 所以我们直接拷贝官方 demo 中的代码。

//  生成特定随机数
export function getNonce() {
  let text = ''
  const possible = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'
  for (let i = 0; i < 32; i++) {
    text += possible.charAt(Math.floor(Math.random() * possible.length))
  }
  return text
}

实现侧边视图

CNode 提供了允许跨域的 API，我们可以在 js 中直接调用，如果你也想开发类似的功能请在 HTTP headers 中加入

Access-Control-Allow-Origin: *

配置 webpack config

在原先 webpack.config.js 中加入打包 React 的没配置，webpack5 支持多份 config 配置。

const viewConfig = {
  entry: './view/index.tsx',
  output: {
    path: path.resolve(__dirname, 'build'),
    filename: 'static/js/[name].js',
  },
  mode: 'production',
  plugins: [new miniCssExtractPlugin()],
  module: {
    rules: [
      {
        test: /\.(ts|tsx)$/i,
        loader: 'ts-loader',
        exclude: ['/node_modules/'],
      },
      {
        test: /\.css$/i,
        use: [miniCssExtractPlugin.loader, 'css-loader', 'postcss-loader'],
      },
    ],
  },
  resolve: {
    extensions: ['.ts', '.tsx'],
  },
}

module.exports = [extensionConfig, viewConfig]

然后启动调试的时候，webpack 就会自动打包了；

注意 这里的 mode 必须设置为 production，webpack development 模式会使用 eval 来执行代码，而 eval 在 VS Code webview 不允许执行。

配置 tailwindcss

为了方便,我这边使用了 tailwindcss，因为我可以使用 tailwindcss-typography 这个插件，帮我生成漂亮的文章类型排版。

yarn add tailwindcss @tailwindcss/typography autoprefixer

使用命令初始化 tailwindcss config

npx tailwindcss init

module.exports = {
  mode: 'jit',
  purge: ['./view/**/*.tsx'],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [require('@tailwindcss/typography')],
}

mode jit 是及时编译模式 tailwindcss 2.1 版本加的，忽略掉我们不需要的 css 代码。

生成文章页面的样式

.markdown-preview {
  @apply prose prose-lg max-w-full bg-white p-20;
}

使用 React 来实现主题列表

使用 react 实现一个列表的代码我这边就不叙述了，跟我们平常写业务没什么区别，最主要的是 数据通信，当我们点击主题列表，右边要打开一个新的 webview 页面

const handleClick = (item: Topic) => {
  setCurrent(item.id)

  tsvscode.postMessage({ type: 'detail', value: item })
}

根据官方例子

scripts-webview_to_extension.gif

Webviews 还可以将消息传递回它们的扩展。这是通过在 webview 中的特殊 VS Code API 对象上使用 postMessage 函数来实现的。要访问 VS Code API 对象，就要在 webview 中调用 acquireVsCodeApi函数。

定义 TS 全局对象

import * as _vscode from "vscode";

declare global {
  const tsvscode: {
    postMessage: ({ type: string, value: any }) => void;
    getState: () => any;
    setState: (state: any) => void;
  };
  const apiBaseUrl: string;
}

接着就可以在 vs-sidebar-view 接收数据了

webviewView.webview.onDidReceiveMessage(async (data) => {
  switch (data.type) {
    case 'detail':
      createPreviewPanel(this._extensionUri, data.value)
      break

    default:
      break
  }
})

实收到数据后可以就可以打开一个预览页面了

预览页面实现

function createPreviewPanel(topic: Topic) {
  // 创建一个新的 panel.
  const panel = vscode.window.createWebviewPanel(
    'cnode-preview',
    'CNODE 技术社区',
    column || vscode.ViewColumn.One,
    {
      // 在 webview 允许脚本
      enableScripts: true,

      // 限制 从 media 文件夹加载资源
      localResourceRoots: [vscode.Uri.joinPath(extensionUri, 'build')],
    }
  )

  panel.webview.html = _getHtmlForWebview(panel.webview, topic)
}

可以使用 内置方法 vscode.window.createWebviewPanel 创建一个新的面板，并且接收主题数据。 _getHtmlForWebview 与 SidebarProvider 中的 _getHtmlForWebview 一致，返回 HTML 即可。

避免重复创建预览页

当然也可以通过 postMessage 传递属性

extension 端

panel.webview.postMessage({text: 'hello'});

webview 端

window.addEventListener('message', event => {
    const message = event.data;
    console.log('Webview接收到的消息：', message);
}

主题适配

VS Code 将主题分为三类，并在 body 元素中添加一个 class 来指示当前主题:

body.vscode-light {
  color: black;
}

body.vscode-dark {
  color: white;
}

body.vscode-high-contrast {
  color: red;
}

Webviews 还可以使用 CSS 变量访问 VS Code 主题颜色。这些变量名以 vscode 作为前缀，并用-替换.。例如 editor.foreground 变为 var (--vscode-editor-foreground)。

查看可用主题变量的主题颜色参考。还有一个扩展可以为变量提供智能建议。

调试

要调试 Webview 不能直接把 VSCode 的开发者工具打开，直接打开你只能看到一个<webview></webview>标签，看不到代码，要看代码需要按下Ctrl+Shift+P然后执行打开Webview开发工具，英文版应该是Open Webview Developer Tools：

image.png

从上图也可以看的 在 html 标签上注入了当前皮肤的 css 变量。

状态保持

与浏览器标签不一样的是，当 webview 移动到后台又再次显示时，webview 中的任何状态都将丢失。因为 webview 是基于 iframe 实现的。

解决此问题的最佳方法是使你的 webview 无状态，通过消息传递来保存 webview 的状态。

 state

在 webview 的 js 中我们可以使用vscode.getState()和vscode.setState()方法来保存和恢复 JSON 可序列化状态对象。当 webview 被隐藏时，即使 webview 内容本身被破坏，这些状态仍然会保存。当然了，当 webview 被销毁时，状态将被销毁。

序列化

通过注册WebviewPanelSerializer可以实现在VScode重启后自动恢复你的webview，当然，序列化其实也是建立在getState和setState之上的。

注册方法：vscode.window.registerWebviewPanelSerializer

 retainContextWhenHidden

对于具有非常复杂的 UI 或状态且无法快速保存和恢复的webview，我们可以直接使用retainContextWhenHidden选项。设置retainContextWhenHidden: true后即使 webview 被隐藏到后台其状态也不会丢失。

尽管retainContextWhenHidden很有吸引力，但它需要很高的内存开销，一般建议在实在没办法的时候才启用。

getState和setState是持久化的首选方式，因为它们的性能开销要比retainContextWhenHidden低得多。

发布

关于发布可以看我的上一篇 一起来写 VS Code 插件:为你的团队提供常用代码片段

小结

本篇通过实现 VS Code 版 CNode 来帮我们熟悉 webview 的 api，当然还可以增加评论系统，创建主题，基于用户系统可以实现点赞收藏等。

开发更复杂的功能，只缺你的想象力。例如：

  1. 韭菜盒子，做最好用的股票和基金插件

  2. create-app 可视化 CLI 工具

最后

附上本插件的下载地址和源码

同时 vscode extensions 开发门槛不高，欢迎大家尝试，或者将有意思的 extensions 推荐在评论区。

希望这篇文章对大家有所帮助，也可以参考我往期的文章或者在评论区交流你的想法和心得，欢迎一起探索前端。

runjs-cool
关注微信公众号，获取最新原创文章（首发）View on GitHub