Como construir snippets inteligentes com variáveis de contexto no VS Code

Os snippets no Visual Studio Code são ferramentas poderosas que podem transformar sua produtividade como desenvolvedor. Quando combinados com variáveis de contexto, eles se tornam verdadeiramente inteligentes, adaptando-se automaticamente ao ambiente, ao arquivo atual e ao conteúdo selecionado. Neste artigo, você aprenderá a construir snippets que vão além do básico, utilizando variáveis dinâmicas, placeholders inteligentes e transformações com expressões regulares.

1. Fundamentos dos Snippets no VS Code

A estrutura básica de um snippet no VS Code é composta por três elementos essenciais: o prefixo (palavra-chave que aciona o snippet), o corpo (o conteúdo gerado) e a descrição (texto explicativo). Os snippets podem ser armazenados em três níveis diferentes:

  • Global: disponível em todos os projetos (~/.config/Code/User/snippets/)
  • Por projeto: criado na pasta .vscode do projeto
  • Por linguagem: snippets específicos para determinadas extensões de arquivo

Para acionar um snippet, você pode usar a tecla Tab, digitar o prefixo seguido de Ctrl+Espaço, ou utilizar o comando "Insert Snippet" pela paleta de comandos.

{
  "Snippet de exemplo": {
    "prefix": "exemplo",
    "body": [
      "console.log('$1');",
      "$0"
    ],
    "description": "Gera um console.log com placeholder"
  }
}

2. Variáveis de Contexto: O Poder da Personalização

As variáveis de contexto são o coração dos snippets inteligentes. O VS Code disponibiliza diversas variáveis que capturam informações do ambiente de desenvolvimento:

$TM_FILENAME        → "meu-arquivo.js"
$TM_FILENAME_BASE   → "meu-arquivo"
$TM_DIRECTORY       → "/home/user/projeto/src"
$TM_CURRENT_LINE    → "linha atual do cursor"
$TM_SELECTED_TEXT   → "texto selecionado pelo usuário"
$TM_LINE_INDEX      → "42" (índice da linha, começando em 0)
$TM_LINE_NUMBER     → "43" (número da linha, começando em 1)

Variáveis de data e hora são particularmente úteis para gerar timestamps e cabeçalhos:

$CURRENT_YEAR      → 2025
$CURRENT_MONTH     → 03
$CURRENT_DATE      → 15
$CURRENT_HOUR      → 14
$CURRENT_MINUTE    → 30
$CURRENT_SECOND    → 45
$CURRENT_DAY_NAME  → "Saturday"
$CURRENT_MONTH_NAME → "March"

Para snippets que dependem do workspace:

$WORKSPACE_NAME    → "meu-projeto"
$WORKSPACE_FOLDER  → "/home/user/meu-projeto"

3. Placeholders e Transformações Inteligentes

Os placeholders permitem navegação entre campos preenchíveis. O $1 é o primeiro campo a ser preenchido, $2 o segundo, e $0 é a posição final do cursor após o preenchimento completo.

{
  "Função com placeholder": {
    "prefix": "fn",
    "body": [
      "function ${1:nomeDaFuncao}(${2:parametros}) {",
      "  ${3:// implementação}",
      "  $0",
      "}"
    ],
    "description": "Estrutura de função com placeholders"
  }
}

Placeholders com valores padrão e escolhas oferecem ainda mais flexibilidade:

{
  "Import com escolha": {
    "prefix": "imp",
    "body": [
      "import ${1:${TM_FILENAME_BASE}} from '${2:./${1}}';",
      "$0"
    ],
    "description": "Import com nome padrão baseado no arquivo"
  }
}

Transformações de texto permitem modificar o conteúdo inserido:

{
  "Constante em maiúsculas": {
    "prefix": "const",
    "body": [
      "const ${1:${TM_FILENAME_BASE/(.*)/${1:/upcase}/}} = ${2:valor};",
      "$0"
    ]
  }
}

4. Snippets com Lógica Condicional

