Personalización del comportamiento del editor mediante la configuración del lenguaje

Puede implementar la sintaxis personalizada específica del lenguaje en el editor de Visual Studio mediante Language Configuration para habilitar operaciones de sintaxis específicas del lenguaje. En comparación con el uso de un servidor de idioma, el uso de Language Configuration puede mejorar el rendimiento, ya que todas sus operaciones son locales.

¿Qué es la configuración del lenguaje?

Visual Studio ofrece funcionalidades de edición inteligentes para varios lenguajes de programación a través de extensiones de lenguaje. Language Configuration complementa los servidores que usan el Protocolo de servidor de lenguaje (LSP) y proporciona datos declarativos que permiten al editor de Visual Studio tomar decisiones de formato, coloración y finalización sin demora de realizar una consulta asincrónica en el servidor LSP. Las características del lenguaje declarativo se definen en los archivos de configuración. Por ejemplo, las extensiones HTML, CSS y typescript-basic agrupadas con Visual Studio ofrecen un subconjunto de las siguientes características de lenguaje declarativo:

• Resaltado de sintaxis
• Finalización del fragmento de código
• Coincidencia de paréntesis
• Cierre automático de corchetes
• Alternancia de comentarios
• Autoindentación

Visual Studio proporciona la capacidad de las extensiones para definir una configuración de lenguaje para cualquier lenguaje de programación. El archivo de configuración de idioma controla las características de edición fundamentales, como la alternancia de comentarios y la coincidencia de corchetes y los alrededores.

Utilizar Configuración de Idioma ayuda con:

• Trabajo sincrónico mientras el usuario escribe
• Simplicidad: los archivos JSON cortos con expresiones regulares son más fáciles de mantener que el algoritmo complejo.
• Portabilidad: no requerir cambios o requerir cambios mínimos entre Visual Studio Code y Visual Studio

Además, los archivos de configuración de lenguaje proporcionan una manera sencilla de ampliar Visual Studio para admitir algunas características básicas de refactorización a través de un archivo JSON fácil de leer.

Agregar compatibilidad con la configuración de lenguaje a una extensión de Visual Studio

Hay tres partes para agregar compatibilidad con Language Configuration a una extensión de Visual Studio:

1. Creación de un proyecto VSIX
2. Crear un archivo de configuración de idioma
3. Agregar un archivo de gramática
4. Actualización del archivo pkgdef

Puede explorar un ejemplo de trabajo en Ejemplo de configuración de lenguaje.

Creación de un proyecto VSIX

Para crear una extensión de servicio de lenguaje mediante Language Configuration, asegúrese de que tiene instalada la carga de trabajo de desarrollo de extensiones de Visual Studio para la instancia de VS.

A continuación, cree un nuevo proyecto VSIX; para ello, vaya a Archivo>nuevo proyecto, busque "vsix" y busque Proyecto VSIX:

Creación de un archivo de configuración de idioma

Al crear su propio archivo de configuración de lenguaje, puede elegir qué aspectos incorporar en el archivo JSON. Por ejemplo, puede optar por admitir la alternancia de comentarios, el cierre automático de llaves o cualquier combinación de funcionalidades disponibles que se describen en esta sección.

Para agregar compatibilidad con la extensión, primero debe crear un archivo de configuración de lenguaje. El nombre del archivo debe seguir un estándar: use guiones para separar las palabras del nombre de archivo y asegúrese de que termina con language-configuration.json.

En el código siguiente se muestra un archivo de configuración de lenguaje de ejemplo.

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

Parámetros de configuración

En las secciones siguientes se describen las opciones disponibles en el archivo de configuración de idioma.

Alternancia de comentarios

Los archivos de configuración de lenguaje ofrecen dos comandos para alternar comentarios. Alternar Comentario de línea y Alternar Comentario de bloque. Puede especificar comments.blockComment y comments.lineComment para controlar cómo Visual Studio debe comentar líneas o bloques.

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

Esta configuración afecta al comportamiento del editor de texto de Visual Studio al presionar Ctrl+K, Ctrl+C.

Definición de corchetes

Al mover el cursor a un corchete definido aquí, Visual Studio resalta ese corchete junto con su par coincidente.

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

Cierre automático

Al escribir ', Visual Studio crea un par de comillas simples y coloca el cursor en el centro: '|'. En esta sección se definen estos 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"] }
  ]
}

La notIn clave deshabilita esta característica en determinados intervalos de código. Por ejemplo, al escribir el código siguiente:

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

La comilla simple no se cierra automáticamente.

Los pares que no requieren una notIn propiedad también pueden usar una sintaxis más sencilla:

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

Cierre automático antes

