Tutorial: Servir arquivos estáticos e usar a herança de modelo com o Django no Visual Studio

2025-06-12

Este artigo apresenta a Etapa 3 da série de tutoriais Trabalhar com a estrutura web do Django no Visual Studio.

A etapa anterior nesta série de tutoriais cria um aplicativo Django mínimo com uma única página de HTML independente. Os aplicativos Web modernos normalmente são compostos por muitas páginas e usam recursos compartilhados, como arquivos CSS e JavaScript, para fornecer estilo e comportamento consistentes. Na Etapa 3, você trabalha com modelos de item do Visual Studio para adicionar conteúdo ao seu projeto do Django e expandir os recursos do aplicativo.

Na Etapa 3 do tutorial, você aprenderá a:

Usar modelos de item do Visual Studio para adicionar rapidamente novos arquivos com código clichê
Servir arquivos estáticos do código Django
Adicionar mais páginas ao aplicativo Django
Usar herança de modelo para criar um cabeçalho e navegação entre páginas

Pré-requisitos

Uma solução do Visual Studio e projetos de aplicativo Django, criados na Etapa 1: criar o projeto Django e atualizados na Etapa 2: criar um aplicativo Django com exibições e modelos de página desta série de tutoriais.
Examine a seção pré-requisitos na Etapa 1 desta série de tutoriais para obter detalhes sobre versões de modelo do Django, projetos do Visual Studio versus projetos do Django e desenvolvimento do Python no Mac.

Explorar modelos de item no Visual Studio

À medida que você desenvolve um aplicativo Django, normalmente você adiciona muito mais arquivos Python, HTML, CSS e JavaScript. Para cada tipo de arquivo (bem como para outros arquivos, como web.config, que podem ser necessários para a implantação), o Visual Studio fornece modelos de itens convenientes para você começar. Você pode usar esses modelos para adicionar rapidamente novos arquivos de diferentes tipos com código clichê.

Para exibir os modelos disponíveis, acesse do Gerenciador de Soluções no Visual Studio e abra sua estrutura de projeto.
Clique com o botão direito do mouse na pasta na qual você deseja criar um novo arquivo e selecione Adicionar>Novo Item. A caixa de diálogo Adicionar Novo Item é aberta:
Para usar um modelo, selecione o modelo desejado, insira um nome para o arquivo e selecione Adicionar.

O Visual Studio adiciona o arquivo ao seu projeto atual e marca as alterações para o controle do código-fonte.

Entender como o Visual Studio identifica modelos de item

O arquivo de projeto do Visual Studio (.pyproj) contém um identificador de tipo de projeto que marca o arquivo como um projeto python. O Visual Studio usa esse identificador de tipo para reconhecer e mostrar apenas os modelos de item adequados para o tipo de projeto. O Visual Studio segue essa abordagem para fornecer um conjunto avançado de modelos de item para muitos tipos de projeto sem solicitar que você os classifique todas as vezes.

Fornecer arquivos estáticos por meio do aplicativo

Em um aplicativo Web criado com Python (usando qualquer estrutura), seus arquivos Python sempre são executados no servidor do host da Web e nunca são transmitidos para o computador de um usuário. Outros arquivos, como CSS e JavaScript, são usados apenas pelo navegador, portanto, o servidor host simplesmente os entrega as-is quando solicitados. Esses tipos de arquivos são chamados de arquivos "estáticos" e o Django pode entregá-los automaticamente sem que você precise escrever nenhum código.

Um projeto do Django é configurado por padrão para servir arquivos estáticos da pasta estática do aplicativo. Esse comportamento é possível pelo código a seguir no arquivo de settings.py do projeto do Django:

# Static files (CSS, JavaScript, Images)
# https://docs.djangoproject.com/en/1.9/howto/static-files/

STATIC_URL = '/static/'

STATIC_ROOT = posixpath.join(*(BASE_DIR.split(os.path.sep) + ['static']))

Você pode organizar os arquivos dentro da pasta estática do aplicativo usando qualquer estrutura de pasta desejada e usar caminhos relativos dentro da pasta estático para se referir aos arquivos.

