Counters, Labels, and References - Счётчики, метки и ссылки в tcolorbox

В этом разделе рассматриваются механизмы работы с нумерацией, перекрёстными ссылками и гиперссылками в рамках tcolorbox.

Counters, Labels, and References - Счётчики, метки и ссылки в tcolorbox

В этом разделе рассматриваются механизмы работы с нумерацией, перекрёстными ссылками и гиперссылками в рамках tcolorbox.

1. Основные команды и параметры

1.1. Основные опции для работы с метками

Опция Синтаксис Описание
phantom phantom={\refstepcounter{mycounter}} Выполняет код без видимого вывода (для счётчиков и меток)
nophantom nophantom Отключает ранее заданный phantom код
label label=mylabel Устанавливает метку для ссылок через \ref
phantomlabel phantomlabel=mylabel Аналог label для ненумерованных боксов
step step=mycounter Увеличивает счётчик (\refstepcounter)
step and label step and label={mycounter}{mylabel} Комбинация step + label

Пример базового использования:

\begin{tcolorbox}[
    label=mybox,
    title=Пример с меткой
]
Содержимое бокса. Ссылка: \ref{mybox}.
\end{tcolorbox}

1.2. Типы ссылок

Опция Синтаксис Описание
label is label label is label Использует стандартные \label/\ref (по умолчанию)
label is zlabel label is zlabel Использует \zlabel из пакета zref
label type label type=theorem Задаёт тип ссылки для cleveref/zref-clever
no label type no label type Сбрасывает тип ссылки

Пример с cleveref:

\usepackage{cleveref}
\begin{tcolorbox}[
    label=mytheorem,
    label type=theorem,
    title=Теорема
]
Содержимое. Ссылка: \cref{mytheorem}.
\end{tcolorbox}

1.3. Дополнительные возможности

Опция Синтаксис Описание
nameref nameref=Моё название Текст для \nameref
short title short title=Краткое название Устанавливает nameref и list entry
hypertarget hypertarget=mytarget Создаёт якорь для гиперссылок
bookmark bookmark=Название Добавляет закладку PDF
index index=Термин Добавляет запись в индекс

2. Примеры использования

2.1. Автоматическая нумерация

\newtcolorbox[auto counter]{mybox}[1][]{
    colback=white,
    title=Блок \thetcbcounter,
    #1
}

\begin{mybox}[label=box1]
Первый блок. Ссылка: \ref{box1}.
\end{mybox}

2.2. Работа с гиперссылками

\usepackage{hyperref}
\begin{tcolorbox}[
    hypertarget=target1,
    title=Кликабельный блок
]
\hyperlink{target2}{Перейти к другому блоку}.
\end{tcolorbox}

\begin{tcolorbox}[
    hypertarget=target2,
    title=Целевой блок
]
Этот блок будет целью ссылки.
\end{tcolorbox}

2.3. Индексирование и закладки

\usepackage{imakeidx,bookmark}
\makeindex

\begin{tcolorbox}[
    bookmark=Важная теорема,
    index=Теоремы,
    title=Теорема Пифагора
]
$a^2 + b^2 = c^2$
\end{tcolorbox}

3. Полный пример

\documentclass{article}
\usepackage{tcolorbox}
\usepackage{hyperref,cleveref,bookmark,imakeidx}
\makeindex

\newtcolorbox[auto counter]{theorem}[2][]{
    colback=green!5,
    title=Теорема \thetcbcounter: #2,
    label type=theorem,
    #1
}

\begin{document}

\section{Примеры}

\begin{theorem}[label=pyth]{Пифагора}
$a^2 + b^2 = c^2$
\end{theorem}

Ссылка на \cref{pyth}.

\begin{tcolorbox}[
    bookmark=Демонстрация,
    index=Примеры,
    hypertarget=demo,
    title=Демо-блок
]
Этот блок имеет:
\begin{itemize}
\item Закладку PDF
\item Запись в индексе
\item Якорь для ссылок
\end{itemize}
\end{tcolorbox}

\printindex
\end{document}

4. Важные замечания

  1. Для работы zlabel требуется пакет zref
  2. phantom код выполняется в группе - используйте \global для глобальных изменений
  3. Опции bookmark и index требуют соответствующих пакетов

Вывод

  • Используйте label и phantom для перекрёстных ссылок
  • label type улучшает работу с cleveref
  • hypertarget и bookmark добавляют интерактивности PDF
  • index интегрирует боксы в предметный указатель