Mestre de Snippets no VS Code para Codificação Eficiente

Ao escrever o código mais recente no Visual Studio Code (VS Code), você se pega digitando a mesma coisa várias vezes? Talvez você tenha digitado a declaração de uma função dez vezes hoje ou definido o mesmo conjunto de parâmetros pela vigésima vez. Você sabia que pode economizar tempo e sanidade usando snippets do Visual Studio Code?

Os snippets do Visual Studio Code são pequenos trechos de texto armazenados no VS Code. Você pode invocar esses snippets por meio de um menu ou sequência de teclas e pode economizar muito tempo quando se encontra repetindo blocos de texto com poucas diferenças entre cada ocorrência.

Por exemplo, abaixo você pode ver que, ao digitar wvb no VS Code, você tem a opção de expandir um texto muito maior, como indicado pelo texto Write-Verbose na caixa. Isso é o poder dos snippets!

Neste artigo, você aprenderá a trabalhar com snippets do VS Code, incluindo o uso de snippets padrão, snippets de extensões e até mesmo a criação dos seus próprios!

Pré-requisitos

Este será um artigo prático para você colocar a mão na massa. Se você pretende acompanhar e aprender como trabalhar com snippets do VS Code, você precisará da versão 1.17 ou superior do VS Code. Para total transparência, estarei usando o VS Code 1.38.1 no Windows.

Você pode baixar a versão mais recente do VS Code para sua plataforma específica aqui.

Encontrando snippets do VS Code

Antes de começar a construir seus próprios trechos de código (o que você fará), é importante aprender a encontrar os trechos de código integrados disponíveis para você.

Você pode encontrar todos os trechos de código no menu de interface. A interface do menu permite que você revise e use os trechos de código. Para acessar o menu, você pode pressionar F1 ou Ctrl-Shift-P, digitar “trecho de código” e pressionar Enter. Você verá um menu aparecer semelhante ao que você vê abaixo.

Quando você pressiona Enter em Inserir Trecho de Código, você verá um menu suspenso de trechos de código disponíveis, como mostrado abaixo. Você pode ver que há vários trechos de código disponíveis por padrão e ver mais rolando para baixo.

O menu suspenso de trechos de código disponíveis permite que você revise os trechos de código integrados que estão disponíveis através da adição de uma extensão de linguagem no VS Code.

Extensões de Linguagem

Você pode usar o VS Code para trabalhar com muitas linguagens diferentes. Cada linguagem tem suas próprias nuances. Para dar suporte a essas diferenças, o VS Code suporta extensões de linguagem.

As extensões de linguagem fornecem ao VS Code recursos de edição inteligentes para diferentes linguagens de programação. As extensões de linguagem oferecem suporte adicional à linguagem de programação, como:

• Destaque de sintaxe
• IntelliSense
• Formatação
• Verificação de erros
• Completude de trechos de código

As extensões são instaladas através do menu de Extensão do VS Code.

Você pode revisar a definição desses trechos fornecidos pelas extensões de linguagem abrindo o arquivo JSON no Windows localizado em C:\Users\\.vscode\extensions\ms-code.-\snippets.

As extensões em si não têm nada a ver com trechos de código, mas você vai encontrar que muitas extensões vêm com trechos embutidos dos quais você deve estar ciente.

Expansão de Trechos

Quando você seleciona um trecho via interface do menu, verá o conteúdo do trecho no arquivo. Esse processo de converter as definições de trechos em código útil é chamado de expansão.

Quando você chama o prefixo, o VS Code lê esse prefixo específico e executa quaisquer instruções que você definiu no trecho. Essas instruções podem variar de trecho para trecho. Todo esse processo de chamar, converter e inserir o trecho é chamado de expansão.

Usando Trechos de Extensão do VS Code

Alguns trechos vêm, por padrão, no VS Code, mas quando você instala uma extensão, às vezes eles vêm com seus próprios trechos. Exemplos de extensões com trechos incluídos são a extensão Python da Microsoft, a extensão PowerShell da Microsoft e a extensão C# da Microsoft.

Onde os Trechos de Extensão são Armazenados

Essas extensões são normalmente instaladas no Windows sob o diretório C:\Users<NomeDoUsuário>.vscode\extensions do seu computador, como você pode ver abaixo.

As pastas para as extensões seguem a convenção de nomenclatura ms-vscode.-. Cada uma dessas pastas contém uma pasta snippet que possui os trechos de código incluídos com a extensão.

Exemplo de Trecho de Código de Extensão

Para demonstrar o uso de um trecho de código de extensão, vamos pegar a extensão do PowerShell como exemplo. Essa extensão vem com alguns trechos de código úteis chamados region e for para acelerar a criação de blocos de região do PowerShell e *loops* for.

