Работа с Датой и Временем в MenuBuilderBot
MegaHubTelegram
Конструктор Menu Builder позволяет вам работать в Датой и Временем используя их в математических Выражениях. Можно добавлять и вычитать время, вычисляя уже прошедшее или оставшееся время "от" или "до" заданного события в будущем или отметки в прошлом. Для этого в конструкторе @MenuBuilderBot добавлен целый набор сущностей, позволяющих работать с Датами и Временем и возможность сохранять отметки времени в переменных. Работа со Временем в основном ориентирована на понятие "относительное время", то есть время между некоторыми событиями - что позволит вам отсчитывать время в часах "от" и "до" отметок. Но можно пользоваться и абсолютными значениями времени - выводя конкретные даты.
📜 Перевод представленных материалов на ваш родной язык может быть автоматически осуществлен при помощи переводчика Google. Перейдите по ссылке и выберите нужный язык в заголовке:
https://translate.googleusercontent.com/translate_c?depth=1&sl=ru&tl=es&u=https://telegra.ph/Working-with-Date-and-Time-in-MenuBuilderBot-RU-04-15
⬛ Содержание
◾ Используемый формат Даты и Времени
◾ Базовые функции для работы с Датой и Временем
⬛ Используемый формат Даты и Времени
Дата и Время всегда Вводятся и ВЫводятся в фиксированном формате:
DD.MM.YYYY HH:mm:ss
где:
● DD - день
● MM - месяц
● YYYY - год (4 цифры)
● HH - часы
● mm - минуты
● ss - секунды
Примеры:
● "01.01.2020 00:00:01" - новый 2020 год
● "17.05.2020 19:45:05" - вот более однозначный пример формата выводимого времени.
⬛ Переменные Даты и Времени
Для хранения Даты/Времени добавлен специальный тип переменных:
«📕 Время».
Чисто технически, Время можно сохранять и в Текстовых Переменных, но полноценно работать с такими переменными у вас не получится. В Текстовой переменной Время можно только хранить, но не выполнять с ним каких-либо действий.
В Сообщениях бота - Вывод Даты/Времени осуществляется как обычно - через макрос той переменной в которой оно сохранено.
В Выражениях Функций Времени, при использовании переменных хранящих Время - макросы этих переменных ДОЛЖНЫ браться "в кавычки" так как по сути они являются текстом.
Пример записи переменной "date1" в выражениях ФУНКЦИЙ ВРЕМЕНИ: {"%date1%"}. Само выражение естественно в {фигурных скобках}.
При передаче значения одной функции в другую даже если значение будет текстом, саму функцию в кавычки брать НЕ НУЖНО (смыл этого пункта вам станет ясен позднее) например:
{dt_passed(dt_now()...)}
В примере функция dt_now() передана в качестве параметра функции dt_passed() - кавычки не нужны. Вы поймете этот пример когда ниже причитаете про функции.
ВАЖНО! Ещё раз: в общем случае, при использовании «Переменных Времени» в Выражениях «Функций Времени» ВСЕГДА берите их макрос "в кавычки"! Иначе ничего не будет работать.
Примеры:
● Сообщение: "Вы нажали кнопку в %date1%".
(Покажет время сохраненное в переменной "date1")
● Выражение: {dt_add("%date1%", 1)}
(Покажет время сохраненное в переменной "date1" плюс 1 час)
⬛ Базовые функции для работы с Датой и Временем
ВСЯ(!) реальная работа с датами происходит ТОЛЬКО через специальные Функции (Кроме случаев, когда Дату/Время нужно просто отобразить в сообщении). Базовых Функций всего 3:
dt_now - Текущее Время
dt_now() - функция получения "сейчас", то есть текущей Даты и Времени. Нужна чтобы можно было от "сейчас" отсчитывать время, сравнивать его и т.д.
Возвращает значение типа "Дата/Время".
Функция имеет практический смысл только в Выражениях, в комбинации с другими функциями или значениями переменных.
Так же результат данной функции можно использовать чтобы сохранить в переменную текущее время (например время, в момент нажатия кнопки). В дальнейшем такую запись можно использовать как "отсечку" для расчетов времени прошедшего с этого момента.
Примеры:
Если использовано в Сообщении - выведет текущую дату и время (пока без учета часового пояса) в момент показа юзеру.
Если использовано в Выражении кнопки или в Action-е - то текущая дата (на момент срабатывания) может быть записана в переменную.
dt_add - Добавить Время
dt_add(date, hours) - функция получения даты, отличающейся от "date" на "hours" часов.
Возвращает значение типа "Дата/Время".
Функция принимает (требует для работы) два параметра:
● date - та дата от которой происходит отсчет времени.
Обычно, к моменту использования, она уже сохранена в какой-либо Переменной Времени (в этом случае используйте макрос той переменной в кавычках), однако это может быть и Текущее Время из функции «dt_now()»).
● hours - это количество часов на которое нужно изменить дату - часы задаются дробным числом (например, 0.5 часов - это 30 минут и т.д.). Данный параметр может быть не только жестко задан при помощи конкретного числа, но может быть представлен и значением Числовой Переменной - в этом случае используйте макрос этой перемеренной (без кавычек).
Часы могут быть отрицательными (если дату надо уменьшить), в этом случае вычисление времени осуществляется в обратном направлении относительный даты в переменной.
Фактически, это функция добавления времени в часах к некой Дате. Результат покажет новую Дату. Функция нужна для отображения в сообщении или сохранения в переменной, некоторой точки в будущем (например - окончание "похода в лес" в играх) - вычисленной в данной функции.
Примеры:
Вычислит дату на час позже чем та, что сохранена в переменной "date1". Обратите внимание на то, что макрос Переменной Времени "%date1%" - в кавычках, это важно!
Вычислит дату на полтора часа позже чем "сейчас" (на момент срабатывания выражения). Например: "Вы ушли, возвращайтесь обратно в {dt_add(dt_now(), 1.5)}"
Вычислит дату на "var1" часов позже чем та, что сохранена в переменной "date1". Обратите внимание на то, что макрос Переменной Времени "%date1%" - в кавычках, а макрос Числовой Переменной %var1% - без кавычек!
Добавление стандартных отрезков сремени.
Бывают ситуации когда к дате (сегодняшней или любой другой) нужно добавить некий стандартный отрезок времени, например: час, день, неделю, месяц или год. Для удобства были введены следующие выражения:
добавит 1 час (для часов можно использовать и следующее выражение {dt_add(dt_now(), 1)}).
добавит 1 день
добавит 1 неделю
добавит 1 месяц
добавит 1 год
ИНФО: Естественно вместо функции dt_now() можно исплльзовать любую дату или макрос переменной времени содержащую дату.
dt_diff - Разница Времени
dt_diff(date1, date2) - функция получения разницы в часах (дробных) между двумя датами. Вычисляет "date1" минус "date2". Если "date2" будет больше (то есть позже по времени) чем "date1" - результат будет отрицательным числом.
Возвращает дробное число Часов.
Функция нужна для получения информации о том, сколько времени прошло между двумя событиями "date1" и "date2".
Примеры:
Допустим ранее вы сохранили Дату/Время в переменной "date1". Данный пример вычислит, сколько часов прошло со времени сохраненного в переменной "date1" (то есть от какого-то события в прошлом) до теперешнего момента из функции «dt_now()».
Обратите внимание на то, что макрос Переменной Времени "%date1%" - в кавычках, это важно!
● Например: "С вашего ухода прошло {dt_diff(dt_now(), "%date1%")} часов".
● Или поинтереснее: "За прошедшие {dt_diff(dt_now(), "%date1%")} часа вы заработали {dt_diff(dt_now(), "%date1%") * 10} монет". (при условии что юзер получает 10 монет в час).
Дополнительные НЕобязательные параметры:
Тип результата: "s", "m", "h", "d" (секунда, минута, час, день). По умолчанию - час.
Округление: "n", "u", "d" (не округлять, округлять вверх, округлять вниз). По умолчанию - не округлять.
{dt_diff("%date%", dt_now(), "s")} - результат в секундах.
{dt_diff("%date%", dt_now(), "d")} - результат в днях (дробных).
{dt_diff("%dater%", dt_now(), "d", "u")} - результат в днях (целых, округленных вверх).
⬛ Сравнение Даты и Времени
Функции Времени, а так же Переменные содержащие данные о Дате и Времени могут служить условием для выполнения тех или иных действий в Кнопках и Action-ах. Для этого Время можно сравнивать в Условиях этих кнопок и Action-ов.
Даты и Время сравниваются обычными операторами сравнения:
● >, >= (Больше, Больше или равно)
● <, <= (Меньше, Меньше или равно)
и другими.
Технически можно сравнивать даты на "равно/не равно" (==, !=), но практического смысла в этом - нет: маловероятно что даты совпадут с точностью до миллисекунд.
Пример:
Наступило ли уже время, сохраненное в переменной "date1" (время в переменной меньше чем сейчас).
⬛ Типы результатов Выражений
При записи в переменные результатов работы функций Даты/Времени (когда они сохраняются в переменную через кнопки типа «Бонус», «Обмен», или через «Action-ы»), важно понимать и учитывать то, какого ТИПА результат возвращает та или иная функция Времени. От этого будет зависеть способ записи данных и соответственно то что останется записанным в переменной в конечном итоге.
Результаты бывают двух Типов:
● Тип - Дата/Время. Если выражение возвращает "Дату" - то дата будет ПРИСВОЕНА переменной. Всегда присвоена: то есть старая дата будет затёрта новой.
● Тип - Число: Если выражение возвращает "Число" - то значение будет ДОБАВЛЕНО (или вычтено, если отрицательное) к Дате в переменной. Работа по принципу функции «dt_add()».
Какой тип результата возвращает та или иная функция, смотрите выше - в описании самих функций.
⬛ Дополнительные Функции
Дополнительные функции предоставляют возможности, которые в принципе можно "собрать" и из «Базовых Функций» - осуществив все вычисления самостоятельно. Однако использование «Дополнительных Функций» для "типовых сценариев", позволяет сократить визуальную сложность Выражений и упростить вам работу.
Набор дополнительных функций, вероятнее всего, будет расширятся по мере выявления новых "типовых", активно используемых сценариев (другими словами - по вашим просьбам).
dt_left
функция, которая возвращает, сколько В ЧАСАХ осталось до указанной даты (date). Если относительно текущего момента дата уже прошла - функция вернет 0 (ноль).
Функция вернет дробное, десятичное количество часов (1.2, 5.7, 34.4). Больше предназначено для удобства вычислений в Выражениях.
Дополнительные НЕобязательные параметры:
Тип результата: "s", "m", "h", "d" (секунда, минута, час, день). По умолчанию - час.
Округление: "n", "u", "d" (не округлять, округлять вверх, округлять вниз). По умолчанию - не округлять.
{dt_left("%date%", dt_now(), "s")} - результат в секундах.
{dt_left("%date%", dt_now(), "d")} - результат в днях (дробных).
{dt_left("%dater%", dt_now(), "d", "u")} - результат в днях (целых, округленных вверх).
dt_left_hm
функция, которая возвращает строку в HH:MM, сколько осталось В ЧАСАХ и МИНУТАХ до указанной даты (date). Если относительно текущего момента дата уже прошла - функция вернет 00:00.
Функция вернет привычное и удобное для понимания человеком количество часов и минут (1:12, 7:42, 36:24). Предназначено для упрощения понимания юзером и удобства вывода значений в Сообщениях.
dt_passed
функция, которая возвращает, сколько прошло В ЧАСАХ с указанной даты (date). Если относительно текущего момента дата ещё не подошла - функция вернет 0 (ноль).
Функция вернет дробное, десятичное количество часов (1.2, 5.7, 34.4). Больше предназначено для удобства вычислений в Выражениях.
Дополнительные НЕобязательные параметры:
Тип результата: "s", "m", "h", "d" (секунда, минута, час, день). По умолчанию - час.
Округление: "n", "u", "d" (не округлять, округлять вверх, округлять вниз). По умолчанию - не округлять.
{dt_passed("%date%", dt_now(), "s")} - результат в секундах.
{dt_passed("%date%", dt_now(), "d")} - результат в днях (дробных).
{dt_passed("%dater%", dt_now(), "d", "u")} - результат в днях (целых, округленных вверх).
dt_passed_hm
функция, которая возвращает строку в HH:MM сколько прошло В ЧАСАХ И МИНУТАХ с указанной даты (date). Если относительно текущего момента дата ещё не подошла - функция вернет 00:00.
Функция вернет привычное и удобное для понимания человеком количество часов и минут (1:12, 7:42, 36:24). Предназначено для упрощения понимания юзером и удобства вывода значений в Сообщениях.
dt_passedm
функция, которая возвращает, сколько прошло В ЧАСАХ с указанной даты (date), но не больше (max) часов. Если относительно текущего момента дата ещё не подошла - функция вернет 0 (ноль). Если относительно (data) прошло больше (max) часов - функция вернет (max).
Функция вернет дробное, десятичное количество часов (1.2, 5.7, 34.4). Больше предназначено для удобства вычислений в Выражениях.
dt_passedm_hm
функция, которая возвращает строку в HH:MM сколько прошло В ЧАСАХ И МИНУТАХ с указанной даты, но не больше (max) часов. Если относительно текущего момента дата ещё не подошла - функция вернет 00:00. Если относительно (data) прошло больше (max) часов - функция вернет (max) в формате HH:MM.
Функция вернет привычное и удобное для понимания человеком количество часов и минут (1:12, 7:42, 36:24). Предназначено для упрощения понимания юзером и удобства вывода значений в Сообщениях.
⬛ Дополнительная Информация
◾ Дату и Время можно записывать в Переменные.
О том что такое переменные и как с ними работать смотри в Боте Помощи
https://t.me/MenuBuilderHelpBot?start=m10350
◾ Функции и Переменные с Дата/Время можно использовать в Выражениях.
О том как применять Выражения, читай в руководстве по Выражениям (пока на Английском, в переводе от Yandex)
◾ Функции и Переменные с Дата/Время можно использовать в Условиях.
О том как применять Условия, читай в руководстве по Условиям (пока на Английском, в переводе от Yandex)
◾ Дату и Время можно использовать в Action-ах.
Подробнее о том что такое Action-ы, чем они удобны и как ими пользоваться смотрите в отдельном Руководстве по Action-ам.
