BlazorMonaco

BlazorMonaco

مكون Blazor لمحرر Microsoft Monaco الذي يعمل على تشغيل رمز Visual Studio.

يتم دعم معظم مجموعة ميزات محرر Monaco الرئيسية مع بعض الميزات الأقل استخدامًا في الوقت الحالي. أي مساهمات أو تعليقات أو اقتراحات مرحب بها إلى حد كبير. لا تتردد في الاتصال بي على x.com/serdarciplak أو عبر github.

نسخة BlazorMonaco الحالية:

• يستخدم Monaco Editor v0.52.2
• يدعم netstandard2.0 و net5.0 و net6.0 و net7.0 و net8.0 و net9.0

العرض التوضيحي

يمكنك رؤية تطبيق عينة العمل webassembly هنا.

تثبيت

• أضف حزمة Nuget إلى مشروع Blazor الخاص بك.

   dotnet add package BlazorMonaco
  // or
  Install-Package BlazorMonaco
  

• أضف علامات البرنامج النصي أدناه إلى نهاية علامة جسم HTML الخاصة بك. لاحظ أنه يجب وضعها قبل علامة البرنامج النصي ( blazor.webassembly.js ، blazor.server.js أو blazor.web.js ).

   < script src =" _content/BlazorMonaco/jsInterop.js " > </ script >
  < script src =" _content/BlazorMonaco/lib/monaco-editor/min/vs/loader.js " > </ script >
  < script src =" _content/BlazorMonaco/lib/monaco-editor/min/vs/editor/editor.main.js " > </ script >

• كل شيء يتواجد في ثلاثة مساحات أسماء. يمكنك إضافة ما يلي باستخدام التوجيهات إلى ملف _Imports.razor Root الخاص بك ، أو أي مكان آخر قد تحتاج إليه.

   @ using BlazorMonaco
  @ using BlazorMonaco . Editor
  @ using BlazorMonaco . Languages

• أضف StandaloneCodeEditor أو مكونًا StandaloneDiffEditor في ملف Razor وسترى المحرر المقدم مع الخيارات الافتراضية.

  < StandaloneCodeEditor />
  <!-- or -->
  < StandaloneDiffEditor />

ملاحظة: إذا كان لديك أي مشكلات مثل المحرر غير مرئي أو عدم تهيئة بشكل صحيح ، فيرجى التحقق من قسم استكشاف الأخطاء وإصلاحها أدناه.

الاستخدام

توفير الخيارات الأولية

لتخصيص الخيارات الأولية للمحرر الخاص بك ، قم بتعيين معلمة ConstructionOptions وتوفير طريقة تُرجع StandaloneEditorConstructionOptions .

< StandaloneCodeEditor Id = " my-code-editor " ConstructionOptions = " EditorConstructionOptions " />

@code {
    private StandaloneEditorConstructionOptions EditorConstructionOptions ( StandaloneCodeEditor editor )
    {
        return new StandaloneEditorConstructionOptions
        {
            AutomaticLayout = true ,
            Language = " javascript " ,
            Value = " function xyz() { n " +
                    "   console.log( " Hello world! " ); n " +
                    " } "
        };
    }
}

الاستماع إلى أحداث المحرر

يمكنك الاشتراك في أحداث المحرر (على سبيل المثال OnDidKeyUp أو OnDidPaste ) عبر معلمات حدث المحرر.

< StandaloneCodeEditor Id = " my-code-editor " OnDidChangeCursorPosition = " EditorDidChangeCursorPosition " />

@code {
    private void EditorDidChangeCursorPosition ( CursorPositionChangedEvent eventArgs )
    {
        Console . WriteLine ( " EditorDidChangeCursorPosition " );
    }
}

الوصول إلى المحررين والأحداث الداخلية لمحرر Diff

