Декодирование хешей

Декодер это малая половина библиотеки (около 2,6 КБ gzip) и единственная часть, которая нужна браузеру, чтобы показывать плейсхолдеры. Его функции экспортируются из hazehash и из hazehash/decode, это один и тот же модуль. Их импорт никогда не подтягивает энкодер.

import { decode, getAspectRatio, getAverageColor, toBytes } from 'hazehash'

Хеш принимается как строка base64url или как сырой Uint8Array его байт. Недопустимый хеш никогда не вешает и не роняет декодер: вызов либо возвращает результат, либо бросает PlaceholderError. Обрезанный хеш допустим и декодируется с меньшей детализацией.

Декодирование в пиксели

decode(hash, options?)

RgbaImage

Восстанавливает размытое превью в виде RGBA-пикселей. У результата то соотношение сторон, которое хранится в хеше, а длинная сторона задаётся size, по умолчанию 32 пикселя, так что хеш фото 1280×959 даёт превью 32×25. Пиксели в sRGB с прямым (не premultiplied) альфа-каналом, а хеш без альфы даёт полностью непрозрачные пиксели. Операция занимает около 0,3 мс.

import { decode } from 'hazehash'

const { width, height, data } = decode('Ed7UwRWKKv5znm6a7sC1tziHDNpMuCikxrYpIg')
// width: 32, height: 25, data: Uint8ClampedArray из 3200 байт

Возвращаемый RgbaImage это { data: Uint8ClampedArray; width: number; height: number }, так что его можно сразу передать в new ImageData(data, width, height). Чтобы рисовать прямо в canvas, см. Рисование в canvas.

hash

string | Uint8Array

Хеш для декодирования.

options

DecodeOptions · необязательно

См. Опции декодера ниже.

Чтение соотношения сторон

getAspectRatio(hash)

number

Ширина, делённая на высоту, которую хранит хеш, числом вроде 1.2968 для изображения 13:10. Функция читает только заголовок, поэтому её достаточно дёшево вызывать при каждом рендере, и именно это число стоит использовать для aspect-ratio, пока настоящая картинка не загрузилась. Соотношение хранится с разрешением около 9%, так что для вёрстки страницы берите настоящие размеры изображения, если они у вас есть.

import { getAspectRatio } from 'hazehash'

getAspectRatio('Ed7UwRWKKv5znm6a7sC1tziHDNpMuCikxrYpIg') // 1.2968395546510096

Чтение среднего цвета

getAverageColor(hash)

{ r: number; g: number; b: number; a: number }

Средний цвет изображения, прочитанный только из заголовка. r, g и b это целые числа от 0 до 255 в sRGB, а a это средняя непрозрачность от 0 до 1, всегда 1 для хеша без альфы. Используйте его как background-color рамки, пока превью не нарисовано.

import { getAverageColor } from 'hazehash'

getAverageColor('Ed7UwRWKKv5znm6a7sC1tziHDNpMuCikxrYpIg')
// { r: 152, g: 142, b: 126, a: 1 }

Преобразование строки в байты

toBytes(base64url)

Uint8Array

Превращает строку base64url хеша в его байты, форму для бинарной колонки. Обратная функция, toBase64Url(), находится в hazehash/encode. Строка недопустимой длины бросает InvalidLength, а символ вне алфавита base64url бросает InvalidCharacter.

import { toBytes } from 'hazehash'

toBytes('Ed7UwRWKKv5znm6a7sC1tziHDNpMuCikxrYpIg').length // 28

Опции декодера

size

number · по умолчанию: 32

Длинная сторона декодированного превью в пикселях. Значение округляется и ограничивается диапазоном 4–128, а короткая сторона следует из соотношения сторон. Более крупное превью стоит больше времени и ничего не добавляет, ведь в хеше несколько десятков коэффициентов, поэтому значение по умолчанию подходит для размытого фона.

dither

boolean · по умолчанию: true

Применяет детерминированный дизеринг при переводе превью в 8-битный цвет, что скрывает полосы, которые иначе видны на плавных градиентах. Узор зависит только от позиции пикселя, поэтому один и тот же хеш всегда даёт одни и те же пиксели. false даёт обычное округление.

Пример:

const larger = decode(hash, { size: 64, dither: false })