Como Identar Código no Visual Studio Code: Guia Completo com Atalhos e API

Você pode identar código no Visual Studio Code usando os atalhos Ctrl+] (identar) e Ctrl+[ (desidentar), comandos da paleta, ou programaticamente via API de extensões através do comando editor.action.indentLines.

A identação automática e manual de código é uma funcionalidade central do editor da Microsoft. Neste artigo, analisamos o código-fonte do repositório microsoft/vscode para explicar como identar código no Visual Studio Code, desde os atalhos de teclado até a arquitetura interna que processa esses comandos no arquivo src/vs/editor/contrib/linesOperations/browser/linesOperations.ts.

Arquitetura da Identação no VS Code: Duas Camadas Principais

O Visual Studio Code implementa a identação através de duas camadas distintas no seu núcleo:

1. Ação do Usuário (Manual): Quando você pressiona Ctrl+] ou seleciona "Indent Lines" na paleta de comandos, o EditorAction dispara o comando editor.action.indentLines. Isso cria uma instância de IndentLinesAction que percorre cada linha da seleção e acrescenta o número de espaços ou tabulações configurado.

2. Re-identação Automática: Ao pressionar Enter ou abrir um arquivo, o motor de language configuration analisa as regras indentationRules da linguagem ativa. Expressões regulares definidas em increaseIndentPattern e decreaseIndentPattern determinam quando aplicar IndentAction.Indent ou IndentAction.Outdent.

Como Identar Código no Visual Studio Code: Métodos Práticos

Atalhos de Teclado para Identar e Desidentar

A forma mais rápida de identar código no VS Code é através dos atalhos padrão:

