vscode async webview

Perkenalan

Ini adalah utilitas untuk membuatnya lebih mudah untuk mengimplementasikan tampilan web dalam ekstensi vScode. Singkatnya, ini abstrak semua lalu lintas pesan antara iframe menjadi API asinkron yang mudah digunakan. Selain itu, ini menyederhanakan injeksi aplikasi web lengkap ke dalam ekstensi tanpa perlu menulis string HTML atau kode vscode spesifik di aplikasi web.

Dokumen ini ditujukan untuk pengguna perpustakaan ini. Jika Anda ingin membaca dokumen untuk pengembang, silakan baca teks ini sebagai gantinya.

Motivasi

Saya baru -baru ini mewarisi proyek ekstensi vScode yang sangat mengandalkan Webview. Setelah analisis kode yang mendalam, saya perhatikan:

• Bagian injeksi HTML dari proses ini sangat kompleks dan sangat bergantung pada fungsi asWebviewUri , sehingga sangat sulit untuk menambahkan sumber daya baru ke proyek.
• Komunikasi antara webview dan ekstensi sangat kompleks, verbose, tidak intuitif dan rentan terhadap kesalahan. Negara -negara yang tidak diketik, pesan -pesan dengan string yang sebagian besar tidak diketik, panggilan eksplisit ke postMessage dan pendaftaran manual pendengar benar -benar tidak membantu.

Saya perlu meningkatkan ekstensi ke tingkat kualitas produksi dan membuatnya menjadi sesuatu yang mudah dipelihara. Saya tidak ragu saya harus membatalkan proyek saat ini dan mengembangkan kerangka kerja untuk bekerja di atas API yang disediakan oleh VScode. Ini adalah kerangka kerja ini.

Ini adalah proyek yang sangat baru dan ekstensi yang kami bangun di atasnya mungkin akan dirilis bulan depan. Segera setelah kami memiliki rilis yang stabil, saya akan menaruh tautan ke sini.

Hasilnya, untuk saat ini, sangat memuaskan. Kode aktual untuk ekstensi kami sangat sederhana dan fokus pada logika ekstensi, tidak pernah pada detail tentang cara mengkomunikasikan dua aplikasi yang berbeda.

Tahap pengembangan

Ini saat ini di Alpha. Saya akan memindahkannya ke beta segera setelah kami merilis versi pertama dari ekstensi kami dan itu langsung di toko vscode.

Ini akan memiliki rilis yang stabil (1.0.0) ketika kami memiliki setidaknya 80% dari cakupan uji.

Penafian

Dokumentasi ini mengasumsikan Anda sudah terbiasa dengan dasar -dasar dokumentasi vScode untuk membuat ekstensi.

Contoh

Kami akan fokus pada contoh yang sangat sederhana di mana WebView menunjukkan pemberitahuan vScode dan pemberitahuan vScode berinteraksi dengan status WebView. Lihat video di bawah ini.

sampel.mov

Perpanjangan

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 :

Ini adalah kelas yang membuat jembatan antara dua aplikasi.

 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 :

File ini menyatakan negara yang dibagikan antara kedua aplikasi:

 export interface ViewState {
  counter ?: number ,
} 

Webview

Contoh ini telah dibuat dengan React, tetapi Anda dapat menggunakan apa pun sebagai kerangka kerja frontend Anda.

webview/src/vscode.ts :

File ini membuat pengaturan dasar untuk menggunakan 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 :

Sebagian besar kode di sini adalah boilerplate Vite. Perhatikan setiap kali kami menggunakan vscode.bridge dan useBridgeState , ini adalah dua struktur yang digunakan di frontend untuk berkomunikasi dengan ekstensi.

 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 

Contoh lengkap

Anda dapat menemukan contoh lengkap dalam proyek sampel kami.

Dokumen

• Memulai
• Perpustakaan Backend
• Perpustakaan Klien