يوفر StandaloneDiffEditor خصائصين يدعى OriginalEditor و ModifiedEditor للوصول إلى مثيلات المحرر الداخلي. يمكنك استخدامها مثل أي مثال آخر StandaloneCodeEditor .

يمكنك التسجيل في أحداث المحررين الداخليين باستخدام معلمات حدث Helper في مثيل StandaloneDiffEditor الرئيسي.

< StandaloneDiffEditor @ref = " _diffEditor " Id = " my-diff-editor " OnKeyUpOriginal = " OnKeyUpOriginal " OnKeyUpModified = " OnKeyUpModified " />

@code {
    private StandaloneDiffEditor _diffEditor ;

    private void OnKeyUpOriginal ( KeyboardEvent keyboardEvent )
    {
        StandaloneCodeEditor originalEditor = _diffEditor . OriginalEditor ;
        Console . WriteLine ( " OnKeyUpOriginal : " + keyboardEvent . Code );
    }

    private void OnKeyUpModified ( KeyboardEvent keyboardEvent )
    {
        StandaloneCodeEditor modifiedEditor = _diffEditor . ModifiedEditor ;
        Console . WriteLine ( " OnKeyUpModified : " + keyboardEvent . Code );
    }
}

تصميم CSS

هناك 3 محددات CSS يمكنك استخدامها لتخصيص أنماط CSS لمحرريك.

• يتم احتواء جميع حالات المحرر في عنصر div يحتوي على فئة CSS من monaco-editor-container .
• تم تعيين قيمة Id التي قمت بتعيينها لمثيل المحرر الخاص بك أيضًا كمعرف لعنصر الحاوية div .
• إذا قمت بتعيين خاصية CssClass الخاصة بالمحرر ، تتم إضافة هذه القيمة إلى سمة الفصل لعنصر الحاوية DIV الخاص به.

وهذا يعني أن مكون الحلاقة أدناه ؛

< StandaloneCodeEditor Id = " my-editor-id " CssClass = " my-editor-class " />

يتم تقديمه مع HTML أدناه ؛

 < div id =" my-editor-id " class =" monaco-editor-container my-editor-class " >
    ...
</ div >

لذلك ، يمكنك استخدام محددات CSS مثل أدناه لتحديد أي عنصر في محرر وتخصيص تصميمه.

 # my-editor-id { /* applies to a specific editor instance */
    height : 100 px ;
}

. my-editor-class { /* applies to all editor instances with this class */
    height : 100 px ;
}

. monaco-editor-container { /* applies to all editor instances */
    height : 100 px ;
}

الأساليب العالمية

تحدد مكتبة محرر Monaco JavaScript بعض الطرق في النطاق العالمي. نظرًا لأن C# لا يسمح بالأساليب العالمية ، يجمع BlazorMonaco تلك الأساليب في فئتين ثابتتين تدعى BlazorMonaco.Editor.Global و BlazorMonaco.Language.Global . إذا كنت بحاجة إلى استخدام طريقة محرر Monaco في النطاق العالمي ، فتحقق من مكان مكتبة JavaScript هذه ، والبحث عنها في الفئة Global المقابلة.

على سبيل المثال ، يمكنك استخدام طريقة SetTheme كما أدناه.

 await BlazorMonaco . Editor . Global . SetTheme ( jsRuntime , "my-custom-theme" ) ;

باستخدام تثبيت محرر موناكو مخصص

إذا قمت بإجراء تغييرات على مكتبة Monaco Editor JS ، وتحتاج إلى استخدام هذا الإصدار المعدل بدلاً من الإصدار غير المعدل المضمن في BlazorMonaco ، يمكنك تعديل علامات البرنامج النصي كما هو الحال أدناه.

 < script src =" _content/BlazorMonaco/jsInterop.js " > </ script >
< script > var require = { paths : { vs : 'my-path/monaco-editor/min/vs' } } ; </ script >
< script src =" my-path/monaco-editor/min/vs/loader.js " > </ script >
< script src =" my-path/monaco-editor/min/vs/editor/editor.main.js " > </ script > 

