API, хуки и возможности

В этом разделе описаны официальные сущности, с которыми можно писать код виджета.

1) useParams — вход в параметры

useParams объявляется ровно один раз в Widget():

const { width, title, theme, recalcBtn } = useParams({
  width: { type: "float", default: 300 },
  title: { type: "string", default: "Мой виджет" },
  theme: { type: "colorGradient", default: "#0077ff" },
  recalcBtn: {
    type: "button",
    title: "Перегенерировать",
    default: 0,
    onClick: (prev) => (prev ?? 0) + 1,
  },
});

Поля параметра

Поддерживаемые поля дескриптора параметра:

Типы параметров

Текущий runtime поддерживает: anchor, boolean, button, color, colorGradient, corners, euler, float, font, gradient, image, imageComponent, integer, json, media, object, object_ref, paddings, position, script, select, shadow, string, table, text, texture, transform3d, vector2, vector3.

Привязка к хранилищу блока

Имена параметров обычно автоматически маппятся в ключи вида имя_param, кроме базовых нативных (width, height, style и др.):

• у параметра text в блоке хранится text_param;
• для специальных/наследуемых полей может использоваться явный v1ParamName.

Также есть список параметров, которые не получают суффикс _param в схеме widgetParamNames (height, width, style, viewBoxWidth, viewBoxHeight, svgPathData, mediaType).

2) useBlockMemo — мемоизация внутри виджета

const {path, pWidth, pHeight} = useBlockMemo("shape", () => {
  // тяжёлые вычисления
  return { path, pWidth, pHeight };
}, [width, radius, recalcBtn]);

useBlockMemo стабильно пересчитывает значение только если изменился ключ зависимостей.

Рекомендации

• Все входные данные, влияющие на результат, должны быть в массиве зависимостей;
• Для тяжёлых расчётов всегда используйте useBlockMemo, чтобы избежать лишних проходов рендера.

3) useControlPoints и контрольные точки фигуры

const controlPoints = useControlPoints();

Возвращает объект контрольных точек с координатами в пикселях относительно текущего блока: ключами являются идентификаторы точек (например, start, end, p0, p1).

4) useStableId — стабильные идентификаторы для SVG defs

const gradId = useStableId("grad");

Ид пригоден для <defs>/url(#id)-ссылок внутри одного блока.

5) Что входит в runtime-сет возможностей

Вычисления в виджете — это не весь JS, а только разрешённый набор функций и тегов.

Безопасные функции (capabilities)

FONTS_BASE_URI, IMAGES_BASE_URI, MEDIA_BASE_URI, Infinity, NaN, PI,
abs, addVec2, arrayToCssStr, clamp, cos, createPolyPath, createSmoothPath,
debug, exp, floor, generateBlobPoints, generatePolyLinePoints, generateWaves,
getDerivativeAt, getNormalAt, getPointAt, getSvgPathBbox, isGradient, isNaN,
join, lerp, log, map, max, min, mulVec2Scalar, outlineStrokePath, pointToStr,
pow, random, round, roundCorners, scalePoint, sin, sqrt, subVec2, substr,
textToPath, textToPathAlongSVGPath, toPx, unionPaths,
useBlockMemo, useControlPoints, useParams, useStableId

Доступные JSX-теги

a, circle, contentimage, defs, div, ellipse, externalvideo, feComponentTransfer, feComposite, feDisplacementMap, feFuncB, feFuncG, feFuncR, feGaussianBlur, fePointLight, feSpecularLighting, feTurbulence, filter, foreignObject, g, line, lottie, marker, mask, path, polygon, polyline, rect, richeditor, span, svg, text, video.

Доступные JSX-атрибуты (основной набор)

amplitude, autoPlay, baseFrequency, cx, cy, d, editable, exponent, exposecontext, fill, fillOpacity, filterUnits, height, href, id, in, in2, k1, k2, k3, k4, key, loop, lightingColor, markerEnd, markerHeight, markerUnits, markerWidth, mask, muted, name, numOctaves, offset, operator, orient, overflow, points, poster, preserveAspectRatio, provider, r, refX, refY, result, rx, ry, scale, seed, specularConstant, specularExponent, src, staticimage, stdDeviation, stroke, strokeDasharray, strokeLinecap, strokeMiterlimit, strokeWidth, style, surfaceScale, transform, type, v1ParamName, vectorEffect, version, viewBox, width, x, x1, x2, xChannelSelector, xmlns, y, y1, y2, yChannelSelector, z.

Разрешённые CSS-свойства в style

WebkitBackgroundClip, WebkitTextStrokeColor, WebkitTextStrokeWidth, backdropFilter, backgroundClip, backgroundColor, backgroundImage, backgroundPosition, backgroundRepeat, backgroundSize, borderColor, borderRadius, borderStyle, borderWidth, boxShadow, color, cursor, display, filter, fontFamily, fontFeatureSettings, fontSize, fontVariationSettings, fontWeight, height, isolation, left, letterSpacing, lineHeight, objectFit, objectPosition, overflow, padding, position, scale, textAlign, textIndent, textOrientation, top, transform, width, wordSpacing, writingMode, zIndex.

6) Редактируемый текст

Для inline-редактирования используется специальный атрибут:

<div editable="text">...</div>

Также поддерживается v1ParamName="..." для обратной совместимости старых проектов.

div с editable рендерится в редакторе как EditableDiv, который пишет результат в параметр с указанным именем.