Text

Обзор

Text — это синглтон (new TextManager()), экспортируемый из @bitrix24/b24jssdk. Он объединяет небольшие хелперы для текста и дат, на которые SDK опирается внутри, и предоставляет их коду приложения:

• Идентификаторы — случайные строки, локально генерируемый UUID v4 и упорядоченный по времени UUID v7 (request id по умолчанию у SDK).
• Кодирование HTML-сущностей — encode / decode в стиле legacy Bitrix Framework.
• Преобразование типов — приведение произвольных значений к числам, целым и булевым.
• Хелперы регистра — camelCase, PascalCase, kebab-case и capitalize.
• Форматирование чисел — группировка тысяч с фиксированным числом знаков после запятой.
• Хелперы дат — парсинг на Luxon и формат yyyy-MM-dd'T'HH:mm:ssZZ, который Bitrix24 ожидает в REST-payload.
• Query-строки — сборка строки application/x-www-form-urlencoded из обычного объекта.

import { Text } from '@bitrix24/b24jssdk'

console.log(Text.getUuidRfc4122())          // '019323ac-8ace-725b-a3dc-6a7c333da066'
console.log(Text.getDateForLog())           // '2026-05-04 09:53:51'
console.log(Text.numberFormat(1234.567, 2)) // '1,234.57'

Сигнатура методов

Идентификаторы

getRandom(length?: number): string          // случайные [a-z0-9], длина по умолчанию 8
getUniqId(): string                          // UUID v4 (по возможности, локально)
getUuidRfc4122(): string                     // UUID v7 (упорядоченный по времени) — request id по умолчанию у SDK

Кодирование сущностей

encode(value: string): string                // & < > ' "  → entity-коды (без завершающей ;)
decode(value: string): string                // обратное к encode, также числовые сущности

Преобразование типов

toNumber(value: any): number                 // 0 при неудаче парсинга
toInteger(value: any): number                // toNumber(parseInt(value, 10))
toBoolean(value: any, trueValues?: string[]): boolean // 'true'/'y'/'1'/1/true → true

Хелперы регистра

toCamelCase(str: string): string
toPascalCase(str: string): string            // capitalize(toCamelCase(str))
toKebabCase(str: string): string
capitalize(str: string): string

Форматирование чисел

numberFormat(
  number: number,
  decimals?: number,        // по умолчанию 0
  decPoint?: string,        // по умолчанию '.'
  thousandsSep?: string     // по умолчанию ','
): string

Хелперы дат (Luxon)

toDateTime(dateString: string, template?: string, opts?: DateTimeOptions): DateTime
toB24Format(date: string | Date | DateTime): string   // yyyy-MM-dd'T'HH:mm:ssZZ
getDateForLog(): string                                // 'yyyy-MM-dd HH:mm:ss'

Query-строка

buildQueryString(params: any): string        // application/x-www-form-urlencoded, без ведущего '?'

Ключевые понятия

• getRandom / getUniqId не криптографически стойкие. Оба построены на Math.random() — используйте их для ключей cache-busting и одноразовых id, но никогда для токенов или секретов.
• Разделители toCamelCase. -, _ и пробелы трактуются как границы слов; полностью заглавный вход приводится к нижнему регистру ('ABC' → 'abc').
• toKebabCase разбивает по границам регистра. getUserId → get-user-id и XMLHttpRequest → xml-http-request, поэтому camelCase и смешанные аббревиатуры обрабатываются. Один крайний случай: последовательность заглавных, сразу за которой идёт цифра, разбивается буква-за-буквой (parseHTML5 → parse-h-t-m-l-5).
• numberFormat соответствует серверу. Не-конечные значения становятся 0, дробная часть округляется до decimals знаков, а разделитель тысяч вставляется каждые три цифры слева от десятичной точки.
• toDateTime возвращает DateTime даже для некорректного ввода. Когда передан template, используется DateTime.fromFormat, иначе DateTime.fromISO. Проверяйте result.isValid перед использованием.
• toB24Format пропускает строки без изменений (считаются уже отформатированными); JS-Date сначала нормализуется через Luxon.

