Разработка на TypeScript для проекта 1С-Битрикс

Разработка на TypeScript для проекта 1С-Битрикс

PHP-шаблоны Битрикс генерируют HTML, а фронтенд-код на «голом» JavaScript в template.php или script.js компонента остаётся без типов, без автодополнения, без защиты от ошибок по типу «undefined is not a function» в продакшене. TypeScript — прагматичный выбор для любого Битрикс-проекта, где JS-кода больше нескольких сотен строк.

Разработка на TypeScript для проекта 1С-Битрикс

Где живёт TypeScript в Битрикс-проекте

Два типичных сценария: TypeScript в шаблоне сайта и TypeScript в D7-модуле.

В шаблоне сайта:

/local/templates/my_site/
    src/
        ts/
            catalog.ts
            cart.ts
            search.ts
        scss/
            ...
    dist/        <- скомпилированный JS
    package.json
    tsconfig.json
    vite.config.ts

В модуле:

/local/modules/mymodule/
    install/
        js/
            src/         <- TypeScript-исходники
                index.ts
            dist/        <- скомпилированный JS
    package.json
    tsconfig.json

tsconfig.json для Битрикс-окружения

{
    "compilerOptions": {
        "target": "ES2020",
        "module": "ESNext",
        "moduleResolution": "bundler",
        "strict": true,
        "noUncheckedIndexedAccess": true,
        "lib": ["ES2020", "DOM"],
        "outDir": "./dist",
        "sourceMap": true,
        "paths": {
            "@/*": ["./src/*"]
        }
    },
    "include": ["src/**/*.ts"],
    "exclude": ["node_modules", "dist"]
}

noUncheckedIndexedAccess: true — строгая проверка обращения к массивам по индексу. Важно для работы с результатами API Битрикс, где поле может отсутствовать.

Типизация данных Битрикс

Первое, что нужно сделать — описать типы данных, которые приходят с PHP-бэкенда. Битрикс передаёт данные через JSON в data-атрибутах или AJAX:

// types/bitrix.ts

export interface BitrixProduct {
    ID: string;
    NAME: string;
    DETAIL_PAGE_URL: string;
    PREVIEW_PICTURE: string | null;
    CATALOG_PRICE_1: string | null;
    CATALOG_CURRENCY_1: string;
    PROPERTY_BRAND_VALUE: string | null;
    PROPERTY_ARTICLE_VALUE: string | null;
}

export interface BitrixCatalogResult {
    ITEMS: BitrixProduct[];
    TOTAL_ITEMS_COUNT: number;
    PAGES_COUNT: number;
    CURRENT_PAGE: number;
}

export interface BitrixAjaxResponse<T = unknown> {
    status: 'success' | 'error';
    data: T;
    errors?: BitrixError[];
}

export interface BitrixError {
    code: string;
    message: string;
    customData?: string;
}

Битрикс возвращает числовые ID как строки — "ID": "42", не "ID": 42. Это нужно учитывать в типах.

Работа с AJAX-ответами Битрикс

// api/catalog.ts
import type { BitrixAjaxResponse, BitrixCatalogResult } from '@/types/bitrix';

export async function fetchCatalogItems(
    sectionId: number,
    page: number,
    filter: Record<string, string[]>
): Promise<BitrixCatalogResult> {
    const params = new URLSearchParams({
        SECTION_ID: String(sectionId),
        PAGE_NUM:   String(page),
        sessid:     BX.bitrix_sessid(), // CSRF-токен Битрикс
        action:     'getCatalogItems',
    });

    Object.entries(filter).forEach(([key, values]) => {
        values.forEach(val => params.append(`filter[${key}][]`, val));
    });

    const response = await fetch('/local/ajax/catalog.php', {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body:    params.toString(),
    });

    if (!response.ok) {
        throw new Error(`HTTP ${response.status}`);
    }

    const json: BitrixAjaxResponse<BitrixCatalogResult> = await response.json();

    if (json.status !== 'success') {
        throw new Error(json.errors?.[0]?.message ?? 'Unknown error');
    }

    return json.data;
}

BX.bitrix_sessid() — метод ядра Битрикс. Чтобы TypeScript знал о глобальном объекте BX:

// types/globals.d.ts
declare global {
    const BX: {
        bitrix_sessid(): string;
        message(params: Record<string, string>): void;
        bind(el: Element, event: string, fn: (e: Event) => void): void;
        // ... остальные методы по необходимости
    };
}
export {};

Работа с DOM в шаблонах компонентов

// Типизированная работа с data-атрибутами
const catalogEl = document.getElementById('catalog-container');
if (!catalogEl) throw new Error('catalog-container not found');

const rawData = catalogEl.dataset['initialData'];
if (!rawData) throw new Error('No initial data');

// Валидация через Zod или ручная проверка типов
const initialData: BitrixCatalogResult = JSON.parse(rawData);

Сборка и подключение в шаблоне

Vite собирает TypeScript в /dist/:

// В header.php шаблона
$assetManager = \Bitrix\Main\Page\Asset::getInstance();
$assetManager->addJs(SITE_TEMPLATE_PATH . '/dist/catalog.js');

При разработке — vite dev с HMR, в продакшне — vite build и /dist/ коммитится в репозиторий (или собирается в CI).

Сроки