Editorgedrag aanpassen met behulp van Taalconfiguratie

U kunt aangepaste taalspecifieke syntaxis implementeren in de Visual Studio-editor met behulp van Taalconfiguratie om taalspecifieke syntaxisbewerkingen in te schakelen. In vergelijking met het gebruik van een taalserver kunnen de prestaties worden verbeterd door taalconfiguratie te gebruiken, omdat alle bewerkingen lokaal zijn.

Wat is taalconfiguratie?

Visual Studio biedt intelligente bewerkingsmogelijkheden voor verschillende programmeertalen via taalextensies. Language Configuration vormt een aanvulling op de servers die gebruikmaken van Language Server Protocol (LSP) en biedt declaratieve gegevens waarmee de Visual Studio-editor opmaak, kleuren en voltooiingsbeslissingen kan nemen zonder dat een asynchrone query naar de LSP-server wordt uitgevoerd. Declaratieve taalfuncties worden gedefinieerd in configuratiebestanden. Html-, CSS- en typescript-basic-extensies die zijn gebundeld met Visual Studio bieden bijvoorbeeld een subset van de volgende declaratieve taalfuncties:

• Syntaxmarkering
• Voltooiing van fragment
• Haakjeskoppeling
• Automatisch sluiten van haakjes
• Wisselknop voor opmerkingen
• Automatische inspringing

Visual Studio biedt de mogelijkheid voor extensies voor het definiëren van een taalconfiguratie voor elke programmeertaal. Het taalconfiguratiebestand bepaalt fundamentele bewerkingsfuncties zoals het schakelen van opmerkingen en het matchen en omringen van haakjes.

Het gebruik van Taalconfiguratie helpt bij het volgende:

• Synchroon werk tijdens het typen door gebruikers
• Eenvoud: Korte JSON-bestanden met reguliere expressies zijn eenvoudiger te onderhouden dan een complex algoritme
• Draagbaarheid: geen of minimale wijzigingen tussen Visual Studio Code en Visual Studio vereisen

Taalconfiguratiebestanden bieden ook een eenvoudige manier om Visual Studio uit te breiden ter ondersteuning van enkele eenvoudige herstructureringsfuncties via een eenvoudig te lezen JSON-bestand.

Taalconfiguratieondersteuning toevoegen aan een Visual Studio-extensie

Er zijn drie onderdelen voor het toevoegen van taalconfiguratieondersteuning aan een Visual Studio-extensie:

1. Een VSIX-project maken
2. Een taalconfiguratiebestand maken
3. Een grammaticabestand toevoegen
4. Het pkgdef-bestand bijwerken

U kunt een werkend voorbeeld verkennen in het voorbeeld van taalconfiguratie.

Een VSIX-project maken

Als u een taalservice-extensie wilt maken met behulp van Language Configuration, moet u eerst de Workload voor de ontwikkeling van de Visual Studio-extensie hebben geïnstalleerd voor uw exemplaar van VS.

Maak vervolgens een nieuw VSIX-project door naar File>New Project te navigeren, te zoeken naar 'vsix' en te zoeken naar VSIX Project:

Een taalconfiguratiebestand maken

Wanneer u uw eigen taalconfiguratiebestand maakt, kunt u kiezen welke aspecten u in het JSON-bestand wilt onboarden. U kunt er bijvoorbeeld voor kiezen om de commentaar omwisseling te ondersteunen, het automatisch sluiten van haakjes, of elke combinatie van de beschikbare functionaliteiten die in deze sectie worden beschreven.

Als u ondersteuning wilt toevoegen aan uw extensie, maakt u eerst een taalconfiguratiebestand. De naam van het bestand moet voldoen aan een standaard: gebruik afbreekstreepjes om de woorden in de bestandsnaam te scheiden en zorg ervoor dat het eindigt met language-configuration.json.

De volgende code toont een voorbeeld van een taalconfiguratiebestand.