Digamos que você precise criar um loop for em um script do PowerShell dentro de um bloco de região. O código para fazer isso é mostrado abaixo. O código na captura de tela abaixo tem 50 caracteres de comprimento e cria um loop for dentro de um bloco de região que itera sobre os números de 1 a 10.

Em vez de digitar cada caractere neste exemplo, você pode usar dois trechos de código que vêm instalados com a extensão do PowerShell da Microsoft chamados region e for.

Dê uma olhada abaixo para ver como é fácil usar cada um desses trechos de código para economizar muito tempo digitando!

Criando Snippets de Código Personalizados no Visual Studio Code

Você não precisa se limitar aos snippets que vêm com o próprio VS Code ou com as extensões. Talvez as extensões existentes não contenham o layout de código que você precisa ou você queira formatar esses snippets você mesmo. Felizmente, você pode criar seus próprios snippets! Nesta seção, você verá como fazer isso.

Para criar um snippet personalizado, abra seus Snippets do Usuário no VS Code clicando em Arquivos → Preferências → Snippets do Usuário. Isso abrirá o escopo de seleção de linguagem de snippet para você. É aqui que você pode especificar a linguagem na qual deseja criar o snippet. Você pode ver um exemplo de como isso se parece na captura de tela abaixo.

Ao escolher uma linguagem, o VS Code criará um arquivo language.json em C:\Users<NomeDeUsuário>\AppData\Roaming\Code\User\snippets no Windows. Todos os snippets do usuário criados para diferentes linguagens terão um arquivo neste diretório.

As linguagens disponíveis podem ser diferentes das que você vê acima. Na instalação do VS Code acima, muitas extensões de linguagem já foram instaladas.

Encontre a linguagem para a qual você deseja criar o snippet e pressione Enter para abrir o arquivo JSON da linguagem. Este arquivo é onde seus snippets personalizados serão armazenados e é aqui que você pode criar seus snippets personalizados.

Há quatro itens de dados a serem especificados para um snippet personalizado:

1. A snippet name (line 9 below)
2. A prefix, which is what you’ll use to call your snippet (line 8 below)
3. A body, which is your snippet code that is loaded into your scripts (lines 7 to 3 below)
4. A description, which will show up in your IntelliSense (line 2 below)

Criando um Snippet Personalizado de Python

Vamos ver o que é necessário para criar um trecho personalizado para a linguagem de programação Python. Neste exemplo, o prefixo dt invocará um trecho personalizado em Python. Este trecho imprimirá uma mensagem com o horário atual pré-populado.

Crie o Arquivo JSON

Primeiro, abra o seletor de linguagem de trechos, digite Python e pressione Enter para criar um arquivo python.json. Isso abrirá um arquivo python.json na pasta C:\Users<NomeDoUsuário>\AppData\Roaming\Code\User\snippets do Windows.

Você pode ver seu estado padrão na imagem abaixo.

Atribuindo um Nome e Prefixo

Agora é hora de começar a editar o arquivo JSON. Primeiro, defina o nome e o prefixo (dt). Os prefixos de trechos são curtos e claros, pois é o valor digitado para chamar o trecho. Quanto mais curto o prefixo do trecho, menos caracteres você precisará digitar ao chamá-lo.

Você pode ver um exemplo de como isso se parece abaixo.

Definindo o Corpo

O corpo contém o código que será expandido quando o trecho for chamado. Este código pode ser texto simples e comentários. Ele também pode ter outras funções que você verá nas seções posteriores. Se o corpo tiver muitas linhas, há algumas armadilhas que você precisará observar.

• Cada linha precisa estar entre aspas duplas
• Cada linha precisa terminar com uma vírgula
• Todas as linhas precisam estar entre colchetes (“[” e “]”)

Você pode ver um exemplo de como o corpo do trecho se parece abaixo.

Definindo a Descrição

A descrição é uma mensagem descrevendo o prefixo como visto abaixo que está definido abaixo do corpo.

A descrição será mostrada abaixo do prefixo na lista de trechos e fornece mais informações sobre o que o trecho faz. Também ajuda a diferenciar o trecho de outros similares criados.

Aqui está um exemplo de captura de tela de trechos identificando prefixos e descrições.

Se você ainda não tiver nenhum trecho Python personalizado definido, quando terminar de criar o trecho, você deverá ter um arquivo python.json que se parece com o trecho de código abaixo.

{
    "DateTime Snippet": {
        "prefix": "dt",
        "body": [
            "import datetime",
            "dt = datetime.datetime.now()",
            "print(f\"The time is {dt} and this is a message\")"
        ],
        "description": "Prints a message with current time"
    }
}

