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

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

Разрыв между PHP-бэкендом Битрикс и фронтендом на ванильном JavaScript — стандартная история. Компоненты каталога, корзина, фильтры, личный кабинет — каждая из этих сущностей живёт на пересечении PHP-логики и клиентского кода. TypeScript закрывает дыры на этом стыке: контракт между PHP и JS описывается в типах, а компилятор ловит несоответствия до деплоя.

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

Архитектура фронтенда Битрикс-проекта

Два полярных подхода к фронтенду Битрикс:

1. MPA (Multi-Page Application) — классический подход. PHP рендерит страницы, TypeScript добавляет интерактивность: фильтр на AJAX, корзина через REST, галереи, карты. Каждый компонент — отдельный изолированный TS-модуль.

2. SPA/Headless — React или Vue на TypeScript потребляют Битрикс как API. Полный фронтенд написан на TypeScript, PHP обеспечивает только данные и бизнес-логику.

Большинство проектов — первый подход с элементами второго в критических частях (каталог, корзина).

Структура фронтенда в шаблоне Битрикс

/local/templates/my_site/
├── src/
│   ├── components/
│   │   ├── catalog/
│   │   │   ├── CatalogFilter.ts
│   │   │   ├── ProductCard.ts
│   │   │   └── CartButton.ts
│   │   ├── cart/
│   │   │   ├── CartDrawer.ts
│   │   │   └── CartCounter.ts
│   │   └── common/
│   │       ├── Modal.ts
│   │       └── Tooltip.ts
│   ├── api/
│   │   ├── catalog.ts
│   │   ├── cart.ts
│   │   └── user.ts
│   ├── types/
│   │   ├── bitrix.d.ts
│   │   └── api.ts
│   ├── utils/
│   │   ├── http.ts
│   │   └── format.ts
│   └── main.ts
├── dist/
├── package.json
├── tsconfig.json
└── vite.config.ts

Компонент корзины на TypeScript

Полноценный пример компонента корзины с типами:

// api/cart.ts
interface CartItem {
    id:       number;
    name:     string;
    price:    number;
    quantity: number;
    img:      string | null;
}

interface CartState {
    items:      CartItem[];
    totalPrice: number;
    totalCount: number;
    currency:   string;
}

interface AddToCartPayload {
    productId: number;
    quantity:  number;
    properties?: Record<string, string>;
}

export async function addToCart(payload: AddToCartPayload): Promise<CartState> {
    const formData = new FormData();
    formData.append('sessid',     BX.bitrix_sessid());
    formData.append('action',     'addItem');
    formData.append('product_id', String(payload.productId));
    formData.append('quantity',   String(payload.quantity));

    if (payload.properties) {
        Object.entries(payload.properties).forEach(([k, v]) => {
            formData.append(`props[${k}]`, v);
        });
    }

    const res = await fetch('/local/ajax/cart.php', {
        method: 'POST',
        body:   formData,
    });

    if (!res.ok) throw new Error(`Cart error: ${res.status}`);

    const json = await res.json();
    if (json.status !== 'success') throw new Error(json.error ?? 'Cart error');

    return json.cart as CartState;
}

// components/cart/CartButton.ts
import { addToCart }   from '@/api/cart';
import { updateCartUI } from './CartCounter';

export function initAddToCartButtons(): void {
    document.querySelectorAll<HTMLButtonElement>('[data-action="add-to-cart"]')
        .forEach(btn => btn.addEventListener('click', handleAddToCart));
}

async function handleAddToCart(e: MouseEvent): Promise<void> {
    const btn = e.currentTarget as HTMLButtonElement;
    const productId = Number(btn.dataset['productId']);
    if (!productId) return;

    btn.disabled = true;
    btn.classList.add('loading');

    try {
        const cart = await addToCart({ productId, quantity: 1 });
        updateCartUI(cart.totalCount, cart.totalPrice);
        showAddedFeedback(btn);
    } catch (err) {
        console.error('Add to cart failed:', err);
        showError(btn);
    } finally {
        btn.disabled = false;
        btn.classList.remove('loading');
    }
}

Интеграция с PHP-компонентами через data-атрибуты

Передача данных из PHP в TypeScript без глобальных переменных:

// template.php компонента каталога
<div
    id="catalog-app"
    data-section-id="<?= (int)$arResult['SECTION']['ID'] ?>"
    data-iblock-id="<?= (int)$arParams['IBLOCK_ID'] ?>"
    data-initial-filter='<?= htmlspecialchars(
        json_encode($arResult['FILTER_PARAMS']), ENT_QUOTES
    ) ?>'
>
    <?php // SSR-вёрстка для первой загрузки ?>
</div>

// TypeScript читает данные типизированно
const appEl = document.getElementById('catalog-app');
if (!appEl) throw new Error('#catalog-app not found');

const sectionId  = Number(appEl.dataset['sectionId']);
const iblockId   = Number(appEl.dataset['iblockId']);
const rawFilter  = appEl.dataset['initialFilter'] ?? '{}';
const initFilter = JSON.parse(rawFilter) as FilterState;

Состояние без React: EventEmitter-паттерн

Для MPA-проектов не всегда нужен React. Лёгкий EventEmitter синхронизирует компоненты:

// utils/EventBus.ts
type Handler<T> = (payload: T) => void;

class EventBus {
    private handlers: Map<string, Handler<unknown>[]> = new Map();

    on<T>(event: string, handler: Handler<T>): void {
        const list = this.handlers.get(event) ?? [];
        list.push(handler as Handler<unknown>);
        this.handlers.set(event, list);
    }

    emit<T>(event: string, payload: T): void {
        this.handlers.get(event)?.forEach(h => h(payload as unknown));
    }
}

export const bus = new EventBus();

// Использование: корзина оповещает хедер
bus.emit<CartState>('cart:updated', newCartState);
bus.on<CartState>('cart:updated', (cart) => {
    updateCartCounter(cart.totalCount);
});

Сборка и деплой

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
    root:  'src',
    build: {
        outDir:          '../dist',
        emptyOutDir:     true,
        rollupOptions: {
            input: {
                main:    'src/main.ts',
                catalog: 'src/pages/catalog.ts',
                cart:    'src/pages/cart.ts',
            },
        },
    },
    resolve: {
        alias: { '@': '/src' },
    },
});

Отдельные entrypoint для каждого раздела сайта — только нужный JS загружается на странице.

Сроки