Dostosowywanie zachowania edytora przy użyciu konfiguracji języka

Niestandardową składnię specyficzną dla języka można zaimplementować w edytorze programu Visual Studio przy użyciu usługi Language Configuration w celu włączenia operacji składni specyficznych dla języka. W porównaniu z używaniem serwera językowego użycie konfiguracji języka może zwiększyć wydajność, ponieważ wszystkie jego operacje są lokalne.

Co to jest konfiguracja języka

Program Visual Studio oferuje inteligentne funkcje edycji dla różnych języków programowania za pośrednictwem rozszerzeń języka. Usługa Language Configuration uzupełnia serwery korzystające z protokołu LSP (Language Server Protocol) i udostępnia dane deklaratywne, które umożliwiają edytorowi programu Visual Studio podejmowanie decyzji dotyczących formatowania, kolorowania i uzupełniania bez opóźnień w podejmowaniu zapytania asynchronicznego na serwerze LSP. Funkcje języka deklaratywnego są definiowane w plikach konfiguracji. Na przykład rozszerzenia HTML, CSS i typescript-basic połączone z programem Visual Studio oferują podzestaw następujących funkcji języka deklaratywnego:

• wyróżnianie składni
• Uzupełnianie fragmentu kodu
• Dopasowywanie nawiasów
• Automatyczne zamykanie nawiasów
• Przełączanie komentarzy
• Autowcięcie

Visual Studio zapewnia możliwość dla rozszerzeń definiowania konfiguracji języka dla dowolnego języka programowania. Plik konfiguracji języka steruje podstawowymi funkcjami edycji, takimi jak przełączanie trybu komentarzy oraz dopasowywanie i otaczanie nawiasami.

Korzystanie z konfiguracji języka pomaga w:

• Synchroniczna praca nad wpisywaniem przez użytkownika
• Prostota: Krótkie pliki JSON z wyrażeniami regularnymi są łatwiejsze do utrzymania niż złożony algorytm
• Przenośność: nie wymagaj ani minimalnych zmian między programem Visual Studio Code i programem Visual Studio

Ponadto pliki konfiguracji języka umożliwiają łatwe rozszerzenie programu Visual Studio w celu obsługi niektórych podstawowych funkcji refaktoryzacji za pomocą łatwego do odczytania pliku JSON.

Dodawanie obsługi konfiguracji języka do rozszerzenia programu Visual Studio

Istnieją trzy części dotyczące dodawania obsługi konfiguracji języka do rozszerzenia programu Visual Studio:

1. Tworzenie projektu VSIX
2. Tworzenie pliku konfiguracji języka
3. Dodawanie pliku gramatycznego
4. Aktualizowanie pliku pkgdef

Możesz zapoznać się z przykładowym roboczym przykładem konfiguracji języka.

Tworzenie projektu VSIX

Aby utworzyć rozszerzenie usługi językowej przy użyciu konfiguracji języka, najpierw upewnij się, że masz zainstalowany pakiet rozwoju rozszerzeń Visual Studio dla Twojego wystąpienia Visual Studio.

Następnie utwórz nowy projekt VSIX, przechodząc do pozycji Plik>Nowy projekt, wyszukaj "vsix" i znajdź Projekt VSIX:

Tworzenie pliku konfiguracji języka

Podczas tworzenia własnego pliku konfiguracji języka można wybrać aspekty do dołączenia w pliku JSON. Możesz na przykład wybrać obsługę przełączania komentarzy, automatycznego zamykania nawiasów klamrowych lub dowolną kombinację dostępnych funkcji opisanych w tej sekcji.

Aby dodać obsługę rozszerzenia, należy najpierw utworzyć plik konfiguracji języka. Nazwa pliku musi być zgodna ze standardem: użyj łączników, aby oddzielić wyrazy w nazwie pliku i upewnij się, że kończy się language-configuration.jsonna .

Poniższy kod przedstawia przykładowy plik konfiguracji języka.

{
    "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*[\\)\\}\\]].*$"
    }
  }

Ustawienia konfiguracji

W poniższych sekcjach opisano ustawienia dostępne w pliku konfiguracji języka.