{
    "comments": {
      "lineComment": "***",
      "blockComment": ["{*", "*}"]
    },
    "brackets": [
      ["@", "@"],
      ["#", "#"],
      ["$", "$"],
      ["(", ")"]
    ],
    "autoClosingPairs": [
      { "open": "{", "close": "}" },
      { "open": "@", "close": "@" },
      { "open": "#", "close": "#" },
      { "open": "$", "close": "$" },
      { "open": "(", "close": ")" },
      { "open": "'", "close": "'", "notIn": ["string", "comment"] },
      { "open": "\"", "close": "\"", "notIn": ["string"] },
    ],
    "autoCloseBefore": ";:.,=}])>` \n\t",
    "surroundingPairs": [
      ["@", "@"],
      ["#", "#"],
      ["$", "$"],
      ["[", "]"],
      ["(", ")"],
      ["'", "'"],
      ["\"", "\""],
      ["`", "`"]
    ],
    "wordPattern": "(-?\\d*\\.\\d\\w*)|([^\\`\\~\\!\\@\\#\\%\\^\\&\\*\\(\\)\\-\\=\\+\\[\\{\\]\\}\\\\\\|\\;\\:\\'\\\"\\,\\.\\<\\>\\/\\?\\s]+)",
    "indentationRules": {
      "increaseIndentPattern": "^((?!\\/\\/).)*(\\{[^}\"'`]*|\\([^)\"'`]*|\\[[^\\]\"'`]*)$",
      "decreaseIndentPattern": "^((?!.*?\\/\\*).*\\*/)?\\s*[\\)\\}\\]].*$"
    }
  }

Configuratie-instellingen

In de volgende secties worden de instellingen beschreven die beschikbaar zijn in het taalconfiguratiebestand.

Wisselknop voor opmerkingen

Taalconfiguratiebestanden bieden twee opdrachten voor het schakelen van opmerkingen. Lijncommentaar in-/uitschakelen en Blokcommentaar in-/uitschakelen. U kunt comments.blockComment en comments.lineComment specificeren om te bepalen hoe Visual Studio regels/blokken als commentaar moet plaatsen.

{
  "comments": {
    "lineComment": "//",
    "blockComment": ["/*", "*/"]
  }
}

Deze instelling is van invloed op het gedrag van de Visual Studio-teksteditor wanneer u op Ctrl+K, Ctrl+C drukt.

Definitie van haakjes

Wanneer u de cursor naar een haak verplaatst die hier is gedefinieerd, markeert Visual Studio die haak samen met zijn overeenkomende paar.

{
  "brackets": [["{", "}"], ["[", "]"], ["(", ")"]]
}

Automatisch sluiten

Wanneer u ' typt, maakt Visual Studio enkele aanhalingstekens en plaatst de cursor in het midden: '|'. In deze sectie worden dergelijke paren gedefinieerd.

{
  "autoClosingPairs": [
    { "open": "{", "close": "}" },
    { "open": "[", "close": "]" },
    { "open": "(", "close": ")" },
    { "open": "'", "close": "'", "notIn": ["string", "comment"] },
    { "open": "\"", "close": "\"", "notIn": ["string"] },
    { "open": "`", "close": "`", "notIn": ["string", "comment"] },
    { "open": "/**", "close": " */", "notIn": ["string"] }
  ]
}

Met notIn de sleutel wordt deze functie uitgeschakeld in bepaalde codebereiken. Wanneer u bijvoorbeeld de volgende code schrijft:

// ES6's Template String
`ES6's Template String`;

Het enkele aanhalingsteken wordt niet automatisch gesloten.

Paren waarvoor geen eigenschap is vereist notIn , kunnen ook een eenvoudigere syntaxis gebruiken:

{
  "autoClosingPairs": [ ["{", "}"], ["[", "]"] ]
}

Automatisch sluiten vóór

