# YAML, noções básicas de formatação **URL:** https://forum.cpha.pt/t/yaml-nocoes-basicas-de-formatacao/3953 **Category:** Tutoriais **Tags:** yaml **Created:** [8 Fevereiro , 2020 10:55 UTC](https://forum.cpha.pt/t/yaml-nocoes-basicas-de-formatacao/3953 "2020-02-08T10:55:28Z") **Posts on this page:** 1 **Page:** 1
### Author: ![j\_assuncao](https://forum.cpha.pt/user_avatar/forum.cpha.pt/j_assuncao/32/3_2.png) [@j\_assuncao](https://forum.cpha.pt/u/j_assuncao) #### Post date: [8 Fevereiro , 2020 10:55 UTC](https://forum.cpha.pt/t/yaml-nocoes-basicas-de-formatacao/3953/1 "2020-02-08T10:55:29Z")
Uma das grandes dores de cabeça na configuração do Home Assistant são os erros provocados pelo código YAML utilizado nos ficheiros de configuração. Embora o HA caminhe para que toda a configuração seja feita através da UI, veja-se o caso da Integrações por exemplo, o caminho ainda será longo e em algumas situações será sempre preciso usar o YAML. O YAML (uma sigla que significa _YAML Ain’t Markup Language_) não é propriamente uma linguagem de programação mas sim uma sintaxe para a criação de ficheiros de configuração. Este tutorial reflecte apenas a implementação do YAML utilizada no HA pois existem pequenas diferenças de implementação entre diversos sistemas. ## Pré-requisitos A utilização de um bom editor de código é fundamental pois um editor que permita a visualização de símbolos (espaços, tabulações, parágrafos, etc) irá facilitar bastante a escrita de código. Nesse sentido, aconselho a utilização do [Notepad++](https://notepad-plus-plus.org/downloads) ou o [VScode](https://code.visualstudio.com/download) caso trabalhem com os ficheiros em modo local. No Notepad++ a visualização dos símbolos tem de ser activada (`view` \> `Show Symbol` \> `Show White Space and TAB`) mas no VScode a visualização dos símbolos vem já activa por defeito. Se quiserem uma integração directa com a interface do HA, o VScode existe como addon para Hassio embora apenas para a arquitectura `amd64`. ![image](https://forum.cpha.pt/uploads/default/original/2X/5/5e7232de51cf0b1761dd66b5555975a0e6fef5cc.png) O VScode quando integrado com o HA permite ter várias funções extra, como por exemplo o autocomplete do nome das entidade, pesquisa e inserção de ícones com um clique, acesso à linha de comandos do Hassio, etc. ![screenshot](https://forum.cpha.pt/uploads/default/original/2X/e/eb26263bae08316aa532861bbe72432374b993e1.png) Um outro pré-requisito muitas vezes ignorado é a codificação do ficheiro, a qual deverá ser sempre `UTF-8`. Por este motivo devem ter sempre atenção quando copiarem ficheiros de outros sistemas para inserir na configuração do HA ou quando criarem novos ficheiros, em especial no Notepad++. > Os exemplos mostrados neste tutorial são escritos no VScode utilizando o código de um cartão de Lovelace. ## YAML ### Identações A estrutura do YAML é determinada pela sua indentação, sendo a indentação definida pelo numero de espaços no inicio da cada linha e podem ser zero, dois ou múltiplos de dois. ```yaml indentação = espaço x 2 ``` Os caracteres de tabulação não devem NUNCA ser utilizados para criar indentações e o HA irá gerar um erro na validação do código caso sejam utilizados. A estrutura de cada bloco é constituída por níveis, sendo que o nível anterior é considerado _parent_ e o inferior _children_. No exemplo seguinte `cards:` é _parent_ de `color: 'rgb(82,148,226)'`. Do mesmo modo, `style:` tem como _children_ `color: white` mas é ele próprio _children_ de `cards:`. ![image](https://forum.cpha.pt/uploads/default/original/2X/3/3bb7b15bee284ef9641b850d1cd2cc54aad5c669.png) O caracter `-` indica o inicio de uma listagem de variaveis ou atributos que se encontram ao mesmo nível, e que deve ser considerado na contagem de espaços na indentação. Embora o HA não considere como um erro, visualmente fica mais simples de ler o código e descobrir eventuais problemas. ![image](https://forum.cpha.pt/uploads/default/original/2X/b/b1799bb444fb6bfeb3f642e160b9b71ecd312053.png) Abaixo podem ver a indentação a funcionar na criação de um cartão que incorpora dois outros cartões na vertical. No nível 1 temos o cartão principal e que é _parent_ dos dois cartões verticais no nivel 2. Em YAML os níveis iguais em termos de indentação chamam-se _siblings_. ![image](https://forum.cpha.pt/uploads/default/original/2X/9/961ca5936cf740a96d131c244f8254263bcd616b.png) ### Linhas Vazias Quando necessitarem de deixar linhas vazias entre blocos de código, o que por vezes ajuda na criação do código, devem deixar a linha em branco sem caracteres ou quanto muito com espaços iguais a dois ou múltiplos de dois. A utilização de tabulações provoca erros na validação. ![image](https://forum.cpha.pt/uploads/default/original/2X/4/450eab75c95b98d4815a796edb40c1158278642d.png) ### Comentários Em YAML os comentários são indicados pelo caracter `#`. Se o comentário estiver entre dois blocos de código deve ser escrito sem espaços à esquerda, se for escrito após uma linha de código deve sempre ser precedido de um espaço ou de uma ou mais tabulações para que os comentários fiquem alinhados. ![image](https://forum.cpha.pt/uploads/default/original/2X/9/93ad18e3aeab8328320651cf46054e9c6ee0e671.png) Se necessitarem de criar comentários em linhas seguidas, seja por o comentário ser muito comprido ou serem dois comentários diferentes, todas as linhas deverão ser iniciadas pelo caracter `#` ![image](https://forum.cpha.pt/uploads/default/original/2X/e/e19b32dab581e728daaacb0bc1e0b3816947db95.png) ## Conclusão Embora inicialmente seja difícil de utilizar o YAML não é um bicho-de-sete-cabeças. Ao fim de algum tempo e com um bom editor de texto rapidamente escreverão código sem erros. E nunca se esqueçam do seguinte: - Depois de editar código devem SEMPRE validar a configuração antes de fazer reboot, - As mensagem de erro na validação e os erros no log ajudam muito no despiste de erros. > Este tutorial é baseado na informação constante na página oficial do YAML e diz respeito apenas à formatação do código. > > [https://yaml.org/spec/1.2/spec.html#Basic](https://yaml.org/spec/1.2/spec.html#Basic)