Przełączanie komentarzy

Pliki konfiguracji języka oferują dwa polecenia umożliwiające przełączanie komentarzy. Przełącz komentarz wiersza i przełącz komentarz blokowy. Możesz określić comments.blockComment i comments.lineComment, aby kontrolować, w jaki sposób program Visual Studio powinien komentować wiersze lub bloki.

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

To ustawienie wpływa na zachowanie edytora tekstów programu Visual Studio po naciśnięciu Ctrl+, Ctrl+C.

Definicja nawiasów

Gdy przesuniesz kursor do nawiasu zdefiniowanego tutaj, program Visual Studio wyróżnia ten nawias wraz z odpowiadającą parą.

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

Autoklosowanie

Podczas wpisywania ' Visual Studio tworzy parę pojedynczych cudzysłowów i umieszcza kursor w środku: '|'. Ta sekcja definiuje takie pary.

{
  "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"] }
  ]
}

Klucz notIn wyłącza tę funkcję w niektórych zakresach kodu. Na przykład podczas pisania następującego kodu:

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

Pojedynczy cudzysłów nie jest automatycznielosowany.

Pary, które nie wymagają notIn właściwości, mogą również używać prostszej składni:

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

Automatyczne zamykanie przed

Domyślnie Visual Studio automatycznie zamyka pary tylko wtedy, gdy zaraz po kursory znajduje się spacja. Dlatego, gdy wpisujesz { w następującym kodzie JSX, nie uzyskujesz automatycznego zamknięcia.

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

Jednak ta definicja zastępuje to zachowanie:

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

Teraz, gdy wprowadzisz { bezpośrednio przed >, program Visual Studio automatycznie zamyka go za pomocą }.

Autosurrounding

Po wybraniu zakresu w Visual Studio i wprowadzeniu nawiasu otwierającego, program otacza wybraną zawartość parą nawiasów. Ta funkcja nazywa się autosurrounding, tutaj możesz zdefiniować pary autosurrounding dla określonego języka.

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

Wzorzec programu Word

wordPattern definiuje to, co jest uważane za słowo w języku programowania. Funkcje sugestii kodu używają tego ustawienia, aby określić granice wyrazów, jeśli wordPattern jest ustawiona.

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

Reguły wcięcia

indentationRules definiuje sposób, w jaki edytor powinien dostosowywać wcięcie bieżącego lub następnego wiersza podczas pisania, wklejania, przenoszenia linii lub formatowania tekstu za pomocą Ctrl+K, Ctrl+D (Formatowanie dokumentu) oraz Ctrl+K, Ctrl+F (Formatowanie zaznaczenia).

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

Na przykład if (true) { dopasowuje się increaseIndentPattern, a następnie po naciśnięciu Enter po otwartym nawiasie { edytor automatycznie zrobi jedno wcięcie, a twój kod będzie wyglądać następująco:

if (true) {
  console.log();

Oprócz increaseIndentPattern i decreaseIndentPatter, istnieją dwie inne zasady dotyczące wcięcia:

• indentNextLinePattern - Jeśli wiersz pasuje do tego wzorca, tylko następny wiersz po nim powinien zostać wcięcie raz.
• unIndentedLinePattern — Jeśli wiersz pasuje do tego wzorca, jego wcięcie nie powinno zostać zmienione i nie powinno być oceniane względem innych reguł.

Jeśli nie ma ustawionej reguły wcięcia dla języka programowania, edytor wstawia wcięcie po zakończeniu wiersza otwartym nawiasem i usuwa wcięcie po wpisaniu nawiasu zamykającego. Nawias w tym miejscu jest zdefiniowany przez bracketselement .

Naciśnięcie Enter

onEnterRules Definiuje listę reguł do oceny, gdy Enter jest naciskany w edytorze.

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

Po naciśnięciu Enter tekst przed lub po jednym wierszu nad kursorem jest sprawdzany względem następujących właściwości:

• beforeText (obowiązkowe). Wyrażenie regularne, które pasuje do tekstu przed kursorem (ograniczone do bieżącego wiersza).
• afterText. Wyrażenie regularne zgodne z tekstem po kursorze (ograniczone do bieżącego wiersza).
• previousLineText. Wyrażenie regularne, które pasuje do tekstu w jednym wierszu nad kursorem.

Jeśli wszystkie określone właściwości pasują, reguła uznawana jest za spełnioną i dalsze onEnterRules nie są oceniane. Element onEnterRule może określać następujące akcje:

• indent (obowiązkowe). Jeden z none, indent, outdent, indentOutdent.
  • none oznacza, że nowa linia dziedziczy wcięcie z bieżącej linii.
  • indent oznacza, że nowy wiersz jest wcięty w stosunku do bieżącego wiersza.
  • outdent oznacza, że nowy wiersz jest niezidentyfikowany względem bieżącego wiersza.
  • indentOutdent oznacza, że wstawiane są dwie nowe linie: jedna z wcięciem, a druga bez wcięcia.
• appendText. Ciąg, który jest dołączany po nowym wierszu i po wcięciu.
• removeText. Liczba znaków do usunięcia z wcięcia nowego wiersza.

Ustawienia właściwości

W projekcie rozszerzenia upewnij się, że plik language-configuration.json ma następujące ustawienia właściwości:

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

(Opcjonalnie) Dodawanie pliku gramatycznego

Ponadto można dodać plik gramatyki TextMate, aby zapewnić kolorowanie składni dla języka. Gramatyki TextMate są kolekcją ze strukturą wyrażeń regularnych i są zapisywane jako pliki plist (XML) lub JSON. Zobacz Gramatyka języka. Jeśli nie podasz pliku gramatycznego specyficznego dla języka, zostanie użyte wbudowane ustawienie domyślne.

Aby dodać niestandardowe pliki gramatyki lub motywu TextMate, wykonaj następujące kroki:

1. Utwórz folder o nazwie "Gramatyki" wewnątrz rozszerzenia (lub może to być dowolna wybrana nazwa).

2. W folderze Grammars dołącz dowolne pliki *.tmlanguage, *.plist, *.tmthemelub wszystkie *.json, które mają zapewnić dostosowane kolorowanie.

   Wskazówka

   Plik .tmtheme definiuje sposób mapowania zakresów na klasyfikacje programu Visual Studio (nazwane klucze kolorów). Aby uzyskać wskazówki, możesz odwołać się do globalnego pliku .tmtheme w%%ProgramFiles(x86)%\Microsoft Visual Studio\<wersji>\<SKU>\Common7\IDE\CommonExtensions\Microsoft\TextMate\Starterkit\Themesg katalogu.

Tworzenie pliku pkgdef

Następnie utwórz .pkgdef plik. Plik .pkgdef zawiera wszystkie informacje rejestracyjne, które w przeciwnym razie zostaną dodane do rejestru systemowego. Aby uzyskać więcej informacji na temat pkgdef plików, zobacz Rejestrowanie pakietów VSPackages i Co to jest plik pkgdef? I dlaczego?. W swoim pliku pkgdef powinieneś mieć ścieżkę do pliku language-configuration.json oraz ścieżkę do gramatyki języka. Usługi językowe, takie jak LSP, proszą o typ zawartości edytora i uzyskają je za pośrednictwem konfiguracji języka. Te informacje zawierają analizę specyficzną dla języka na serwerze, która może komunikować się z narzędziami programistycznymi. Gdy usługa językowa nie istnieje, aparat konfiguracji języka wraca do gramatyki TextMate. Plik .pkgdef powinien wyglądać następująco:

[$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

Upewnij się, że właściwości pkgdef pliku są ustawione w następujący sposób:

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

Aby udostępnić informacje o konfiguracji języka dla programu Visual Studio, dołącz language-configuration plik do pakietu VSIX. Dołączenie tego pliku oznacza, że jest dostarczany z rozszerzeniem programu Visual Studio. Plik informuje program Visual Studio, że konfiguracja języka jest dostępna do użycia. Aby dodać plik, zmodyfikuj vsixmanifest, aby włączyć plik PKGDEF def, na przykład:

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

Treści powiązane

• Protokół serwera językowego

• Przykład konfiguracji języka