Usar o arquivo CSS estático no modelo HTML

Siga estas etapas para adicionar um arquivo CSS ao aplicativo e, em seguida, use a folha de estilos CSS no modelo index.html:

No Gerenciador de Soluções, clique com o botão direito do mouse na pasta HelloDjangoApp no projeto, selecione Adicionar>Nova pasta e nomeie a pasta static.
Clique com o botão direito do mouse na pasta estático e selecione Adicionar>Novo Item.
Na caixa de diálogo Adicionar Novo Item, selecione o modelo folha de estilos, nomeie o arquivo site.cse selecione Adicionar.

O Visual Studio adiciona o arquivo site.css ao projeto e abre o arquivo no editor. Aqui está um exemplo da estrutura de projeto atualizada do Django:
Substitua o conteúdo do arquivo site.css pelos seguintes estilos:
```
.message {
    font-weight: 600;
    color: blue;
}
```
Substitua o conteúdo do arquivo HelloDjangoApp/templates/index.html pela seguinte marcação:
```
<html>
   <head>
      <title>{{ title }}</title>
      {% load static %} 
      <link rel="stylesheet" type="text/css" href="{% static 'site.css' %}" />
   </head>
   <body>
      <span class="message">{{ message }}</span>{{ content }}
   </body>
</html>
```
Esse código substitui o elemento HTML <strong> da Etapa 2 na série de tutoriais por um elemento <span> que faz referência à classe de estilo message. Usar uma classe de estilo dessa forma oferece mais flexibilidade no estilo do elemento HTML.
Salve as alterações do projeto selecionando Arquivo>Salvar Tudo ou use o atalho de teclado Ctrl+Shift+S. (Esta etapa não é necessária porque, à medida que você desenvolve seu projeto, o Visual Studio salva seus arquivos automaticamente.)
Execute o projeto e observe os resultados. Quando terminar, interrompa o aplicativo.
(Opcional) Você pode confirmar suas alterações no controle do código-fonte e atualizar seu repositório remoto. Para obter mais informações, confira Confirmar alterações no controle do código-fonte na Etapa 2 desta série de tutoriais.

Usar a tag {% load static %}

A instrução {% load static %} deve estar presente no arquivo index.html antes que referências relativas do site a arquivos estáticos em elementos HTML como <head> e <body>. No exemplo mostrado nesta seção, "arquivos estáticos" refere-se a um conjunto de marcas de modelo personalizado do Django. O conjunto de marcas permite que você use a sintaxe {% static %} para se referir a arquivos estáticos. Sem a etiqueta {% load static %}, você verá uma exceção quando o aplicativo for executado.

Adicionar referências sem a tag {% load static %}

Você também pode configurar referências relativas de site para arquivos estáticos na marcação HTML sem usar a tag {% load static %}. Nesse caso, você especifica a localização da pasta estática na hierarquia de pastas do projeto Django.

<html>
    <head>
        <title>{{ title }}</title>
        <link rel="stylesheet" type="text/css" href="../../static/site.css" />
    </head>
    <body>
        <span class="message">{{ message }}</span>{{ content }}
    </body>
</html>

Organizar arquivos e pastas estáticos

Você pode adicionar outros arquivos CSS, JavaScript e HTML na pasta estático de acordo com as necessidades do projeto. Uma maneira típica de organizar arquivos estáticos é criar subpastas chamadas fontes, scriptse de conteúdo (para folhas de estilo e quaisquer outros arquivos). Em cada caso, lembre-se de incluir as pastas no caminho de arquivo relativo nas referências {% static %}.

Adicionar página ao aplicativo Django

Adicionar outra página ao aplicativo Django envolve as seguintes tarefas:

Adicionar uma função Python que define a visão
Adicionar um modelo para a marcação HTML da página
Atualizar as rotas de URL no arquivo urls.py do projeto do Django

Siga estas etapas para adicionar uma página Sobre (/about) ao projeto HelloDjangoApp e links para essa página a partir da página inicial.

