guides

Migrando da configuração YAML de Espanso para um expansor de texto GUI

Por Equipe Lightning Assist26 de julho de 20269 minutos de leitura
espansoyamlmigrationguitext-expanderlinuxwindowsmacos
Compartilhar:
Migrando da configuração YAML de Espanso para um expansor de texto GUI

Resposta rápida: Espanso armazena cada snippet como um par trigger/replace dentro de arquivos de correspondência YAML (~/.config/espanso/match/*.yml), o que significa que adicionar ou editar um snippet exige abrir um editor de texto, respeitar as regras de indentação do YAML e reiniciar o serviço para testá-lo. Migrar para um expansor de texto GUI como Lightning Assist significa recriar cada correspondência como um snippet em um editor visual – o mesmo texto de gatilho, a mesma substituição, mas um campo de formulário em vez de um arquivo. Não há importação YAML em massa hoje, então a migração é manual, um snippet de cada vez; a maioria das bibliotecas com menos de 50 snippets leva bem menos de 15 minutos.

Divulgação: fazemos Lightning Assist, um expansor de texto pago, então Espanso é um concorrente nosso. Espanso é gratuito e de código aberto, e todas as correções abaixo são para o próprio Espanso – nenhuma delas exige trocar de ferramenta.

Se você nunca abriu ~/.config/espanso/match/base.yml, nada disso significará nada para você, e esse é exatamente o público-alvo deste guia: pessoas que fizeram Espanso funcionar, adicionaram uma dúzia de snippets e agora estão se perguntando se existe uma versão disso em que não precisem pensar em YAML de jeito nenhum.

Por que a configuração YAML de Espanso se torna um atrito

Espanso é genuinamente bem construído. É gratuito, de código aberto, multiplataforma e seu modelo baseado em arquivo é uma escolha de design deliberada, não um descuido - o YAML é portátil, permite comparação com diff e é programável por script. O atrito aparece mais tarde, quando você realmente o usa no dia a dia:

Arquivos de correspondência espalhados pelo seu sistema de arquivos. Espanso organiza a configuração em uma pasta match/ (o que expandir) e uma pasta config/ (como a expansão se comporta), começando em match/base.yml. À medida que sua contagem de snippets aumenta, você continua adicionando àquele mesmo arquivo ou começa a dividir em mais arquivos .yml - de qualquer forma, encontrar "aquele sobre preços" seis meses depois significa abrir arquivos e vasculhar, porque não há caixa de pesquisa.

Indentação é a sintaxe. Uma correspondência básica se parece com:

matches:
  - trigger: ":br"
    replace: "Best Regards,\nJon Snow"

A própria documentação de Espanso é direta sobre isso: "Certifique-se de incluir o recuo, caso contrário não será uma sintaxe YAML válida." Isso é bom para um desenvolvedor confortável em um editor de texto, e é exatamente o tipo de coisa que quebra silenciosamente quando você cola um snippet vindo do Slack ou copia um bloco de várias linhas e o espaço em branco não vem junto. A maneira como você geralmente descobre é que o gatilho simplesmente não expande – nenhum diálogo, nenhum rabisco vermelho, apenas um snippet que silenciosamente não faz nada até que você procure um espaço perdido.

Sem sincronização, sem equipe. Espanso armazena tudo localmente por design - genuinamente bom para a privacidade, mas significa que colocar seus snippets em uma segunda máquina é uma cópia manual de arquivo, uma pasta do Dropbox ou um repositório git pessoal que você mesmo mantém. Não há conta, nem sincronização integrada entre vários dispositivos, nem maneira de entregar sua biblioteca de snippets a um colega, exceto enviando-lhes os arquivos .yml e pedindo-lhes para colocá-los na pasta correta.

Reiniciar para testar. Editar um arquivo de correspondência e confirmar se ele funcionou geralmente significa salvar, voltar para o aplicativo em que você está testando, digitar o gatilho e - se ele não disparar - voltar para verificar o arquivo. É um loop curto, mas é um loop que você repete a cada mudança, para sempre.

Nada disso faz de Espanso um software ruim. Isso o torna um software desenvolvido para pessoas que se sentem confortáveis ​​em tratar a configuração como código. Se não é assim que você deseja gastar seu tempo, uma GUI é a solução - não um editor YAML "melhor".

Qual é a aparência real do equivalente da GUI

Em um expansor de texto com GUI, um snippet é uma linha, não um arquivo. Você abre um painel (em Lightning Assist, é “Meus Snippets”), clica em “Criar Snippet”, digita o gatilho em um campo e a expansão em outro e salva. Não há nenhum arquivo para localizar, nenhum serviço para reiniciar e nenhum recuo para acertar, porque não há recuo - rich text, formatação HTML e conteúdo multilinha são todos digitados ou colados diretamente no campo de expansão sem necessidade de escape. Os snippets são organizados em pastas que você mesmo nomeia e você pode pesquisar em toda a sua biblioteca em vez de vasculhar arquivos.

A compensação é a que você esperaria: você abre mão do acesso direto ao arquivo (sem fazer git diff no histórico dos seus snippets, sem editar no Vim) em troca de não precisar de nenhuma das mecânicas do YAML desde o início.

Espanso → Lightning Assist: Mapa Conceitual

Se você já pensa no vocabulário de Espanso, veja como cada peça é mapeada:

Conceito de Espanso Em YAML Equivalente na GUI
Correspondência Uma entrada em matches: em um arquivo .yml Um snippet — uma linha no painel Snippets
Gatilho trigger: ":br" O campo Trigger — digite a mesma abreviação diretamente, sem necessidade dos dois pontos, a menos que você queira mantê-los
Substituir replace: "Best Regards,\nJon Snow" O texto de expansão do snippet — rich text, HTML e conteúdo multilinha com suporte nativo
Vars/extensões (data, shell, área de transferência, formulário) Um bloco vars: referenciando um tipo de variável Espaços reservados inseridos na expansão — [#Date#], [#Name#] e variáveis ​​da área de transferência
Arquivos de correspondência (base.yml, .ymls personalizados) Arquivos dentro de ~/.config/espanso/match/ Pastas no painel Snippets — organize visualmente em vez de por nome de arquivo
Recarregar / espanso restart Reinicialização manual do serviço para coletar alterações Nada para fazer – os snippets ficam ativos no momento em que você salva
Gatilhos Regex, correspondências de comando shell YAML + script, específico de Espanso Não replicado. Se isso for fundamental para seu fluxo de trabalho, continue no Espanso para esses casos

A última linha é importante: este é um guia de migração, não uma afirmação "Lightning Assist pode fazer tudo que Espanso pode". Gatilhos baseados em regex e correspondências apoiadas por comandos shell são pontos fortes genuínos do Espanso, sem equivalente de GUI aqui.

Passo a passo: migrando seus snippets manualmente

  1. Encontre suas correspondências existentes. Abra ~/.config/espanso/match/base.yml e quaisquer outros arquivos .yml personalizados que você criou. Cada par trigger/replace é algo que você recriará.
  2. Instale o expansor GUI e ignore qualquer arquivo de configuração. Experimente Lightning Assist gratuitamente por 14 dias — sem cartão de crédito. O aplicativo abre diretamente no painel de snippets; não há arquivo de configuração para escrever primeiro.
  3. Recrie cada correspondência como um snippet. Clique em Novo Snippet, cole o texto do gatilho no campo Trigger (mantenha :br ou /addr exatamente como estava se você gostar dessa convenção - qualquer texto é um gatilho válido) e cole o texto de substituição no campo de expansão.
  4. Reconstrua variáveis ​​como espaços reservados. Uma var de data se torna o espaço reservado [#Date#]; uma var da área de transferência torna-se o espaço reservado da área de transferência; texto simples permanece texto simples. Vars de comando shell e gatilhos regex não têm um equivalente direto - deixe essas correspondências em Espanso se precisar delas.
  5. Defina seu modo de gatilho. A expansão conforme você digita (digite o gatilho, ele se expande em linha) é o padrão e não precisa de configuração. Se preferir pressionar uma tecla depois de digitar o gatilho, configure-o uma vez em Configurações → Gatilhos.
  6. Teste antes de excluir qualquer coisa. Experimente cada snippet em um documento de rascunho. Mantenha sua configuração Espanso em vigor até confirmar que o conjunto migrado funciona da maneira esperada - não há problema algum em os dois coexistirem temporariamente.

Seja realista quanto ao tempo que isso leva: não há importação YAML em massa hoje, então cada snippet é recriado manualmente. Para uma biblioteca com menos de 50 snippets, isso geralmente leva bem menos de 15 minutos. Se você estiver migrando mais de 100 entradas, a estrutura do YAML pelo menos torna o copiar e colar simples - leia o valor de trigger e o de replace de cada bloco e cole-os nos campos correspondentes da GUI.

O que você ganha e o que você desiste

O que você ganha: sem arquivos de configuração, sem loop de reinicialização para teste, uma biblioteca de snippets pesquisável ​​organizada em pastas, comandos de IA que reescrevem ou traduzem o texto selecionado a partir de uma tecla de atalho, voz para texto push-to-talk no mesmo aplicativo, sincronização automática na nuvem entre dispositivos e compartilhamento de snippets em equipe, se necessário. Tudo isso é executado em Windows, macOS e Linux da mesma conta.

Do que você desiste: Espanso é gratuito e de código aberto, para sempre — a expansão de texto de Lightning Assist também é gratuita e ilimitada, com até 20 snippets, pastas e uma equipe incluídos — mas uma biblioteca maior e mais equipes custam US$ 5,99/mês após um teste de 14 dias (os comandos de IA e a voz consomem Créditos de IA adquiridos separadamente). Você também perde gatilhos baseados em regex e correspondências de comando shell, que não têm equivalente no modelo GUI. Se é por isso que você usa Espanso, esta migração não é para você – e esse é um motivo legítimo para ficar.

Se você deseja uma GUI sem sair totalmente do ecossistema de Espanso, existem projetos comunitários - espansoGUI (Rust/Iced, no Flathub), EspansoEdit (freeware para Windows) e o IDE EspansoGUI. Vale a pena experimentá-los, mas cada um é uma camada separada mantida por voluntários sobre os mesmos arquivos YAML por baixo; o próprio Espanso ainda não possui GUI oficial (a versão estável mais recente do projeto principal é v2.4.0, julho de 2026). Se o que você deseja é uma ferramenta onde a GUI é o produto, essa é a lacuna que esta migração fecha.

Perguntas frequentes

Posso importar meus arquivos Espanso YAML diretamente?

Hoje não – não há importação em massa. Você recria cada correspondência como um snippet no editor visual. Para a maioria das bibliotecas com menos de 50 snippets, isso leva bem menos de 15 minutos; bibliotecas maiores demoram proporcionalmente mais tempo, pois ainda é uma por uma.

Vou perder meus gatilhos baseados em regex ou correspondências de comando shell?

Sim. Esses são recursos específicos de Espanso construídos sobre seu modelo de YAML e scripts, e não há equivalente de GUI para eles aqui. Se gatilhos de regex ou correspondências baseadas em shell forem fundamentais para sua configuração, continue usando Espanso para eles e considere um expansor de GUI apenas para seus snippets estáticos mais simples.

Posso manter o mesmo texto de gatilho, como :br ou /addr?

Sim. O campo Trigger aceita qualquer texto digitado, incluindo : ou / inicial, se essa for a convenção com a qual você está acostumado. Nada obriga você a alterar seu estilo de abreviação durante a migração.

Existe uma GUI Espanso oficial que eu deveria tentar antes de trocar totalmente de ferramenta?

Oficial, nenhuma. Projetos comunitários como espansoGUI, EspansoEdit e o IDE EspansoGUI adicionam uma camada gráfica, mas são ferramentas separadas, mantidas por voluntários, sobre os mesmos arquivos YAML – você ainda está a um passo da configuração bruta. Se você deseja que a GUI seja o produto completo, em vez de um complemento, essa é a diferença desta migração.

Leitura Relacionada

Fontes

Artigos relacionados