De forma predeterminada, Visual Studio solo cierra automáticamente los pares si hay un espacio justo después del cursor. Cuando escribes { en el siguiente código JSX, no se obtendrá cierre automático.

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

Sin embargo, esta definición invalida ese comportamiento:

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

Ahora, cuando escriba { justo antes de >, Visual Studio lo cierra automáticamente con }.

Autosurrounding

Al seleccionar un rango en Visual Studio e introducir un corchete que abre, el contenido seleccionado se rodeará automáticamente con un par de corchetes. Esta característica se denomina Autosurrounding y aquí puede definir los pares de autosurrounding para un idioma específico:

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

Patrón de palabras

wordPattern define lo que se considera una palabra en el lenguaje de programación. Las características de sugerencia de código usan esta configuración para determinar los límites de palabras si wordPattern se establece.

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

Reglas de sangría

indentationRulesdefine cómo el editor debe ajustar la sangría de la línea actual o de la línea siguiente al escribir, pegar y mover líneas, o al dar formato al texto con Ctrl+K, Ctrl+D (Formato documento) y Ctrl+, Ctrl+F (Formato selección).

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

Por ejemplo, if (true) { coincide con increaseIndentPattern, y luego si presiona Enter después del corchete { abierto, el editor hará una sangría automáticamente y el código se presentará como:

if (true) {
  console.log();

Además de increaseIndentPattern y decreaseIndentPatter, hay otras dos reglas de sangría:

• indentNextLinePattern - Si una línea coincide con este patrón, entonces solo la siguiente línea después debe tener una sangría.
• unIndentedLinePattern - Si una línea coincide con este patrón, no se debe cambiar su sangría y no se debe evaluar con las demás reglas.

Si no hay ninguna regla de sangría establecida para el lenguaje de programación, el editor aplica sangría cuando la línea termina con un paréntesis abierto y reduce la sangría cuando escribes un paréntesis de cierre. El corchete aquí se define por brackets.

Presionar Entrar

onEnterRules define una lista de reglas que se van a evaluar cuando se presiona Entrar en el editor.

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

Al presionar Entrar, el texto antes, después o una línea encima del cursor se comprueba con las siguientes propiedades:

• beforeText (obligatorio). Expresión regular que coincide con el texto antes del cursor (limitado a la línea actual).
• afterText. Expresión regular que coincide con el texto después del cursor (limitado a la línea actual).
• previousLineText. Expresión regular que coincide con el texto de una línea encima del cursor.

Si todas las propiedades especificadas coinciden, la regla se considera que coincide y no se evalúa más onEnterRules . Una onEnterRule puede especificar las siguientes acciones:

• indent (obligatorio). Uno de none, indent, outdent, indentOutdent.
  • none significa que la nueva línea hereda la sangría de la línea actual.
  • indent significa que la nueva línea está indentada en relación con la línea actual.
  • outdent significa que la nueva línea no está cargada en relación con la línea actual.
  • indentOutdent significa que se insertan dos nuevas líneas: una con sangría y la segunda sin sangría.
• appendText. Cadena que se anexa después de la nueva línea y después de la sangría.
• removeText. Número de caracteres a eliminar de la sangría de la nueva línea.

Configuración de propiedades

En el proyecto de extensión, asegúrese de que el archivo language-configuration.json tenga las siguientes configuraciones de propiedades:

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

(Opcional) Agregar un archivo de gramática

Además, puede agregar un archivo de gramática TextMate para proporcionar colores de sintaxis para el idioma. Las gramáticas textMate son una colección estructurada de expresiones regulares y se escriben como archivos plist (XML) o JSON. Consulte Gramáticas de lenguaje. Si no proporciona un archivo de gramática específico del idioma, se usa una configuración predeterminada integrada.

Para agregar archivos personalizados de gramática o tema de TextMate, siga estos pasos:

1. Cree una carpeta denominada "Gramáticas" dentro de la extensión (o puede ser el nombre que elija).

2. Dentro de la carpeta Grammars, incluya cualquier archivo *.tmlanguage, *.plist, *.tmtheme, o *.json que desee para proporcionar coloración personalizada.

   Sugerencia

   Un archivo .tmtheme define cómo los ámbitos se asignan a las clasificaciones de Visual Studio (claves de color con nombre). Para obtener instrucciones, puede hacer referencia al archivo global .tmtheme en el directorio %ProgramFiles(x86)%\Microsoft Visual Studio\<version>\<SKU>\Common7\IDE\CommonExtensions\Microsoft\TextMate\Starterkit\Themesg.

Creación de un archivo pkgdef

A continuación, cree un .pkgdef archivo. Un .pkgdef archivo contiene toda la información de registro que, de lo contrario, se agregaría al registro del sistema. Para obtener más información sobre pkgdef los archivos, consulte Registrar VSPackages y ¿Qué es un archivo pkgdef? ¿Y por qué?. En tu archivo pkgdef, debes tener la ruta al archivo language-configuration.json y la ruta de la gramática del idioma. Los servicios de lenguaje como LSP solicitan el tipo de contenido del editor y lo obtienen a través de Language Configuration. Esta información proporciona la inteligencia específica del lenguaje dentro de un servidor que puede comunicarse con herramientas de desarrollo. Cuando no existe un servicio de idioma, el motor de configuración de idioma vuelve a la gramática TextMate. El archivo .pkgdef debería tener este aspecto:

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

Asegúrese de que las propiedades del archivo pkgdef se establezcan de la siguiente manera:

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

Para que la información de configuración del lenguaje sea accesible para Visual Studio, incluya el language-configuration archivo en el paquete VSIX. Incluir este archivo significa que se incluye con la extensión de Visual Studio. El archivo permite a Visual Studio saber que hay disponible una configuración de lenguaje para su uso. Para agregar el archivo, edite vsixmanifest para agregar el archivo PKGDEF def, por ejemplo:

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

Contenido relacionado

• Protocolo de servidor de idioma

• Ejemplo de configuración de idioma