No Gerenciador de Soluções, clique com o botão direito do mouse na pasta templates/HelloDjangoApp no projeto e selecione Adicionar>Novo Item.

Dica

Se você não vir o comando Novo Item no menu Adicionar, pare o aplicativo Django para que o Visual Studio saia do modo de depuração, conforme necessário.
Na caixa de diálogo Adicionar Novo Item, selecione o modelo Página HTML, nomeie o arquivo about.html, e depois selecione Adicionar.

Substitua o conteúdo do arquivo about.html pela seguinte marcação HTML:

<html>
   <head>
      <title>{{ title }}</title>
      {% load static %}
      <link rel="stylesheet" type="text/css" href="{% static 'site.css' %}" />
   </head>
   <body>
      <div><a href="home">Home</a></div>
      {{ content }}
   </body>
</html>

Em uma etapa subsequente, você substitui o link explícito para a home page por uma barra de navegação.

No arquivo HelloDjangoApp/views.py, adicione uma função chamada about que usa o modelo:

def about(request):
   return render(
      request,
      "HelloDjangoApp/about.html",
      {
         'title' : "About HelloDjangoApp",
         'content' : "Example app page for Django."
      }
   )

No arquivo BasicProject/urls.py do projeto django, adicione o caminho para a página about como o último item na matriz urlPatterns:

# Django processes URL patterns in the order they appear in the array
urlpatterns = [
   re_path(r'^$', HelloDjangoApp.views.index, name='index'),
   re_path(r'^home$', HelloDjangoApp.views.index, name='home'),
   re_path(r'^about$', HelloDjangoApp.views.about, name='about')
 ]

No arquivo templates/HelloDjangoApp/index.html, adicione a seguinte marcação como a primeira instrução no elemento <body>:
```
<div><a href="about">About</a></div>
```
Essa marcação adiciona um link à página /about do aplicativo Django. Em uma etapa posterior, você substituirá esse link por uma barra de navegação.
Salve as alterações do projeto e execute o projeto novamente. Navegue até a página /about e verifique a navegação entre as várias páginas do aplicativo.
Quando terminar, interrompa o aplicativo.

Ir para a página "índice"

Se você tentar navegar até a página /index para seu aplicativo em execução, verá um erro Page não encontrado (404).

Embora o arquivo HelloDjangoApp/views.py tenha uma função chamada index, os padrões de roteamento de URL no arquivo BasicProject/urls.py do projeto django não contêm uma expressão regular que corresponda à cadeia de caracteres index. A expressão atual da página "índice" do aplicativo é ^$. Para corresponder à cadeia de caracteres index, você precisa adicionar outra entrada de URL para o padrão ^index$.

A próxima seção descreve como é melhor usar a tag {% url '<pattern_name>' %} no modelo de página para se referir ao nome de um padrão. Nesse caso, o Django cria a URL adequada para você. Por exemplo, você pode substituir a marcação <div><a href="home">Home</a></div> no arquivo templates/HelloDjangoApp/about.html pela marcação <div><a href="{% url 'index' %}">Home</a></div>. O uso da cadeia de caracteres de 'index' agora funciona porque o primeiro padrão de URL no arquivo urls.py é nomeado 'index'. Você também pode usar 'home' para se referir ao segundo padrão.

Usar a herança de modelo para cabeçalho e navegação

Em vez de links de navegação explícitos em cada página, muitos aplicativos Web têm um cabeçalho de identidade visual e uma barra de navegação que fornece os links de página mais importantes, menus pop-up e assim por diante. Para garantir a consistência dentro do aplicativo, o cabeçalho e a barra de navegação devem ser iguais em todas as páginas, mas você não precisa repetir o mesmo código em cada modelo de página. Você pode definir as partes comuns de todas as suas páginas em um único arquivo.

O sistema de modelagem do Django fornece duas maneiras de reutilizar elementos específicos em vários modelos:

