Personalizando o comportamento do editor usando a Configuração de Idioma

Você pode implementar uma sintaxe específica de linguagem personalizada no editor do Visual Studio usando a Configuração de Linguagem para habilitar operações de sintaxe específicas do idioma. Em comparação com o uso de um Servidor de Idiomas, o uso da Configuração de Idiomas pode melhorar o desempenho, já que todas as operações são locais.

O que é a Configuração de Idioma

O Visual Studio oferece recursos inteligentes de edição para várias linguagens de programação por meio de extensões de linguagem. A Configuração de Linguagem complementa os servidores que usam o Protocolo do Servidor de Linguagem (LSP) e fornece dados declarativos que permitem ao editor do Visual Studio tomar decisões de formatação, colorização e conclusão sem o atraso de fazer uma consulta assíncrona para o servidor LSP. Os recursos de linguagem declarativa são definidos em arquivos de configuração. Por exemplo, extensões HTML, CSS e typescript-basic agrupadas com o Visual Studio oferecem um subconjunto dos seguintes recursos de linguagem declarativa:

• Realce de sintaxe
• Conclusão do snippet
• Correspondência entre colchetes
• Autofechamento de colchetes
• Alternância de comentários
• Recuo automático

O Visual Studio fornece o recurso para extensões definirem uma configuração de idioma para qualquer linguagem de programação. O arquivo de configuração de idioma controla os recursos de edição fundamentais, como a alternância de comentários, a correspondência de colchetes e o cercamento.

Usar a Configuração de Idioma ajuda com:

• Trabalho síncrono na entrada de dados do usuário
• Simplicidade: arquivos JSON curtos com expressões regulares são mais fáceis de manter do que algoritmo complexo
• Portabilidade: não exigir nenhuma ou apenas mínimas alterações entre o Visual Studio Code e o Visual Studio

Além disso, os arquivos de configuração de idioma fornecem uma maneira fácil de estender o Visual Studio para dar suporte a alguns recursos básicos de refatoração por meio de um arquivo JSON fácil de ler.

Adicionar suporte à Configuração de Idioma a uma extensão do Visual Studio

Há três partes para adicionar suporte à Configuração de Idioma a uma extensão do Visual Studio:

1. Criar um projeto VSIX
2. Criar um arquivo de Configuração de Idioma
3. Adicionar um arquivo de gramática
4. Atualizar o arquivo pkgdef

Você pode explorar um exemplo de trabalho no Exemplo de Configuração de Idioma.

Criar um projeto VSIX

Para criar uma extensão de serviço de linguagem usando a Configuração de Linguagem, primeiro verifique se você tem a Carga de Trabalho de desenvolvimento de extensão do Visual Studio instalada para sua instância do VS.

Em seguida, crie um novo projeto VSIX navegando até File>New Project, pesquise "vsix" e procure o Projeto VSIX:

Criar um arquivo de configuração de idioma

Ao criar seu próprio arquivo de configuração de idioma, você pode escolher quais aspectos integrar no arquivo JSON. Por exemplo, você pode optar por dar suporte à alternância de comentários, fechamento automático de chaves ou qualquer combinação da funcionalidade disponível descrita nesta seção.

Para adicionar suporte à sua extensão, primeiro crie um arquivo de configuração de idioma. O nome do arquivo deve seguir um padrão: usar hifens para separar as palavras no nome do arquivo e verificar se ele termina com language-configuration.json.

O código a seguir mostra um arquivo de configuração de idioma de exemplo.

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

Definições de configuração

As seções a seguir descrevem as configurações disponíveis no arquivo de configuração de idioma.

Alternância de comentários

Os arquivos de configuração de idioma oferecem dois comandos para agregação de comentários. Alterne o comentário de linha e alterne o comentário de bloco. Você pode especificar comments.blockComment e comments.lineComment, para controlar como o Visual Studio deve comentar linhas ou blocos.

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

Essa configuração afeta o comportamento do editor de texto do Visual Studio quando você pressiona Ctrl+K, Ctrl+C.

Definição de colchetes

Quando você move o cursor para um colchete definido aqui, o Visual Studio realça esse colchete junto com seu par correspondente.

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

Fechamento Automático

Quando você digita ', o Visual Studio cria um par de aspas simples e coloca o cursor no meio: '|'. Esta seção define esses pares.

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

A notIn chave desabilita esse recurso em determinados intervalos de código. Por exemplo, quando você está escrevendo o seguinte código:

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

A aspa única não é fechada automaticamente.

Pares que não exigem uma notIn propriedade também podem usar uma sintaxe mais simples:

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

Fechamento Automático antes

