Файлы

Назначение

Используйте панель files, чтобы просматривать список файлов, связанных с объектом, выбранным в другой панели, открывать их для предпросмотра, скачивать и изменять.

Когда использовать

Выберите filesList, если нужна сетка со страницами и элементами управления для каждого файла. Выберите preview, если просмотрщик документов должен быть виден всегда. Панель файлов подходит, только когда другая панель публикует событие выбора объекта; это не универсальный каталог файлов.

Предварительные условия и ответственность

• request.getSelectedObjectForEventId должен указывать событие, которое передаёт GUID объекта.
• Хранилище панели запрашивает связи выбранного объекта с наборами данных (Dataset), получает метаданные их файлов и очищается, когда выбор снят.
• Запросы данных и запросы, изменяющие файлы, выполняет сама панель.
• Документы в области просмотра отображает @mes/aps-document-viewer.
• filesList.actions — действия строки. Загрузка файла относится к panelActions.

Карта возможностей

Область	Поддерживаемое поведение
Привязка	Отслеживает указанное в конфигурации событие выбора и заново запрашивает связанные наборы данных, когда меняется объект
Режим списка	Адаптивная сетка со страницами, при необходимости с фиксированным числом колонок; метаданные: имя файла, размер, MIME-тип, дата изменения
Предпросмотр	Необязательные миниатюры в карточках, которые готовит сервер; в режиме списка кнопка со значком глаза открывает галерею в модальном окне
Режим просмотра	Галерея внутри панели для всех файлов, связанных с выбранным объектом; одновременно открыт один файл
Скачивание	Кнопка скачивания видна всегда и сохраняет исходный файл; fileDownload.useModernApi просит браузер открыть окно сохранения, когда файл скачан, если браузер это умеет и нажатие ещё считается действием пользователя; иначе браузер сохраняет файл обычным способом
Изменение из строки	deleteFile, editDatasetMeta, replaceDatasetFile (сохраняет GUID файла) и unlinkDataset через filesList.actions
Действия заголовка	Общие panelActions, включая uploadFile; панель показывает их над содержимым
Состояния	Индикатор загрузки и локализованное сообщение о пустом списке, в русском интерфейсе — «Нет файлов для отображения»

Модель поведения

Выбор объекта в другой панели передаёт GUID этого объекта. Хранилище панели запрашивает связи и метаданные файлов, формирует по одной модели представления на каждый набор данных и показывает список или область просмотра. Когда выбор снят, панель очищается. После изменений панель заново запрашивает связанные наборы данных; номер открытого файла в режиме просмотра и состояние модального окна остаются локальными для панели.

Каждый запрос файла передаёт токен пользователя, поэтому панель скачивает содержимое сама, а не отдаёт браузеру обычную ссылку:

• Миниатюра в карточке. Если showPreviews включён и сервер сообщает, что миниатюра готова, карточка запрашивает GET /files/{guid}/thumbnail и показывает её. Иначе карточка показывает тип файла, например PDF. Миниатюра, которую сервер ещё готовит, появится, когда панель в следующий раз загрузит список файлов: при выборе объекта, а также после загрузки, замены, удаления или отвязки файла или правки его метаданных.
• Галерея. Галерея скачивает только открытый файл. Стрелки над просмотрщиком открывают предыдущий или следующий файл и скачивают его в момент открытия.
• Скачивание. Кнопка скачивания всегда сохраняет исходный файл, а не его миниатюру.
• Замена. replaceDatasetFile загружает новое содержимое в тот же файл. GUID файла не меняется, а прежнее содержимое из панели не открыть и не восстановить. Все карточки этой панели сразу показывают новое содержимое; другая панель с тем же файлом покажет его после следующей загрузки своего списка.

Варианты, значения по умолчанию и приоритеты

