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

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

Использование React в связке с 1С-Битрикс — решение, которое вызывает вопросы: зачем React, если есть компоненты Битрикса? Ответ прагматичный: когда требования к интерактивности страниц выходят за пределы jQuery-виджетов, а команда фронтенда уже работает на React и TypeScript — тащить старый стек Битрикса не имеет смысла.

Паттерны интеграции React с Битрикс

Три основных сценария использования React в Битрикс-проекте:

1. Встроенные виджеты. React-компонент монтируется на конкретный DOM-элемент внутри Битрикс-шаблона. Оптимально для сложных форм, интерактивных фильтров, кастомных UI-компонентов.

2. Страница-SPA внутри Битрикс. Весь контент страницы рендерится React, Битрикс служит только контейнером (шапка, футер, меню) и источником данных через API.

3. Полный headless. React-приложение живёт отдельно, Битрикс — только API. Самый чистый подход, но требует наибольших инвестиций.

Настройка проекта

Структура проекта для React-фронтенда внутри Битрикс:

/local/
  /js/
    /src/                   # исходники React
      /components/
      /hooks/
      /api/                 # слой работы с Битрикс API
        bitrix.ts
        catalog.ts
        cart.ts
      /store/               # Zustand/Redux
    vite.config.ts
    package.json
    tsconfig.json
  /templates/
    /main/                  # Битрикс-шаблон сайта

Критично держать React-исходники в /local/js/src/, а не в public/ — так они не попадают в веб-доступ напрямую и обрабатываются через сборщик.

Типизированный клиент Битрикс API

Вместо прямых fetch-запросов создайте типизированный API-клиент:

// /local/js/src/api/bitrix.ts
interface BitrixResponse<T> {
    result: T;
    total?: number;
    error?: string;
}

class BitrixApiClient {
    private baseUrl: string;
    private sessionId: string;

    constructor() {
        this.baseUrl = '/local/ajax/api.php';
        // Получаем sessid из глобальной переменной Битрикс
        this.sessionId = (window as any).BX?.bitrix_sessid?.() || '';
    }

    async get<T>(action: string, params: Record<string, unknown> = {}): Promise<T> {
        const url = new URL(this.baseUrl, window.location.origin);
        url.searchParams.set('action', action);
        Object.entries(params).forEach(([k, v]) =>
            url.searchParams.set(k, String(v)));

        const response = await fetch(url.toString(), {
            headers: { 'X-Bitrix-Csrf-Token': this.sessionId },
        });

        const data: BitrixResponse<T> = await response.json();
        if (data.error) throw new Error(data.error);
        return data.result;
    }

    async post<T>(action: string, body: Record<string, unknown>): Promise<T> {
        const formData = new FormData();
        formData.append('action', action);
        formData.append('sessid', this.sessionId);
        Object.entries(body).forEach(([k, v]) =>
            formData.append(k, String(v)));

        const response = await fetch(this.baseUrl, {
            method: 'POST',
            body: formData,
        });

        const data: BitrixResponse<T> = await response.json();
        if (data.error) throw new Error(data.error);
        return data.result;
    }
}

export const bitrixApi = new BitrixApiClient();

React Query для работы с данными

React Query (TanStack Query) — стандартный выбор для работы с серверными данными в React. Интеграция с Битрикс:

// /local/js/src/api/catalog.ts
import { useQuery } from '@tanstack/react-query';
import { bitrixApi } from './bitrix';

interface CatalogItem {
    id: number;
    name: string;
    price: number;
    quantity: number;
    previewPicture: string;
}

export function useCatalogItems(sectionId: number, page: number) {
    return useQuery({
        queryKey: ['catalog', sectionId, page],
        queryFn: () => bitrixApi.get<CatalogItem[]>('catalog.list', {
            section_id: sectionId,
            page,
            limit: 24,
        }),
        staleTime: 5 * 60 * 1000, // кэш на 5 минут
    });
}

// В компоненте:
function CatalogSection({ sectionId }: { sectionId: number }) {
    const [page, setPage] = useState(1);
    const { data, isLoading, error } = useCatalogItems(sectionId, page);

    if (isLoading) return <CatalogSkeleton />;
    if (error) return <ErrorMessage error={error} />;

    return (
        <div className="catalog-grid">
            {data?.map(item => <ProductCard key={item.id} item={item} />)}
            <Pagination page={page} onChange={setPage} />
        </div>
    );
}

Интеграция с Битрикс-авторизацией

Авторизация — специфическая задача при React + Битрикс. Стандартный подход: Битрикс управляет сессией и авторизацией, React проверяет текущее состояние через API:

// Hook для проверки авторизации
export function useAuth() {
    return useQuery({
        queryKey: ['auth'],
        queryFn: () => bitrixApi.get<{ isAuthorized: boolean; userId?: number }>('user.current'),
        staleTime: Infinity, // не перезапрашивать без необходимости
    });
}

Для действий, требующих авторизации (добавление в корзину, оформление заказа), при неавторизованном пользователе перенаправляйте на стандартную страницу авторизации Битрикса — не пишите свою, если нет специфических требований.

Тестирование

Компоненты тестируются через Vitest + Testing Library, независимо от Битрикса:

// Мокируем API для тестов
vi.mock('../api/bitrix', () => ({
    bitrixApi: {
        get: vi.fn().mockResolvedValue([
            { id: 1, name: 'Товар 1', price: 1000 }
        ]),
    }
}));

test('рендерит список товаров каталога', async () => {
    render(<CatalogSection sectionId={5} />);
    expect(await screen.findByText('Товар 1')).toBeInTheDocument();
});

React-фронтенд в Битрикс-проекте работает хорошо, когда правила игры чёткие: Битрикс отвечает за данные и бизнес-логику, React — за UI и взаимодействие. Смешивать логику в шаблонах Битрикса и React-компонентах одновременно — путь к неподдерживаемому коду через 6 месяцев.