Справочник API: Параграф (Макет форматированного текста)

Для любого текста, который требует более одной строки или нескольких стилей (например, слово жирным шрифтом, за которым следует слово курсивом), Skija предоставляет API Paragraph. Он обрабатывает сложные задачи макета, такие как перенос строк, поддержка RTL и многоскриптовый текст.

Три основы параграфов

Создание параграфа включает три основных шага:

1. FontCollection: Определяет, откуда параграф получает шрифты.
2. ParagraphStyle: Определяет глобальные настройки (выравнивание, максимальное количество строк, многоточие).
3. ParagraphBuilder: "Собирает" текст и стили.

1. Настройка FontCollection

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

FontCollection fc = new FontCollection();
fc.setDefaultFontManager(FontMgr.getDefault());

2. Глобальное оформление (ParagraphStyle)

Это определяет, как ведет себя весь блок текста.

ParagraphStyle style = new ParagraphStyle();
style.setAlignment(Alignment.CENTER);
style.setMaxLinesCount(3);
style.setEllipsis("..."); // Показывается, если текст слишком длинный

3. Сборка форматированного текста (ParagraphBuilder)

ParagraphBuilder использует стековый подход к стилям. Вы "помещаете" (push) стиль, добавляете текст и "извлекаете" (pop) его, чтобы вернуться к предыдущему стилю.

ParagraphBuilder builder = new ParagraphBuilder(style, fc);

// Добавляем текст со стилем по умолчанию
builder.pushStyle(new TextStyle().setColor(0xFF000000).setFontSize(16f));
builder.addText("Skija это ");

// Добавляем жирный текст
builder.pushStyle(new TextStyle().setColor(0xFF4285F4).setFontWeight(FontWeight.BOLD));
builder.addText("Мощный");
builder.popStyle(); // Возвращаемся к стилю по умолчанию: 16pt, черный

builder.addText(" и простой в использовании.");

4. Макет и отрисовка

Paragraph нужно "разместить" (измерить и перенести строки) перед тем, как его можно нарисовать. Для этого требуется конкретная ширина.

Paragraph p = builder.build();

// Размещаем текст, чтобы он поместился в 300 пикселей
p.layout(300);

// Рисуем его в точке (x, y)
p.paint(canvas, 20, 20);

Основные методы

• p.getHeight(): Получить общую высоту размещенного текста.
• p.getLongestLine(): Получить ширину самой длинной строки.
• p.getLineNumber(): На сколько строк был перенесен текст.
• p.getRectsForRange(...): Получить ограничивающие прямоугольники для выделения (полезно для подсветки текста).

Производительность и лучшие практики

1. Используйте FontCollection повторно: Обычно для всего приложения нужен только один FontCollection.
2. Основная работа — в layout: p.layout() — самая затратная часть, потому что она включает измерение каждого глифа и расчет переносов строк. Если ваш текст не меняется и ширина та же, не вызывайте этот метод снова.
3. Метрики текста: Используйте p.getLineMetrics(), если вам нужна подробная информация о позиции и высоте каждой строки для сложных UI-макетов.
4. Заполнители (Placeholders): Вы можете использовать builder.addPlaceholder(), чтобы оставить место для встроенных изображений или UI-виджетов внутри потока текста.