• variant обязателен: filesList или preview.
• Размеры страницы списка по умолчанию — [4, 5, 10, 15]; первое значение задаёт начальный размер страницы.
• Без grid.itemsInRow число колонок адаптивно подбирает CSS.
• showPreviews управляет миниатюрами в карточках списка; на кнопку со значком глаза и отдельный режим preview он не влияет.
• fileDownload.useModernApi по умолчанию равен false.

Ограничения

• Без выбранного объекта панель не показывает содержимое файлов.
• Панель получает связанные данные фиксированным способом; в JSON нельзя задать собственный запрос файлов.
• Не добавляйте uploadFile в filesList.actions: действие строки работает с файлом и набором данных этой строки, а загрузка файла — действие заголовка для выбранного объекта.
• Предпросмотр зависит от MIME-типа и установленного просмотрщика. Файлы Word, Excel и PowerPoint просмотрщик не отображает.
• Открывая файл в галерее, панель сначала скачивает его целиком (до 1 ГиБ), и только затем просмотрщик его показывает. Просмотрщик получает по одному файлу, поэтому ленты миниатюр и переключения клавишами-стрелками в нём нет; файлы переключают стрелки над ним.

Минимальная конфигурация

{
  "id": "files",
  "type": "files",
  "request": {
    "getSelectedObjectForEventId": "orders--selected"
  },
  "variant": "filesList"
}

Сценарий: управление файлами выбранного заказа

{
  "id": "order-files",
  "type": "files",
  "ui": { "title": "Attachments" },
  "request": {
    "getSelectedObjectForEventId": "orders--selected"
  },
  "variant": "filesList",
  "fileDownload": { "useModernApi": false },
  "filesList": {
    "showPreviews": true,
    "pagination": { "rowsPerPage": [6, 12, 24] },
    "grid": { "itemsInRow": 3 },
    "actions": [
      { "id": "edit-file-metadata", "method": "editDatasetMeta", "label": "Edit metadata", "icon": "pencil" },
      { "id": "replace-file", "method": "replaceDatasetFile", "label": "Replace", "icon": "upload" },
      { "id": "unlink-file", "method": "unlinkDataset", "label": "Unlink", "icon": "times" },
      { "id": "delete-file", "method": "deleteFile", "label": "Delete", "icon": "trash" }
    ]
  },
  "panelActions": [
    { "id": "upload-file", "method": "uploadFile", "label": "Upload", "icon": "plus" }
  ]
}

Ожидаемый результат: после выбора заказа панель запрашивает связанные с ним файлы, загрузка файла выполняется для выбранного заказа, а каждое действие строки — для файла и набора данных этой строки.

Запускаемые демонстрации

Открыть общие сценарии настройки

Откройте вкладку Files и выберите любой заказ. Настоящее хранилище Files запрашивает ObjectToDataSetLink, получает два связанных объекта Dataset, затем вызывает GET /files/:guid/params, чтобы узнать MIME-тип, имя, размер, отметки времени и состояние миниатюры их файлов. Карточки запрашивают GET /files/:guid/thumbnail; кнопка со значком глаза и кнопка скачивания запрашивают исходное содержимое файла через GET /files/:guid.

В этих демонстрационных данных намеренно нет загрузки файлов и действий строки, изменяющих данные. Демонстрация подтверждает привязку к выбору, filesList, предпросмотр, страницы, колонки сетки, метаданные, а также передачу файлов для чтения и скачивания. Разрушающие операции она не проверяет.

Точная справка по параметрам

Страницы параметров пока представлены на английском языке.

• событие выбора
• окно сохранения в браузере
• вариант: список или просмотр
• миниатюры в карточках
• размеры страницы
• колонки сетки
• действия строки
• действия заголовка

Связанные руководства и следующий шаг

• События и условия
• Действия
• Общая конфигурация панели

Далее скопируйте конфигурацию выбора и списка. Загрузку файлов и изменяющие действия строки добавляйте только после того, как отдельно проверите контракты файлов и Dataset на развёрнутом сервере.