Ação	Windows/Linux	macOS
Identar linhas	Ctrl+]	⌘+]
Desidentar linhas	Ctrl+[	⌘+[
Re-identar documento inteiro	Shift+Alt+F	Shift+Option+F

Esses atalhos acionam os comandos editor.action.indentLines e editor.action.outdentLines, implementados nas classes IndentLinesAction e OutdentLinesAction no arquivo src/vs/editor/contrib/linesOperations/browser/linesOperations.ts.

Comandos da Paleta de Comandos

Você também pode acessar a funcionalidade através da paleta de comandos (Ctrl+Shift+P ou ⌘+Shift+P):

• Indent Line: Adiciona indentação à linha atual ou seleção.
• Outdent Line: Remove indentação.
• Reindent Lines: Reaplica as regras de indentação do documento inteiro.

Re-identação Automática com Format Document

O comando Format Document (Shift+Alt+F) utiliza a classe ReindentLinesAction definida em src/vs/editor/contrib/indentation/browser/indentation.ts. Este processo reanalisa o documento inteiro aplicando as regras de indentationRules de forma iterativa até que a estrutura de blocos esteja estável.

Configurações de Identação no VS Code

Opções de Editor: tabSize, insertSpaces e detectIndentation

O comportamento da identação é controlado pelas configurações expostas em src/vs/workbench/common/editor/editorOptions.ts e src/vs/editor/common/config/editorOptions.ts:

• editor.tabSize: Define o número de espaços equivalentes a uma tabulação (padrão: 4).
• editor.insertSpaces: Determina se o editor deve inserir espaços em vez de caracteres de tabulação (padrão: true).
• editor.detectIndentation: Quando habilitado, o VS Code detecta automaticamente o estilo de identação do arquivo aberto.

Para modificar estas configurações via API de extensão:

const config = vscode.workspace.getConfiguration('editor');
await config.update('insertSpaces', true, vscode.ConfigurationTarget.Workspace);
await config.update('tabSize', 4, vscode.ConfigurationTarget.Workspace);

API de Extensões: Como Identar Código Programaticamente

Desenvolvedores de extensões podem acionar a identação através da API do VS Code:

Executando Comandos de Identação

import * as vscode from 'vscode';

// Indenta as linhas atualmente selecionadas
vscode.commands.executeCommand('editor.action.indentLines');

// Desindenta as linhas selecionadas
vscode.commands.executeCommand('editor.action.outdentLines');

// Re-identa todo o documento (usa a formatação do editor)
vscode.commands.executeCommand('editor.action.formatDocument');

Definindo Regras de Identação Customizadas

Para linguagens personalizadas, você pode definir regras de identação no package.json da extensão:

{
  "contributes": {
    "languages": [
      {
        "id": "myLang",
        "extensions": [".ml"],
        "configuration": "./language-configuration.json"
      }
    ]
  }
}

E no arquivo language-configuration.json:

{
  "indentationRules": {
    "increaseIndentPattern": "^\\s*(if|while|for)\\b.*\\{$",
    "decreaseIndentPattern": "^\\s*\\}"
  }
}

Com essa configuração, o VS Code aplicará IndentAction.Indent ao digitar { após if, while ou for, e IndentAction.Outdent ao encontrar }, conforme implementado em src/vs/editor/common/languages/languageConfiguration.ts.

Arquivos-Fonte-Chave da Identação no VS Code

A implementação da identação no VS Code está distribuída entre os seguintes arquivos principais:

Arquivo	Responsabilidade
src/vs/editor/contrib/linesOperations/browser/linesOperations.ts	Implementa IndentLinesAction e OutdentLinesAction (comandos editor.action.indentLines / outdentLines).
src/vs/editor/contrib/indentation/browser/indentation.ts	Implementa ReindentLinesAction usado por Format Document.
src/vs/editor/common/languages/languageConfiguration.ts	Define a estrutura IndentAction e a lógica que interpreta indentationRules.
src/vs/workbench/contrib/codeEditor/common/languageConfigurationExtensionPoint.ts	Registra a configuração de linguagem (padrões de indentação, comentários, etc.).
src/vs/workbench/common/editor/editorOptions.ts	Expõe as opções de editor que controlam tamanho da tabulação e uso de espaços.
src/vs/editor/common/config/editorOptions.ts	Reflete as mesmas opções no lado do editor Monaco.

Esses arquivos compõem a cadeia completa que transforma um pedido de identação (via atalho, comando da paleta ou API) em modificação de texto dentro do editor, obedecendo às regras de formatação definidas para a linguagem ativa.

Summary

• O VS Code processa a identação manual através de IndentLinesAction em linesOperations.ts, acionada por Ctrl+] ou editor.action.indentLines.
• A re-identação automática utiliza indentationRules definidas em languageConfiguration.ts para ajustar blocos ao pressionar Enter.
• As configurações editor.tabSize, editor.insertSpaces e editor.detectIndentation controlam o comportamento dos caracteres de indentação.
• Desenvolvedores podem acionar identação programaticamente via vscode.commands.executeCommand ou definir regras customizadas para linguagens específicas.

Frequently Asked Questions

Qual a diferença entre identar linhas e reidentar documento no VS Code?

Identar linhas (editor.action.indentLines) adiciona um nível de indentação às linhas selecionadas sem analisar a estrutura do código, utilizando a classe IndentLinesAction. Reidentar documento (editor.action.formatDocument) utiliza ReindentLinesAction para analisar todo o arquivo aplicando as regras de indentationRules da linguagem iterativamente até estabilizar a estrutura de blocos.

Como configurar o VS Code para usar espaços em vez de tabs?

Acesse as configurações (Ctrl+,) e defina editor.insertSpaces como true para converter tabs em espaços. Ajuste editor.tabSize para definir quantos espaços representam uma tabulação (geralmente 2 ou 4). Se desejar que o VS Code detecte automaticamente o estilo existente do arquivo, mantenha editor.detectIndentation habilitado, conforme implementado em src/vs/workbench/common/editor/editorOptions.ts.

Por que o VS Code não identa automaticamente minha linguagem personalizada?

O VS Code depende de regras de indentationRules definidas na configuração da linguagem para identação automática ao pressionar Enter. Se sua linguagem personalizada não possui uma extensão que registre essas regras via languageConfigurationExtensionPoint em src/vs/workbench/contrib/codeEditor/common/languageConfigurationExtensionPoint.ts, o editor não saberá quando aumentar ou diminuir a indentação. Você precisa criar um arquivo language-configuration.json com increaseIndentPattern e decreaseIndentPattern adequados à sintaxe da sua linguagem.

É possível identar código no VS Code via extensão personalizada?

Sim, extensões podem acionar a identação programaticamente utilizando a API vscode.commands.executeCommand. Você pode chamar 'editor.action.indentLines' para identar a seleção atual, 'editor.action.outdentLines' para remover indentação, ou 'editor.action.formatDocument' para reidentar todo o documento. Além disso, extensões podem definir regras de indentação customizadas para linguagens específicas através do ponto de contribuição languages no package.json, especificando padrões regex para increaseIndentPattern e decreaseIndentPattern.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}