Standaard sluit Visual Studio alleen automatisch paren als er spaties direct na de cursor volgen. Dus wanneer u de volgende JSX-code typt { , krijgt u geen autoclose:

const Component = () =>
  <div className={>
                  ^ Does not get autoclosed by default
  </div>

Deze definitie overschrijft dit gedrag echter:

{
  "autoCloseBefore": ";:.,=}])>` \n\t"
}

Wanneer u { vlak voor > invoert, sluit Visual Studio dit automatisch met }.

Autosurrounding

Wanneer u een bereik in Visual Studio selecteert en een openingshaak invoert, wordt de geselecteerde inhoud omgeven door haakjes. Deze functie wordt Autosurrounding genoemd, en hier kunt u de autosurrounding-paren voor een specifieke taal definiëren:

{
  "surroundingPairs": [
    ["{", "}"],
    ["[", "]"],
    ["(", ")"],
    ["'", "'"],
    ["\"", "\""],
    ["`", "`"]
  ]
}

Woordpatroon

wordPattern definieert wat wordt beschouwd als een woord in de programmeertaal. Functies voor codesuggesties gebruiken deze instelling om woordgrenzen te bepalen als wordPattern deze is ingesteld.

{
  "wordPattern": "(-?\\d*\\.\\d\\w*)|([^\\`\\~\\!\\@\\#\\%\\^\\&\\*\\(\\)\\-\\=\\+\\[\\{\\]\\}\\\\\\|\\;\\:\\'\\\"\\,\\.\\<\\>\\/\\?\\s]+)"
}

Regels voor inspringing

indentationRulesdefinieert hoe de editor de inspringing van de huidige regel of de volgende regel moet aanpassen wanneer u een regel typt, plakt of verplaatst, of wanneer u tekst opmaakt met Ctrl+, CtrlD (Document opmaken) en Ctrl+, CtrlF (Selectie opmaken).

{
  "indentationRules": {
    "increaseIndentPattern": "^((?!\\/\\/).)*(\\{[^}\"'`]*|\\([^)\"'`]*|\\[[^\\]\"'`]*)$",
    "decreaseIndentPattern": "^((?!.*?\\/\\*).*\\*/)?\\s*[\\)\\}\\]].*$"
  }
}

Komt bijvoorbeeld if (true) { overeen met increaseIndentPattern, als u op Enter drukt na het geopende haakje {, voert de editor automatisch een inspringing in en wordt de code uiteindelijk als volgt weergegeven:

if (true) {
  console.log();

Naast increaseIndentPattern en decreaseIndentPatter zijn er twee andere inspringingsregels.

• indentNextLinePattern - Als een regel overeenkomt met dit patroon, moet alleen de volgende regel erna één keer worden ingesprongen.
• unIndentedLinePattern - Als een regel overeenkomt met dit patroon, moet de inspringing niet worden gewijzigd en mag deze niet worden geëvalueerd op basis van de andere regels.

Als er geen inspringingsregel is ingesteld voor de programmeertaal, zorgt de editor voor inspringing wanneer de regel eindigt met een open accolade en springt hij terug naar links wanneer u een sluitaccolade typt. De haak hier is gedefinieerd door brackets.

Op Enter drukken

onEnterRules definieert een lijst met regels die moeten worden geëvalueerd wanneer Enter wordt ingedrukt in de editor.

{
  "onEnterRules": [{
    "beforeText": "^\\s*(?:def|class|for|if|elif|else|while|try|with|finally|except|async).*?:\\s*$",
    "action": { "indent": "indent" }
  }]
}

Wanneer u op Enter drukt, wordt de tekst vóór, na of één regel boven de cursor gecontroleerd op de volgende eigenschappen:

• beforeText (verplicht). Een reguliere expressie die overeenkomt met de tekst vóór de cursor (beperkt tot de huidige regel).
• afterText. Een reguliere expressie die overeenkomt met de tekst na de cursor (beperkt tot de huidige regel).
• previousLineText. Een reguliere expressie die overeenkomt met de tekst één regel boven de cursor.

Als alle opgegeven eigenschappen overeenkomen, wordt de regel beschouwd als overeenkomend en wordt deze niet verder onEnterRules geëvalueerd. Een onEnterRule kan de volgende acties opgeven:

• indent (verplicht). Een van none, indent, outdent, indentOutdent.
  • none betekent dat de nieuwe regel de inspringing van de huidige regel over neemt.
  • indent betekent dat de nieuwe regel ingesprongen is ten opzichte van de huidige regel.
  • outdent betekent dat de nieuwe regel niet is ingedekend ten opzichte van de huidige regel.
  • indentOutdent betekent dat er twee nieuwe regels worden ingevoegd, waarbij de eerste regel ingesprongen is en de tweede regel zonder inspringing.
• appendText. Een tekenreeks die na de nieuwe regel en na de inspringing wordt toegevoegd.
• removeText. Het aantal tekens dat uit de inspringing van de nieuwe regel moet worden verwijderd.

Eigenschapsinstellingen

Zorg ervoor dat het language-configuration.json bestand in het extensieproject de volgende eigenschapsinstellingen heeft:

Build Action = Content
Include in VSIX = True
Copy to output = Copy always 

(Optioneel) Een grammaticabestand toevoegen

Daarnaast kunt u een TextMate-grammaticabestand toevoegen om syntaxiskleuring voor de taal te bieden. TextMate-grammatica's zijn een gestructureerde verzameling reguliere expressies en worden geschreven als een plist-bestand (XML) of JSON-bestanden. Zie Taal grammatica. Als u geen taalspecifiek grammaticabestand opgeeft, wordt een ingebouwde standaardinstelling gebruikt.

Volg deze stappen om aangepaste TextMate-grammatica- of themabestanden toe te voegen:

1. Maak een map met de naam Grammars in uw extensie (of het kan elke gewenste naam zijn).

2. Neem in de map Grammars alle *.tmlanguage, *.plist, *.tmthemeof *.json bestanden op die u wenst voor aangepaste kleuring.

   Aanbeveling

   Een .tmtheme-bestand definieert hoe de scopes worden toegewezen aan Visual Studio-classificaties (genaamde kleursleutels). Voor hulp kunt u verwijzen naar het algemene bestand .tmtheme in de %ProgramFiles(x86)%\Microsoft Visual Studio\<versie>\<SKU>\Common7\IDE\CommonExtensions\Microsoft\TextMate\Starterkit\Themesg directory.

Een pkgdef-bestand maken

Maak vervolgens een .pkgdef bestand. Een .pkgdef bestand bevat alle registratiegegevens die anders aan het systeemregister zouden worden toegevoegd. Zie voor meer informatie over pkgdef bestanden VsPackages registreren en Wat is een pkgdef-bestand? En waarom?. In het pkgdef bestand moet u het pad naar het language-configuration.json bestand en het pad voor de taal grammatica hebben. Taalservices zoals LSP vragen om het inhoudstype van de editor en krijgen dat via Taalconfiguratie. Deze informatie biedt de taalspecifieke intelligentie binnen een server die kan communiceren met ontwikkelhulpprogramma's. Wanneer er geen taalservice bestaat, valt de taalconfiguratie-engine terug op de TextMate-grammatica. Het .pkgdef bestand moet er als volgt uitzien:

[$RootKey$\TextMate\Repositories]
"AspNetCoreRazor="$PackageFolder$\Grammars

// Defines where the language configuration file for a given
// grammar name is (value of the ScopeName tag in the tmlanguage file).
[$RootKey$\TextMate\LanguageConfiguration\GrammarMapping]
"text.aspnetcorerazor"="$PackageFolder$\language-configuration.json"

// Defines where the language configuration file for a given
// language name is (partial value of the content type name).
[$RootKey$\TextMate\LanguageConfiguration\ContentTypeMapping]
"RazorLSP"="$PackageFolder$\language-configuration.json"

[$RootKey$\TextMate\LanguageConfiguration\GrammarMapping]
"text.html.basic"="$PackageFolder$\html-language-configuration.json"
"source.js"="$PackageFolder$\javascript-language-configuration.json"
"source.css"="$PackageFolder$\css-language-configuration.json"
"source.cs"="$PackageFolder$\csharp-language-configuration.json

Zorg ervoor dat de eigenschappen van het pkgdef bestand als volgt zijn ingesteld:

Build Action = Content
Include in VSIX = True
Copy to output = Copy always 

Als u de taalconfiguratiegegevens toegankelijk wilt maken voor Visual Studio, neemt u het language-configuration bestand op in het VSIX-pakket. Inclusief dit bestand betekent dat het wordt geleverd met de Visual Studio-extensie. Het bestand laat Visual Studio weten dat een taalconfiguratie beschikbaar is voor gebruik. Als u het bestand wilt toevoegen, bewerkt u het vsixmanifest bestand om uw PKGDEF-def-bestand toe te voegen, bijvoorbeeld:

<Asset Type="Microsoft.VisualStudio.VsPackage" Path="Test.pkgdef"/> 

Verwante inhoud

• Language Server Protocol

• Voorbeeld van taalconfiguratie