Link Search Menu Expand Document

Details

Topics

local content

  • Webviews run in isolated contexts that cannot directly access local resources. This is done for security reasons. This means that in order to load images, stylesheets, and other resources from your extension, or to load any content from the userโ€™s current workspace, you must use the Webview.asWebviewUri function to convert a local file: URI into a special URI that VS Code can use to load a subset of local resources.
import * as vscode from 'vscode';
import * as path from 'path';

export function activate(context: vscode.ExtensionContext) {
  context.subscriptions.push(
    vscode.commands.registerCommand('catCoding.start', () => {
      const panel = vscode.window.createWebviewPanel(
        'catCoding',
        'Cat Coding',
        vscode.ViewColumn.One,
        {}
      );

      // Get path to resource on disk
      const onDiskPath = vscode.Uri.file(
        path.join(context.extensionPath, 'media', 'cat.gif')
      );

      // And get the special URI to use with the webview
      const catGifSrc = panel.webview.asWebviewUri(onDiskPath);

      panel.webview.html = getWebviewContent(catGifSrc);
    })
  );
}
  • disk based url: vscode-resource:/Users/toonces/projects/vscode-cat-coding/media/cat.gif

Scripts and message passing

  • . JavaScript is disabled in webviews by default, but it can easily re-enable by passing in the enableScripts: true option.

  • scripts in a webview do not have access to the VS Code API. Thatโ€™s where message passing comes in!

API

properties

visible

desc: is webview in foreground

methods

reveal

desc: bring webview to foreground

Lifecycle

  • Webview panels are owned by the extension that creates them
  • extension must hold onto the webview returned from createWebviewPanel
  • If your extension loses this reference, it cannot regain access to that webview again, even though the webview will continue to show in VS Code
  • a user can also close a webview panel at any time. When a webview panel is closed by the user, the webview itself is destroyed. Attempting to use a destroyed webview throws an exception.

Quickstart

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  context.subscriptions.push(
    vscode.commands.registerCommand('catCoding.start', () => {
      // Create and show a new webview
      const panel = vscode.window.createWebviewPanel(
        'catCoding', // Identifies the type of the webview. Used internally
        'Cat Coding', // Title of the panel displayed to the user
        vscode.ViewColumn.One, // Editor column to show the new webview panel in.
        {} // Webview options. More on these later.
      );
    })
  );
}
  • set content
activate {
    ...
    panel.webview.html = getWebviewContent();
}

function getWebviewContent() {
  return `<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Cat Coding</title>
</head>
<body>
    <img src="https://media.giphy.com/media/JIX9t2j0ZTN9S/giphy.gif" width="300" />
</body>
</html>`;
}
  • update content

activate {
    ...
    let iteration = 0;
    const updateWebview = () => {
        const cat = iteration++ % 2 ? 'Compiling Cat' : 'Coding Cat';
        panel.title = cat;
        panel.webview.html = getWebviewContent(cat);
    };

    // Set initial content
    updateWebview();

    // And schedule updates to the content every second
    setInterval(updateWebview, 1000);
    }

  • check for disposal
activate {
    ...
      panel.onDidDispose(
        () => {
          // When the panel is closed, cancel any future updates to the webview content
          clearInterval(interval);
        },
        null,
        context.subscriptions
      );
}

Copyright © 2020 Thence LLC