Includes corresponde a outros modelos de página que você insere em um local específico no modelo de referência com a sintaxe {% include <template_path> %}. Você também pode usar uma variável se quiser alterar o caminho dinamicamente no código. Os elementos Inclui normalmente são usados no corpo de uma página para extrair o modelo compartilhado em um local específico na página.
Inheritance usa a sintaxe {% extends <template_path> %} no início de um modelo de página para especificar um modelo de base compartilhado no qual o modelo de referência se baseará. A herança é usada normalmente para definir um layout compartilhado, uma barra de navegação e outras estruturas para as páginas de um aplicativo. Essa abordagem requer que os modelos de referência adicionem ou modifiquem apenas áreas específicas do modelo base chamado blocos.

Em ambas as abordagens, o valor <template_path> é relativo à pasta templates do aplicativo (../ ou ./ também é permitido).

Um modelo base delinea blocos usando as marcas {% block <block_name> %} e {% endblock %}. Se um modelo de referência usar marcas com o mesmo nome de bloco, o conteúdo do bloco no modelo de referência substituirá o bloco correspondente no modelo base.

As etapas a seguir demonstram a herança do modelo:

No Solution Explorer, clique com o botão direito do mouse na pasta templates/HelloDjangoApp e crie um novo arquivo a partir do template HTML Page com o nome layout.html.

Substitua o conteúdo do arquivo layout.html pela seguinte marcação HTML:

<!DOCTYPE html>
<html>
<head>
   <meta charset="utf-8" />
   <title>{{ title }}</title>
   {% load static %}
   <link rel="stylesheet" type="text/css" href="{% static 'site.css' %}" />
</head>

<body>
   <div class="navbar">
      <a href="/" class="navbar-brand">Hello Django</a>
      <a href="{% url 'home' %}" class="navbar-item">Home</a>
      <a href="{% url 'about' %}" class="navbar-item">About</a>
   </div>

   <div class="body-content">
      {% block content %}
      {% endblock %}
      <hr/>
      <footer>
         <p>&copy; 2024</p>
      </footer>
   </div>
</body>
</html>

Esse modelo contém um bloco chamado content, que identifica todo o conteúdo que as páginas de referência precisam substituir.

No arquivo HelloDjangoApp/static/site.css, adicione os seguintes estilos ao final do arquivo:

.navbar {
   background-color: lightslategray;
   font-size: 1em;
   font-family: 'Trebuchet MS', 'Lucida Sans Unicode', 'Lucida Grande', 'Lucida Sans', Arial, sans-serif;
   color: white;
   padding: 8px 5px 8px 5px;
}

.navbar a {
   text-decoration: none;
   color: inherit;
}

.navbar-brand {
   font-size: 1.2em;
   font-weight: 600;
}

.navbar-item {
   font-variant: small-caps;
   margin-left: 30px;
}

.body-content {
   padding: 5px;
   font-family:'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
}

Essas definições de estilo geram um resultado interessante para este exercício. Este passo a passo não demonstra design responsivo.

Substitua o conteúdo do arquivo templates/HelloDjangoApp/index.html pelo seguinte código:
```
{% extends "HelloDjangoApp/layout.html" %}
{% block content %}
<span class="message">{{ message }}</span>{{ content }}
{% endblock %}
```
O modelo index agora refere-se ao modelo base e substitui o bloco de content. Você pode ver que, usando a herança, esse modelo é simplificado.
Substitua o conteúdo do arquivo templates/HelloDjangoApp/about.html pelo seguinte código, portanto, o modelo de about também se refere ao modelo base e substitui o bloco content:
```
{% extends "HelloDjangoApp/layout.html" %}
{% block content %}
{{ content }}
{% endblock %}
```
Execute o aplicativo novamente e observe os resultados. Use os links da barra de navegação para alternar entre as páginas do aplicativo.
Quando terminar, interrompa o aplicativo e salve as alterações do projeto.
Como você fez alterações substanciais no aplicativo, é um bom momento para salvar suas alterações em um repositório Git. Para obter mais informações, confira Confirmar alterações no controle do código-fonte na Etapa 2 desta série de tutoriais.

Próxima etapa

Etapa 4: Usar o modelo completo do Projeto Web do Django

Compartilhar via