Embora snippets não suportem estruturas condicionais completas, é possível usar variáveis de contexto para criar comportamentos adaptativos. A sintaxe ${VAR:+valor_se_existir} permite verificar se uma variável está definida:

{
  "Cabeçalho de arquivo": {
    "prefix": "header",
    "body": [
      "/**",
      " * ${TM_FILENAME}",
      " * ${TM_FILENAME_BASE:+Arquivo: }${TM_FILENAME_BASE}",
      " * ${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}",
      " * ${WORKSPACE_NAME:+Projeto: }${WORKSPACE_NAME}",
      " */",
      "$0"
    ],
    "description": "Cabeçalho adaptável ao contexto"
  }
}

5. Snippets Dinâmicos com Expressões Regulares

As transformações com expressões regulares permitem manipular o texto de formas sofisticadas. A sintaxe é: ${VAR/expressao_regular/formato/opcoes}

{
  "Converter snake_case para camelCase": {
    "prefix": "tocamel",
    "body": [
      "${TM_SELECTED_TEXT/([a-z]+)_([a-z]+)/${1:/capitalize}${2:/capitalize}/}",
      "$0"
    ],
    "description": "Converte texto selecionado de snake_case para camelCase"
  }
}

Para capturar múltiplos grupos e aplicar transformações diferentes:

{
  "Gerar getter e setter": {
    "prefix": "gs",
    "body": [
      "${1:propriedade}",
      "",
      "get ${1/(.*)/${1:/pascalcase}/}() {",
      "  return this._${1};",
      "}",
      "",
      "set ${1/(.*)/${1:/pascalcase}/}(value) {",
      "  this._${1} = value;",
      "}",
      "$0"
    ],
    "description": "Gera getter e setter com nome em PascalCase"
  }
}

6. Integração com Workspaces e Profiles

Para criar snippets específicos por workspace, crie um arquivo na pasta .vscode do projeto:

// .vscode/meus-snippets.code-snippets
{
  "Snippet específico do projeto": {
    "scope": "javascript,typescript",
    "prefix": "api",
    "body": [
      "import { ${1:servico} } from '@/services/${1}';",
      "import { ${2:tipo} } from '@/types/${2}';",
      "$0"
    ],
    "description": "Import de serviço e tipo do projeto atual"
  }
}

Para ativar conjuntos diferentes de snippets, utilize Profiles. Crie perfis específicos para cada tipo de projeto (web, mobile, backend) e associe os snippets correspondentes a cada perfil. A sincronização entre máquinas pode ser feita via Settings Sync, que inclui os snippets na configuração sincronizada.

7. Boas Práticas e Exemplos Avançados

Um exemplo avançado é a geração automática de documentação JSDoc:

{
  "Documentação JSDoc": {
    "prefix": "jsdoc",
    "body": [
      "/**",
      " * ${1:Descrição da função}",
      " * @param {${2:tipo}} ${3:parametro} - ${4:descrição}",
      " * @returns {${5:tipo}} ${6:descrição do retorno}",
      " */",
      "function ${7:nomeFuncao}(${3}) {",
      "  $0",
      "}"
    ],
    "description": "Gera documentação JSDoc completa"
  }
}

O uso de $CLIPBOARD permite criar snippets que formatam conteúdo copiado:

{
  "Colar como lista": {
    "prefix": "lista",
    "body": [
      "${CLIPBOARD/\\n/\\n- /g}",
      "$0"
    ],
    "description": "Converte texto da área de transferência em lista com marcadores"
  }
}

Para depurar snippets complexos, utilize a funcionalidade de preview do VS Code (Ctrl+Shift+P → "Developer: Inspect Editor Tokens and Scopes") e teste cada variável individualmente antes de combiná-las.

Snippets inteligentes com variáveis de contexto são uma forma elegante de automatizar tarefas repetitivas e manter a consistência do código. Comece com exemplos simples e gradualmente adicione mais complexidade, sempre testando cada transformação em um arquivo de rascunho antes de incorporá-la ao seu fluxo de trabalho.

Referências