vscode async webview

مقدمة

هذه فائدة لجعل من السهل تنفيذ طرق عرض الويب ضمن امتدادات VSCODE. باختصار ، هذا يرفع جميع حركة مرور الرسائل بين IFRAMES إلى واجهة برمجة تطبيقات غير متزامنة غير متزامنة. علاوة على ذلك ، فإنه يبسط حقن تطبيق الويب الكامل في الامتداد دون الحاجة إلى كتابة سلاسل HTML أو رمز VSCODE محدد في تطبيق الويب.

يستهدف هذا المستند مستخدمي هذه المكتبة. إذا كنت ترغب في قراءة المستند للمطورين ، فيرجى قراءة هذا النص بدلاً من ذلك.

تحفيز

لقد ورثت مؤخرًا مشروع تمديد VSCODE الذي اعتمد بشكل كبير على WebView. بعد تحليل عميق للرمز ، لاحظت:

• كان جزء حقن HTML من العملية معقدًا للغاية ويعتمد كثيرًا في وظيفة asWebviewUri ، مما يجعل من الصعب للغاية إضافة موارد جديدة إلى المشروع.
• كان التواصل بين WebView و Extension معقدًا للغاية ، مطولًا ، غير بديهي وعرضة للأخطاء. حالات غير معدّة ، فإن الرسائل التي تحتوي على سلاسل في الغالب ، مكالمات صريحة واضحة إلى postMessage والتسجيل اليدوي للمستمعين لم تساعد حقًا.

كنت بحاجة إلى رفع التمديد إلى مستوى إنتاج الجودة وجعله شيء سهل الصيانة. لم يكن لدي أدنى شك في أنني اضطررت إلى إلغاء المشروع الحالي وتطوير إطار عمل للعمل على رأس واجهة برمجة التطبيقات التي توفرها VSCODE. هذا هو هذا الإطار.

هذا مشروع جديد للغاية ، ومن المحتمل أن يتم إصدار التمديد الذي نبنيه فوقه الشهر المقبل. بمجرد أن يكون لدينا إصدار مستقر ، سأضع رابطًا إليه هنا.

النتائج ، في الوقت الحالي ، كانت مرضية للغاية. الكود الفعلي لتمديدنا بسيط للغاية ويركز على منطق الامتداد ، ولا على تفاصيل كيفية توصيل تطبيقين مختلفين.

مرحلة التنمية

هذا حاليا على ألفا. سأنقلها إلى الإصدار التجريبي بمجرد إصدار الإصدار الأول من امتدادنا وهو مباشر في متجر VSCODE.

سيكون لهذا إصدار مستقر (1.0.0) عندما يكون لدينا 80 ٪ على الأقل من تغطية الاختبار.

تنصل

تفترض هذه الوثائق أنك على دراية بالفعل بأساسيات وثائق VSCODE لإنشاء امتداد.

مثال

سنركز على مثال بسيط للغاية حيث يعرض WebView إشعار VSCode ويتفاعل إشعار VSCODE مع حالة WebView. انظر الفيديو أدناه.

عينة

امتداد

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's Boilerplate. انتبه إلى كلما استخدمنا 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 

مثال كامل

يمكنك العثور على المثال الكامل في عينة مشروعنا.

مستندات

• ابدء
• مكتبة الخلفية
• مكتبة العميل