add: CodeMirror
This commit is contained in:
275
frontend-assembly/CODEMIRROR_INTEGRATION_GUIDE.md
Normal file
275
frontend-assembly/CODEMIRROR_INTEGRATION_GUIDE.md
Normal file
@@ -0,0 +1,275 @@
|
||||
# CodeMirror 6 для Django Admin на LPON.RU
|
||||
|
||||
## Обзор
|
||||
|
||||
CodeMirror 6 — это мощный редактор кода/текста для использования в Django Admin.
|
||||
Используется для редактирования HTML, JavaScript, CSS и других текстовых полей со синтаксис-хайлайтингом.
|
||||
|
||||
## Структура проекта
|
||||
|
||||
```
|
||||
frontend-assembly/
|
||||
├── package.json # Зависимости CodeMirror 6 (обновляй версии здесь!)
|
||||
├── package-lock.json # Заблокированные версии (обновляется через npm install)
|
||||
├── build-codemirror6.sh # Скрипт сборки (создает минифицированный бандл)
|
||||
└── README.md
|
||||
|
||||
public/static/codemirror/
|
||||
├── editor.js # Готовый минифицированный бандл (427 KB, GZIP ~130 KB)
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Версии пакетов (обновлены 11 июня 2026)
|
||||
|
||||
```json
|
||||
{
|
||||
"@babel/runtime": "7.29.7",
|
||||
"@codemirror/autocomplete": "6.20.3",
|
||||
"@codemirror/commands": "6.10.3",
|
||||
"@codemirror/lang-css": "6.3.1",
|
||||
"@codemirror/lang-html": "6.4.11",
|
||||
"@codemirror/lang-javascript": "6.2.5",
|
||||
"@codemirror/language": "6.12.3",
|
||||
"@codemirror/state": "6.6.0",
|
||||
"@codemirror/view": "6.43.1",
|
||||
"@uiw/codemirror-theme-solarized": "4.25.10",
|
||||
"esbuild": "0.28.0"
|
||||
}
|
||||
```
|
||||
|
||||
### Что обновилось
|
||||
- `@babel/runtime` 7.29.2 → 7.29.7
|
||||
- `@codemirror/autocomplete` 6.20.1 → 6.20.3
|
||||
- `@codemirror/view` 6.41.0 → 6.43.1
|
||||
- `@uiw/codemirror-theme-solarized` 4.25.9 → 4.25.10
|
||||
|
||||
## О package-lock.json
|
||||
|
||||
**НИКОГДА не удаляй `package-lock.json` из репозитория!**
|
||||
|
||||
### Почему package-lock.json важен
|
||||
|
||||
1. **Воспроизводимость** - гарантирует одинаковые версии пакетов на всех машинах
|
||||
2. **Скрипт сборки использует `npm ci`** - это команда для CI/CD, работает с package-lock.json
|
||||
3. **Безопасность** - lockfile содержит хеши пакетов, которые проверяются при установке
|
||||
|
||||
### Правильный workflow обновления
|
||||
|
||||
```bash
|
||||
# 1. Обновляешь версии в package.json
|
||||
# 2. Удаляешь node_modules (опционально, можешь оставить)
|
||||
# 3. Запускаешь:
|
||||
npm install
|
||||
|
||||
# 4. npm автоматически обновит package-lock.json
|
||||
# 5. Коммитишь обновленные package.json и package-lock.json в гит
|
||||
```
|
||||
|
||||
## Как собрать CodeMirror
|
||||
|
||||
### Один раз (после обновления версий пакетов)
|
||||
|
||||
```bash
|
||||
# Обновляешь версии в frontend-assembly/package.json
|
||||
# Затем запускаешь сборку:
|
||||
bash ./frontend-assembly/build-codemirror6.sh
|
||||
```
|
||||
|
||||
### Что делает скрипт
|
||||
|
||||
1. Создает временную рабочую папку
|
||||
2. Копирует `package.json` и `package-lock.json` туда
|
||||
3. Генерирует файл `src/editor.js` с интеграцией CodeMirror 6
|
||||
4. Запускает `npm ci` для установки точно таких же версий
|
||||
5. Запускает `npm run build` для минификации через esbuild
|
||||
6. Копирует результат в `public/static/codemirror/editor.js`
|
||||
7. Удаляет временные файлы и папки
|
||||
|
||||
### Размеры
|
||||
- Минифицированный бандл: **427 KB** (js файл)
|
||||
- После GZIP: ~**130 KB** (в половине случаев браузер будет получать сжатый файл)
|
||||
|
||||
## Как использовать CodeMirror в Django Admin
|
||||
|
||||
### 1. Подключи скрипт в template админки
|
||||
|
||||
Добавь в `lpon_site/templates/admin/base_site.html` (или создай этот файл):
|
||||
|
||||
```html
|
||||
{% extends "admin/base_site.html" %}
|
||||
|
||||
{% block extrahead %}
|
||||
{{ block.super }}
|
||||
<link rel="stylesheet" href="{% static 'codemirror/editor.css' %}">
|
||||
<script type="module" src="{% static 'codemirror/editor.js' %}"></script>
|
||||
<style>
|
||||
/* Стили для обертки CodeMirror */
|
||||
.cm6-editor-wrapper {
|
||||
height: 400px;
|
||||
border: 1px solid #ccc;
|
||||
border-radius: 4px;
|
||||
margin-bottom: 20px;
|
||||
font-size: 14px;
|
||||
}
|
||||
|
||||
.cm-editor {
|
||||
height: 100% !important;
|
||||
font-family: 'Menlo', 'Monaco', 'Courier New', monospace;
|
||||
}
|
||||
</style>
|
||||
{% endblock %}
|
||||
```
|
||||
|
||||
### 2. Используй в ModelForm
|
||||
|
||||
В `frontend/admin.py` для текстовых полей используй виджет с `data-codemirror-editor`:
|
||||
|
||||
```python
|
||||
from django import forms
|
||||
|
||||
class ArticleForm(forms.ModelForm):
|
||||
"""Форма для статей с CodeMirror"""
|
||||
|
||||
class Meta:
|
||||
model = TbArticle
|
||||
fields = '__all__'
|
||||
widgets = {
|
||||
's_article_teaser_html': forms.Textarea(attrs={
|
||||
'data-codemirror-editor': 'true',
|
||||
'data-language': 'html',
|
||||
'class': 'vLargeTextField',
|
||||
}),
|
||||
's_article_content_html': forms.Textarea(attrs={
|
||||
'data-codemirror-editor': 'true',
|
||||
'data-language': 'html',
|
||||
'class': 'vLargeTextField',
|
||||
}),
|
||||
}
|
||||
|
||||
class ArticleAdmin(admin.ModelAdmin):
|
||||
form = ArticleForm
|
||||
# ... остальная конфигурация
|
||||
```
|
||||
|
||||
### 3. Поддерживаемые языки
|
||||
|
||||
CodeMirror автоматически определяет язык по атрибуту `data-language`:
|
||||
|
||||
- `html` (по умолчанию) - HTML/Vue/Svelte шаблоны
|
||||
- `javascript` - JavaScript/TypeScript код
|
||||
- `css` - CSS стили
|
||||
|
||||
Пример:
|
||||
```html
|
||||
<textarea data-codemirror-editor data-language="javascript">
|
||||
let x = 42;
|
||||
console.log(x);
|
||||
</textarea>
|
||||
```
|
||||
|
||||
## Фишки CodeMirror 6
|
||||
|
||||
### Подсветка синтаксиса
|
||||
- HTML / CSS / JavaScript с красивой подсветкой
|
||||
- Тема Solarized (dark/light) автоматически определяется по теме админки
|
||||
|
||||
### Возможности
|
||||
- :leftwards_arrow_with_hook: Undo/Redo
|
||||
- :mag: Find and Replace (Ctrl+H / Cmd+Ctrl+H)
|
||||
- :keyboard: Автодополнение (Ctrl+Space)
|
||||
- :arrow_right: Автоотступы
|
||||
- :straight_ruler: Нумерация строк
|
||||
- :paperclip: Перенос слов на новую строку
|
||||
|
||||
### Синхронизация
|
||||
Все изменения в CodeMirror:
|
||||
1. Живо синхронизируются в скрытое текстовое поле
|
||||
2. При сохранении формы отправляются на сервер
|
||||
|
||||
## Проверка работы
|
||||
|
||||
1. Откройся на http://localhost:8000/admin/
|
||||
2. Перейди в раздел "Статьи" (или другой с HTML полями)
|
||||
3. Создай или отредактируй статью
|
||||
4. В полях с HTML кодом должен появиться CodeMirror с подсветкой синтаксиса
|
||||
|
||||
Вместо обычного текстового поля должен быть редактор с:
|
||||
- Нумерацией строк слева
|
||||
- Подсветкой синтаксиса (теги, атрибуты, значения...)
|
||||
- Темой Solarized (light или dark)
|
||||
|
||||
## Обновление CodeMirror в будущем
|
||||
|
||||
Когда выйдут новые версии пакетов:
|
||||
|
||||
```bash
|
||||
# 1. Проверь обновления
|
||||
cd frontend-assembly
|
||||
npm outdated
|
||||
|
||||
# 2. При необходимости обнови версии в package.json вручную
|
||||
# Или используй npm update (осторожнее, может нарушить совместимость)
|
||||
|
||||
# 3. Пересоздай package-lock.json
|
||||
rm package-lock.json
|
||||
npm install
|
||||
|
||||
# 4. Собери новый бандл
|
||||
bash build-codemirror6.sh
|
||||
|
||||
# 5. Коммит обновов (если через гит)
|
||||
git add package.json package-lock.json ../public/static/codemirror/editor.js
|
||||
git commit -m "Update CodeMirror 6 and dependencies"
|
||||
```
|
||||
|
||||
## Возможные ошибки и решения
|
||||
|
||||
### Ошибка: "npm: command not found"
|
||||
```bash
|
||||
# Установи Node.js
|
||||
brew install node
|
||||
```
|
||||
|
||||
### Ошибка: "не найден package-lock.json"
|
||||
```bash
|
||||
# Пересоздай его
|
||||
cd frontend-assembly
|
||||
npm install
|
||||
bash build-codemirror6.sh
|
||||
```
|
||||
|
||||
### CodeMirror не появляется в админке
|
||||
1. Проверь, что `public/static/codemirror/editor.js` существует
|
||||
2. Проверь, что `static/` папка будет скопирована при deploy
|
||||
3. Запусти `python manage.py collectstatic` если используешь Django collectstatic
|
||||
|
||||
### Медленная загрузка админки
|
||||
CodeMirror бандл ~427 KB - это нормально. Он:
|
||||
- :white_check_mark: кэшируется браузером
|
||||
- :white_check_mark: отправляется в GZIP (~130 KB)
|
||||
- :white_check_mark: загружается асинхронно
|
||||
|
||||
Если всё еще медленно, можно:
|
||||
1. Использовать CDN (например, jsDelivr)
|
||||
2. Лениво загружать CodeMirror только на нужных страницах
|
||||
|
||||
## Файлы конфигурации
|
||||
|
||||
### frontend-assembly/package.json
|
||||
Главный файл для управления версиями. Обновляй здесь версии пакетов.
|
||||
|
||||
### frontend-assembly/package-lock.json
|
||||
**Не трогай вручную!** Обновляется автоматически через `npm install`.
|
||||
|
||||
### frontend-assembly/build-codemirror6.sh
|
||||
Скрипт сборки. Не требует изменений если только не нужна другая сборка.
|
||||
|
||||
### public/static/codemirror/
|
||||
**Не редактируй вручную!** Пересоздается каждый раз при запуске `build-codemirror6.sh`.
|
||||
|
||||
## Дополнительное чтение
|
||||
|
||||
- [CodeMirror 6 документация](https://codemirror.net/docs/guide/)
|
||||
- [Доступные расширения](https://codemirror.net/docs/ref/)
|
||||
- [Solarized тема](https://github.com/uiwjs/codemirror-theme-solarized)
|
||||
|
||||
Reference in New Issue
Block a user