Руководство по предпросмотру PDF

Обзор

Блок pdf-preview отображает PDF-файлы встроенно в сообщениях диалога — показывает первую страницу с кнопкой разворачивания для полной навигации по страницам в полноэкранном оверлее.

Ключевой принцип: в отличие от html-preview, для которого требуется transform_data для извлечения HTML, PDF уже являются файлами на диске. Просто укажите путь к файлу напрямую — шаг извлечения не нужен.

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

Используйте pdf-preview, если:

• Результаты инструментов ссылаются на PDF-файл — инструмент Read, загрузка файлов, ответы API с путями к PDF
• Сгенерированные отчёты — скрипты или инструменты, создающие PDF-вывод
• Загруженные документы — PDF, полученные из API или сохранённые из веба
• Пользователь просит посмотреть PDF — любой PDF-файл, который пользователь упоминает или на который ссылается

Не используйте pdf-preview, если:

• Содержимое — структурированные данные — вместо этого используйте datatable или spreadsheet
• Содержимое — HTML — вместо этого используйте html-preview
• PDF — это файл кода/текста — просто прочитайте его и отобразите как markdown
• Пользователь хочет извлечь текст из PDF — вместо этого используйте поддержку PDF в инструменте Read

Базовое использование

Один элемент

```pdf-preview
{
  "src": "/absolute/path/to/file.pdf",
  "title": "Q4 Financial Report"
}
```

Несколько элементов (вкладки)

Если есть несколько связанных PDF (например, квартальные отчёты, версии договора), используйте массив items. Под заголовком появится панель вкладок для переключения между элементами.

```pdf-preview
{
  "title": "Quarterly Reports",
  "items": [
    { "src": "/path/to/q1-report.pdf", "label": "Q1" },
    { "src": "/path/to/q2-report.pdf", "label": "Q2" },
    { "src": "/path/to/q3-report.pdf", "label": "Q3" }
  ]
}
```

Содержимое загружается лениво при переключении вкладок и кэшируется после загрузки.

Поля конфигурации

*Требуется либо src (один), либо items (несколько). Если присутствуют оба, приоритет у items.

Важно: путь в src должен быть абсолютным. Используйте точный путь из результатов инструментов или соберите его с помощью известных путей к папкам.

Частые сценарии

После использования инструмента Read для PDF

Когда инструмент Read читает PDF, файл уже существует на диске. Ссылайтесь на него напрямую:

```pdf-preview
{
  "src": "/Users/john/Documents/report.pdf",
  "title": "Annual Report 2025"
}
```

PDF из загрузки через API

Когда инструмент загружает PDF (например, из ответа API, возвращающего двоичные данные):

1. Файл обычно сохраняется в папку загрузок сессии
2. Укажите сохранённый путь в блоке pdf-preview

```pdf-preview
{
  "src": "/absolute/path/to/downloaded/invoice.pdf",
  "title": "Invoice #12345"
}
```

PDF, сгенерированный скриптом

При запуске Python-скрипта, создающего PDF (например, с reportlab, fpdf2 или weasyprint):

# Пример: генерация PDF с fpdf2
from fpdf import FPDF
import sys

pdf = FPDF()
pdf.add_page()
pdf.set_font('Helvetica', size=16)
pdf.cell(text='Hello World')
pdf.output(sys.argv[-1])

Вызовите через transform_data, затем укажите выходной файл:

```pdf-preview
{
  "src": "/absolute/path/from/transform_data/report.pdf",
  "title": "Generated Report"
}
```

PDF из файловой системы пользователя

Когда пользователь ссылается на PDF, который есть у него локально:

```pdf-preview
{
  "src": "/Users/john/Downloads/contract.pdf",
  "title": "Service Agreement"
}
```

Поведение при отображении

Встроенный предпросмотр

• Показывает только первую страницу с максимальной высотой 400px и нижним градиентным затуханием
• Белый фон — стандарт для PDF-документов
• Кнопка разворачивания (в правом верхнем углу, видна при наведении) открывает полноэкранный просмотр
• Верхняя панель показывает иконку FileText и заголовок
• Нет элементов управления страницами во встроенном режиме — для навигации по нескольким страницам используйте полноэкранный режим

Полноэкранный оверлей

• Полная навигация по страницам с кнопками «предыдущая/следующая»
• Счётчик страниц в формате «Page X / Y»
• Кнопка «Copy path» копирует путь к файлу в буфер обмена
• Бейдж «PDF» в заголовке указывает тип содержимого
• Включены выделение текста и слои аннотаций для интерактивности

Заметки по производительности

• PDF загружаются как двоичные данные (Uint8Array) через IPC — эффективно даже для больших файлов
• Рабочий поток pdf.js обрабатывает декодирование и рендеринг в фоновом потоке
• Встроенный предпросмотр рендерит только страницу 1 — остальные страницы загружаются по запросу в полноэкранном режиме
• Объект файла мемоизируется, чтобы избежать ненужных повторных рендерингов

Интеграция с инструментом Read

Инструмент Read уже поддерживает чтение PDF с параметром pages. Используйте pdf-preview для визуального отображения, а Read — для извлечения текста:

Дерево решений

• Пользователь хочет увидеть документ?
  • Да: используйте pdf-preview (важна визуальная точность)
  • Нет: извлеките текст инструментом Read и отобразите как markdown
• Содержимое уже является PDF-файлом на диске?
  • Да: используйте pdf-preview с прямым путём к файлу
  • Нет:
    • Это HTML? → используйте html-preview
    • Это данные? → используйте datatable/spreadsheet
    • Это двоичные данные из API? → сначала сохраните в файл, затем pdf-preview

Устранение неполадок

«Loading...» отображается бесконечно

• Путь src должен быть абсолютным — не относительным
• Убедитесь, что файл существует по указанному пути
• Проверьте, что файл действительно является PDF (а не переименованный HTML и т. п.)

Пустой/белый предпросмотр

• PDF-файл может быть пустым или повреждённым
• Некоторые зашифрованные PDF требуют пароль — pdf.js не может их отобразить
• Попробуйте открыть файл системным просмотрщиком PDF, чтобы убедиться, что он корректен

Первая страница выглядит обрезанной

• У встроенного предпросмотра максимальная высота 400px — это сделано намеренно
• Нажмите кнопку разворачивания (в правом верхнем углу) для отображения полной страницы
• В полноэкранном режиме страница отображается в полном размере с прокруткой

Ошибка «Failed to render PDF»

• Файл может не быть корректным PDF
• Очень большие PDF (100MB и более) могут не загрузиться — рассмотрите возможность сначала извлечь нужные страницы
• Сканированные PDF отображаются как изображения — это ожидаемое поведение

В полноэкранном оверлее отображается другое содержимое

• Оверлей загружает PDF независимо, по указанному пути к файлу
• Если файл был изменён между встроенной загрузкой и открытием полноэкранного режима, содержимое может отличаться

Текст нельзя выделить во встроенном предпросмотре

• Выделение текста намеренно отключено во встроенном предпросмотре (рендеринг без текстового слоя для производительности)
• Откройте полноэкранный просмотр для поддержки выделения текста — там включён текстовый слой