Salve este arquivo JSON e agora o trecho personalizado estará disponível em qualquer arquivo Python no VS Code.

Agora, quando você abrir uma aba Python e digitar o prefixo dt, o trecho personalizado abaixo aparecerá. Pressionar Enter expandirá o corpo do trecho na aba Python.

Criando um Trecho JavaScript Personalizado Usando Texto Incluído

Os trechos não estão isolados nas palavras que você define no corpo do trecho. Os trechos também podem incluir texto do arquivo de onde você os está chamando.

O VS Code possui variáveis internas que você pode usar. Estas são espaços reservados que pegam o texto atualmente destacado e o inserem no trecho. Por exemplo, ao colocar a variável $TM_SELECTED_TEXT no trecho, você pode mostrar o texto selecionado. Confira a página de Referência de Variáveis do VS Code para uma descrição completa de todas as variáveis internas do VS Code.

Para demonstrar, vamos criar um trecho de código que simplesmente cria uma linha para imprimir o texto selecionado no console chamado log-it.

Abra o seletor de linguagem do trecho, digite JavaScript e pressione Enter para criar um arquivo javascript.json. Este arquivo será semelhante ao arquivo python.json criado na seção anterior. Embora desta vez, contenha um código JavaScript de exemplo em vez de código Python. Você pode ver seu estado padrão na captura de tela abaixo.

Agora crie um trecho usando o seguinte JSON:

{
	"Print selected line to console": {
		"prefix": "log-it",
		"body": [
			"console.log('$TM_SELECTED_TEXT');"
		],
		"description": "Log highlighted text output to console"
	}
}

Salve este arquivo JSON e agora você pode usar este trecho em seus arquivos JavaScript.

Ao chamar este trecho com texto destacado, ele substituirá $TM_SELECTED_TEXT pelo texto que você destacou. Ao chamar este trecho sem texto destacado, $TM_SELECTED_TEXT estará vazio. Você pode ver isso em ação na captura de tela abaixo.

Criando um Trecho de Código Personalizado do PowerShell Com Paradas de Tabulação

Até agora, os exemplos que você viu foram completos quando chamados. Até mesmo o JavaScript pressupõe que você destacou o texto anteriormente. Mas e nos casos em que você precisa digitar valores no trecho depois que ele for chamado?

E se você quiser digitar o valor no console.log() em vez de usar o texto destacado? E se você quiser digitar em vários lugares no trecho?

Nesta seção, você aprenderá como usar as paradas de tabulação para permitir que você digite texto no código produzido para o qual o snippet se expande. As paradas de tabulação são lugares definidos em seu snippet para onde o cursor irá. Esses lugares são visitados na ordem a cada vez que você pressiona tab. Com essas paradas de tabulação, você pode digitar valores no snippet após ele ser expandido.

As paradas de tabulação, definidas pelo uso das variáveis de snippet $0, $1, $2 e assim por diante no corpo do snippet, especificam para o snippet onde seu cursor irá em seguida quando você chamar seu snippet e pressionar tab.

As paradas de tabulação seguem a ordem normal (1 segue 2 segue 3, etc.) com uma exceção: A parada de tabulação 0 é o lugar onde o cursor estará após todas as outras paradas de tabulação. Para demonstrar isso, o snippet abaixo se expande para uma mensagem Write-Output com a data atual e um lugar para mais texto.

Este corpo com duas paradas de tabulação

• $1 no final da mensagem Write-Output
• $0 na próxima linha para que o snippet termine em uma linha em branco

{
    "DateTime Snippet PS": {
        "prefix": "dtPS",
        "body" : [
            "Write-Output -Message "The time is $((Get-Date).ToLocalTime()) and $1"","$0"
        ]
        "description": "PSCustomObject with 3 lines"
    }
}

Salve este snippet e chame-o digitando o prefixo dtPS em um arquivo do PowerShell.

Quando o snippet se expandir, seu cursor pulará para a posição da parada de tabulação 1. A partir daqui, adicione o valor ou código que deseja e pressione tab para pular o cursor para a próxima parada de tabulação. Isso continuará até que você tenha passado por todas as paradas de tabulação que especificou.

Você pode ver isso em ação na captura de tela abaixo.

Adicionando Valores Padrão aos Tab Stops

Embora os tab stops sejam ótimos para começar, e se você precisar de valores específicos geralmente nesses pontos, mas quiser a capacidade de alterá-los, se necessário? Agora é hora de incluir valores padrão.

O exemplo acima tinha um tab stop, mas quando o trecho foi expandido, não havia texto em seu lugar. O cursor pulou para a localização do tab stop e então o usuário teve que assumir o controle.