استكشاف الأخطاء وإصلاحها

• س: لقد أضفت StandaloneCodeEditor كما هو موضح أعلاه ، لكنه لا يتم تحميله.

  ج: على الأرجح ، يتم تحميل المحرر فعليًا ولكن لا يمكنك رؤيته لأنه يبلغ ارتفاعه 0. كيف يمكن ضبط ارتفاع عنصر DOM يعتمد على عناصره الأم وتصميمها. لذلك ، لا يمكن لـ BlazorMonaco إدارة ارتفاع مثيلات المحرر داخليًا. إذا لم تقم بتعيين ارتفاع المحرر ، فقد يكون ذلك غير مرئي لأنه يبلغ ارتفاعه 0px . يرجى إضافة نمط CSS لتعيين ارتفاع المحرر الخاص بك وفقًا للمكان الذي تم وضعه فيه.

   # my-editor-id {
      height : 100 px ;
  }

• س: لا يهيئ المحرر بشكل صحيح في تطبيق Web Blazor الخاص بي.

  ج: لتكون قادرًا على العمل مع مكتبة Monacoeditor JS التفاعلية ، يتطلب BlazorMonaco وضع عرض تفاعلي. إذا قمت بوضع مثيل المحرر في صفحة تستخدم عرضًا ثابتًا من جانب الخادم (SSR ثابت) ، فلن يتمكن مثيل المحرر من تهيئة ويعمل.

  يمكنك تعيين وضع عرض تفاعلي على مستوى العالم على مستوى التطبيق ،

   <!-- In your App.razor file -->
  < Routes @rendermode = " InteractiveServer " />

  فقط لصفحة محددة ،

   <!-- In the razor file of your page that contains the editor -->
  @page " /editor-page "
  @rendermode InteractiveServer
  
  < StandaloneCodeEditor />

  أو فقط للمكون الذي يلف مثيل المحرر.

   <!-- In the razor file of your interactive wrapper component -->
  @rendermode InteractiveServer
  
  < StandaloneCodeEditor />

• س: يعمل المحرر بشكل جيد في المرة الأولى التي يتم عرضه فيها. ولكن تم كسره (كما لو كان نمط CSS غير صحيح) ، إذا كان المستخدم ينتقل إلى صفحة أخرى ويعود إلى صفحة المحرر.

  ج: يرجى التحقق من أن الصفحة التي تحتوي على مثيل المحرر لا يتم فتحها مع التنقل المحسّن للبلازور. تعزيز التنقل التخلص من التغييرات الديناميكية التي تم إجراؤها على DOM بواسطة مكتبة Monacoeditor JS وكسر المحرر. تحتاج إلى تعطيل التنقل المحسّن للصفحات التي تحتوي على محرر.

  يمكنك تعيين سمة- data-enhance-nav لروابطك إلى false ،

   < a href =" editor-page " data-enhance-nav =" false " > Editor Page </ a >

  تعيين معلمة forceLoad في مكالمات NavigateTo() إلى True ،

   Navigation . NavigateTo ( "editor-page" , true ) ;

  أو استخدم مستندات Blazor هنا لمعرفة جميع طرق تعطيل التنقل المحسن.

الوثائق

نظرًا لأن Blazormonaco هو مجرد جسر بين JavaScript و Blazor ، يمكنك استخدام وثائق Monaco Editor.

دليل الهجرة

بعد تحديث إصدار رئيسي (مثل من v2.x إلى v3.x ) ، قد تحتاج إلى إجراء بعض التغييرات في التكامل الخاص بك. يرجى الاطلاع على ملف migrate.md للحصول على التفاصيل.

Changelog

يمكنك عرض التاريخ والتغييرات في ملف changelog.md.

رخصة

معهد ماساتشوستس للتكنولوجيا ، راجع ملف الترخيص للحصول على التفاصيل.