> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/latex/overleaf-learn-latex-pt/ficheiros-de-classe/04-writing-your-own-class.md). # Escrever a sua própria classe Por vezes, a melhor opção para personalizar um documento é escrever uma nova classe de raiz. Este artigo explica a estrutura principal e os comandos necessários numa nova classe. ## Introdução A primeira coisa a fazer antes de programar uma nova classe é determinar se realmente precisa ou não de uma nova classe. Recomenda-se [pesquisar no CTAN (Comprehensive TeX Archive Network)](http://www.ctan.org/ctan-portal/search/) e ver se alguém já criou algo semelhante à classe de documento de que precisa. Outra coisa importante a ter em mente é [a diferença entre pacotes e classes](/latex/overleaf-learn-latex-pt/ficheiros-de-classe/01-understanding-packages-and-class-files.md). Fazer a escolha errada pode afetar a flexibilidade do produto final. ## Estrutura geral A estrutura de todos os ficheiros de classe pode ser descrita, de forma aproximada, nas quatro partes seguintes: * ***Identificação***. O ficheiro declara-se como uma classe escrita com a sintaxe LaTeX2ε. * ***Declarações preliminares***. Aqui são importados os pacotes e classes externos necessários. Além disso, nesta parte do ficheiro são codificados os comandos e definições necessários pelas opções declaradas. * ***Opções***. A classe declara e processa as opções. * ***Mais declarações***. O corpo principal da classe. Quase tudo o que uma classe faz é definido aqui. Nas próximas subseções será apresentada uma descrição mais detalhada da estrutura e um exemplo funcional, *exampleclass.cls*, serão apresentados. ### Identificação Existem dois comandos simples que todas as classes devem ter: ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesClass{exampleclass}[2014/08/16 Example LaTeX class] ``` O comando `\NeedsTeXFormat{LaTeX2e}` define a versão do LaTeX com que a classe funciona. Além disso, pode ser adicionada uma data entre parênteses retos para especificar a data mínima de lançamento necessária. O comando `ProvidesClass{exampleclass}[...]` identifica esta classe como *exampleclass* e, dentro das chavetas, inclui a data de lançamento e algumas informações adicionais. A data deve estar no formato AAAA/MM/DD [Abrir um exemplo de como escrever uma classe no Overleaf](https://www.overleaf.com/project/new/template/19419?id=65524436\&templateName=An+example+of+writing+a+LaTeX+class\&latexEngine=\&texImage=texlive-full%3A2020.1\&mainFile=) ### Declarações preliminares A maioria das classes estende e personaliza as existentes, e também precisa de alguns pacotes externos para funcionar. Abaixo, é adicionado mais algum código à classe de exemplo `exampleclass.cls`. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesClass{exampleclass}[2014/08/16 Example LaTeX class] \newcommand{\headlinecolor}{\normalcolor} \LoadClass[twocolumn]{article} \RequirePackage{xcolor} \definecolor{slcolor}{HTML}{882B21} ``` Os comandos nesta parte ou inicializam alguns parâmetros que mais tarde serão usados para gerir as opções, ou importam ficheiros externos. O comando `\LoadClass[twocolumn]{article}` carrega a classe `article` com o parâmetro adicional `twocolumn`. Assim, todos os comandos da `article` classe padrão estarão automaticamente disponíveis na **exemplo** classe, exceto pelo facto de o documento ser impresso num formato de duas colunas. `\RequirePackage` é muito semelhante ao conhecido `\usepackage`, adicionar parâmetros opcionais entre chavetas também funcionará. A única diferença é que o `\usepackage` não pode ser usado antes do comando `\documentclass` . É fortemente recomendado usar `\RequirePackage` ao escrever novas classes ou pacotes. [Abrir um exemplo de como escrever uma classe no Overleaf](https://www.overleaf.com/project/new/template/19419?id=65524436\&templateName=An+example+of+writing+a+LaTeX+class\&latexEngine=\&texImage=texlive-full%3A2020.1\&mainFile=) ### Opções Para permitir alguma flexibilidade nas classes, algumas opções adicionais são muito úteis. A próxima parte do ficheiro `exampleclass.cls` trata dos parâmetros passados ao comando da classe do documento. Também movemos `\LoadClass` para *depois de* as opções são processadas, para que as opções definidas no ficheiro .tex possam ser passadas à classe base. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesClass{exampleclass}[2014/08/16 Example LaTeX class] \newcommand{\headlinecolor}{\normalcolor} \RequirePackage{xcolor} \definecolor{slcolor}{HTML}{882B21} \DeclareOption{onecolumn}{\OptionNotUsed} \DeclareOption{green}{\renewcommand{\headlinecolor}{\color{green}}} \DeclareOption{red}{\renewcommand{\headlinecolor}{\color{slcolor}}} \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} \ProcessOptions\relax \LoadClass[twocolumn]{article} ``` Existem aqui quatro comandos principais que tratam as opções passadas à classe. O comando `\DeclareOption{}{}` trata de uma dada opção. Aceita dois parâmetros: o primeiro é o nome da opção e o segundo é o código a executar se a opção for passada. O comando `\OptionNotUsed` irá imprimir uma mensagem no compilador e nos registos, a opção não será usada. Neste caso, o documento é definido para duas colunas e, se o utilizador tentar alterá-lo para uma coluna, isso não funcionará; a opção será ignorada. O comando `\Declareoption*{}` trata de todas as opções não definidas explicitamente. Recebe apenas um parâmetro, o código a executar quando é passada uma opção desconhecida. Neste caso, executará o comando seguinte: `\PassOptionsToClass{}{}`. Passa a opção dentro do primeiro par de chavetas para a classe de documento definida dentro do segundo par de chavetas. No exemplo, todas as opções desconhecidas serão passadas para a **article** classe de documento. `\CurrentOption` guarda o nome da opção da classe que está a ser tratada num determinado momento. O comando `\ProcessOptions\relax` executa o código de cada opção e deve ser inserido depois de todos os comandos de tratamento de opções terem sido escritos. Existe uma versão com asterisco deste comando que executará as opções exatamente pela ordem especificada pelos comandos de chamada. No exemplo, se as opções `vermelho` ou `green` são passados ao documento, o tipo de letra usado para o cabeçalho e as secções será definido com a cor correspondente. A cor chamada `slcolor` foi definida em [declarações preliminares](#preliminary-declaration) após importar o `xcolor` pacote. [Abrir um exemplo de como escrever uma classe no Overleaf](https://www.overleaf.com/project/new/template/19419?id=65524436\&templateName=An+example+of+writing+a+LaTeX+class\&latexEngine=\&texImage=texlive-full%3A2020.1\&mainFile=) ### Mais declarações Nesta parte aparecerão a maioria dos comandos. Em "exampleclass.cls", são definidos as dimensões da página, o tamanho da letra para o título, o corpo e as secções. Abaixo pode ver o ficheiro de classe completo. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesClass{exampleclass}[2014/08/16 Example LaTeX class] \newcommand{\headlinecolor}{\normalcolor} \RequirePackage{xcolor} \definecolor{slcolor}{HTML}{882B21} \DeclareOption{onecolumn}{\OptionNotUsed} \DeclareOption{green}{\renewcommand{\headlinecolor}{\color{green}}} \DeclareOption{red}{\renewcommand{\headlinecolor}{\color{slcolor}}} \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} \ProcessOptions\relax \LoadClass[twocolumn]{article} \renewcommand{\maketitle}{% \twocolumn[% \fontsize{50}{60}\fontfamily{phv}\fontseries{b}% \fontshape{sl}\selectfont\headlinecolor \@title \medskip ]% } \renewcommand{\section}{% \@startsection {section}{1}{0pt}{-1.5ex plus -1ex minus -.2ex}% {1ex plus .2ex}{\large\sffamily\slshape\headlinecolor}% } \renewcommand{\normalsize}{\fontsize{9}{10}\selectfont} \setlength{\textwidth}{17.5cm} \setlength{\textheight}{22cm} \setcounter{secnumdepth}{0} ``` Para compreender o resto dos comandos, veja [guia de referência](#reference-guide) e os links na [secção de leitura adicional](#further-reading). Os últimos quatro comandos no exemplo mostram as quatro coisas que todas as classes devem conter: * A definição de `normalsize`. Define o [tamanho da fonte](/latex/overleaf-learn-latex-pt/fontes/01-font-sizes-families-and-styles.md). * Um valor predefinido para [`textwidth`](/latex/overleaf-learn-latex-pt/formatacao/07-page-size-and-margins.md) * Um valor predefinido para [`textheight`](/latex/overleaf-learn-latex-pt/formatacao/07-page-size-and-margins.md) * As especificações para a [numeração das páginas](/latex/overleaf-learn-latex-pt/formatacao/03-page-numbering.md). Abaixo, um documento que usa a classe *exampleclass.cls*. ```latex \documentclass[red]{exampleclass} \usepackage[utf8]{inputenc} \usepackage[english]{babel} \usepackage{blindtext} \title{Exemplo para mostrar como as classes funcionam} \author{Equipa Learn ShareLaTeX} \date{Agosto de 2014} \begin{document} \maketitle \noindent Vamos começar aqui com um exemplo simples e funcional. \blindtext \section{Introdução} O problema de Monty Hall... \section{A mesma coisa} O Monty... ``` ![WrittingClassesEx1.png](/files/52bb5e2b3e80403d44d1cd1c23accfbdfe838369) Note que o primeiro comando aqui é ```latex \documentclass[red]{exampleclass} ``` [Abrir um exemplo de como escrever uma classe no Overleaf](https://www.overleaf.com/project/new/template/19419?id=65524436\&templateName=An+example+of+writing+a+LaTeX+class\&latexEngine=\&texImage=texlive-full%3A2020.1\&mainFile=) ## Tratamento de erros Quando se trata de desenvolver novas classes, é importante tratar possíveis erros para informar o utilizador de que algo correu mal. Existem quatro comandos principais para comunicar erros no compilador. * `\ClassError{*class-name*}{*error-text*}{*help-text*}`. Recebe três parâmetros, cada um entre chavetas: o nome da classe, o texto do erro que será apresentado (o processo de compilação será pausado) e o texto de ajuda que será impresso se o utilizador premir "h" quando a compilação parar devido ao erro. * `\ClassWarning{*class-name*}{*warning-text*}`. Neste caso, o texto é apresentado mas o processo de compilação não irá parar. Será mostrada a linha onde o aviso ocorreu. * `\ClassWarningNoLine{*class-name*}{*warning-text*}`. Funciona exatamente como o comando anterior, mas não mostrará a linha onde o aviso ocorreu. * `\ClassInfo{*class name*}{*info-text*}`. Neste caso, a informação no segundo parâmetro será impressa apenas no ficheiro de transcrição, incluindo o número da linha. [Abrir um exemplo de como escrever uma classe no Overleaf](https://www.overleaf.com/project/new/template/19419?id=65524436\&templateName=An+example+of+writing+a+LaTeX+class\&latexEngine=\&texImage=texlive-full%3A2020.1\&mainFile=) ## Guia de referência **Lista de comandos comumente usados em classes e pacotes** * `\newcommand{*name*}{*definition*}`. Define um [novo comando](/latex/overleaf-learn-latex-pt/comandos/01-commands.md#defining-a-new-command), o primeiro parâmetro é o nome do novo comando, o segundo parâmetro é o que o comando fará. * `\renewcommand{}{}`. O mesmo que `\newcommand` mas irá sobrescrever um comando existente. * `\providecommand{}{}`. Funciona como `\newcommand` mas, se o comando já estiver definido, este será ignorado silenciosamente. * `\CheckCommand{}{}`. A sintaxe é a mesma que `\newcommand`, mas, em vez disso, verificará se o comando existe e tem a definição esperada; o LaTeX mostrará um aviso se o comando não for o que `\CheckCommand` era esperado. * `\setlength{}{}`. Define o comprimento do elemento passado como primeiro parâmetro para o valor indicado como segundo parâmetro. * `\mbox{}`. Cria uma caixa que contém os elementos escritos dentro das chavetas. * `\fbox{}`. O mesmo que `\mbox`, mas é realmente desenhada uma caixa à volta do conteúdo. ## Leitura adicional Para mais informações, veja * [Compreender pacotes e ficheiros de classe](/latex/overleaf-learn-latex-pt/ficheiros-de-classe/01-understanding-packages-and-class-files.md) * [Escrever o seu próprio pacote](/latex/overleaf-learn-latex-pt/ficheiros-de-classe/03-writing-your-own-package.md) * [Comandos](/latex/overleaf-learn-latex-pt/comandos/01-commands.md) e [Ambientes](/latex/overleaf-learn-latex-pt/comandos/02-environments.md) * [Comprimentos em LaTeX](/latex/overleaf-learn-latex-pt/formatacao/01-lengths-in-latex.md) * [Utilizar cores no LaTeX](/latex/overleaf-learn-latex-pt/formatacao/13-using-colors-in-latex.md) * [Gestão num grande projeto](/latex/overleaf-learn-latex-pt/estrutura-do-documento/07-management-in-a-large-project.md) * [LaTeX2ε para autores de classes e pacotes](http://www.latex-project.org/guides/clsguide.pdf) * [Notas sobre programação em TeX](http://pgfplots.sourceforge.net/TeX-programming-notes.pdf) * [Minutos em vez de horas: Usando recursos do LaTeX](https://tug.org/pracjourn/2005-4/hefferon/hefferon.pdf) * [O Companheiro de LaTeX. Segunda edição](http://ptgmedia.pearsoncmg.com/images/9780201362992/samplepages/0201362996.pdf) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://overleaf-pro.ayaka.space/latex/overleaf-learn-latex-pt/ficheiros-de-classe/04-writing-your-own-class.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.