vscode async webview

Введение

Это утилита, позволяющая облегчить реализацию веб -представлений в расширениях VSCODE. Таким образом, это абстрагирует весь трафик сообщений между iframes в простой в использовании асинхронный API. Кроме того, он упрощает инъекцию полного веб -приложения в расширение без необходимости написания строк HTML или конкретного кода VSCODE в веб -приложении.

Этот документ предназначен для пользователей этой библиотеки. Если вы хотите прочитать документ для разработчиков, пожалуйста, прочитайте этот текст вместо этого.

Мотивация

Недавно я унаследовал проект расширения VSCODE, который в значительной степени полагался на веб -просмотр. После глубокого анализа кода я заметил:

• Часть HTML -инъекции этого процесса была очень сложной и сильно опиралась на функцию asWebviewUri , что затрудняло добавление новых ресурсов в проект.
• Связь между веб-просмотром и расширением была очень сложной, многословной, неинтуитивной и подверженной ошибкам. Необычные состояния, сообщения с струнами, в основном нетипированными, явные призывы к postMessage и ручной регистрации слушателей, действительно не помогли.

Мне нужно было поднять расширение до уровня качества производства и сделать его чем -то простым в обслуживании. Я не сомневался, что мне пришлось отказаться от текущего проекта и разработать основу для работы над API, предоставленным VSCODE. Это эта структура.

Это очень новый проект, и расширение, которое мы строим на вершине, вероятно, будет выпущено в следующем месяце. Как только у нас появится стабильный релиз, я помесчу здесь ссылку.

Результаты на данный момент были очень удовлетворительными. Фактический код для нашего расширения очень прост и сосредоточен на логике расширения, никогда не на деталях того, как передавать два разных приложения.

Стадия развития

В настоящее время это на Альфе. Я перееду в бета -версию, как только мы выпустим первую версию нашего расширения, и он будет в прямом эфире в магазине Vscode.

Это будет иметь стабильный выпуск (1.0.0), когда у нас будет не менее 80% тестового покрытия.

Отказ от ответственности

Эта документация предполагает, что вы уже знакомы с основными основаниями документации VSCODE для создания расширения.

Пример

Мы собираемся сосредоточиться на очень простом примере, где веб -просмотр показывает уведомление VSCODE, а уведомление VSCODE взаимодействует с состоянием WebView. Смотрите видео ниже.

Образец.mov

Расширение

extension/src/extension.ts :

 import * as vscode from 'vscode'
import { VSCodeWebview } from '@stack-spot/vscode-async-webview-backend'
import { Bridge } from './Bridge'

export function activate ( context : vscode . ExtensionContext ) {
  const webview = new VSCodeWebview ( {
    type : 'myExtension' ,
    path : 'packages/webview' ,
    title : 'My Extension' ,
    bridgeFactory : ( webview ) => new Bridge ( webview ) ,
    context ,
  } )

  let disposable = vscode . commands . registerCommand ( 'myExtension.start' , ( ) => {
    webview . show ( )
  } )

  context . subscriptions . push ( disposable )
}

extension/src/Bridge.ts :

Это тот класс, который делает мост между двумя приложениями.

 import { VSCodeWebviewBridge } from '@stack-spot/vscode-async-webview-backend'
import { ViewState } from './ViewState'
import { window } from 'vscode'

export class Bridge extends VSCodeWebviewBridge < ViewState > {
  async showMessage ( message : string ) {
    const action = await window . showInformationMessage ( message , 'reset counter' , 'close' )
    if ( action === 'reset counter' ) {
      this . state . set ( 'counter' , 0 )
    }
  }
}

extension/src/ViewState.ts :

Этот файл объявляет государство, общее между двумя приложениями:

 export interface ViewState {
  counter ?: number ,
} 

WebView

Этот пример был создан с помощью React, но вы можете использовать все в качестве фронтальной структуры.

webview/src/vscode.ts :

Этот файл делает базовую настройку для использования LIB.

 import { VSCodeWeb , VSCodeWebInterface } from '@stack-spot/vscode-async-webview-client'
import { createVSCodeHooks } from '@stack-spot/vscode-async-webview-react'
import type { Bridge } from 'extension/Bridge'

export const vscode : VSCodeWebInterface < Bridge > = new VSCodeWeb < Bridge > ( { } )
const vsHooks = createVSCodeHooks ( vscode )
export const useBridgeState = vsHooks . useState

webview/src/App.tsx :

Большая часть кода здесь является шаблоном Vite. Обратите внимание на то, что всякий раз, когда мы используем vscode.bridge и useBridgeState , это две структуры, используемые на фронте, чтобы общаться с расширением.

 import reactLogo from './assets/react.svg'
import viteLogo from '/vite.svg'
import './App.css'
import { useBridgeState , vscode } from './vscode'

function App ( ) {
  const [ count = 0 , setCount ] = useBridgeState ( 'counter' )

  return (
    < >
      < div >
        < a href = "https://vitejs.dev" target = "_blank" >
          < img src = { viteLogo } className = "logo" alt = "Vite logo" / >
        < / a >
        < a href = "https://react.dev" target = "_blank" >
          < img src = { reactLogo } className = "logo react" alt = "React logo" / >
        < / a >
      < / div >
      < h1 > Vite + React < / h1 >
      < div className = "card" >
        < button onClick = { ( ) => {
          setCount ( count + 1 )
          vscode . bridge . showMessage ( `The counter is at: ${ count + 1 } .` )
        } } >
          count is { count }
        < / button >
        < p >
          Edit < code > src/App.tsx < / code > and save to test HMR
        < / p >
      < / div >
      < p className = "read-the-docs" >
        Click on the Vite and React logos to learn more
      < / p >
    < / >
  )
}

export default App 

Полный пример

Вы можете найти полный пример в нашем образце проекта.

Док

• Начиная
• Бэкэнд библиотека
• Клиентская библиотека