Плагин отображения имени клиента (timetable-record-client-name)

Репозиторий

https://github.com/yclients/example-plugin-frontend/tree/main/apps/timetable-record-client-name

Что делает

Плагин отображает полное имя клиента (фамилия, имя, отчество) в расписании записей. Плагин получает персональные данные клиента от хоста и форматирует их в читаемый вид для отображения в пользовательском интерфейсе.

Пример работы: Клеперов Евгений Викторович вместо сокращенного «Евгений К.».

*Рис. 1. Полное ФИО клиента в таблице записи

Принцип работы

Старт работы плагина

Запуск плагина происходит через функцию initializePlugin
(репозиторий)

export function initializePlugin() {
  // Обработчик события готовности хоста
  const handleHostReadyEvent = (event: CustomEvent<THostReadyEvent>): void => {
    console.log('[Plugin] Получено событие готовности хоста:', event);
    const { containerId, payload } = event.detail;

    const container = document.querySelector(
      `[data-plugin-container="${containerId}"]`,
    );

    // Формируем полное имя клиента с помощью сервиса
    const fullName = ClientNameService.formatFullName(payload);
    container.replaceChildren(fullName);

    // Отправляем событие о готовности плагина
    pluginEventEmitter.emit(PLUGIN_EVENT_NAMES.READY);
  };

  // Подписываемся на событие готовности хоста
  hostEventEmitter.onDocument(HOST_EVENT_NAMES.READY, handleHostReadyEvent);
}

При старте плагин подписывается на событие HOST_EVENT_NAMES.READY, которое будет отправлено хостом, когда он будет готов для работы с плагинами.

handleHostReadyEvent

Обработчик события готовности хоста выполняет следующие действия:

1. Получает данные о клиенте (имя, фамилия, отчество) из payload события.
2. Находит контейнер для отображения по containerId.
3. Форматирует полное имя клиента с помощью ClientNameService.
4. Заменяет содержимое контейнера на отформатированное имя.
5. Отправляет событие о готовности плагина.

ClientNameService

(репозиторий)

export class ClientNameService {
  /**
   * Создает читаемое представление клиента для отображения в пользовательском интерфейсе.
   *
   * @param personalData - Персональные данные клиента.
   * @returns Готовое к отображению полное имя клиента.
   */
  static formatFullName({
    clientSurname,
    clientName,
    clientPatronymic,
  }: THostReadyPayload): string {
    return [clientSurname, clientName, clientPatronymic]
      .map((part) => part?.trim())
      .filter(Boolean)
      .join(' ');
  }
}

Сервис принимает персональные данные клиента и возвращает отформатированную строку с полным именем. Метод:

• Удаляет лишние пробелы из каждой части имени.
• Фильтрует пустые значения.
• Объединяет части имени через пробел.

Примеры:

• ["Иванов", "Иван", "Иванович"] → "Иванов Иван Иванович"
• ["Петров", "", "Сергеевич"] → "Петров Сергеевич"
• [" Сидоров ", "Алексей", null] → "Сидоров Алексей"

Типы событий

(репозиторий)

Плагин использует систему событий для коммуникации с хостом:

• THostReadyEvent — событие готовности хоста, содержит данные клиента.
• TPluginReadyEvent — событие готовности плагина, отправляется после инициализации.

Структура данных клиента:

export type THostReadyPayload = {
  clientName: string; // Имя клиента
  clientSurname: string; // Фамилия клиента
  clientPatronymic: string; // Отчество клиента
};

Зависимости

Плагин использует следующие основные зависимости:

• @yclients-plugins/utils — утилиты для работы с событиями.
• @yclients-configs/vite — конфигурация сборки.

Сборка и разработка

># Установка зависимостей
npm install

# Запуск в режиме разработки
npm run dev

# Сборка для продакшена
npm run build

# Проверка типов
npm run typecheck

# Линтинг
npm run lint

Требования

• Node.js 18+.
• npm 8+.