umbot
Version:
Мультиплатформенный фреймворк для создания голосовых навыков и чат-ботов с единой бизнес-логикой. Встроенная поддержка ВКонтакте, Telegram, Viber, MAX, Яндекс Алисы, Маруси и Сбера SmartApp. Архитектура на адаптерах позволяет подключать любые другие платф
276 lines (275 loc) • 11.1 kB
JavaScript
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.Card = void 0;
const button_1 = require("../button");
const Image_1 = require("../image/Image");
/**
* @class Card
* Класс для создания и управления карточками на различных платформах.
*
* Класс предоставляет функциональность для:
* - Создания карточек с изображениями, заголовками и описаниями
* - Добавления кнопок к карточкам
* - Адаптации карточек под различные платформы
* - Поддержки галерей изображений
*
* Ограничения платформ обрабатываются самими адаптерами
*/
class Card {
/**
* Заголовок элемента карточки.
* Отображается в верхней части карточки.
* @example
* ```ts
* card.setTitle('Название товара');
* ```
*/
title;
/**
* Описание элемента карточки.
* Отображается под заголовком.
* @example
* ```ts
* card.setDescription('Подробное описание товара');
* ```
*/
desc;
/**
* Массив с изображениями или элементами карточки.
* Каждый элемент может содержать изображение, заголовок, описание и кнопки.
* @see IImageType
* @example
* ```ts
* card.addImage('product.jpg', 'Название товара', 'Описание товара');
* ```
*/
images;
/**
* Кнопки элемента карточки.
* Используются для взаимодействия с пользователем.
* @see Buttons
* @example
* ```ts
* card.addButton('Купить');
* card.addButton({
* title: 'Подробнее',
* url: 'http://localhost'
* });
* ```
*/
button;
/**
* Определяет необходимость отображения только одного элемента карточки.
* true - отображается только первый элемент
* false - отображаются все элементы
* @example
* ```ts
* card.isOne = true; // Отобразить только первый элемент
* ```
*/
isOne;
/**
* Использование галереи изображений.
* true - изображения отображаются в виде галереи
* false - изображения отображаются как отдельные карточки
* @example
* ```ts
* card.isUsedGallery = true; // Включить режим галереи
* ```
*/
isUsedGallery = false;
/**
* Произвольный шаблон для отображения карточки.
* Используется для кастомизации отображения на определенных платформах.
* ⚠️ ОПАСНО: Использование этого свойства полностью обходит адаптеры платформ.
* Данные отправляются платформе «как есть» без преобразования в её формат.
*
* Последствия:
* - Карточка может не отобразиться на других платформах
* - Нарушается кроссплатформенность фреймворка
* - Ответственность за корректность формата лежит на разработчике
*
* Используйте ТОЛЬКО если:
* - Вы точно знаете формат ответа целевой платформы
* - Стандартные методы (`addImage()`, `addButton()`) не решают задачу
* @example
* ```ts
* card.template = {
* type: 'custom_card',
* content: { ... }
* };
* ```
*/
template = null;
/**
* Контекст приложения
*/
#appContext;
/**
* Карточка с изображениями, заголовком и кнопками.
*
* Предоставляет унифицированный интерфейс для описания контента.
* Фактическая адаптация под формат целевой платформы происходит
* в адаптере платформы при вызове метода `getCards()`.
* @param appContext Контекст приложения
* ⚠️ Обычно НЕ создаётся вручную — автоматически передаётся через контроллер:
* ```ts
* // Правильно — через контроллер:
* this.card.addImage('token', 'Title');
*
* // НЕ рекомендуется — ручное создание:
* new Card(this.appContext); // appContext берётся из контроллера
* ```
*/
constructor(appContext) {
this.isOne = false;
this.button = new button_1.Buttons(appContext);
this.images = [];
this.title = null;
this.desc = null;
this.#appContext = appContext;
this.clear();
}
/**
* Устанавливает контекст приложения.
* @param appContext
*/
setAppContext(appContext) {
this.#appContext = appContext;
this.button.setAppContext(appContext);
return this;
}
/**
* Устанавливает заголовок для карточки.
* @param {string} title - Заголовок карточки
* @returns {Card}
* @example
* ```ts
* card.setTitle('Название товара');
* ```
*/
setTitle(title) {
this.title = title;
return this;
}
/**
* Устанавливает описание для карточки.
* @param {string} description - Описание карточки
* @returns {Card}
* @example
* ```ts
* card.setDescription('Подробное описание товара');
* ```
*/
setDescription(description) {
this.desc = description;
return this;
}
/**
* Добавляет кнопку в карточку.
* @param {TButton} button - Кнопка для добавления (строка или объект)
* @returns {Card}
* @example
* ```ts
* // Добавление простой кнопки
* card.addButton('Купить');
*
* // Добавление кнопки с дополнительными параметрами
* card.addButton({
* title: 'Подробнее',
* url: 'http://localhost',
* payload: { action: 'details' }
* });
* ```
*/
addButton(button) {
(0, Image_1.initButton)(button, this.button);
return this;
}
/**
* Очищает все элементы карточки.
* @returns {void}
* @example
* ```ts
* card.clear(); // Удалить все изображения
* ```
*/
clear() {
this.images = [];
this.isOne = false;
this.isUsedGallery = false;
}
/**
* Добавляет изображение в карточку.
* @param {string} image - Идентификатор или URL изображения
* @param {string} title - Заголовок изображения
* @param {string} [desc=' '] - Описание изображения
* @param {TButton} [button=null] - Кнопки для элемента
* @returns {Card}
*
* @remarks
* Ограничения на изображения:
* - Алиса: до 1MB, 1024x1024px, JPG/PNG
* - VK: до 5MB, рекомендуется 13:8, JPG/PNG/GIF
* - Telegram: до 10MB, 1280x1280px, JPG/PNG/WEBP
* - Viber: до 1MB, рекомендуется 400x400px, JPG/PNG
*
* @example
* ```ts
* // Добавление одного изображения
* card.addImage('image.jpg', 'Название', 'Описание');
*
* // Добавление изображения с кнопкой
* card.addImage('product.jpg', 'Товар', 'Описание', {
* title: 'Купить',
* url: 'http://localhost/product',
* payload: { action: 'buy', id: 123 }
* });
*
* // Добавление нескольких изображений в галерею
* card.isUsedGallery = true;
* card.addImage('image1.jpg', 'Фото 1')
* .addImage('image2.jpg', 'Фото 2')
* .addImage('image3.jpg', 'Фото 3');
* ```
*/
addImage(image, title = ' ', desc = ' ', button = null) {
const img = (0, Image_1.getImage)(this.#appContext, image, title, desc, button);
if (img) {
this.images.push(img);
}
return this;
}
/**
* Добавляет одно изображение в виде карточки. Внутри себя выставляет isOne в true.
* Если ранее были указаны другие изображения, то они очистятся.
* Стоит использовать в том случае, если у вас всегда должно отобразиться только 1 изображение.
* @param {string} image - Идентификатор или URL изображения
* @param {string} title - Заголовок изображения
* @param {string} [desc=' '] - Описание изображения
* @param {TButton} [button=null] - Кнопки для элемента
* @returns {Card}
*/
addOneImage(image, title = ' ', desc = ' ', button = null) {
this.isOne = true;
this.images = [];
return this.addImage(image, title, desc, button);
}
/**
* Получает карточку в формате для текущей платформы.
*/
getCards(cardProcessing, controller) {
if (this.template) {
return this.template;
}
return cardProcessing({
usedGallery: this.isUsedGallery,
buttons: this.button,
images: this.images,
title: this.title,
description: this.desc,
showOne: this.isOne,
}, controller);
}
}
exports.Card = Card;