--- id: "canvas.notas.visao-geral" titulo: "Notas no Canvas" resumo: "Use cartões de nota como memória do projeto: onde os arquivos ficam, como editar e como buscar dentro de uma nota." idioma: "pt-br" tipo: "guia" categoria: "telas" aplicavelDesde: "0.0.16" capabilities: ["note.cards.create", "note.cards.edit", "note.cards.find", "note.cards.colors", "note.files.location"] estadoEditorial: "aprovado" nivelEvidencia: "artefato-distribuido" refFonte: "27574c339b58316408f6be2d62169d59041d07bf" revisaoFonte: "2026-09-24" revisor: "mantenedor (v1, 2026-10-03)" rota: "/docs/pt-br/canvas/notas/visao-geral/" fonte: "pt-br/canvas/notas/visao-geral.md" caminhoPublico: "docs/publica/pt-br/canvas/notas/visao-geral.md" hashFonte: "sha256:83a99a861ff0206366df451aeb82561a66b89f13f47bf4121a7a19e34be9cd14" hashDestaPagina: "sha256:83a99a861ff0206366df451aeb82561a66b89f13f47bf4121a7a19e34be9cd14" traducaoAssistidaPorIA: false traducaoDesatualizada: false corpoRetido: false --- Um **cartão de nota** é texto em **Markdown** guardado num arquivo `.md`. Serve para duas coisas ao mesmo tempo: é a sua memória do projeto no quadro, e é o material que os agentes podem ler e escrever. Porque é um arquivo de verdade, a nota sobrevive ao app: fechar e reabrir não perde texto, e qualquer ferramenta de fora do Elyra pode ler o mesmo arquivo. ## Onde os arquivos ficam As notas **não moram dentro do projeto**. Elas ficam numa pasta gerenciada pelo app, fora do repositório, com um caminho por workspace no formato: ``` ~/.elyra/projetos///notas/ ``` Os nomes das pastas de projeto e de workspace carregam um sufixo identificador, então o caminho exato não é previsível de cabeça. **O caminho absoluto real é o que a linha de comando devolve no campo `noteFilePath`** ao listar ou ler uma nota — use esse valor quando precisar do arquivo no disco. Essa decisão tem um motivo prático: quando as notas ficavam dentro do repositório, uma limpeza de arquivos não versionados (`git clean -xdf`) levava as notas junto. Fora do projeto, isso não acontece. Duas consequências: - **Workspace remoto por SSH é a exceção.** Nesse caso a pasta de notas fica **dentro do checkout**, no host remoto. Isso é declarado como temporário, até existir resolução de pasta pessoal remota — não conte com paridade entre local e SSH para notas. - **O identificador guardado da nota não é um endereço.** O cartão guarda uma identidade no formato `.elyra/notas/.md`, que não é onde o arquivo está de fato. Só o `noteFilePath` é o caminho real. > **Notas antigas.** As notas que ficavam dentro do projeto, nas duas pastas antigas, são **movidas** para a pasta gerenciada. A migração roda na inicialização, **não sobrescreve** um arquivo já existente no destino (um nome ocupado ganha um sufixo) e, se falhar, **deixa o arquivo onde está** para tentar de novo na próxima inicialização. Ela é **best-effort**: um arquivo pode ficar para trás numa falha. ## Criar uma nota Pela barra do topo: **Adicionar Nota › Nota**. Pelo clique direito no fundo: **"Adicionar aqui" › Nota**. Os dois criam o cartão e o arquivo, e o editor da nota recém-criada **recebe o foco automaticamente** — você pode começar a escrever. Pela linha de comando, a nota nasce já com conteúdo: ``` elyra canvas create note --title "Resumo da reunião" --content "Primeira linha" elyra canvas create note --content-file ./texto.md ``` - `--content` escreve o texto no arquivo no nascimento. - `--content-file` lê de um arquivo, ou de `-` para ler da entrada padrão. É o caminho para **texto com várias linhas** — aspas no shell estragam quebras de linha. - Com `--title`, o arquivo nasce com esse nome e **o nome fica fixo**. - Sem `--title`, **o nome segue a primeira linha do conteúdo**. Enquanto você não digitar um nome, o cartão mostra "automático"; digitar um nome o fixa. O nome do arquivo é saneado: caracteres inválidos viram `-`, nomes reservados do sistema ganham prefixo e há um teto de comprimento. Você não precisa cuidar disso. ## Editar O corpo do cartão é um **editor rico** de Markdown, com barra de ferramentas e um campo de escrita com a dica "Escreva sua nota…". - **A gravação é adiada em cerca de 600 ms** depois da última tecla. É por isso que parar de digitar por um instante e olhar o arquivo no disco é a forma de confirmar que ele foi salvo. - **Edições feitas fora do app aparecem no cartão.** O app observa o arquivo e reflete o que mudou. - **Uma falha de leitura bloqueia o editor** em vez de esvaziar o arquivo. Se a nota não puder ser lida, o cartão avisa e oferece **Tentar novamente** — nada foi apagado, e você deve conferir se o arquivo foi movido ou apagado fora do Elyra. - **Fechar durante uma edição pendente** descarrega a gravação adiada antes de apagar, para não recriar um arquivo que deveria sair. ### Ferramentas da nota A barra da nota traz **negrito**, **itálico**, **riscado**, **lista** e **lista numerada**, além da paleta de cores. ### Cor de fundo A paleta oferece **Padrão**, **Amarelo**, **Verde**, **Azul**, **Rosa**, **Roxo** e **Cinza**. Escolher **Padrão** limpa a cor. A cor é uma propriedade do **cartão**, não do texto: ela **não altera o arquivo `.md`** e, portanto, não viaja junto com a nota se você abrir o arquivo em outro lugar. ## Buscar dentro da nota A barra de busca **"Buscar na nota"** destaca e navega pelos resultados dentro do corpo do cartão, com **Anterior**, **Próximo** e um contador no formato `atual de total`, além de **"Nenhum resultado"** quando não há correspondência. **Esc** fecha a busca. A busca é só de interface e não altera o arquivo nem o processo. ## Escrever numa nota pela linha de comando Um agente pode ler e escrever a nota sem abrir o editor: ``` elyra canvas note read [--workspace ] [--json] elyra canvas note write (--content | --content-file ) [--append] [--workspace ] [--json] ``` - `` aceita o **id do cartão**, o **título do cartão** ou o **nome da nota**. - **Sem `--append`, o conteúdo substitui o arquivo inteiro.** Com `--append`, o texto vai para o fim, depois de uma quebra de linha. - Sem `--json`, a leitura imprime **o conteúdo puro** da nota. > **Escrita concorrente com o editor.** O comando é o **escritor mais novo**: o texto que ainda estava na gravação adiada do editor é descartado de propósito, e o cartão na tela pega o conteúdo novo pelo observador de arquivo. Antes de escrever numa nota que está aberta, salve o que você digitou. > **O app precisa estar aberto.** Sem janela do aplicativo, essas operações são recusadas em vez de gravar num estado que ninguém vê. ## Limites - **Workspace remoto por SSH.** As notas ficam **dentro do checkout** no host remoto, e a migração para a pasta gerenciada **não roda** nesse caso. Não há paridade entre local e SSH para notas. - **Uma nota cujo arquivo sumiu não monta editor nem grava.** Isso é proposital: evita que o salvamento automático recrie o arquivo vazio por cima do que existia. O cartão mostra o erro, preserva o texto que já conhecia e oferece **Tentar novamente**. - **Dois cartões com o mesmo nome tornam o seletor ambíguo.** A linha de comando pede para você usar o **id** nesse caso — o nome é conforto, não endereço único. - **Não há um limite de tamanho documentado para a nota.** Uma nota grande é lida e gravada inteira; não conte com truncamento nem com aviso de "grande demais".