Se apenas houvesse uma maneira de um valor poder estar onde o tab stop está – dessa forma, o trecho poderia se expandir e esse valor seria expandido com ele. Quando o tab stop chega a essa localização, o valor padrão pode ser sobrescrito ou pode ser ignorado ao ser tabulado e manterá seu valor padrão.

Vamos ver como adicionar valores padrão aos trechos de código personalizados. Você fará isso editando o arquivo JSON do trecho de código do PowerShell acima mencionado.

Para começar, abra o seletor de linguagem de trecho, escolha PowerShell e altere os tab stops de $1 para ${1:este é meu mensagem padrão}. O valor após os dois pontos se torna o valor padrão. Este valor é expandido com o trecho de código.

Quando esse tab stop é atingido, duas coisas podem acontecer. O valor padrão pode ser sobrescrito ou pode ser ignorado ao ser tabulado e manterá seu valor padrão.

Abaixo você pode ver a mudança no corpo.

{
	"DateTime Snippet PS" {
		"prefix": "dtPS",
		"body" : [
			"Write-Output -Message \"The time is $((Get-Date).ToLocalTime()) and $1{1:this is my default message}\"",
			"$0"
		],
		"description": "PSCustomObject with 3 lines"
	}
}

Depois de atualizados e salvos, esses valores padrão são expandidos e também aparecem na janela de IntelliSense quando chamados, como mostrado na captura de tela abaixo.

Mensagens padrão são bons exemplos do que você pode fazer com paradas de tabulação. Paradas de tabulação também oferecem a opção de escolha. Na próxima seção, você verá um exemplo de adição de escolhas às suas paradas de tabulação.

Adicionando Escolhas às Paradas de Tabulação

As paradas de tabulação não estão limitadas a ter um valor padrão ou nenhum valor. Elas podem ser definidas na definição do snippet do VS Code para dar ao usuário opções quando o snippet é expandido.

Talvez você tenha uma situação em que queira escolher um valor ou comando diferente em um snippet. Em vez de criar três snippets diferentes com escolhas diferentes, você pode editar o snippet para apresentar uma escolha com uma parada de tabulação, como mostrado na captura de tela abaixo.

Paradas de tabulação apresentarão uma escolha quando a seguinte sintaxe for usada no corpo do snippet:

${N|Choice1,Choice2,Choice3[,Choice]|}

A parada de tabulação mostrada acima foi modificada para dar a escolha de:

• Write-Output
• Write-Warning
• Write-Error

Isso foi feito colocando dois caracteres de tubo ( | ) após a parada de tabulação. As escolhas são colocadas dentro dos caracteres de tubo, separadas por vírgulas. Você pode ver isso no bloco de código abaixo.

${1|
    Write-Output -Message \"The time is $((Get-Date).ToLocalTime()) and this is my default message\", // <-- Escolha 1 
    Write-Warning -Message \"The time is $((Get-Date).ToLocalTime()) and this is my default message\", // <-- Escolha 2
    Write-Error -Message \"The time is $((Get-Date).ToLocalTime()) and this is my default message\" // <-- Escolha 3
|}

Abaixo, você pode ver o exemplo de snippet.

{
    "DateTime Snippet PS" {
        "prefix": "dtPS",
        "body" : [
            "Write-Output -Message \"The time is $((Get-Date).ToLocalTime()) and this is my default message\", Write-Warning -Message \"The time is $(Get-Date).ToLocalTime()) and this is my default message\", Write-Error -Message \"The time is $(Get-Date).ToLocalTime()) and this is my default message\"|}",
            "$0"
        ],
        "description": "PSCustomObject with 3 lines"
    }
}

Quando o snippet personalizado é expandido agora, a escolha de qual opção escolher aparecerá em uma janela de IntelliSense, como visto na captura de tela abaixo.

A partir daqui, você pode selecionar a opção desejada e vê-la se expandir para essa escolha. Em nosso exemplo de captura de tela abaixo, toda a linha de código é substituída pela opção de escolher entre três comandos Write diferentes, e mostra que cada um pode ser chamado e executado sem problemas.

Resumo

Os trechos personalizados podem ser texto simples ou código. Eles podem ter paradas de tabulação para incluir mensagens, valores padrão ou escolhas, além de texto destacado.

Não precisa ser uma tarefa árdua digitar cada caractere de cada bloco de código. Com trechos, você não precisa lembrar a sintaxe exata para um for, um foreach, ou uma instrução switch toda vez. Os trechos são a opção perfeita para esse nicho.

I’ve shown Python, JavaScript, and PowerShell snippets in this post. VS Code snippets are available for many, many more languages. Your limits are only what you use and what you can think of!

Leitura Adicional

• Introdução às Funções PowerShell