Por padrão, o Visual Studio só fechará automaticamente pares se houver espaço em branco logo após o cursor. Portanto, ao digitar { no seguinte código JSX, você não obtém o fechamento automático.

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

No entanto, essa definição substitui esse comportamento:

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

Agora, quando você insere { logo antes de >, o Visual Studio o fecha automaticamente com }.

Autosurrounding

Quando você seleciona um intervalo no Visual Studio e insere um colchete de abertura, o Visual Studio envolve o conteúdo selecionado com um par de colchetes. Esse recurso é chamado de Autosurrounding e, aqui, você pode definir os pares de pareamento automático para um idioma específico.

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

Padrão de palavras

wordPattern define o que é considerado como uma palavra na linguagem de programação. Os recursos de sugestão de código usam essa configuração para determinar os limites de palavras se wordPattern estiver definido.

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

Regras de indentação

indentationRules define como o editor deve ajustar o recuo da linha atual ou da próxima linha quando você digitar, colar e mover linhas, ou quando você formatar texto com Ctrl+K, Ctrl+D (Formatar Documento) e Ctrl+K, Ctrl+F (Seleção de Formato).

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

Por exemplo, if (true) { corresponde increaseIndentPattern, então se você pressionar Enter após o colchete { aberto, o editor recuará automaticamente um nível, e seu código acabará como:

if (true) {
  console.log();

Além de increaseIndentPattern e decreaseIndentPatter, há duas outras regras de recuo.

• indentNextLinePattern - Se uma linha corresponder a esse padrão, somente a próxima linha depois dela, deverá ser indentada uma vez.
• unIndentedLinePattern - Se uma linha corresponder a esse padrão, seu recuo não deverá ser alterado e não deverá ser avaliado em relação às outras regras.

Se não houver nenhuma regra de indentação definida para a linguagem de programação, o editor recuará quando a linha terminar com um parêntese aberto e recuará quando você digitar um parêntese de fechamento. O colchete aqui é definido por brackets.

Pressionando Enter

onEnterRules define uma lista de regras a serem avaliadas quando Enter é pressionado no editor.

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

Ao pressionar Enter, o texto antes, depois ou uma linha acima do cursor é verificado nas seguintes propriedades:

• beforeText (obrigatório). Uma expressão regular que corresponde ao texto antes do cursor (limitado à linha atual).
• afterText. Uma expressão regular que corresponde ao texto após o cursor (limitado à linha atual).
• previousLineText. Uma expressão regular que corresponde ao texto uma linha acima do cursor.

Se todas as propriedades especificadas corresponderem, a regra será considerada correspondente e nenhuma outra onEnterRules opção será avaliada. Um onEnterRule pode especificar as seguintes ações:

• indent (obrigatório). Um dos none, indent, outdent, indentOutdent.
  • none significa que a nova linha herda a indentação da linha atual.
  • indent significa que a nova linha é indentada em relação à linha atual.
  • outdent significa que a nova linha está sem recuo em relação à linha atual.
  • indentOutdent significa que duas novas linhas são inseridas, uma com recuo e a segunda sem recuo.
• appendText. Uma cadeia de caracteres acrescentada após a nova linha e após o recuo.
• removeText. O número de caracteres a serem removidos da indentação da nova linha.

Definições de propriedades

No projeto de extensão, verifique se o language-configuration.json arquivo tem as seguintes configurações de propriedade:

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

(Opcional) Adicionar um arquivo de gramática

Além disso, você pode adicionar um arquivo de gramática TextMate para fornecer coloração de sintaxe para o idioma. As gramáticas TextMate são uma coleção estruturada de expressões regulares e são escritas como arquivos PLIST (XML) ou JSON. Consulte gramáticas de linguagem. Se você não fornecer um arquivo de gramática específico do idioma, uma configuração padrão interna será usada.

Para adicionar arquivos de gramática ou tema do TextMate personalizados, siga estas etapas:

1. Crie uma pasta chamada "Gramáticas" dentro de sua extensão (ou pode ser qualquer nome que você escolher).

2. Dentro da pasta gramáticas, inclua quaisquer arquivos *.tmlanguage, *.plist, *.tmthemeou *.json que você deseja que forneçam colorização personalizada.

   Dica

   Um arquivo .tmtheme define como as áreas de escopos são mapeadas para as classificações do Visual Studio (chaves de cores nomeadas). Para obter diretrizes, você pode referenciar o arquivo .tmtheme global no diretório %ProgramFiles(x86)%\Microsoft Visual Studio\<versão>\<SKU>\Common7\IDE\CommonExtensions\Microsoft\TextMate\Starterkit\Themesg.

Criar um arquivo pkgdef

Em seguida, crie um .pkgdef arquivo. Um .pkgdef arquivo contém todas as informações de registro que, de outra forma, seriam adicionadas ao registro do sistema. Para obter mais informações sobre pkgdef arquivos, consulte Registrar VSPackages e o que é um arquivo pkgdef? E por quê? No seu arquivo pkgdef, você deve ter o caminho para o arquivo language-configuration.json e o caminho para a gramática do idioma. Os serviços de linguagem, como provedores de serviços de linguagem (LSP), solicitam o tipo de conteúdo do editor e o obtêm por meio da Configuração de Linguagem. Essas informações fornecem a inteligência específica do idioma dentro de um servidor que pode se comunicar com ferramentas de desenvolvimento. Quando um serviço de idioma não existe, o mecanismo de Configuração de Linguagem volta para a gramática TextMate. O arquivo .pkgdef deve ter esta aparência:

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

Verifique se as propriedades do pkgdef arquivo estão definidas da seguinte maneira:

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

Para tornar as informações de configuração de idioma acessíveis para o Visual Studio, inclua o language-configuration arquivo no pacote VSIX. Incluir esse arquivo significa que ele é fornecido com a Extensão do Visual Studio. O arquivo permite que o Visual Studio saiba que uma Configuração de Idioma está disponível para uso. Para adicionar o arquivo, edite-o vsixmanifest para adicionar o arquivo def PKGDEF, por exemplo:

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

Conteúdo relacionado

• Protocolo do Servidor de Idiomas

• Exemplo de configuração de idioma