Тег canvas (от английского canvas, «холст») создаёт на странице прямоугольную область, на которой рисуют скриптом: фигуры, текст, картинки, графики, игры. Сам по себе тег ничего не показывает: новый холст полностью прозрачен, и под ним виден фон страницы, пока JavaScript не нарисует что-нибудь через контекст холста.
Дальше разобраны принцип работы, атрибуты, размер, рисование, метод getContext, запасное содержимое, сохранение в картинку, события мыши, сравнение с svg и img и причины, по которым холст остаётся пустым. Другие теги группы собраны в шпаргалке по тегам.
<canvas id="c" width="200" height="100"></canvas>
<script>
const ctx = document.getElementById("c").getContext("2d");
ctx.fillRect(10, 10, 80, 50);
</script>
В этой статье
- Тег canvas в HTML: что это и для чего нужен
- Как работает тег canvas: холст и контекст
- Атрибуты тега canvas: width, height и общие атрибуты
- Размер тега canvas: атрибуты, CSS и растяжение
- Использование тега canvas: рисование фигур, текста и картинок
- Метод getContext тега canvas: 2d, webgl и другие контексты
- Запасное содержимое тега canvas: когда оно нужно
- Тег canvas в картинку: toDataURL, toBlob и защита от чужих данных
- События мыши и анимация на теге canvas
- Тег canvas, svg или img: чем отличаются
- Почему тег canvas не работает
Тег canvas в HTML: что это и для чего нужен
Сначала о том, для чего нужен canvas и чем он отличается от обычных тегов.
Большинство тегов описывают содержимое разметкой: заголовок, абзац, картинку. Тег canvas устроен иначе: это пустая растровая область, и всё, что на ней видно, нарисовано скриптом. Поэтому его используют там, где разметкой не обойтись: для графиков и диаграмм, игр, редакторов рисунков, обработки фотографий, анимации и визуальных эффектов.
Закрывающий тег нужен всегда: между <canvas> и </canvas> записывают запасное содержимое. Рамки у тега нет. Размер без атрибутов — 300 на 150 пикселей, тег строчный.
Готовые картинки на странице показывают тегом img, а не холстом: canvas нужен, когда изображение строится на лету.
Как работает тег canvas: холст и контекст
Работа с холстом всегда идёт в три шага: найти элемент, получить контекст и вызвать методы рисования.
Холст хранит сетку цветных пикселей, как растровая картинка. Рисовать на нём напрямую нельзя: для этого используют объект контекст, который даёт метод getContext. У контекста есть методы для прямоугольников, линий, дуг, текста и картинок. Начало координат находится в левом верхнем углу, ось x идёт вправо, ось y вниз.
const canvas = document.getElementById("c");
const ctx = canvas.getContext("2d");
ctx.fillStyle = "#4A90D9";
ctx.fillRect(10, 10, 80, 50);
Важное следствие: после рисования браузер помнит только цвета пикселей, а не фигуры. Нарисованный прямоугольник нельзя «подвинуть» как элемент страницы: холст очищают и рисуют заново. Если скрипт выполняется раньше, чем в разметке появился тег, холст не будет найден, поэтому скрипт записывают после тега или запускают по событию DOMContentLoaded.
Атрибуты тега canvas: width, height и общие атрибуты
Собственных атрибутов у canvas всего два — width и height, остальные общие для всех тегов.
| Атрибут | Что делает | Пример |
|---|---|---|
width | Ширина холста в пикселях. По умолчанию 300 | width="200" |
height | Высота холста в пикселях. По умолчанию 150 | height="100" |
id | Название для поиска холста из скрипта | id="c" |
class и style | Оформление холста: рамка, фон, размер на экране | style="border:1px solid" |
Устарел, был только у браузера Firefox. Вместо него записывают getContext("2d", {alpha: false}) | Не используют |
В значениях width и height записывают целое число без единиц. Другие записи ведут себя необычно. Значение "200px" даёт 200, а 200.7 даёт 200. Запись "50%" проценты не включает, а даёт 50 пикселей. Неверные значения (abc или -5) отбрасываются, и холст получает размер по умолчанию 300 на 150. Если записан только width, высота остаётся 150.
Атрибутов src и alt у холста нет: картинки на него рисуют методом drawImage, а текстовую замену пишут внутри тега.
Размер тега canvas: атрибуты, CSS и растяжение
У холста два размера: размер сетки пикселей из атрибутов и размер на экране, который задаёт CSS.
Атрибуты width и height задают, сколько пикселей в холсте. Стили width и height в CSS задают, какое место холст занимает на странице. Если размеры разные, браузер растягивает или сжимает готовую картинку. Холст 200 на 100 при width: 300px занимает 300 на 150: пропорции сохранились, а рисунок стал мягким, как увеличенная фотография. Если задан только один размер в CSS, второй считается по пропорциям холста. Если заданы оба, рисунок искажается.
Чтобы рисунок был чётким, размеры холста делают равными размеру на экране. Для экранов с высокой плотностью пикселей холст делают больше, чем нужно на экране, а в CSS записывают меньший размер. Последняя кнопка примера показывает такой случай: холст 400 на 200 выведен как 200 на 100.
const k = window.devicePixelRatio;
canvas.width = 200 * k;
canvas.height = 100 * k;
canvas.style.width = "200px";
canvas.style.height = "100px";
ctx.scale(k, k);
Пример: размер и CSS тега canvas
Кнопки задают размер холста атрибутами и стилями. Строки показывают размер на экране и размер холста. При разных размерах рисунок растянут или искажён, а холст вдвое больше экранного размера остаётся чётким.
Есть правило, о которое спотыкаются: запись в width или height очищает холст, даже если значение прежнее. То же делает setAttribute("width", ...). Изменение размера в CSS холст не очищает. Этим пользуются для сброса: canvas.width = canvas.width, но чаще очищают методом clearRect.
Тег строчный, поэтому под холстом остаётся зазор в несколько пикселей, как у картинки. Его убирает display: block.
canvas {
display: block;
max-width: 100%;
}
Использование тега canvas: рисование фигур, текста и картинок
Рисовать можно фигурами, линиями, текстом, градиентами и готовыми картинками, и всё это методы контекста.
| Метод | Что рисует | Пример |
|---|---|---|
fillRect | Закрашенный прямоугольник | fillRect(10, 10, 80, 50) |
clearRect | Стирает прямоугольник | clearRect(0, 0, 200, 100) |
moveTo и lineTo | Путь из линий, который затем обводят методом stroke | lineTo(80, 15) |
arc | Дугу или круг, который затем закрашивают методом fill | arc(85, 55, 16, 0, 6.28) |
fillText | Текст. Шрифт задаёт свойство font | fillText("Привет", 10, 50) |
createLinearGradient | Градиент для заливки | createLinearGradient(0, 0, 170, 0) |
drawImage | Картинку, другой холст или кадр видео | drawImage(img, 10, 10) |
Текст на холсте остаётся пикселями: его нельзя выделить мышью и найти поиском по странице. Картинку методом drawImage рисуют только после её загрузки: если вызвать метод раньше, холст остаётся прозрачным. Метод принимает и тег video: на холст попадает текущий кадр ролика.
const img = new Image();
img.onload = () => ctx.drawImage(img, 10, 10);
img.src = "photo.png";
Пример: использование тега canvas для рисования
Каждая кнопка рисует на новом холсте 170 на 85 одним методом. Строка «Вызов» показывает, какой метод сработал. Картинка и холст на холсте нарисованы тем же drawImage.
Метод getContext тега canvas: 2d, webgl и другие контексты
Метод getContext возвращает контекст нужного типа, но на одном холсте можно получить только один тип.
Чаще всего записывают "2d": это плоское рисование из примеров выше. Для трёхмерной графики есть "webgl" и "webgl2", а ещё "bitmaprenderer" и "webgpu". Повторный вызов с тем же типом возвращает тот же объект. Вызов с другим типом после первого возвращает null: так ведут себя webgl и bitmaprenderer после 2d. В обратном порядке тоже: 2d после webgl возвращает null. Неизвестный тип тоже даёт null.
Пример: метод getContext тега canvas
Каждая кнопка вызывает getContext на новом холсте. Строки показывают порядок вызовов и результат: тот же объект или null.
const gl = canvas.getContext("webgl");
if (!gl) {
console.log("WebGL недоступен");
}
Результат всегда проверяют на null: контекст может быть недоступен, и тогда вызов его методов приведёт к ошибке.
Запасное содержимое тега canvas: когда оно нужно
Запасное содержимое записывают между тегами canvas, и оно нужно, когда скрипт не выполнился.
Всё, что записано внутри <canvas>, браузер скрывает: при включённых скриптах это содержимое занимает 0 на 0 пикселей. Если скрипты отключены, оно показано на странице. Холст сам не несёт смысла: это набор пикселей, поэтому запасное содержимое должно передавать то же, что нарисовано. Спецификация рекомендует именно это.
<canvas id="chart" width="300" height="150">
<p>Продажи по месяцам: январь 12, февраль 18, март 25.</p>
</canvas>
Ссылки и кнопки внутри запасного содержимого остаются доступными с клавиатуры: клавиша Tab переходит на них, хотя на экране они не видны. На этом строят управление холстом без мыши. Если интерактивных элементов нет, содержимое достаточно сделать текстом или таблицей данных.
Тег canvas в картинку: toDataURL, toBlob и защита от чужих данных
Из холста можно получить картинку методами toDataURL и toBlob, но чужие данные на холсте это запрещают.
Метод toDataURL возвращает адрес вида data:image/png;base64,.... Формат по умолчанию PNG, другой задаёт первый аргумент, а качество JPEG второй. Для image/webp возвращается картинка WebP, а неизвестный формат вроде image/gif заменяется на PNG. Для холста 0 на 0 результат равен data:,. Метод toBlob работает асинхронно и передаёт в функцию объект Blob.
Пример: тег canvas в картинку, toDataURL и toBlob
Кнопки сохраняют холст 170 на 85 в картинку. Строки показывают формат и размер результата, а под холстом выведена полученная картинка. Холст 0 на 0 даёт пустую строку data:,.
const link = document.createElement("a");
link.href = canvas.toDataURL("image/png");
link.download = "canvas.png";
link.click();
Защита от утечки данных работает так. Если на холст нарисована картинка с чужого сайта, холст считается «грязным», и методы toDataURL, toBlob и getImageData вызывают ошибку SecurityError.
| Картинка на холсте | Результат методов |
|---|---|
| С того же сайта | Работают |
Адрес data: | Работают |
С чужого сайта без crossorigin | Ошибка SecurityError |
С чужого сайта с crossorigin="anonymous", сервер присылает Access-Control-Allow-Origin | Работают |
С чужого сайта с crossorigin="anonymous", сервер заголовок не присылает | Картинка не загружается |
События мыши и анимация на теге canvas
События мыши приходят на весь холст, а не на нарисованные фигуры, поэтому координаты пересчитывают вручную.
Холст остаётся одним элементом: на нём работают click, mousemove и другие события, но «клик по кругу» браузер не различает. Свойства offsetX и offsetY дают точку клика в пикселях страницы от левого верхнего угла холста, рамка в отсчёт не входит. Если холст растянут в CSS, эти числа не совпадают с пикселями холста, и точку пересчитывают: умножают на отношение размера холста к размеру на экране.
canvas.onclick = (e) => {
const r = canvas.getBoundingClientRect();
const x = e.offsetX * canvas.width / r.width;
const y = e.offsetY * canvas.height / r.height;
ctx.fillRect(x, y, 4, 4);
};
Пример: координаты мыши на теге canvas
Холст 200 на 100 выведен размером 150 на 75. Кликните по холсту при обеих кнопках: без пересчёта точка рисуется не под указателем, с пересчётом точно под ним.
Анимацию строят так: в каждом кадре холст очищают и рисуют сцену заново. Вызов requestAnimationFrame просит браузер запустить функцию перед следующей отрисовкой экрана, а cancelAnimationFrame останавливает цикл.
let x = 0;
function frame() {
ctx.clearRect(0, 0, canvas.width, canvas.height);
ctx.fillRect(x, 20, 30, 30);
x = (x + 2) % canvas.width;
requestAnimationFrame(frame);
}
frame();
Тег canvas, svg или img: чем отличаются
Холст, svg и img показывают графику, но по-разному хранят и масштабируют рисунок.
| Свойство | canvas | svg | img |
|---|---|---|---|
| Что это | Пиксели, нарисованные скриптом | Разметка из фигур | Готовый файл |
| Масштаб | Растягивается как растр, рисунок мягчеет | Без потерь | Растр мягчеет, SVG-файл без потерь |
| Отдельные фигуры | Нет, остаются только пиксели | Есть, у каждой фигуры свои события | Нет |
| Запасной вариант | Содержимое внутри тега | Текст внутри разметки | Атрибут alt |
| Сохранение в файл | toDataURL и toBlob | Файл с разметкой | Уже файл |
Выбор такой. Для готовых картинок берут img, для логотипов, иконок и схем с событиями на фигурах берут svg, а для графики, которая строится на лету, игр, обработки фотографий и анимации с множеством мелких деталей берут canvas.
Почему тег canvas не работает
Если холст остаётся пустым или ведёт себя неожиданно, причину ищут в порядке выполнения скрипта, размере и контексте.
| Причина | Что видно | Что делать |
|---|---|---|
| Скрипт выполнился раньше, чем появился тег | Холст не найден, ошибка в консоли | Записать скрипт после тега или запускать по DOMContentLoaded |
| Рисунок совпадает по цвету с фоном или находится вне холста | Холст прозрачен, ничего не видно | Проверить fillStyle и координаты |
| Картинку рисуют до загрузки | Холст остаётся прозрачным | Вызывать drawImage в onload |
| Размер задан только в CSS | Рисунок растянут и размыт | Задать width и height атрибутами |
| Размер холста меняют из скрипта | Рисунок исчезает | Рисовать после смены размера |
| Первым получен другой контекст | getContext возвращает null | Использовать один тип контекста на холсте |
| На холсте чужая картинка | Ошибка SecurityError у toDataURL | Добавить crossorigin и разрешить на сервере |
| Холст растянут в CSS | Клик попадает не в ту точку | Пересчитывать координаты |
| Скрипты отключены | Холст пуст, виден только запасной текст | Записать полезное запасное содержимое |
Частые ошибки с тегом canvas
Основные ошибки связаны с размером, незакрытым тегом, чужими картинками и ожиданием, что фигуры остаются объектами.
| Ошибка | Что происходит | Как исправить |
|---|---|---|
<canvas style="width:400px"> | Размер холста остаётся 300 на 150, рисунок растянут | Записать width и height атрибутами |
<canvas width="50%"> | Проценты не работают: холст получает 50 пикселей | Задать пиксели в атрибуте, процент в CSS |
<canvas /> | Слэш тег не закрывает: все следующие элементы оказываются внутри холста и скрыты | Записать </canvas> |
ctx.drawImage(img, 0, 0) | Картинка не загружена, ничего не нарисовано | Вызвать в img.onload |
canvas.width = 300 | Холст очищается | Менять размер до рисования |
canvas.getContext("webgl") | После 2d возвращает null | Выбрать один тип контекста |
Чужая картинка и toDataURL | Ошибка SecurityError | Добавить crossorigin и заголовок на сервере |
| Клик по растянутому холсту без пересчёта | Точка рисуется не под указателем | Умножить на отношение размеров |
| Ожидание, что фигуры остаются объектами | Остаются только пиксели, переместить фигуру нельзя | Очищать и рисовать заново или взять svg |
| Нет запасного содержимого | При выключенных скриптах пусто | Записать текст или таблицу внутри тега |