Обработка ошибок

Хелперы Text не выбрасывают исключений для неожиданного ввода — они деградируют мягко: toNumber / toInteger возвращают 0, toBoolean возвращает false, buildQueryString(null) возвращает '', а encode / decode возвращают не-строковые значения без изменений. toDateTime тоже никогда не выбрасывает — он возвращает DateTime, чей флаг isValid равен false для неразбираемого ввода, поэтому проверяйте result.isValid перед использованием значения.

Примеры

Идентификаторы и request id:

import { Text } from '@bitrix24/b24jssdk'

Text.getRandom()          // 'a7f3k1z9'
Text.getRandom(4)         // 'p2x8'
Text.getUniqId()          // 'd2b8a1f0-3c4e-4a9b-8f7c-1e2d3a4b5c6d'  (UUID v4)
Text.getUuidRfc4122()     // '019323ac-8ace-725b-a3dc-6a7c333da066'  (UUID v7)

Кодирование и преобразование типов:

import { Text } from '@bitrix24/b24jssdk'

Text.encode('<b>Tom & Jerry</b>') // '&ltb&gtTom &amp Jerry&lt/b&gt'
Text.decode('&ltb&gtTom &amp Jerry&lt/b&gt') // '<b>Tom & Jerry</b>'

Text.toNumber('12.5')     // 12.5
Text.toInteger('42.9')    // 42
Text.toBoolean('Y')       // true
Text.toBoolean('on', ['on']) // true

Хелперы регистра и форматирование чисел:

import { Text } from '@bitrix24/b24jssdk'

Text.toCamelCase('get_user_id')  // 'getUserId'
Text.toPascalCase('get_user_id') // 'GetUserId'
Text.toKebabCase('getUserId')    // 'get-user-id'
Text.capitalize('hello')         // 'Hello'

Text.numberFormat(1234.567, 2)           // '1,234.57'
Text.numberFormat(1234.567, 2, ',', ' ') // '1 234,57'

Даты и query-строки:

import { Text } from '@bitrix24/b24jssdk'

// Форматирование даты для REST-payload
Text.toB24Format(new Date()) // '2026-05-04T09:53:51+03:00'

// Разбор ISO-строки или кастомного шаблона
const dt = Text.toDateTime('04.05.2026', 'dd.MM.yyyy')
if (dt.isValid) {
  console.log(dt.toISODate()) // '2026-05-04'
}

// Сборка query-строки (ведущий '?' не включается)
Text.buildQueryString({ id: 7, tag: ['a', 'b'] })
// 'id=7&tag%5B0%5D=a&tag%5B1%5D=b'

Альтернативы и рекомендации

• Предпочитайте getUuidRfc4122() вместо getUniqId(). Идентификатор v7 упорядочен по времени и совместим с RFC 4122 — поэтому SDK использует его как request id по умолчанию. Берите getUniqId() (UUID v4) только когда вам конкретно нужен случайный, несортируемый id, и ни то ни другое — когда нужна криптографическая случайность.
• Используйте toB24Format для каждой даты, которую отправляете в REST API. Передача сырого Date или ISO-строки с неверным смещением — самая частая причина несовпадений фильтров; примеры фильтров по диапазону дат см. в Фильтрации.
• Проверки типов в runtime живут в Type. Text сфокусирован на преобразовании; используйте проверки Type (isStringFilled, isArrayFilled, …), когда сначала нужно ветвиться по форме значения.
• Форматирование валюты / IBAN с учётом локали живёт в useFormatter. numberFormat — это лёгкий хелпер тысяч-и-десятичных; для валюты, процентов или IBAN используйте специализированные форматтеры.
• Для чего-либо богаче парсинга работайте с Luxon напрямую. toDateTime — тонкая обёртка над DateTime.fromISO / DateTime.fromFormat; для арифметики, зон и длительностей импортируйте DateTime из luxon и оперируйте возвращённым значением.