Класс B24Frame

B24Frame наследуется от AbstractB24 и реализует TypeB24. Поверх общего набора REST-методов (actions.v2.*, actions.v3.*, tools.*) он предоставляет менеджеры, которые общаются с родительским окном через postMessage: auth, parent, slider, dialog, placement, options.

Конструктор

constructor(
  queryParams: B24FrameQueryParams,
  options?: { restrictionParams?: Partial<RestrictionParams> }
)

B24FrameQueryParams описывает предоставляемые Bitrix24 идентификаторы, разобранные из window.name:

В отличие от B24Hook и B24OAuth, B24Frame требует await b24.init() перед любым REST-вызовом — init() выполняет рукопожатие getInitData с родительским окном. initializeB24Frame() делает это за вас.

Геттеры

isInit

get isInit(): boolean

true после завершения рукопожатия с родительским окном. До этого обращение к auth, actions, tools или любому менеджеру фрейма выбрасывает 'B24 not initialized'.

isFirstRun

get isFirstRun(): boolean

true при самом первом запуске приложения (Bitrix24 устанавливает FIRST_RUN). При isFirstRun = true SDK автоматически отправляет setInstall: true родительскому окну.

isInstallMode

get isInstallMode(): boolean

true пока приложение находится в процессе установки (флаг INSTALL от родителя). Требуется для installFinish.

auth

get auth(): AuthManager

Менеджер авторизации. Предоставляет getAuthData, refreshAuth, getUniq, isAdmin, а также автообновление при ответах 401.

parent

get parent(): ParentManager

Менеджер родительского окна. Отправка сообщений в окружающую страницу Bitrix24 и чтение её метаданных.

slider

get slider(): SliderManager

Менеджер слайдеров. Открытие и закрытие слайдеров Bitrix24.

placement

get placement(): PlacementManager

Менеджер placement. Просмотр и обновление контекста placement.

options

get options(): OptionsManager

Менеджер опций. Чтение опций приложения и пользователя, синхронизированных из родительского окна.

dialog

get dialog(): DialogManager

Менеджер диалогов. Запрос к Bitrix24 на отображение нативных диалогов подтверждения / сообщений / выбора файлов.

Методы

init

init(): Promise<void>

Выполняет рукопожатие с родительским окном (getInitData), настраивает состояние менеджеров и создаёт оба HTTP-клиента REST API. На практике идемпотентен — initializeB24Frame() устраняет дублирование параллельных вызовов.

destroy

destroy(): void

Отписывается от событий postMessage. Всегда вызывайте перед размонтированием хост-компонента, чтобы избежать утечек.

installFinish

installFinish(): Promise<any>

Отправляет setInstallFinish родителю. Выбрасывает Error('Application was previously installed. You cannot call installFinish') при вызове вне режима установки — защищайтесь проверкой isInstallMode.

getAppSid

getAppSid(): string

Идентификатор сессии приложения относительно родительского окна (повторяет APP_SID).

getLang

getLang(): B24LangList

Enum языка интерфейса Bitrix24. См. LangList.

getTargetOrigin / getTargetOriginWithPath

getTargetOrigin(): string
getTargetOriginWithPath(): Map<ApiVersion, string>

Origin портала и REST-endpoint-ы для каждой версии (предоставляются родителем).

Унаследовано от AbstractB24

getHttpClient, setHttpClient, setRestrictionManagerParams, getLogger, setLogger, actions, tools. См.:

• Лимитеры
• Логгер

Использование

import {
  initializeB24Frame,
  LoggerFactory,
  EnumCrmEntityTypeId,
  Text,
  type B24Frame,
  type ISODate
} from '@bitrix24/b24jssdk'

const $logger = LoggerFactory.createForBrowser('MyApp', import.meta.env?.DEV === true)
let $b24: undefined | B24Frame

async function loadCompanies() {
  if (!$b24) return

  const response = await $b24.actions.v2.callList.make<{ id: number, title: string, createdTime: ISODate }>({
    method: 'crm.item.list',
    params: {
      entityTypeId: EnumCrmEntityTypeId.company,
      select: ['id', 'title', 'createdTime']
    },
    idKey: 'id',
    requestId: 'companies-list'
  })

  if (!response.isSuccess) {
    $logger.error('REST error', { messages: response.getErrorMessages() })
    return
  }

  return response.getData()!.map((item) => ({
    id: Number(item.id),
    title: item.title,
    createdTime: Text.toDateTime(item.createdTime)
  }))
}

async function bootstrap() {
  try {
    $b24 = await initializeB24Frame()
    const companies = await loadCompanies()
    $logger.notice('companies', { companies })
  } catch (error) {
    $logger.error('init failed', { error })
  }
}

bootstrap()