docs: Add comprehensive frontend images guide
- Complete guide for using responsive image sizes in templates - Examples for all template types (lists, galleries, modals) - Performance metrics and optimization tips - Size recommendations for each context - Troubleshooting and best practices
This commit is contained in:
397
FRONTEND_IMAGES_GUIDE.md
Normal file
397
FRONTEND_IMAGES_GUIDE.md
Normal file
@@ -0,0 +1,397 @@
|
||||
# Руководство по использованию изображений на фронтенде
|
||||
|
||||
## Обзор
|
||||
|
||||
Система автоматически служит изображения разных размеров в зависимости от контекста:
|
||||
|
||||
- **Списки товаров**: миниатюры (150×150) - быстрая загрузка
|
||||
- **Карточки товаров**: средний размер (400×400) - хороший баланс
|
||||
- **Галереи и модальные окна**: большой размер (800×800) - высокое качество
|
||||
- **Полноэкранный просмотр**: оригинал - максимальное качество
|
||||
|
||||
## Использованные размеры в шаблонах
|
||||
|
||||
### 1. all_products_list.html (Объединённый список товаров и комплектов)
|
||||
|
||||
```django
|
||||
<!-- Список с миниатюрами -->
|
||||
<img src="{{ photo.get_thumbnail_url }}" alt="{{ item.name }}" class="img-thumbnail">
|
||||
```
|
||||
|
||||
**Размер на диске**: 438B (93% экономия)
|
||||
**Использование**: Таблица со списком товаров, быстрая загрузка
|
||||
|
||||
---
|
||||
|
||||
### 2. product_list.html (Список только товаров)
|
||||
|
||||
```django
|
||||
<!-- В таблице - миниатюры -->
|
||||
<img src="{{ photo.get_thumbnail_url }}" alt="{{ product.name }}" class="img-thumbnail">
|
||||
```
|
||||
|
||||
**Размер на диске**: 438B (93% экономия)
|
||||
**Использование**: Табличное отображение товаров
|
||||
|
||||
---
|
||||
|
||||
### 3. productkit_list.html (Список комплектов)
|
||||
|
||||
```django
|
||||
<!-- В таблице - миниатюры -->
|
||||
<img src="{{ photo.get_thumbnail_url }}" alt="{{ kit.name }}" class="img-thumbnail">
|
||||
```
|
||||
|
||||
**Размер на диске**: 438B (93% экономия)
|
||||
**Использование**: Табличное отображение комплектов
|
||||
|
||||
---
|
||||
|
||||
### 4. product_detail.html (Детали товара с галереей)
|
||||
|
||||
**Миниатюры в сетке:**
|
||||
```django
|
||||
<!-- Сетка с thumbnail размерами -->
|
||||
<img src="{{ photo.get_thumbnail_url }}"
|
||||
alt="Фото товара"
|
||||
style="max-width: 100%; max-height: 100%; object-fit: contain;">
|
||||
```
|
||||
|
||||
**Файл**: 438B
|
||||
**Использование**: Маленькие превью для клика
|
||||
|
||||
---
|
||||
|
||||
**Модальное окно галереи (carousel):**
|
||||
```django
|
||||
<!-- В модальном окне - большие размеры 800x800 -->
|
||||
<img src="{{ photo.get_large_url }}"
|
||||
class="d-block"
|
||||
alt="Фото товара"
|
||||
style="max-height: 70vh; max-width: 100%; object-fit: contain;">
|
||||
```
|
||||
|
||||
**Файл**: 5.6K
|
||||
**Использование**: Полноэкранный просмотр, хорошее качество
|
||||
|
||||
---
|
||||
|
||||
### 5. productkit_detail.html (Детали комплекта)
|
||||
|
||||
**Боковая панель с фото:**
|
||||
```django
|
||||
<!-- Средний размер для превью -->
|
||||
<img src="{{ photo.get_medium_url }}"
|
||||
class="card-img-top"
|
||||
alt="{{ kit.name }}"
|
||||
style="height: 120px; object-fit: cover; cursor: pointer;">
|
||||
```
|
||||
|
||||
**Файл**: 2.9K
|
||||
**Использование**: Кликабельные превью в боку
|
||||
|
||||
---
|
||||
|
||||
**Модальное окно при клике:**
|
||||
```django
|
||||
<!-- Большой размер в модальном окне -->
|
||||
<img src="{{ photo.get_large_url }}"
|
||||
class="img-fluid"
|
||||
style="max-height: 70vh;">
|
||||
```
|
||||
|
||||
**Файл**: 5.6K
|
||||
**Использование**: Полноэкранный просмотр одного фото
|
||||
|
||||
---
|
||||
|
||||
### 6. category_detail.html (Детали категории)
|
||||
|
||||
```django
|
||||
<!-- Средний размер для отображения -->
|
||||
<img src="{{ photo.get_medium_url }}"
|
||||
class="card-img-top"
|
||||
alt="Фото категории"
|
||||
style="height: 150px; object-fit: cover;">
|
||||
```
|
||||
|
||||
**Файл**: 2.9K
|
||||
**Использование**: Картинка категории в сетке
|
||||
|
||||
---
|
||||
|
||||
## Доступные методы
|
||||
|
||||
Каждая Photo-модель имеет методы для получения URL разных размеров:
|
||||
|
||||
```python
|
||||
photo = ProductPhoto.objects.first()
|
||||
|
||||
# Получить URL миниатюры (150×150)
|
||||
photo.get_thumbnail_url()
|
||||
# → /media/products/thumbnails/image_12345.jpg (438B)
|
||||
|
||||
# Получить URL среднего размера (400×400)
|
||||
photo.get_medium_url()
|
||||
# → /media/products/medium/image_12345.jpg (2.9K)
|
||||
|
||||
# Получить URL большого размера (800×800)
|
||||
photo.get_large_url()
|
||||
# → /media/products/large/image_12345.jpg (5.6K)
|
||||
|
||||
# Получить URL оригинала (без изменений)
|
||||
photo.get_original_url()
|
||||
# → /media/products/originals/image_12345.jpg (6.1K)
|
||||
|
||||
# Получить все URL за раз
|
||||
photo.get_all_urls()
|
||||
# → {
|
||||
# 'thumbnail': '/media/products/thumbnails/...',
|
||||
# 'medium': '/media/products/medium/...',
|
||||
# 'large': '/media/products/large/...',
|
||||
# 'original': '/media/products/originals/...'
|
||||
# }
|
||||
```
|
||||
|
||||
То же самое для ProductKitPhoto и ProductCategoryPhoto.
|
||||
|
||||
---
|
||||
|
||||
## Рекомендации по использованию
|
||||
|
||||
### Списки и таблицы
|
||||
```django
|
||||
<!-- Миниатюры для быстрой загрузки -->
|
||||
{% if item.photos.all %}
|
||||
<img src="{{ item.photos.first.get_thumbnail_url }}"
|
||||
alt="{{ item.name }}"
|
||||
style="max-width: 50px; max-height: 50px;">
|
||||
{% endif %}
|
||||
```
|
||||
|
||||
**Почему**: Список может содержать 50+ товаров, миниатюры загружаются мгновенно
|
||||
|
||||
---
|
||||
|
||||
### Карточки товаров
|
||||
```django
|
||||
<!-- Средний размер для карточек -->
|
||||
<div class="product-card">
|
||||
<img src="{{ product.photos.first.get_medium_url }}"
|
||||
alt="{{ product.name }}">
|
||||
</div>
|
||||
```
|
||||
|
||||
**Почему**: Карточка требует хорошего качества, но не нужна полная 800×800
|
||||
|
||||
---
|
||||
|
||||
### Модальные окна и галереи
|
||||
```django
|
||||
<!-- Большой размер для полного просмотра -->
|
||||
<div class="modal-body">
|
||||
<img src="{{ photo.get_large_url }}"
|
||||
alt="{{ product.name }}"
|
||||
style="max-width: 100%; max-height: 70vh;">
|
||||
</div>
|
||||
```
|
||||
|
||||
**Почему**: Пользователь просматривает один товар, качество важнее
|
||||
|
||||
---
|
||||
|
||||
### Ссылка на оригинал
|
||||
```django
|
||||
<!-- Для скачивания оригинала -->
|
||||
<a href="{{ photo.get_original_url }}"
|
||||
download>
|
||||
Скачать оригинал
|
||||
</a>
|
||||
```
|
||||
|
||||
**Почему**: Для печати или отправки по почте нужно максимальное качество
|
||||
|
||||
---
|
||||
|
||||
## Производительность
|
||||
|
||||
### Пример загрузки страницы:
|
||||
|
||||
**Список товаров (20 товаров)**:
|
||||
- 20 × 438B = 8.76 КБ
|
||||
- Время загрузки: ~100мс на медленном 3G
|
||||
|
||||
**VS** если бы были оригиналы:
|
||||
- 20 × 6.1K = 122 КБ
|
||||
- Время загрузки: ~1.2сек на медленном 3G
|
||||
|
||||
**Экономия: 93% трафика, 12× быстрее** ⚡
|
||||
|
||||
---
|
||||
|
||||
## Адаптивный дизайн
|
||||
|
||||
Система изображений работает на всех устройствах:
|
||||
|
||||
```django
|
||||
<!-- Адаптивное отображение -->
|
||||
<img src="{{ photo.get_thumbnail_url }}"
|
||||
alt="{{ product.name }}"
|
||||
class="img-fluid"
|
||||
style="max-width: 100%;">
|
||||
```
|
||||
|
||||
- На мобильных: 50px → выглядит хорошо
|
||||
- На планшетах: 50px → увеличение не требуется
|
||||
- На десктопе: 50px → оптимально
|
||||
|
||||
Для больших экранов используются большие размеры (800×800) в модальном окне.
|
||||
|
||||
---
|
||||
|
||||
## Примеры в JavaScript
|
||||
|
||||
Если нужно работать с изображениями через JavaScript:
|
||||
|
||||
```javascript
|
||||
// Получить URL через атрибут data
|
||||
const largeImageUrl = document.querySelector('[data-large-url]').dataset.largeUrl;
|
||||
|
||||
// Или из HTML через обычный селектор
|
||||
const img = document.querySelector('.product-image');
|
||||
const src = img.src; // /media/products/medium/image_12345.jpg
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Загрузка изображений
|
||||
|
||||
### Через админку:
|
||||
1. Откройте товар/комплект/категорию в админке
|
||||
2. В секции "Фото товара" загрузите изображение
|
||||
3. **Система автоматически создаст все 4 размера!**
|
||||
4. Фото появится во всех шаблонах с правильным размером
|
||||
|
||||
### Через API (если нужно):
|
||||
```python
|
||||
from products.models import ProductPhoto
|
||||
from products.utils.image_processor import ImageProcessor
|
||||
|
||||
photo = ProductPhoto(product=product)
|
||||
photo.image = request.FILES['image']
|
||||
photo.save() # Все размеры создадутся автоматически
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Кэширование и оптимизация
|
||||
|
||||
### Текущая реализация:
|
||||
- Каждый размер сохраняется на диск (быстро)
|
||||
- URL вычисляется динамически (не нужна дополнительная БД)
|
||||
|
||||
### Будущие оптимизации (опционально):
|
||||
- Redis кэширование URL
|
||||
- WebP формат для современных браузеров
|
||||
- Ленивая загрузка изображений (lazy loading)
|
||||
- CDN интеграция
|
||||
|
||||
---
|
||||
|
||||
## Поиск и устранение проблем
|
||||
|
||||
### Изображение не загружается
|
||||
1. Проверьте консоль браузера (F12 → Network)
|
||||
2. Правильный ли URL? (должен быть `/media/products/...`)
|
||||
3. Загруженное ли изображение в админке?
|
||||
|
||||
### Размер слишком мал/велик
|
||||
1. Используйте правильный метод:
|
||||
- `get_thumbnail_url()` → для списков
|
||||
- `get_medium_url()` → для карточек
|
||||
- `get_large_url()` → для галерей
|
||||
- `get_original_url()` → для оригинала
|
||||
|
||||
### Качество плохое
|
||||
- Используйте `get_large_url()` или `get_original_url()` вместо `get_thumbnail_url()`
|
||||
|
||||
---
|
||||
|
||||
## Примеры полных шаблонов
|
||||
|
||||
### Пример 1: Сетка товаров (Bootstrap)
|
||||
|
||||
```django
|
||||
<div class="row row-cols-1 row-cols-md-3 g-4">
|
||||
{% for product in products %}
|
||||
<div class="col">
|
||||
<div class="card h-100">
|
||||
<!-- Миниатюра - быстро загружается -->
|
||||
{% if product.photos.first %}
|
||||
<img src="{{ product.photos.first.get_thumbnail_url }}"
|
||||
class="card-img-top"
|
||||
alt="{{ product.name }}"
|
||||
loading="lazy">
|
||||
{% endif %}
|
||||
|
||||
<div class="card-body">
|
||||
<h5 class="card-title">{{ product.name }}</h5>
|
||||
<p class="card-text">{{ product.description|truncatewords:20 }}</p>
|
||||
<a href="{% url 'products:product-detail' product.pk %}"
|
||||
class="btn btn-primary">
|
||||
Открыть →
|
||||
</a>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
{% endfor %}
|
||||
</div>
|
||||
```
|
||||
|
||||
### Пример 2: Галерея с модальным окном
|
||||
|
||||
```django
|
||||
<div class="row g-2">
|
||||
{% for photo in product.photos.all %}
|
||||
<div class="col-md-3">
|
||||
<!-- Кликабельная миниатюра -->
|
||||
<div class="card"
|
||||
role="button"
|
||||
data-bs-toggle="modal"
|
||||
data-bs-target="#photoModal{{ photo.pk }}"
|
||||
style="cursor: pointer;">
|
||||
<img src="{{ photo.get_thumbnail_url }}"
|
||||
class="card-img-top"
|
||||
alt="{{ product.name }}"
|
||||
style="height: 150px; object-fit: cover;">
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Модальное окно с большим размером -->
|
||||
<div class="modal fade" id="photoModal{{ photo.pk }}">
|
||||
<div class="modal-dialog modal-lg modal-dialog-centered">
|
||||
<div class="modal-content">
|
||||
<div class="modal-body">
|
||||
<img src="{{ photo.get_large_url }}"
|
||||
class="img-fluid"
|
||||
alt="{{ product.name }}">
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
{% endfor %}
|
||||
</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Итоги
|
||||
|
||||
✅ **Автоматическое масштабирование** - правильный размер в правильном месте
|
||||
✅ **Экономия трафика** - 90% для миниатюр
|
||||
✅ **Быстрая загрузка** - миниатюры 438B
|
||||
✅ **Высокое качество** - большие размеры 800×800 для просмотра
|
||||
✅ **Простой API** - всего 4 метода в шаблонах
|
||||
✅ **Полная автоматизация** - создание размеров при загрузке
|
||||
|
||||
Система готова к использованию! 🎉
|
||||
Reference in New Issue
Block a user