Это многостраничный печатный вид этого раздела. Нажмите что бы печатать.
Добро пожаловать в раздел спецпроектов! Здесь вы найдете полезные справочные материалы, инструкции и гайды по различным темам, которые помогут вам в работе, учебе и повседневной жизни.
Здесь вы найдете конкретные методы, основанные на:
Каждый из этих элементов — часть единой мозаики. Внедряя их в повседневность, можно не только избавиться от конкретных недугов, но и создать прочный фундамент для долгой, активной и осознанной жизни.
Этот раздел — для тех, кто готов брать ответственность за свое здоровье в свои руки и искать естественные пути исцеления. Добро пожаловать в мир, где тело, разум и дух работают в согласии!
Здоровье — это не просто отсутствие болезней, а состояние гармонии тела, ума и духа. В этом разделе собраны статьи, посвящённые универсальным практикам укрепления здоровья, которые подходят людям любого возраста и уровня физической подготовки.
Здесь вы найдёте проверенные рекомендации по питанию, движению, ментальному балансу и профилактике заболеваний. Независимо от того, только начинаете ли вы заботиться о себе или ищете способы оптимизировать уже привычный ритм жизни, эти материалы помогут сделать каждый день более энергичным, осознанным и наполненным vitality.
Помните: маленькие, но регулярные шаги к здоровью часто значат больше, чем радикальные изменения. Давайте вместе создавать прочный фундамент для долгой и активной жизни!
Общий массаж обычно проводится в положении лежа на спине, на животе и на боку, охватывая основные группы мышц. Последовательность может варьироваться, но классическая схема выглядит так:
flowchart TD
A[Начало массажа] --> B[Спина]
B --> B1[Поглаживание]
B1 --> B2[Растирание]
B2 --> B3[Разминание]
B3 --> B4[Вибрация]
B4 --> B5[Поглаживание]
B --> C[Шея и воротниковая зона]
C --> C1[Поглаживание]
C1 --> C2[Растирание]
C2 --> C3[Разминание]
C3 --> C4[Поглаживание]
C --> D[Ноги: Задняя поверхность]
D --> D1[Бедро: П-Р-Р-В]
D1 --> D2[Голень: П-Р-Р]
D2 --> D3[Стопа: Растирание]
D --> E[Вторая нога: аналогично]
E --> F[Перед: Грудная клетка]
F --> F1[Поглаживание]
F1 --> F2[Растирание]
F2 --> F3[Разминание]
F --> G[Живот]
G --> G1[Круговые поглаживания]
G1 --> G2[Разминание косых мышц]
G --> H[Руки]
H --> H1[Плечо: П-Р-Р]
H1 --> H2[Предплечье: П-Р-Р]
H2 --> H3[Кисть: Растирание]
H --> I[Лицо-голова]
I --> I1[Поглаживание лба]
I1 --> I2[Массаж волосистой части]
I --> J[Завершение]
J --> J1[Общее поглаживание]
J1 --> K[Конец сеанса]
Время указано ориентировочно и может корректироваться в зависимости от целей (расслабление/тонизирование) и индивидуальных потребностей.
Поглаживание (поверхностное только на кожу) – от поясницы к шее.
Растирание (глубже чем поглаживание, направлено на разогрев подкожной зоны, и немного поверхностных мышц) (пиление, пересекание, ладонные круговые движения) – разогрев поверхностных мышц.
Обязательно после каждого растирания выполнять прием поглаживание
Разминание (щипцеобразное, валяние, сдвигание) – проработка широчайших, трапециевидных и поясничных мышц.
при работе с трацецией, голова пациента повернута в противоположную сторону
после каждого приема выполнять поглаживание
Вибрация (похлопывание, рубление, точечные надавливания).
выполнять в произвольном направлении по всей поверхности спины. Кисти расслаблены, пальцы расслаблены. Постепенно увеличиваем силу воздействия.
По почкам не бить!!!
После каждого воздействия выполняем поглаживание.
Классический массаж шейно-воротниковой зоны направлен на расслабление мышц, улучшение кровообращения, снятие напряжения и профилактику остеохондроза. Зона включает:
Плоскостное поглаживание – ладонями от подлопаточной зоны через надплечья, плечи и обхватывающим движением вниз к подмышечным лимфоузлам и повторяем 3 раза
Скользящее движение до волосистой части головы паравертебрально (пальцы касаются тела тыльной стороной фаланг) и от волосистой части головы прижимаем ладони к коже и с небольшим усилием опускаемся по шее, надплечью, дельта, по боковой линии возвращаемся в исходную точку. Повторяем 3 раза.
Поперечное обхватывающее поглаживание - из стойки сбоку попеременно поглаживание от позвоночника лотерально через надплечье и дельту. Постепенно переходим в движениях к подключичной зоне. Проглаживание выполняем ладонями с небольшим нажимом от позвоночника лотерально, возвращаемся с легким контактом с кожей пациента и повторяем проглаживание лотерально.
Цель: разогрев кожи, улучшение лимфотока.
Прямолинейное и круговое растирание подушечками пальцев вдоль позвоночника и мышц шеи снизу-вверх с переходом на надплечье и трапецию.
Пиление – ребром ладони вдоль паравертебрально и по трапеции перпендикулярно. Немного интенсивнее, чем поглаживание руки стоят с левой и правой стороны позвоночника и совершают растирающие движения в противонаправлении. На второй фазе пропиливаем сначала одну сторону трапеции с постепенным опусканием но нижней части лопатки, затем другую сторону.
Выжимание – всей ладонью от позвоночника лотерально выжимаем через лопаточную зону. Второе выжимание от шеи к дельте через трапецию. Выжимание выполняем плотно прилегающими ладонями от позвоночника лотерально. Сначала выжимаем лопаточную зону, затем поднимаемся вверх к трапеции и шеи. 3-4 повторения. Руки при выполнении выжимания не отрываются от тела пациента. Обратно руки возвращаются легким скольжением по коже в исходную точку.
Цель: усиление кровообращения, размягчение мышечных уплотнений.
После каждого растирающего упражнения выполнить поглаживание.
Вращательное разминание 4-мя пальцами — опора на большой палец и подушечками 4-х пальцев выполняем разминающие вращательные движения и поднимаемся снизу вверх от лопаток к шее (до волосистой части головы). От волосистой части головы по шее и трапециевидной мышце опускаемся к плечевому суставу выполняя вращательные движения подушечками 4-х пальцев с опорой на большой палец. Повторить 2-3 прохода.
Вращательное разминание фалангами пальцев — выполняем разминание по схеме похожей, как описано выше, вращательными движениями от лопаточной зоны до волосистой части головы паравертебрально и от шеи к плечевым суставам, далее вокруг плечевого сустава, плечо, лопаточная зона. Рабочей поверхностью являются тыльные стороны 1-й и 2-й фаланги 4-х пальцев рук с опорой на большой палец. Движения более амплитудные и прорабатывают большую площадь во время вращения. Выполняем 2-3 прохода.
Вращательное разминание большими пальцами — опора на четыре пальца и большими пальцами выполняем разминающие вращательные движения и поднимаемся снизу вверх от лопаток к шее (до волосистой части головы). 2-3 прохода.
Кольцевое разминание – мышца захватывается большим и остальными пальцами, разминается волнообразно (движение рук разнонаправленно навстречу друг-другу). Перекатываем валик. Разминаем лопаточную зону, переходим на зону шеи и трапеции и перекатываем валик не выпуская его. Движение выполняется по спине в сторону подмышечных лимфоузлов. По шее движения выполняются в сторону подключичных лимфоузлов. При переходе между левой и правой стороной трапеции, отдельно прорабатываем волной шейный отдел, слегка оттянув кожу с мышцами на шее.
Поперечное глубокое выжимание — техника выполняется кулочками (тыльной стороной фаланг пальцев рук выжимаем от позвоночника лотерально всю межлопаточную зону от C7-TH6) выполняем стоя сбоку от пациента на противоположной стороне.
Щипцеобразное разминание – мышцы шеи разминаются пальцами, как щипцами. Руки чередуются или выполняем одной рукой с постепенным увеличением силы и глубины проработки.
Проработка мест крепления мышц шеи по основанию черепа – мягкими вращательными движениями большим пальцем с опорой на четыре пальца проработать места крепления мышц шеи к основанию черепа. Отдельно проработать проблемные зоны. На шее, трапеции, лопатках.
Проработка межлопаточной зоны — глубокими пунктирными движениями от позвоночника к лопатке проработать межлопаточные мышцы. Используйте технику проработки суставами 2-3-й фаланги пальцев с нажимом и легким подкручиванием по ходу движения руки.
Цель: глубокая проработка мышц, снятие спазмов.
После каждого разминающего действия выполнить поглаживание.
Цель: активизация нервных окончаний, улучшение тонуса.
Эффект: снятие боли, улучшение подвижности шеи, снижение усталости, профилактика мигреней.
Смысл буддийских медитаций заключается в глубоком внутреннем исследовании, позволяющем напрямую пережить и осознать Четыре Благородные Истины, закон кармы, принцип анатмана (не-я) и элементы Восьмеричного пути. Через практики осознанности (сатипаттхана), сосредоточения (самадхи) и аналитической медитации (випассана) практикующий развивает ясность ума, которая раскрывает: непостоянство и страдательную природу существования (дуккха), причины страдания в виде жажды и неведения, возможность освобождения через угасание привязанностей, а также действенность Восьмеричного пути как средства трансформации сознания.
Медитация становится лабораторией, где теоретические положения Дхармы проверяются на личном опыте – наблюдая возникновение и исчезновение мыслей, эмоций и ощущений, практик убеждается в иллюзорности “я” (анатман) и закономерности кармических последствий, что постепенно освобождает ум от омрачений и ведет к пробуждению.
(материал для медитаций 9-10-11-12-13)
Перед медитацией важно вспомнить Четыре Благородные Истины и принцип анатмана (отсутствия “Я”), чтобы направить ум к правильному пониманию.
Настройка:
Когда вы осознаёте, что неведение — это ошибочное восприятие реальности, происходит ослабление кармических связей.
Результат:
Эта медитация — не разовое действие, а постепенное очищение ума. Чем чаще вы наблюдаете проявления неведения, тем слабее его власть.
Перед медитацией вспомните:
Настройка:
Когда сознание перестаёт цепляться:
Финальное осознание:
“Нет ни глаза, ни уха, ни носа, ни языка, ни тела, ни ума.
Нет ни форм, ни звуков, ни запахов, ни вкусов, ни прикосновений, ни мыслей.
Нет ни наблюдателя, ни наблюдаемого.
Есть только свобода – за пределами сансары.”
Разбираем каждый компонент ума:
a) Чувства (ведана)
b) Восприятие (сання)
c) Воля (четана)
d) Контакт (пхасса)
e) Внимание (манасикара)
Итог:
«Нама – это набор функций, как программа. Нет „пользователя“ за ними».
Заключительная фраза:
«Нама-Рупа – как река.
Я – не капля в ней, я – тот, кто видит реку.
Когда видение становится абсолютным, река исчезает.
Остаётся только свобода».
Через глубокое наблюдение мы увидим, как привязанности и желания, возникающие в этих сферах, приковывают нас к страданиям. Осознав их природу, мы сможем ослабить их хватку и сделать шаг к освобождению от колеса сансары.
Примите удобное положение сидя с прямой спиной. Закройте глаза или опустите взгляд. Настройтесь на естественное дыхание, позволяя телу расслабиться.
“Позвольте уму успокоиться. Ощутите, как дыхание входит и выходит, не цепляясь ни за что. Пусть тело и ум придут в состояние тихого, ясного присутствия.”
Обратите внимание на то, что видите, даже если глаза закрыты. Заметьте свет, тени, образы.
“Осознайте: глаза воспринимают формы, цвета, но сами по себе они лишь инструменты. Видимое — непостоянно, оно приходит и уходит. Не цепляйтесь за зримые образы, не отвергайте их. Просто наблюдайте, как они появляются и исчезают, не создавая желания или отвращения.”
Прислушайтесь к звукам вокруг: далёким и близким, громким и тихим.
“Звуки возникают и растворяются в пустоте. Уши улавливают их, но сами звуки не имеют собственной природы. Позвольте им быть, не цепляясь за приятное, не сопротивляясь неприятному. Просто слушайте, как эхо в горах — оно приходит и уходит само.”
Ощутите запахи вокруг: может, аромат благовоний, воздуха или просто отсутствие запаха.
“Запахи приходят и уходят, как ветер. Нос их воспринимает, но они не принадлежат вам. Не стремитесь удержать приятный аромат, не избегайте неприятного. Осознайте их мимолётность.”
Ощутите вкус во рту: нейтральный, сладкий, горький — какой есть.
“Вкус — лишь временное явление. Даже самый изысканный вкус исчезает. Не жаждите его продления, не бегите от горечи. Наблюдайте, как вкус растворяется в пустоте.”
Почувствуйте прикосновение одежды, воздуха, поверхности, на которой сидите.
“Ощущения в теле постоянно меняются: тепло, холод, давление, лёгкость. Они непостоянны. Тело — лишь проводник, а не владелец этих чувств. Позвольте им приходить и уходить, не отождествляясь с ними.”
Наблюдайте за потоком мыслей и эмоций.
“Ум создаёт образы, воспоминания, желания. Но мысли — как облака: они появляются и исчезают. Не цепляйтесь за них, не подавляйте. Осознайте: ум — лишь шестая сфера чувств, а не “я”. Наблюдайте за ним со стороны, как за течением реки.”
Теперь осознайте, как через эти шесть сфер возникают желания:
“Позвольте шести сферам быть, но не позволяйте им управлять вами. Как зеркало отражает, но не цепляется за отражения, так и вы — осознавайте, но не цепляйтесь.”
Представьте, как все ощущения, мысли, восприятия проходят сквозь вас, не оставляя следа.
“Шесть сфер чувств — лишь врата, а не дом. Вы — не тело, не ум, не чувства. Вы — осознавание за пределами всех форм. Сансара держится на привязанности к чувствам, но когда осознаёшь их пустоту — колесо останавливается.”
Побудьте в этом состоянии чистого осознания, без цепляния, без отождествления.
Медленно возвращайтесь к обычному восприятию. Пошевелите пальцами, ощутите тело. Откройте глаза.
“Пусть это осознание шести сфер чувств остаётся с вами в повседневной жизни. Наблюдайте, но не цепляйтесь. Так вы ослабите оковы сансары и приблизитесь к освобождению.”
Осознав природу контакта, мы можем прервать автоматические реакции ума и остановить вращение колеса сансары.
Примите удобную позу, закройте глаза. Дышите естественно, отпуская напряжение.
“Пусть тело успокоится, а ум станет ясным и бдительным. Осознайте настоящее мгновение — здесь и сейчас.”
Напомните себе:
*“Контакт происходит в шести сферах:
“Каждый миг где-то происходит контакт. Но кто его хозяин?”
Ощутите прикосновение одежды, воздуха, поверхности под вами.
“Есть тело, есть касание, есть сознание прикосновения. Но нет того, кто ощущает. Есть лишь процесс: “тело → касание → осознавание”. Нет “я” в этом контакте.”
Прислушайтесь к любому звуку.
“Звук ударяет в ухо, возникает слуховое сознание. Но где “слушатель”? Нет никого за этим процессом — только пустота, в которой звук появляется и исчезает.”
Наблюдайте мысль.
“Ум соприкоснулся с образом, памятью, идеей. Возникло умственное сознание. Но это не “моя” мысль. Она пришла из ниоткуда и уйдёт в никуда. Нет “я”, которое думает.”
*“Обычно мы говорим: “Я вижу”, “Я слышу”, “Я чувствую”. Но где это “я”?
“Контакт происходит, но никто не контактирует. Ощущение есть, но никто не ощущает. Всё происходит само — без хозяина, без “я”.”
Теперь проследите, как из контакта рождается страдание:
“Но если увидеть, что в контакте нет “я”, то где тогда жажда? Где цепляние? Где страдание? Всё рассыпается, как песочный замок.”
Перенесите внимание на то, что осознаёт сам контакт.
“Кто знает, что есть контакт? Кто наблюдает? Даже этот вопрос — лишь мысль, ещё один контакт. Вернитесь в тишину до всяких ярлыков.”
“Нет глаза, нет формы, нет зрения — есть лишь чистое осознавание, в котором всё возникает и исчезает. Это и есть свобода.”
Медленно возвращайтесь к обычному восприятию. Пошевелите пальцами, откройте глаза.
“Пусть это понимание контакта остаётся с вами. Всякий раз, когда возникает ощущение, спрашивайте: “Кто чувствует?” И увидите: есть лишь процесс, но нет страдающего. Так колесо сансары теряет свою силу.”
Сядьте в удобную позу, закройте глаза. Дышите спокойно.
*“Чувства возникают в шести сферах:
“Все они мимолетны. Ни одно чувство не длится вечно. Но ум цепляется за приятное и бежит от неприятного — так вращается колесо сансары.”
Спросите себя:
Не пытайтесь изменить его — просто знайте, что оно есть.
“Это чувство уже меняется. Даже сильная боль ослабевает, даже великая радость уходит. Оно не принадлежит вам — оно просто проходит через вас.”
*“Обычно мы говорим: “Мне больно”, “Мне приятно”. Но где это “я”?
Проследите механизм сансары:
“Но если чувство осознано как пустое и безличное — жажда не возникает. Нет жажды — нет привязанности. Нет привязанности — нет страдания.”
Теперь — ключевой момент: прекратите кормить чувства вниманием.
“Чувства подобны искрам — если не раздувать их, они гаснут сами.”
Перенесите внимание на того, кто знает чувства.
“Кто осознаёт, что есть чувство?
Даже этот вопрос — лишь мысль.
Вернись в тишину, где нет ни приятного, ни неприятного — только чистое знание.”
“Когда чувства больше не владеют тобой — колесо сансары останавливается.”
Медленно вернитесь к обычному восприятию. Пошевелите пальцами, откройте глаза.
“Пусть эта осознанность сопровождает тебя всегда.
Приятное приходит — не цепляйся.
Неприятное приходит — не сопротивляйся.
Нейтральное — не игнорируй.
Так ты разорвешь оковы чувств и выйдешь из круга страданий.”
Как применять в жизни:
Эта практика ведёт к вираге (бесстрастию) и ниродхе (прекращению возникновения страдания).
Жажда (Танха) – это тот крючок, который цепляет нас за колесо сансары. Она проявляется в трех формах:
Эта медитация поможет вам распознать и растворить механизм жажды в самом его корне.
Примите удобную позу. Закройте глаза. Сделайте три глубоких вдоха и выдоха.
“Обратите внимание: прямо сейчас в вашем уме уже есть какие-то желания. Может быть, это тонкое ожидание приятного переживания от медитации? Или легкое раздражение от постороннего звука? Это и есть проявления жажды – тяга к приятному и отвращение от неприятного.”
Вспомните недавнее желание:
“Посмотрите: когда возникает это желание, появляется напряжение. Ум создает образ того, чего нет, и страдает от этого разрыва между реальностью и фантазией. Но где вы будете, когда получите желаемое? То же самое “я” будет искать новое желание.”
Обратите внимание на:
“Эта жажда заставляет нас бесконечно совершенствоваться, но куда? Каждое достижение рождает новую цель. Нет конца этому бегу.”
Наблюдайте:
“Даже отрицание – это форма жажды. Пытаясь убежать от чего-то, мы по-прежнему привязаны к этому через сопротивление.”
Проследите цепочку:
“Разорвите эту цепь на третьем шаге. Когда появляется приятное чувство – просто осознайте его, не превращая в желание.”
Выберите небольшое текущее желание (например, желание почесаться или изменить позу).
*“Осознайте это желание, но не удовлетворяйте его сразу. Наблюдайте, как оно:
Вы увидите: жажда – это просто волна в уме. Она приходит и уходит, если ее не подпитывать.”*
Когда возникает сильное желание, спросите:
“Вы обнаружите: нет того, кто желает – есть лишь пустой процесс возникновения мысли.”
Представьте, что ваш ум – это океан. Жажда – это волны на поверхности.
“Не пытайтесь остановить волны – это создаст новые волны усилий. Просто осознайте глубину океана под ними. В этой глубине нет жажды – есть лишь покой.”
Перенесите внимание на того, кто осознает желания.
“Кто знает, что есть жажда?
Этот вопрос тоже исчезает…
Остается лишь чистое пространство осознавания,
в котором желания возникают и растворяются,
как узоры на воде.”
Медленно возвращайтесь к обычному состоянию. Пошевелите пальцами. Откройте глаза.
“Пусть это понимание сопровождает вас.
Когда появляется желание – встречайте его как гостя,
но не как хозяина.
Так вы перестанете быть рабом жажды
и сделаете шаг к свободе.”
Помните: Нет жажды – нет цепляния. Нет цепляния – нет кармы. Нет кармы – остановка колеса сансары.
mindmap
root((Факт-карта:<br>Мой муж))
1. Четыре Благородные Истины
1.1 Дуккха
▪ Его равнодушие ранит
▪ Конфликты вызывают боль
1.2 Причина
▪ Ожидание идеального поведения
▪ Привязанность к "моему" счастью
1.3 Прекращение
▪ Отпускание требований
▪ Принятие несовершенства
1.4 Путь
▪ Практика правильной речи
▪ Развитие осознанности
2. Закон кармы
2.1 Его карма
▪ Поведение — следствие прошлых причин
▪ Обусловленности характера
2.2 Моя карма
▪ Гнев создает будущие страдания
▪ Терпение улучшает отношения
3. Анатта Не-я
3.1 Нет неизменной сущности
▪ Он — поток меняющихся состояний
▪ "Плохой муж" — временный ярлык
3.2 Мои проекции
▪ Приписывание постоянных качеств
▪ Ошибка отождествления
4. Иллюзорность мира
4.1 Ожидания как иллюзия
▪ "Он должен..." — конструкция ума
▪ Брачные роли — социальный договор
4.2 Реальность без ярлыков
▪ Конфликт существует только в восприятии
▪ Пустота форм
Визуализация факт-карты
Анализ через Четыре Истины
Размышление о карме
Созерцание анатты
Прорыв иллюзии
Итог: Этот метод помогает не только анализировать отношения, но и трансформировать своё восприятие, уменьшая страдания через мудрость.
Объект исследования: Моя жена
Итог: Правильные взгляды помогают увидеть жену без искажений эго и уменьшить страдания в отношениях.
Объект исследования: Мой муж
Итог: Эта практика помогает увидеть мужа без искажений эго и снизить уровень страданий в отношениях.
Объект исследования: Мой муж
mindmap
root((Правильные намерения<br>Самма санкаппа))
Устранить
Жажда - "Требование идеала"
Злоба - "Обиды и проекции"
Жестокость - "Месть за боль"
Культивировать
Метта - Добрые пожелания
Каруна - Понимание его боли
Упеккха - Свобода от ожиданий
Действия
Речь - Без обвинений
Мысли - "Он тоже страдает"
Медитация - Визуализация света
① Жажда (Танха)
② Злоба (Доса)
③ Жестокость (Вьяпада)
① Культивирование доброжелательности (Метта)
② Развитие сострадания (Каруна)
③ Воспитание непривязанности (Упеккха)
| Ситуация | Старое намерение | Новое намерение | Действие |
|---|---|---|---|
| Он забыл о важной дате | «Он специально меня игнорирует!» | «Возможно, он перегружен. Я спокойно напомню» | Сказать: «Я ценю, когда ты помнишь такие моменты. Давай вместе отметим в выходные?» |
| Он критикует меня | «Он меня не уважает!» | «Его слова — его тревоги, а не моя суть» | Глубокий вдох - ответить: «Я услышала тебя. Давай обсудим это без обвинений» |
Итог: Правильные намерения перестраивают кармические паттерны, превращая конфликты в возможности для роста. Как сказал Будда: «Ненависть не прекращается ненавистью. Она прекращается только любовью».
Эта карта — инструмент для ежедневной работы. Пересматривайте её каждую неделю, отмечая прогресс.
Объект исследования: Моё общение с мужем
| Аспект | Что есть сейчас | К чему приводит (дуккха) | Кармические последствия | Как практиковать |
|---|---|---|---|---|
| ① Ложь | Умалчиваю свои истинные чувства («Всё нормально») | Накопление обиды, потеря доверия | Цикл недопонимания → усиление одиночества | Говорить правду мягко: «Я чувствую грусть, когда ты отдаляешься» вместо молчания |
| ② Сплетни | Жалуюсь подругам: «Он никогда меня не слышит!» | Рост негатива, проецирование образа «плохого мужа» | Укрепление разобщённости в отношениях | Обсуждать проблемы напрямую с ним, без оценок: «Мне важно, чтобы мы слышали друг друга» |
| ③ Грубость | Кричу: «Ты вообще думаешь хоть иногда?!» | Мгновенная боль → долгие обиды | Карма гнева → ответная агрессия или холодность | Пауза перед реакцией. Замена на: «Я злюсь, потому что…» (без «ты-обвинений») |
| ④ Пустословие | Часы разговоров о бытовых мелочах без смысла | Усталость, ощущение пустоты в общении | Трата энергии на бесполезную карму | Сократить болтовню. Задать осмысленный вопрос: «Что для тебя важно сейчас?» |
① Этический (что исключить)
② Психологический (мотивы речи)
③ Медитативный (осознанность)
mindmap
root((Объект:<br>Моя речь с мужем))
1. Текущие проблемы
1.1 Ложь
▪ "Говорю 'Всё нормально', когда обижена"
1.2 Сплетни
▪ "Жалуюсь маме на его привычки"
1.3 Грубость
▪ "Кричу в ссорах"
1.4 Пустословие
▪ "Часы разговоров ни о чём"
2. Последствия
2.1 Мои страдания
▪ "Накопление обиды"
2.2 Его страдания
▪ "Он закрывается"
2.3 Карма
▪ "Цикл взаимных обид"
3. Практика изменений
3.1 Замены
▪ Ложь → "Я чувствую..."
▪ Крик → Пауза + "Я-высказывания"
3.2 Упражнения
▪ "Три вопроса" перед речью
▪ День метта-речи
4. Связь с Восьмеричным путём
4.1 С взглядами
▪ "Речь отражает мои заблуждения"
4.2 С намерениями
▪ "Говорю из гнева или любви?"
4.3 С действиями
▪ "Слова согласуются с поступками"
5. Прогресс
5.1 Успехи
▪ "Не кричала неделю"
5.2 Трудности
▪ "Сложно избегать сплетен"
Центральный объект - фокус исследования (ваше общение)
5 основных ветвей:
Формат записей:
▪ Конкретные примеры из вашей жизни
▪ Стрелки трансформации (ложь → “Я-высказывания”)
Как использовать:
«Пусть мои слова будут мягкими, как лепестки, и правдивыми, как земля под ногами» (парафраз буддийской молитвы).
Объект исследования: Мои повседневные поступки в отношениях с мужем
mindmap
root((Факт-карта<br>Самма камманта))
Основные принципы
["Не вредить"]
Физические действия
Эмоциональные воздействия
Кармические последствия
["Помогать"]
Акты щедрости
Поддержка
Совместная практика
Уровни анализа
Этический
Запрещённые действия
Границы дозволенного
Психологический
Мотивация
Эмоциональные триггеры
Медитативный
Осознание тела
Наблюдение импульсов
Практические инструменты
Упражнение "Три действия"
Утренний ритуал
Дневное наблюдение
Вечерняя практика
Метта-ритуалы
Безусловная помощь
День без жалоб
Связи с Восьмеричным путём
Правильные взгляды
Правильная речь
Правильный образ жизни
Пример медитации
Восстановление ситуации
Анализ телесных реакций
Ментальная репетиция
| Принцип | Что есть сейчас | К чему приводит (дуккха) | Кармические последствия | Как практиковать |
|---|---|---|---|---|
| ① Не вредить | Кричу во время ссор, хлопаю дверьми | Муж замыкается, растёт дистанция | Цикл взаимной агрессии - разлад | Заменить физические реакции на паузу и дыхание (3 вдоха перед действием) |
| Игнорирую его просьбы («Сделаю потом») | Накопление resentment (скрытой обиды) | Карма безответственности - потеря доверия | Выполнять мелкие просьбы сразу («Помогу с посудой сейчас») | |
| ② Помогать | Жду, чтобы он первый проявлял заботу | Ощущение «нам нечего дать друг другу» | Карма ожидания - застой в отношениях | Инициатива без условий: приготовить его любимое блюдо «просто так» |
| Экономлю на общих праздниках («Деньги важнее») | Потеря радости в совместном быте | Карма скупости - обеднение эмоций | Вложиться в переживание (например, устроить пикник вместо дорогого ресторана) |
Перед поступком спрашивать:
Алгоритм:
Эффект: Постепенная перестройка автоматических реакций.
Фокус: Повседневные выборы, влияющие на карму.
mindmap
root((Личный образ жизни<br>Цель: Осознанное потребление без вреда))
Финансы
"Чистые" расходы
Этичные бренды
Локальные производители
Отказ от fast-fashion
Инвестиции
"Зелёные" вклады
Бойкот вредных корпораций
Ресурсы
Энергия
Солнечные панели
Снижение потребления
Вода
Фильтрация вместо бутилированной
Сбор дождевой воды
Социальные привычки
Цифровая гигиена
Осознанное использование соцсетей
Отказ от токсичного контента
Семейные ритуалы
Вегетарианские ужины
Совместная медитация
Действия:
Наводящие вопросы:
Пример замены:
| Текущее | Альтернатива |
|---|---|
| Фаст-фуд | Веганское кафе |
| Бытовая химия | Эко-средства |
Практика:
Контрольные точки:
Фокус: Этичность источника дохода.
mindmap
root((Профессиональная этика<br>Цель: Работа как служение))
Этический аудит
Вредные аспекты
Производственные цепочки
Клиенты/партнёры
Экологический след
Альтернативы
Перевод в этичное подразделение
Смена специализации
Ресурсный баланс
Время
Соотношение работы/практики
Осознанные перерывы
Энергия
Не навреди коллегам
Эмоциональный интеллект
Трансформация
Минимальная планка
Отказ от откровенно вредных задач
Идеальный сценарий
Создание этичного стартапа
Профпереподготовка
Шаги:
Ключевые вопросы:
Пример трансформации:
| Должность | Проблема | Решение |
|---|---|---|
| Менеджер | Продажа кредитов | Перейти в микрофинансы НКО |
Действия:
Вопросы для рефлексии:
Фокус: Влияние на макросистемы.
mindmap
root((Глобальная ответственность<br>Цель: Сангха как модель общества))
Системные рычаги
Политика
Голосование за концепции человечности (Русский космизм)
Участие в экодвижениях
Экономика
Банки с этичной политикой
Технологии очищающие Планету
Невидимые связи
Цифровая карма
Хостинг на "чистой" энергии
Блокировка токсичных ресурсов
Пищевые цепочки
Бойкот монокультур
Поддержка пермакультуры
Утопическая матрица
Общинные модели
Экопоселения
Кооперативы
Образование
Просветительские курсы
Практика:
Вопросы:
Конкретные шаги:
Чек-лист вовлечённости:
Пример структуры:
Текущее состояние: [Конкретная проблема, например: «Каждый спор с женой переходит в крик»]
Вопросы для анализа:
Как использовать:
Важно: Не пытаться охватить всё сразу. Лучше медленные, но устойчивые изменения.
— это коренная причина страданий и циклического перерождения. Это первое звено в цепи “12 звеньев взаимозависимого возникновения” (пратитья-самутпада), которая удерживает существ в сансаре.
Это фундаментальное непонимание истинной природы реальности, проявляющееся в:
Из-за авидьи возникают:
Через пробуждение (бодхи):
Пример:
Как человек в темноте принимает верёвку за змею, так и мы из-за авидьи видим в мире то, чего нет. Просветление — это свет, рассеивающий тьму неведения.
“Неведение — величайшая тьма,
Мудрость — величайшее сокровище”.
— Дхаммапада
что означает “формирующие факторы” или “кармические импульсы”. Они возникают из первого звена — Неведения (авидьи) — и запускают цепь кармических последствий, ведущих к новым перерождениям.
Это:
Важно: Санскары — это не фатум, а привычки ума. Буддизм учит, что их можно изменить через практику!
“Ум — предтеча всех состояний.
Если кто-то говорит или действует с нечистым умом,
страдание следует за ним, как колесо за следом быка.”
— Дхаммапада 1:1
Сознание (виджняна на санскрите, винняна на пали) — это третье звено в цепи зависимого возникновения (пратитья-самутпада), следующее за санскарами (кармическими импульсами). Оно играет ключевую роль в процессе перерождения и формировании опыта.
Это не постоянная душа, а поток осознавания, который:
В буддизме выделяют 6 видов сознания, связанных с органами чувств и умом:
📌 Пример:
Представь, что сознание — это река, а кармические отпечатки (санскары) — это краска, которая окрашивает её течение. В зависимости от “цвета” кармы, река (сознание) течёт в сторону счастливого или несчастливого перерождения.
Поскольку сознание зависит от неведения и кармы, освобождение (нирвана) достигается через:
“Когда мудрый уничтожает неведение знанием,
сознание, лишённое опоры, не возникает вновь.”
— СН 12.38 (Саньютта-никая)
Это психофизическая основа будущего существа, возникающая после того, как сознание (виджняна) входит в новое рождение.
Пример из человеческого рождения:
После зачатия сознание + карма формируют:
Пятое звено — это возникновение шести органов восприятия, через которые существо взаимодействует с миром:
Почему это важно?
Шестое звено — момент соприкосновения органа чувств, объекта и сознания:
Пример:
Когда вы видите красивый предмет (форма), глаз (орган) и сознание соединяются — возникает “контакт”, который может породить желание или отвращение.
Седьмое звено — ощущение от контакта:
Ключевой момент:
Само по себе чувство — ещё не страдание, но реакция на него запускает следующее звено…
Восьмое звено — желание или отвращение, возникающее из чувств:
Пример:
Вы едите сладкое → возникает приятное чувство → появляется жажда съесть ещё.
Девятое звено — усиление жажды в цепляние:
Чем сильнее цепляние, тем болезненнее рождение.
Десятое звено — формирование новой кармы для перерождения:
Пример:
Ненависть → карма → рождение в мире страданий.
Щедрость → карма → рождение в благоприятных условиях.
Одиннадцатое звено — фактическое новое рождение в одном из 6 миров сансары:
Рождение неизбежно ведёт к смерти. Любое рождение является причиной смерти.
Двенадцатое звено — завершение цикла:
Через пробуждение (бодхи):
“Кто видит зависимое возникновение — тот видит Дхарму.”
— Будда
Четыре Благородные Истины — это основа учения Будды, которое он впервые изложил в своей проповеди в Сарнатхе после Просветления. Они описывают природу страдания и путь к его прекращению.
“Рождение — страдание, старость — страдание, болезнь — страдание, смерть — страдание. Соединение с неприятным — страдание, разлучение с приятным — страдание. Не получить желаемого — страдание. Короче говоря, пять совокупностей, подверженных цеплянию, — это страдание.”
— Дхаммачакка-паваттана Сутта
Пример: Даже радость от встречи с близким человеком содержит семя страдания, потому что рано или поздно придётся расстаться.
“Это жажда, ведущая к новым рождениям, связанная с наслаждением и страстью, ищущая удовольствия то здесь, то там; а именно: жажда чувственных наслаждений, жажда существования и жажда несуществования.”
“Это полное угасание и прекращение этой самой жажды, отказ от неё, отбрасывание, освобождение, оставление её.”
Пример: Представь, что ты нёс тяжёлый камень и наконец положил его. Вот что такое нирвана — конец ноши страдания.
“Это Благородный Восьмеричный Путь, то есть: правильные взгляды, правильные намерения, правильная речь, правильные действия, правильный образ жизни, правильные усилия, правильная осознанность, правильное сосредоточение.”
Это практический метод для устранения причин страдания.
Три группы практики:
Мудрость (Праджня)
Нравственность (Шила)
Сосредоточение (Самадхи)
Пример: Как врач ставит диагноз (1-я истина), находит причину болезни (2-я), подтверждает возможность излечения (3-я) и назначает лечение (4-я).
“Как океан имеет один вкус — вкус соли, так и учение Будды имеет один вкус — вкус освобождения.”
— Упали-сутта
Это практическое руководство, данное Буддой для прекращения страдания (дуккхи) и достижения пробуждения (нирваны). Он объединяет мудрость, нравственность и сосредоточение в единую систему.
Правильные взгляды – это первый и фундаментальный шаг Восьмеричного пути, формирующий основу для всей буддийской практики. Это не просто интеллектуальное знание, а глубокое понимание истинной природы реальности, освобождающее ум от заблуждений.
Правильные взгляды начинаются с осознания:
1. Истины о страдании (дуккха) – жизнь непостоянна и пронизана неудовлетворённостью.
2. Истины о причине страдания (танха) – его корень в жажде, привязанности и неведении.
3. Истины о прекращении страдания (ниродха) – освобождение возможно через устранение причин.
4. Истины о пути (марга) – Восьмеричный путь ведёт к прекращению страданий.
Пример:
Пример:
Пример:
Будда выделял 10 видов заблуждений, которые искажают восприятие:
Пример:
Правильные взгляды – это не теория, а образ мышления, который проявляется в:
✔ Осознанности – наблюдении за умом без отождествления.
✔ Анализе – «Это страдание? Каков его источник?».
✔ Отказе от крайностей – избегании фанатизма и цинизма.
Пример из жизни:
Вывод:
Правильные взгляды – это путь от неведения к мудрости. Они не навязываются слепо, а проверяются личным опытом, ведя к подлинной свободе.
Следующий шаг – Правильные намерения (Самма санкаппа), где эти взгляды превращаются в мотивацию к действию.
Правильные намерения — это развитие чистых и благотворных мотивов, которые лежат в основе наших мыслей, слов и поступков. Этот шаг тесно связан с первым — Правильным воззрением, поскольку понимание истинной природы реальности (непостоянства, страдания и отсутствия вечного “я”) формирует основу для искренних и мудрых намерений.
Правильные намерения предполагают осознанный отказ от трех корней неблагой кармы:
Эти три яда ума порождают страдание, поэтому их преодоление — ключ к духовному развитию.
Вместо негативных побуждений практикующий развивает три противоположных, но взаимосвязанных качества:
Правильные намерения — это не просто подавление негативных мыслей, а их замена позитивными. Например:
Этот процесс требует осознанности (сати) и постоянной практики, включая медитацию любящей доброты (метта-бхавана).
Самма санкаппа укрепляет нравственную дисциплину (шила) и создает основу для правильной речи, действий и образа жизни. Без чистых намерений даже внешне благие поступки могут быть омрачены скрытыми мотивами.
Таким образом, Правильные намерения — это внутренняя работа по очищению ума, ведущая к подлинной гармонии, мудрости и освобождению от страданий.
В традиционном изображении колеса сансары (бхавачакра) три основных яда ума, соответствующие корням страдания, символизируются тремя животными в центре колеса Сансары:
Жажда (танха, или лобха — жадность)
Злоба (вьяпада, или доса — ненависть)
Заблуждение (моха — неведение)
В колесе сансары животные часто изображены кусающими друг друга, образуя замкнутый круг. Это показывает, как три яда подпитывают друг друга:
В контексте Самма санкаппы (Правильных намерений) акцент делается на вьяпаду (злобу) и вихимсу (жестокость) как проявления ненависти, а моха (неведение) рассматривается отдельно — как корень всех омрачений. Однако в колесе сансары три яда представлены в их фундаментальном единстве.
Три животных в центре бхавачакры — наглядная иллюстрация того, как жажда, злоба и неведение удерживают существ в цикле страданий. Преодоление этих ядов через Правильные намерения (развитие доброжелательности, сострадания и мудрости) — ключ к выходу из сансары.
Будда учил, что яды ума — это привычные шаблоны, которые можно заменить осознанной практикой:
Пример:
Эти антидоты эффективны только вместе с Правильными взглядами (Самма диттхи). Например:
Вывод:
Преодоление ядов — не подавление, а трансформация ума через системную работу:
Правильная речь – третий шаг Восьмеричного пути, формирующий основу этичного взаимодействия с миром. Это не просто запрет на определённые слова, а глубокая практика осознанности в общении, направленная на прекращение страдания – как своего, так и чужого. В буддизме речь считается мощным кармическим действием: она может исцелять или ранить, объединять или разрушать.
Вывод:
Правильная речь – это медитация в действии. Она очищает карму, строит доверие и приближает к пробуждению.
Следующий шаг – Правильные действия (Самма камманта), где принципы переносятся на поступки.
Правильные действия – четвёртый шаг Восьмеричного пути, воплощающий мудрость и сострадание в повседневных поступках. Это не просто свод запретов, а осознанный выбор поведения, который уменьшает страдания и создаёт условия для духовного роста. В буддизме тело считается инструментом кармы, поэтому каждое действие – это семя, из которого вырастают последствия.
Вывод:
Правильные действия – это практика мудрости в движении. Они превращают теорию Дхармы в живую реальность, создавая основу для медитации и пробуждения.
Следующий шаг – Правильный образ жизни (Самма аджива), где принципы применяются к профессии и социуму.
Правильный образ жизни — пятый шаг Восьмеричного пути, объединяющий все предыдущие принципы (взгляды, намерения, речь, действия) в целостную систему повседневного бытия. Это не просто отказ от «плохих» профессий, но глубокая переоценка своего места в мире, где работа, потребление и социальные отношения становятся частью духовной практики.
Вывод:
Правильный образ жизни — это медитация в социуме. Он превращает каждый день в путь к пробуждению.
Следующий шаг — Правильное усилие (Самма ваяма), где фокус смещается на работу с умом.
Правильные усилия — шестой шаг Восьмеричного пути, формирующий осознанный контроль над умственными процессами. Это не борьба с собой, а искусство трансформации сознания через системную работу с мыслями, эмоциями и привычками. Будда сравнивал этот процесс с уходом за садом: нужно выпалывать сорняки и взращивать цветы.
Решение:
Работать не «против» тьмы, а «за» свет — через развитие противоположных качеств.
Вывод:
Правильные усилия — это топливо для духовного пути. Они превращают теорию в живую трансформацию.
Следующий шаг — Правильное осознавание (Самма сати), углубляющее внимание к настоящему моменту.
Правильная осознанность — седьмой шаг Восьмеричного пути, представляющий собой чистое, нецепляющееся внимание к реальности «здесь и сейчас». Это не просто концентрация, а глубинное понимание природы ума и тела, раскрывающее Четыре Благородные Истины в непосредственном опыте. Будда называл осознанность «единственным путём» (Сатипаттхана-сутта), ведущим к освобождению.
| Ошибка | Решение |
|---|---|
| Попытки «остановить» ум | Позволять мыслям приходить и уходить |
| Самокритика за отвлечения | Принимать их как часть практики |
| Ожидание «озарений» | Фокусироваться на процессе, а не результате |
Вывод:
Правильная осознанность — это прямой путь к ниббане. Она превращает каждый момент в возможность пробуждения.
Следующий шаг — Правильное сосредоточение (Самма самадхи), углубляющее осознанность до единения с объектом.
Правильное сосредоточение — завершающий шаг Восьмеричного пути, представляющий собой глубинное состояние медитативного погружения, где ум становится единым с объектом созерцания. Это не просто “расслабление”, а мощный инструмент для прорыва сквозь иллюзии к прямому постижению истины.
| Уровень | Характеристики | Что отпускается |
|---|---|---|
| 1-я джхана | Восторг (пити), блаженство (сукха), однонаправленность | Чувственные желания, беспокойства |
| 2-я джхана | Глубокий покой, внутренняя уверенность | Интеллектуальная активность |
| 3-я джхана | Чистое, ровное блаженство | Восторг (пити) |
| 4-я джхана | Совершенная невозмутимость, чистая осознанность | Блаженство (сукха) |
После них идут нематериальные джханы (сферы бесконечного пространства и т.д.), но они не обязательны для пробуждения.
В Махасатипаттхана-сутте Будда говорит:
“Монах, сосредоточив ум, знает: ‘Ум сосредоточен’… Так он наблюдает ум в уме”.
Это не двойственность (“я медитирую”), а чистое осознавание процесса.
Правильное сосредоточение — это кульминация пути, где ум становится настолько чистым, что прозрение возникает само.
«Как дождь проникает в дом с плохой крышей, так страсти проникают в неразвитый ум.
Как дождь не проникает в дом с хорошей крышей, так страсти не проникают в развитый ум».
— Дхаммапада 1:13-14
Карма (санскр. कर्म, пали камма) — это закон причинно-следственной связи, который определяет, как наши действия (физические, речевые и умственные) влияют на настоящее и будущее.
Ключевая идея:
“Мысли становятся поступками, поступки становятся судьбой.”
“Незначительные поступки, совершаемые постоянно,
становятся привычкой и определяют судьбу.”
— Будда
В буддизме карма (пали камма) — это закон причины и следствия, но её можно разделить на два аспекта:
Карма действия (крийя-карма)
Карма результата (випака-карма)
Согласно буддизму, прекращение кармического становления возможно через:
Таким образом, бхава — это динамический процесс, поддерживаемый кармой, а прекращение кармических циклов ведёт к нирване (освобождению).
Буддийское учение о карме — это не фатализм, а гибкая система, где:
Освобождение (нирвана) достигается не через накопление “хорошей кармы”, а через прекращение кармического процесса — выход из цикла бхавы (становления).
Анатман (санскр. अनात्मन्, пали анатта) — это одно из ключевых понятий буддизма, которое означает отсутствие вечной, неизменной души или независимого «Я». Это не просто философская идея, а прямое указание на природу реальности, которое помогает выйти из страдания.
Пример:
Мы говорим: «Моё тело, мои мысли, мои чувства» — но где тогда тот, кто этим владеет? При детальном анализе такого «хозяина» найти невозможно.
Учение об анатмане тесно связано с тремя характеристиками бытия:
Пример с рекой:
Река кажется одной и той же, но её вода никогда не повторяется. Так и человек — поток элементов (скандх), но нет неизменной сущности «я».
Будда объяснял, что то, что мы называем «Я», — это просто временная комбинация пяти процессов:
| Скандха | Что включает? | Почему это не «Я»? |
|---|---|---|
| 1. Рупа (форма) | Тело, материальные объекты | Тело стареет, болеет, его нельзя контролировать. |
| 2. Ведана (чувства) | Приятное, неприятное, нейтральное | Чувства возникают и исчезают сами. |
| 3. Сання (восприятие) | Распознавание объектов (например, «это яблоко») | Зависит от органов чувств и памяти. |
| 4. Санскары (умственные формирования) | Мысли, привычки, воля | Мысли приходят и уходят без нашего ведома. |
| 5. Виджняна (сознание) | Осознавание объектов | Сознание зависит от условий (нет независимого «наблюдателя»). |
Нет ни одной скандхи, которую можно было бы назвать «Я», потому что все они:
«Видеть не-Я — значит видеть истину.
Видя истину, человек освобождается».
— СН 22.15 (Саньютта-никая)
Пример из жизни:
Вы расстроились из-за критики. Но если разобрать:
«Как собраны вместе спицы в колесной ступице,
так собраны в этом теле и ум, и материя.
Когда Дхамма понята,
рождение уничтожено,
и нет больше становления».
— Итивуттака 1.1
«Где нет ни „я“, ни „моего“, там нет и „души“»
— СН 12.15 (Саньютта-никая)
Условная «личность» – это пять совокупностей (скандх), которые ошибочно принимаются за «Я»:
Пример:
«Как пламя гаснет, когда кончается топливо, так и сознание угасает, лишённое опоры»
— Дхаммапада 47
Медитируйте на вопрос:
«Если нет души, то что перерождается?»
Ответ:
«Ничто. Есть лишь пустой процесс, подобный волне на воде. Когда ветер кармы стихает – волна успокаивается».
Это и есть конец страдания.
Вместо концепции энергии буддизм говорит о:
С буддийской перспективы жизнь существует благодаря:
Пище для поддержания (ахара):
Кармических импульсах:
Хотя буддизм не отрицает физиологию, он интерпретирует ее иначе:
Смерть наступает когда:
Буддизм подчеркивает:
Практическое значение: Осознание этого помогает:
“Как свеча горит не за счет ‘жизненной силы огня’, а благодаря горючему веществу и условиям, так и существование поддерживается комплексом причин, а не некоей ‘душой’ или ‘энергией’” (Мадджхима-никая)
В буддизме нет понятия “жизненной силы” или души — есть поток обусловленных процессов, которые создают иллюзию “живого существа”.
Ключевые условия для возникновения жизни:
“Когда есть это — возникает то. С прекращением этого — прекращается то” (Пратитья-самутпада, СН 12.1).
Пример:
Сознание (виньяна) — это не постоянная сущность, а цепь мгновенных актов осознавания, зависящих от:
Сознание возникает только при наличии:
У неживого (например, камня) нет сознания, потому что:
| Живое | Неживое |
|---|---|
| Имеет пять совокупностей (скандхи) | Нет скандх (только материальные элементы) |
| Обладает сознанием (виньяна) | Нет сознания |
| Подвержено карме и перерождениям | Не создаёт карму |
| Испытывает страдание (дуккха) | Не испытывает страдания |
| Способно к намеренным действиям (четана) | Действует только по физическим законам |
Главный критерий:
Пример:
Через пробуждение (нирвану):
“Когда мудрый полностью освобождается, его сознание, не находя опоры, не возникает вновь” (СН 12.38).
Живое становится живым не из-за “жизненной силы”, а из-за:
Неживое не обладает этим механизмом. Ключ к освобождению — прозреть эту зависимость и выйти из цикла.
Практика:
Медитируйте на вопрос:
“Если нет „я“ в этом теле и уме, то что же тогда рождается и умирает?”
Ответ:
“Ничто. Есть лишь пустой процесс, подобный волне на воде. Когда ветер кармы стихает — волна успокаивается”.
В буддизме (особенно в Махаяне и Ваджраяне) описывается несколько “тел” или уровней существования, которые есть у живых существ. Эти “тела” не физические, а скорее аспекты бытия.
Важно: Эти “тела” не существуют независимо - они взаимопроникающие аспекты одного потока опыта.
“Из жажды возникает цепляние” (СН 12.38)
Буддизм не отрицает биологию, но интерпретирует её через призму учения о:
Гены — это современное название “материальной пищи”, но:
| Уровень | Буддийский термин | Современный аналог |
|---|---|---|
| Глубинный | Бхава-танха | Инстинкт выживания вида |
| Эмоциональный | Кама-танха | Сексуальное влечение |
| Физический | Рупа-скандха | Генетические механизмы |
Парадокс: Даже Будда имел физическое тело с генами, но полностью освободился от обусловленности ими. Это показывает — биология создаёт условия, но не определяет сознание.
Но:
Утверждение в целом верно, особенно с точки зрения недвойственных школ (Махаяна, Ваджраяна), где сансара рассматривается как динамический, мгновенно обновляющийся процесс.
Однако:
Таким образом, сансара — это непрерывный поток обусловленного существования, в котором:
Этот процесс можно осознать и прекратить через практику (медитация, мудрость, этика).
| Состояние | Сходство со смертью | Духовный смысл в буддизме |
|---|---|---|
| Смерть | Полный распад тела/ума | Переход в бардо, кармический выбор |
| Сон | Частичное отключение ума | Тренировка осознанности (в тантре) |
| Обморок | Временная потеря сознания | Пример непостоянства |
| Оргазм | Кратковременный “раствор” | Объект тантрической трансформации |
| Самадхи | Остановка обычного ума | Путь к нирване |
Буддизм рассматривает эти состояния как:
Наиболее глубоко разработана теория смерти и бардо, остальные состояния служат её частными случаями или тренировочными “полигонами” для практики.
Но:
В школах Махаяны (особенно в Йогачаре) ниданы иногда трактуют как постоянно действующий психический процесс, а не только как описание беременности.
Например:
В этом случае “9 месяцев” – лишь метафора для иллюстрации непрерывности кармического потока.
То есть биологическое рождение – лишь частный случай “рождения” (джати) как нового кармического цикла.
Каждый день — это мини-сансара:
Осознавая это, можно практиковать освобождение даже в повседневности:
Вывод: Сам факт пробуждения не обязывает человека бросать семью или работу.
Но даже тогда уход должен быть без ненависти и отвращения, а с состраданием.
Буддизм не требует резко рвать связи после просветления. Главное — не цепляться за них. Можно:
«Просветлённый идёт по миру, как лист, уносимый ветром — ни к чему не прилипая и ни за что не цепляясь».
Важен не внешний поступок, а внутренняя свобода.
Protocol Buffers (Protobuf) — это эффективный и высокопроизводительный механизм сериализации структурированных данных от Google. Позволяет определять структуры данных один раз и генерировать код для их чтения и записи на различных языках программирования.
Protocol Buffers — это:
.proto файлы📏 Компактный размер — до 90% меньше JSON
⚡ Высокая скорость — сериализация в 6 раз быстрее
🔒 Строгая типизация — контроль данных на этапе компиляции
🔄 Версионность — обратная и прямая совместимость
🌍 Мультиязычность — единый контракт для всех языков
.proto файлахProtobuf — это современная замена XML и JSON для высоконагруженных систем, где важны производительность и эффективность использования ресурсов.
{
"model": "qwen3:4b",
"prompt": "Ваш запрос",
"stream": false,
"format": "json",
"options": {
"temperature": 0.8,
"top_p": 0.9,
"top_k": 40,
"num_predict": 512,
"stop": ["\n", "###"],
"repeat_penalty": 1.1,
"presence_penalty": 0.0,
"frequency_penalty": 0.0,
"seed": 42,
"mirostat": 0,
"num_ctx": 2048,
"num_thread": 8
},
"template": "{{ .Prompt }}",
"context": [1, 2, 3]
}
"model": "qwen3:4b""llama3:8b", "mistral:7b", etc"model": "llama3:8b""prompt": "Ваш запрос""prompt": "Напиши рецепт пасты карбонара:\n""stream": falsefalse - весь ответ сразу (для скриптов)true - потоковая передача (для UI)"stream": true"format": "json""format": "json" + "prompt": "Верни JSON с именем и возрастом"В Ollama параметр format поддерживает несколько значений:
"format": "json""Верни JSON: {\\\"name\\\": \\\"John\\\", \\\"age\\\": 30}"{"name": "John", "age": 30}"format": "text" (по умолчанию)"Расскажи о космосе""Космос - это бескрайнее пространство...""format": "markdown""Напиши документацию в markdown"# Заголовок
- Список
**Жирный текст**
"format": "html""Создай HTML страницу"<html><body><h1>Заголовок</h1></body></html>"format": "xml""Верни данные в XML"<data><name>John</name><age>30</age></data>"format": "yaml""Верни конфигурацию в YAML"name: John
age: 30
"format": "csv""Верни данные в CSV"name,age\nJohn,30\nJane,25"format": "code""Напиши функцию на Python"def hello():
return "Hello World"
curl http://localhost:11434/api/generate -d '{
"model": "qwen3:4b",
"prompt": "Верни JSON с информацией о пользователе: имя, возраст, город",
"format": "json",
"stream": false
}'
curl http://localhost:11434/api/generate -d '{
"model": "qwen3:4b",
"prompt": "Напиши руководство по Git в markdown",
"format": "markdown",
"stream": false
}'
curl http://localhost:11434/api/generate -d '{
"model": "qwen3:4b",
"prompt": "Создай простую HTML страницу с заголовком и параграфом",
"format": "html",
"stream": false
}'
# Более надежный способ
curl http://localhost:11434/api/generate -d '{
"model": "qwen3:4b",
"prompt": "Верни ответ в формате JSON: {\"name\": \"string\", \"age\": number}",
"format": "json",
"stream": false
}'
Большинство моделей лучше всего работают с json и text форматами.
options:"temperature": 0.80.1 - детерминированные, повторяемые ответы0.8 - креативные, разнообразные ответы1.0 - максимальная случайность"temperature": 0.3 для фактологических ответов"top_p": 0.90.1 - только самые вероятные слова0.9 - более разнообразный выбор"top_p": 0.7"top_k": 4010 - только 10 самых вероятных слов40 - хороший баланс"top_k": 20top_p (также known as nucleus sampling) - это алгоритм выборки, который ограничивает генерацию только теми словами, кумулятивная вероятность которых попадает в верхние P% распределения.
top_pВыбрать множество V таких что: ∑(p(x) для x в V) ≥ p
где p = значение top_p (0.0-1.0)
top_p = 0.3 (очень строгий)Возможные слова:
- "кот" (p=0.25)
- "собака" (p=0.20)
- "птица" (p=0.15)
- "рыба" (p=0.10)
- ... остальные (сумма p=0.30)
Выбор: только "кот" (0.25 ≤ 0.3)
top_p = 0.6 (умеренный)Выбор: "кот" + "собака" + "птица" (0.25+0.20+0.15=0.6)
top_p = 0.9 (либеральный)Выбор: почти все вероятные слова кроме самых маловероятных
top_k:| Параметр | Что делает | Преимущества | Недостатки |
|---|---|---|---|
top_p |
Динамический выбор вероятностей | Автоматически адаптируется к распределению | Может быть непредсказуемым |
top_k |
Фиксированное количество слов | Предсказуемость | Не учитывает распределение вероятностей |
{
"top_p": 0.3,
"temperature": 0.1,
"top_k": 20
}
{
"top_p": 0.9,
"temperature": 0.8,
"top_k": 60
}
{
"top_p": 0.7,
"temperature": 0.5,
"top_k": 40
}
curl http://localhost:11434/api/generate -d '{
"model": "qwen3:4b",
"prompt": "Столица Франции это",
"top_p": 0.3,
"temperature": 0.1,
"stream": false
}'
Результат: “Париж” (максимально точный ответ)
curl http://localhost:11434/api/generate -d '{
"model": "qwen3:4b",
"prompt": "Опиши закат на море",
"top_p": 0.9,
"temperature": 0.8,
"stream": false
}'
Результат: Развернутое художественное описание
{
"top_p": 0.7,
"top_k": 50,
"temperature": 0.6,
"repeat_penalty": 1.1
}
{"top_p": 0.1} # Может приводить к зацикливанию
{"top_p": 0.99} # Почти не фильтрует, может включать nonsense
{"top_p": 0.3, "temperature": 0.9} # Противоречивые настройки
top_p и temperature должны быть согласованыОптимальные значения для большинства задач: top_p: 0.7-0.9
"num_predict": 51264 - короткие ответы512 - средние ответы2048 - длинные тексты"num_predict": 256"stop": ["\n", "###"]["\n"] - остановиться в конце строки["###", "Конец"] - кастомные стоп-слова"stop": ["\n\n", "Ответ:"]"repeat_penalty": 1.11.0 - без штрафа1.2 - сильный штраф за повторения"repeat_penalty": 1.15"presence_penalty": 0.0-2.0 до 2.0"frequency_penalty": 0.0-2.0 до 2.0"seed": 42"seed": 12345Seed (сид) - это начальное значение для генератора псевдослучайных чисел. В контексте LLM это означает, что при одинаковых:
Вы получите идентичный результат каждый раз.
seed = 42# Первый запуск
curl http://localhost:11434/api/generate -d '{
"model": "qwen3:4b",
"prompt": "Напиши короткое стихотворение о весне",
"seed": 42,
"stream": false
}'
# Второй запуск (ТОЧНО такой же результат)
curl http://localhost:11434/api/generate -d '{
"model": "qwen3:4b",
"prompt": "Напиши короткое стихотворение о весне",
"seed": 42,
"stream": false
}'
# Seed 42
curl http://localhost:11434/api/generate -d '{
"model": "qwen3:4b",
"prompt": "Придумай название для кофе",
"seed": 42,
"stream": false
}'
# Результат: "Утренняя свежесть"
# Seed 43 (немного другой)
curl http://localhost:11434/api/generate -d '{
"model": "qwen3:4b",
"prompt": "Придумай название для кофе",
"seed": 43,
"stream": false
}'
# Результат: "Золотой эспрессо"
{
"seed": 123,
"temperature": 0.1, // Должен быть низким!
"top_p": 0.3 // Должен быть низким!
}
# Изменится ЛЮБОЙ параметр → изменится результат
seed=42 + prompt="A" ≠ seed=42 + prompt="A "
# Сегодня
seed=42 → "Ответ А"
# Завтра
seed=42 → "Ответ А" (тот же самый)
# После перезагрузки
seed=42 → "Ответ А" (все равно тот же)
# Тестирование изменений промпта
seed=42 + prompt="Версия 1" → Результат А
seed=42 + prompt="Версия 2" → Результат Б
# Можно точно сравнить улучшения
# Найден хороший результат → сохраняем seed
curl ... -d '{
"prompt": "Креативное название",
"seed": 78901, # ← ЗАПОМНИТЬ ЭТОТ SEED
"temperature": 0.3
}'
# Результат: "Небесный аромат" (сохраняем для производства)
# Сравнение моделей на одинаковых данных
seed=42 + model="qwen3:4b" → Результат А
seed=42 + model="llama3:8b" → Результат Б
# Честное сравнение без случайности
# Демо для клиента - всегда одинаковый результат
seed=12345 → "Ваш идеальный бизнес-план..."
{
"seed": 42,
"temperature": 0.9, // ❌ Высокая randomness
"top_p": 0.9 // ❌ Высокая randomness
}
// Результат НЕ будет детерминированным!
{
"seed": 42,
"temperature": 0.1, // ✅ Низкая случайность
"top_p": 0.3, // ✅ Строгая выборка
"top_k": 20, // ✅ Ограниченный выбор
"repeat_penalty": 1.1 // ✅ Предсказуемость
}
# Модель обновилась → результаты могут измениться
seed=42 + model=v1.0 → Результат А
seed=42 + model=v1.1 → Результат Б (может отличаться)
{
"seed": 12345,
"temperature": 0.1,
"top_p": 0.2,
"top_k": 10,
"prompt": "Напиши функцию на Python для сложения чисел"
}
{
"seed": 67890,
"temperature": 0.2,
"top_p": 0.4,
"prompt": "Проанализируй преимущества технологии блокчейн"
}
{
"seed": 11111,
"temperature": 0.1,
"prompt": "Версия 1 промпта..."
}
// Меняем только промпт, сохраняем seed
# Любое целое число
"seed": 42
"seed": 1234567890
"seed": 999888777
# Но лучше избегать:
"seed": 0 # Иногда особый случай
"seed": 1 # Слишком простой
"seed": 123456 # Нормально
"seed": 12345 для воспроизводимости{
"model": "qwen3:4b",
"prompt": "Генерируй креативные названия для кофе",
"seed": 424242,
"temperature": 0.3,
"top_p": 0.6,
"top_k": 30,
"num_predict": 50
}
Seed - это мощный инструмент для обеспечения воспроизводимости и отладки LLM приложений!
"mirostat": 00 - выключено1 или 2 - для контроля качестваMirostat - это алгоритм контроля качества текста, который динамически регулирует параметры генерации чтобы поддерживать заданный уровень перплексии (сложности/предсказуемости текста).
Mirostat постоянно измеряет перплексию генерируемого текста и подстраивает параметры в реальном времени чтобы достичь целевого значения.
Представьте круиз-контроль в автомобиле:
"mirostat": 0 - Выключено{"mirostat": 0}
"mirostat": 1 - Mirostat 1.0{
"mirostat": 1,
"mirostat_tau": 5.0,
"mirostat_eta": 0.1
}
"mirostat": 2 - Mirostat 2.0{
"mirostat": 2,
"mirostat_tau": 5.0,
"mirostat_eta": 0.1
}
mirostat_tau - Целевая перплексия{"mirostat_tau": 5.0}
mirostat_eta - Скорость обучения{"mirostat_eta": 0.1}
{
"mirostat": 2,
"mirostat_tau": 3.0, // Низкая перплексия = простота
"mirostat_eta": 0.05,
"prompt": "Объясни концепцию API REST"
}
Результат: Четкий, структурированный текст без излишней сложности
{
"mirostat": 2,
"mirostat_tau": 7.0, // Высокая перплексия = сложность
"mirostat_eta": 0.2,
"prompt": "Напиши поэтическое описание заката"
}
Результат: Богатый, образный язык с сложными конструкциями
{
"mirostat": 1,
"mirostat_tau": 5.0, // Баланс
"mirostat_eta": 0.1,
"prompt": "Напиши статью о искусственном интеллекте"
}
{
"temperature": 0.7,
"top_p": 0.9,
"top_k": 40
}
// Качество может "плавать" в течение генерации
{
"mirostat": 2,
"mirostat_tau": 5.0,
"mirostat_eta": 0.1
}
// Постоянное качество throughout текста
| Задача | mirostat_tau | mirostat_eta |
|---|---|---|
| Техническая документация | 2.0-4.0 | 0.05-0.1 |
| Новостные статьи | 4.0-6.0 | 0.1-0.2 |
| Художественная литература | 6.0-8.0 | 0.2-0.3 |
| Научные тексты | 5.0-7.0 | 0.1-0.15 |
Высокое качество, стабильность:
{
"mirostat": 2,
"mirostat_tau": 5.0,
"mirostat_eta": 0.1,
"temperature": 0.3,
"top_p": 0.8
}
Креативность с контролем:
{
"mirostat": 2,
"mirostat_tau": 7.0,
"mirostat_eta": 0.25,
"temperature": 0.7
}
curl http://localhost:11434/api/generate -d '{
"model": "qwen3:4b",
"prompt": "Напиши подробное руководство по использованию Docker",
"mirostat": 2,
"mirostat_tau": 4.0,
"mirostat_eta": 0.08,
"temperature": 0.2,
"stream": false
}' | jq -r '.response'
✅ Длинные тексты (избегает деградации качества)
✅ Консистентность (техдокументация, руководства)
✅ Точный контроль сложности текста
✅ Автоматизация генерации контента
❌ Короткие ответы (излишне сложно)
❌ Максимальная скорость (дополнительные вычисления)
❌ Эксперименты (проще использовать temperature)
❌ Очень креативные задачи (может ограничивать)
Если текст слишком простой:
{"mirostat_tau": 6.0} // Увеличить перплексию
Если текст слишком сложный:
{"mirostat_tau": 3.0} // Уменьшить перплексию
Если качество нестабильное:
{"mirostat_eta": 0.05} // Уменьшить скорость обучения
"num_ctx": 2048"num_thread": 8"template": "{{ .Prompt }}""template": "Ответь как эксперт: {{ .Prompt }}\nОтвет:"
"context": [1, 2, 3]Context - это массив чисел, который представляет собой “память” предыдущего взаимодействия с моделью. Это позволяет продолжить диалог или текст точно с того места, где остановились.
Контекст содержит эмбеддинги (векторные представления) предыдущего взаимодействия:
contextresponse=$(curl -s http://localhost:11434/api/generate -d '{
"model": "qwen3:4b",
"prompt": "Расскажи о преимуществах Python",
"stream": false
}')
# Извлекаем ответ И контекст
answer=$(echo $response | jq -r '.response')
context=$(echo $response | jq '.context')
curl http://localhost:11434/api/generate -d '{
"model": "qwen3:4b",
"prompt": "А какие недостатки?",
"context": '"$context"',
"stream": false
}'
#!/bin/bash
# Первый запрос
echo "Шаг 1: Первый запрос"
response1=$(curl -s http://localhost:11434/api/generate -d '{
"model": "qwen3:4b",
"prompt": "Расскажи о Python для начинающих",
"stream": false
}')
answer1=$(echo $response1 | jq -r '.response')
context=$(echo $response1 | jq '.context')
echo "Ответ: $answer1"
echo "Контекст сохранен"
# Второй запрос с контекстом
echo -e "\nШаг 2: Продолжение диалога"
response2=$(curl -s http://localhost:11434/api/generate -d '{
"model": "qwen3:4b",
"prompt": "Какие книги посоветуешь для изучения?",
"context": '"$context"',
"stream": false
}')
answer2=$(echo $response2 | jq -r '.response')
echo "Ответ: $answer2"
Контекст возвращается и принимается как массив чисел:
{
"context": [123, 456, 789, 12, 34, 56, 78, 90, ...]
}
# Пользователь: Привет
# Модель: Привет! Как дела?
# Пользователь: Хорошо, расскажи о погоде
# Модель: Помнит предыдущие реплики
# Начало: "В далекой галактике..."
# Продолжение: "где мы остановились..."
# Шаг 1: Обсуждение проблемы
# Шаг 2: Уточняющие вопросы
# Шаг 3: Решение с учетом всей истории
# Сначала: архитектура проекта
# Затем: реализация конкретных функций
# В конце: тестирование
# Без context (громоздко):
"prompt": "Предыдущий разговор: Привет - Привет! Как дела? - Хорошо. Текущий вопрос: Что нового?"
# С context (эффективно):
"prompt": "Что нового?",
"context": [123, 456, 789]
# Контекст от одной модели может не работать с другой
context от "qwen3:4b" ≠ context для "llama3:8b"
# Контекст может "устаревать" после долгого времени
# Или после обновления модели
# Слишком длинный контекст может быть обрезан
# Зависит от ограничений модели
# Для совершенно новых тем лучше не использовать context
# Чтобы избежать влияния предыдущего разговора
#!/bin/bash
ask_question() {
local prompt="$1"
local context="$2"
local data='{
"model": "qwen3:4b",
"prompt": "'"$prompt"'",
"stream": false'
if [ -n "$context" ] && [ "$context" != "null" ]; then
data+=', "context": '"$context"
fi
data+='}'
curl -s http://localhost:11434/api/generate -d "$data"
}
# Диалог
response1=$(ask_question "Привет! Как тебя зовут?")
answer1=$(echo $response1 | jq -r '.response')
context1=$(echo $response1 | jq '.context')
echo "Модель: $answer1"
response2=$(ask_question "А чем ты занимаешься?" "$context1")
answer2=$(echo $response2 | jq -r '.response')
echo "Модель: $answer2"
Для чат-интерфейсов лучше использовать /api/chat:
curl http://localhost:11434/api/chat -d '{
"model": "qwen3:4b",
"messages": [
{"role": "user", "content": "Привет"},
{"role": "assistant", "content": "Привет! Как дела?"},
{"role": "user", "content": "Хорошо, а у тебя?"}
],
"stream": false
}'
# В приложении сохраняйте context в:
# - Базе данных
# - Файле
# - Памятии сессии
# Если тема полностью меняется:
context=null
if [ "$context" != "null" ] && [ -n "$context" ]; then
# Используем контекст
else
# Новый разговор
fi
# После N реплик начинайте новый контекст
# Чтобы избежать накопления ошибок
# Сохраняем
echo $context > context.json
# Загружаем
context=$(cat context.json)
# Разные контексты для разных тем
context_python=$(cat python_context.json)
context_js=$(cat js_context.json)
# Для тестирования можно сохранить и воспроизвести
# exact диалог с одинаковым context
# Псевдокод для веб-приложения
sessions = {}
def handle_message(user_id, message):
if user_id not in sessions:
# Новый диалог
response = ollama.generate(prompt=message)
sessions[user_id] = {
'context': response['context'],
'history': [message, response['response']]
}
else:
# Продолжение диалога
response = ollama.generate(
prompt=message,
context=sessions[user_id]['context']
)
sessions[user_id]['context'] = response['context']
sessions[user_id]['history'].extend([message, response['response']])
return response['response']
{
"temperature": 0.1,
"top_p": 0.3,
"top_k": 20,
"repeat_penalty": 1.2
}
{
"temperature": 0.9,
"top_p": 0.95,
"top_k": 60,
"num_predict": 1024
}
{
"temperature": 0.1,
"seed": 42,
"top_p": 0.1
}
#!/bin/bash
# Первый запрос - получаем контекст
echo "=== Первый запрос ==="
response1=$(curl -s http://localhost:11434/api/generate -d '{
"model": "qwen3:4b",
"prompt": "Расскажи о преимуществах языка Python",
"stream": false,
"format": "json",
"options": {
"temperature": 0.7,
"top_p": 0.9,
"top_k": 40,
"num_predict": 256,
"stop": ["\n", "###"],
"repeat_penalty": 1.1,
"presence_penalty": 0.0,
"frequency_penalty": 0.0,
"seed": 42,
"mirostat": 2,
"mirostat_tau": 5.0,
"mirostat_eta": 0.1,
"num_ctx": 2048,
"num_thread": 8
},
"template": "Ответь как эксперт: {{ .Prompt }}\n\nОтвет:"
}')
# Извлекаем ответ и контекст
answer1=$(echo $response1 | jq -r '.response')
context=$(echo $response1 | jq '.context')
echo "Ответ: $answer1"
echo "Контекст получен"
# Второй запрос с контекстом
echo -e "\n=== Второй запрос с контекстом ==="
response2=$(curl -s http://localhost:11434/api/generate -d '{
"model": "qwen3:4b",
"prompt": "А какие у Python недостатки?",
"context": '"$context"',
"stream": false,
"format": "text",
"options": {
"temperature": 0.5,
"top_p": 0.8,
"top_k": 30,
"num_predict": 200,
"stop": ["\n\n"],
"repeat_penalty": 1.2,
"seed": 123
}
}')
answer2=$(echo $response2 | jq -r '.response')
echo "Ответ: $answer2"
# Создаем конфигурационный файл для первого запроса
cat > first_request.txt << 'EOF'
Расскажи о преимуществах языка Python для data science
EOF
# Первый запрос с полными параметрами через stdin
echo "=== Первый запрос ==="
response1=$(ollama run qwen3:4b --temperature 0.7 --top-p 0.9 --top-k 40 \
--num-predict 256 --seed 42 --mirostat 2 --mirostat-tau 5.0 --mirostat-eta 0.1 \
--repeat-penalty 1.1 --stop "\n" --stop "###" < first_request.txt)
echo "$response1"
# Сохраняем промпт для второго запроса
cat > second_request.txt << 'EOF'
А какие недостатки у Python для data science по сравнению с R?
EOF
# Второй запрос (Ollama run не поддерживает context напрямую,
# поэтому используем альтернативный подход)
echo -e "\n=== Второй запрос ==="
ollama run qwen3:4b --temperature 0.5 --top-p 0.8 --top-k 30 \
--num-predict 200 --seed 123 --repeat-penalty 1.2 < second_request.txt
# Для Ubuntu/Debian
sudo apt-get install yq jq
#Для Arch
sudo pacman -S yq jq
# Alias для работы с конфигурационным файлом
alias ollama-config='func() {
local config_file="$1"
local prompt="$2"
if [ ! -f "$config_file" ]; then
echo "Config file $config_file not found!"
return 1
fi
# Читаем конфигурацию из файла
local model=$(yq eval ".model" "$config_file")
local temperature=$(yq eval ".options.temperature" "$config_file")
local top_p=$(yq eval ".options.top_p" "$config_file")
local top_k=$(yq eval ".options.top_k" "$config_file")
local num_predict=$(yq eval ".options.num_predict" "$config_file")
local seed=$(yq eval ".options.seed" "$config_file")
# Выполняем запрос
ollama run "$model" --temperature "$temperature" --top-p "$top_p" \
--top-k "$top_k" --num-predict "$num_predict" --seed "$seed" "$prompt"
}; func'
# Alias для JSON конфигурации
alias ollama-json='func() {
local config_file="$1"
local prompt="$2"
if [ ! -f "$config_file" ]; then
echo "Config file $config_file not found!"
return 1
fi
# Используем jq для извлечения параметров
local model=$(jq -r ".model" "$config_file")
local temperature=$(jq -r ".options.temperature" "$config_file")
local top_p=$(jq -r ".options.top_p" "$config_file")
ollama run "$model" --temperature "$temperature" --top-p "$top_p" "$prompt"
}; func'
model: qwen3:4b
options:
temperature: 0.7
top_p: 0.9
top_k: 40
num_predict: 256
seed: 42
repeat_penalty: 1.1
mirostat: 2
mirostat_tau: 5.0
mirostat_eta: 0.1
format: text
# Установите yq для работы с YAML: brew install yq
ollama-config ollama_config.yaml "Расскажи о machine learning"
# Или с JSON конфигом
ollama-json config.json "Напиши код на Python"
request_config.json:{
"model": "qwen3:4b",
"prompt": "Объясни концепцию искусственного интеллекта",
"stream": false,
"format": "markdown",
"options": {
"temperature": 0.7,
"top_p": 0.9,
"top_k": 40,
"num_predict": 300,
"stop": ["\n", "##"],
"repeat_penalty": 1.1,
"presence_penalty": 0.0,
"frequency_penalty": 0.0,
"seed": 424242,
"mirostat": 2,
"mirostat_tau": 5.0,
"mirostat_eta": 0.1,
"num_ctx": 2048,
"num_thread": 8
},
"template": "Ответь как эксперт по AI: {{ .Prompt }}\n\n"
}
#!/bin/bash
process_ollama_config() {
local config_file="$1"
if [ ! -f "$config_file" ]; then
echo "Config file $config_file not found!"
return 1
fi
# Извлекаем параметры из JSON
local model=$(jq -r '.model' "$config_file")
local prompt=$(jq -r '.prompt' "$config_file")
local temperature=$(jq -r '.options.temperature' "$config_file")
local top_p=$(jq -r '.options.top_p' "$config_file")
local top_k=$(jq -r '.options.top_k' "$config_file")
local num_predict=$(jq -r '.options.num_predict' "$config_file")
local seed=$(jq -r '.options.seed' "$config_file")
local repeat_penalty=$(jq -r '.options.repeat_penalty' "$config_file")
# Строим команду ollama run
local command="ollama run '$model' --temperature $temperature --top-p $top_p --top-k $top_k --num-predict $num_predict --seed $seed --repeat-penalty $repeat_penalty"
# Добавляем stop слова если они есть
local stop_words=$(jq -r '.options.stop[]?' "$config_file" 2>/dev/null)
if [ -n "$stop_words" ]; then
while IFS= read -r word; do
command+=" --stop \"$word\""
done <<< "$stop_words"
fi
# Добавляем промпт
command+=" \"$prompt\""
echo "Выполняем команду: $command"
eval "$command"
}
# Использование
process_ollama_config "request_config.json"
#!/bin/bash
# Прямое использование JSON конфига с curl
curl -s http://localhost:11434/api/generate \
-H "Content-Type: application/json" \
-d "$(cat request_config.json)" \
| jq -r '.response'
Создаем скрипт advanced_dialog.sh:
#!/bin/bash
CONFIG_FILE="dialog_config.json"
CONTEXT_FILE="context.json"
# Функция для отправки запроса
send_request() {
local prompt="$1"
local context="${2:-null}"
local request_data=$(jq --arg prompt "$prompt" --argjson context "$context" '
{
model: .model,
prompt: $prompt,
stream: false,
format: .format,
options: .options,
template: .template,
context: $context
}' "$CONFIG_FILE")
curl -s http://localhost:11434/api/generate \
-H "Content-Type: application/json" \
-d "$request_data"
}
# Основной диалог
echo "🤖 Начинаем диалог с AI"
# Шаг 1
echo "👤: Расскажи о Python"
response1=$(send_request "Расскажи о Python")
answer1=$(echo $response1 | jq -r '.response')
context=$(echo $response1 | jq '.context')
echo "🤖: $answer1"
# Сохраняем контекст
echo "$context" > "$CONTEXT_FILE"
# Шаг 2 с контекстом
echo -e "\n👤: А какие у него недостатки?"
response2=$(send_request "А какие у него недостатки?" "$(cat $CONTEXT_FILE)")
answer2=$(echo $response2 | jq -r '.response')
echo "🤖: $answer2"
# Обновляем контекст
echo "$(echo $response2 | jq '.context')" > "$CONTEXT_FILE"
# Шаг 3
echo -e "\n👤: Что посоветуешь для изучения?"
response3=$(send_request "Что посоветуешь для изучения?" "$(cat $CONTEXT_FILE)")
answer3=$(echo $response3 | jq -r '.response')
echo "🤖: $answer3"
dialog_config.json:{
"model": "qwen3:4b",
"format": "text",
"template": "Ответь дружелюбно и подробно: {{ .Prompt }}\n\n",
"options": {
"temperature": 0.7,
"top_p": 0.9,
"top_k": 40,
"num_predict": 200,
"stop": ["\n\n", "###"],
"repeat_penalty": 1.1,
"seed": 12345,
"mirostat": 1,
"mirostat_tau": 5.0,
"mirostat_eta": 0.1
}
}
chmod +x advanced_dialog.sh
./advanced_dialog.sh
npm init -y
npm install axios
ollama-client.js:const axios = require('axios');
class OllamaClient {
constructor(baseURL = 'http://localhost:11434') {
this.baseURL = baseURL;
this.context = null;
}
/**
* Генерация текста с полным набором параметров
*/
async generate({
prompt,
model = 'qwen3:4b',
stream = false,
format = 'text',
temperature = 0.7,
top_p = 0.9,
top_k = 40,
num_predict = 256,
stop = ['\n', '###'],
repeat_penalty = 1.1,
presence_penalty = 0.0,
frequency_penalty = 0.0,
seed = null,
mirostat = 0,
mirostat_tau = 5.0,
mirostat_eta = 0.1,
num_ctx = 2048,
num_thread = 8,
template = null,
useContext = true
}) {
const payload = {
model,
prompt,
stream,
format,
options: {
temperature,
top_p,
top_k,
num_predict,
stop,
repeat_penalty,
presence_penalty,
frequency_penalty,
mirostat,
mirostat_tau,
mirostat_eta,
num_ctx,
num_thread
}
};
// Добавляем опциональные параметры
if (seed !== null) {
payload.options.seed = seed;
}
if (template) {
payload.template = template;
}
if (useContext && this.context) {
payload.context = this.context;
}
try {
const response = await axios.post(`${this.baseURL}/api/generate`, payload, {
timeout: 30000
});
// Сохраняем контекст для следующего запроса
if (useContext && response.data.context) {
this.context = response.data.context;
}
return response.data;
} catch (error) {
console.error('Ошибка запроса:', error.message);
return { error: error.message };
}
}
/**
* Чат-интерфейс с поддержкой истории
*/
async chat(messages, model = 'qwen3:4b', options = {}) {
try {
const response = await axios.post(`${this.baseURL}/api/chat`, {
model,
messages,
stream: false,
options
}, {
timeout: 30000
});
return response.data;
} catch (error) {
console.error('Ошибка чата:', error.message);
return { error: error.message };
}
}
/**
* Очистить контекст
*/
clearContext() {
this.context = null;
}
/**
* Сохранить контекст в файл
*/
async saveContext(filename) {
const fs = require('fs').promises;
try {
await fs.writeFile(filename, JSON.stringify(this.context, null, 2));
console.log(`Контекст сохранен в ${filename}`);
} catch (error) {
console.error('Ошибка сохранения контекста:', error.message);
}
}
/**
* Загрузить контекст из файла
*/
async loadContext(filename) {
const fs = require('fs').promises;
try {
const data = await fs.readFile(filename, 'utf8');
this.context = JSON.parse(data);
console.log(`Контекст загружен из ${filename}`);
} catch (error) {
console.error('Ошибка загрузки контекста:', error.message);
}
}
}
// Пример использования
async function main() {
const client = new OllamaClient();
// Пример 1: Простая генерация
console.log('=== Пример 1: Простая генерация ===');
const result1 = await client.generate({
prompt: 'Расскажи о JavaScript и его особенностях',
model: 'qwen3:4b',
temperature: 0.7,
top_p: 0.9,
num_predict: 200,
seed: 42,
format: 'text'
});
console.log('Ответ:', result1.response || result1.error);
// Пример 2: Продолжение с контекстом
console.log('\n=== Пример 2: Продолжение с контекстом ===');
const result2 = await client.generate({
prompt: 'А какие современные фреймворки используются?',
temperature: 0.5,
top_p: 0.8
});
console.log('Ответ:', result2.response || result2.error);
// Пример 3: Чат с историей
console.log('\n=== Пример 3: Чат-интерфейс ===');
const chatResult = await client.chat([
{ role: 'user', content: 'Привет! Расскажи о Node.js' },
{ role: 'assistant', content: 'Node.js - это JavaScript runtime...' },
{ role: 'user', content: 'Какие пакеты самые популярные?' }
], 'qwen3:4b', {
temperature: 0.6,
top_p: 0.85
});
console.log('Чат ответ:', chatResult.message?.content || chatResult.error);
// Пример 4: Сохранение и загрузка контекста
await client.saveContext('context.json');
client.clearContext();
await client.loadContext('context.json');
// Пример 5: Генерация кода с специфическими параметрами
console.log('\n=== Пример 5: Генерация кода ===');
const codeResult = await client.generate({
prompt: 'Напиши простой HTTP сервер на Node.js',
temperature: 0.3,
top_p: 0.7,
num_predict: 300,
seed: 12345,
format: 'code',
stop: ['```']
});
console.log('Сгенерированный код:');
console.log(codeResult.response || codeResult.error);
}
// Запуск примера
main().catch(console.error);
{
"name": "ollama-client",
"version": "1.0.0",
"description": "Ollama client with full parameters support",
"main": "ollama-client.js",
"scripts": {
"start": "node ollama-client.js",
"dev": "node ollama-client.js"
},
"dependencies": {
"axios": "^1.6.0"
},
"keywords": ["ollama", "ai", "llm", "javascript"],
"author": "Your Name",
"license": "MIT"
}
go mod init ollama-client
go get github.com/valyala/fasthttp
main.go:package main
import (
"encoding/json"
"fmt"
"log"
"strings"
"time"
"github.com/valyala/fasthttp"
)
type OllamaOptions struct {
Temperature float32 `json:"temperature"`
TopP float32 `json:"top_p"`
TopK int `json:"top_k"`
NumPredict int `json:"num_predict"`
Stop []string `json:"stop"`
RepeatPenalty float32 `json:"repeat_penalty"`
PresencePenalty float32 `json:"presence_penalty"`
FrequencyPenalty float32 `json:"frequency_penalty"`
Seed int64 `json:"seed,omitempty"`
Mirostat int `json:"mirostat"`
MirostatTau float32 `json:"mirostat_tau"`
MirostatEta float32 `json:"mirostat_eta"`
NumCtx int `json:"num_ctx"`
NumThread int `json:"num_thread"`
}
type OllamaRequest struct {
Model string `json:"model"`
Prompt string `json:"prompt"`
Stream bool `json:"stream"`
Format string `json:"format,omitempty"`
Options OllamaOptions `json:"options"`
Template string `json:"template,omitempty"`
Context []int `json:"context,omitempty"`
}
type OllamaResponse struct {
Model string `json:"model"`
Response string `json:"response"`
Context []int `json:"context,omitempty"`
Done bool `json:"done"`
Error string `json:"error,omitempty"`
}
type OllamaClient struct {
BaseURL string
Context []int
}
func NewOllamaClient(baseURL string) *OllamaClient {
if baseURL == "" {
baseURL = "http://localhost:11434"
}
return &OllamaClient{BaseURL: baseURL}
}
func (c *OllamaClient) Generate(prompt string, options OllamaOptions) (OllamaResponse, error) {
request := OllamaRequest{
Model: "qwen3:4b",
Prompt: prompt,
Stream: false,
Format: "text",
Options: options,
}
if len(c.Context) > 0 {
request.Context = c.Context
}
requestBody, err := json.Marshal(request)
if err != nil {
return OllamaResponse{}, err
}
req := fasthttp.AcquireRequest()
defer fasthttp.ReleaseRequest(req)
req.SetRequestURI(c.BaseURL + "/api/generate")
req.Header.SetMethod("POST")
req.Header.SetContentType("application/json")
req.SetBody(requestBody)
resp := fasthttp.AcquireResponse()
defer fasthttp.ReleaseResponse(resp)
client := &fasthttp.Client{
ReadTimeout: 30 * time.Second,
}
if err := client.Do(req, resp); err != nil {
return OllamaResponse{}, err
}
var response OllamaResponse
if err := json.Unmarshal(resp.Body(), &response); err != nil {
return OllamaResponse{}, err
}
// Сохраняем контекст для следующих запросов
if response.Context != nil {
c.Context = response.Context
}
return response, nil
}
func (c *OllamaClient) ClearContext() {
c.Context = nil
}
func main() {
client := NewOllamaClient("")
// Пример 1: Простая генерация
options1 := OllamaOptions{
Temperature: 0.7,
TopP: 0.9,
TopK: 40,
NumPredict: 200,
Stop: []string{"\n", "###"},
RepeatPenalty: 1.1,
Seed: 42,
Mirostat: 2,
MirostatTau: 5.0,
MirostatEta: 0.1,
}
fmt.Println("=== Пример 1: Простая генерация ===")
response1, err := client.Generate("Расскажи о Go языке программирования", options1)
if err != nil {
log.Fatal("Ошибка:", err)
}
fmt.Printf("Ответ: %s\n", response1.Response)
// Пример 2: Продолжение с контекстом
options2 := OllamaOptions{
Temperature: 0.5,
TopP: 0.8,
TopK: 30,
NumPredict: 150,
RepeatPenalty: 1.2,
}
fmt.Println("\n=== Пример 2: Продолжение с контекстом ===")
response2, err := client.Generate("Какие у него преимущества?", options2)
if err != nil {
log.Fatal("Ошибка:", err)
}
fmt.Printf("Ответ: %s\n", response2.Response)
// Пример 3: Генерация кода
options3 := OllamaOptions{
Temperature: 0.3,
TopP: 0.7,
NumPredict: 300,
Seed: 12345,
}
fmt.Println("\n=== Пример 3: Генерация кода ===")
response3, err := client.Generate("Напиши HTTP сервер на Go", options3)
if err != nil {
log.Fatal("Ошибка:", err)
}
fmt.Printf("Код: %s\n", response3.Response)
// Очищаем контекст
client.ClearContext()
fmt.Println("\nКонтекст очищен")
}
pip install requests python-dotenv
ollama_client.py:import requests
import json
import os
from typing import Dict, Any, List, Optional
class OllamaClient:
def __init__(self, base_url: str = "http://localhost:11434"):
self.base_url = base_url
self.context = None
def generate(
self,
prompt: str,
model: str = "qwen3:4b",
stream: bool = False,
format: str = "text",
temperature: float = 0.7,
top_p: float = 0.9,
top_k: int = 40,
num_predict: int = 256,
stop: List[str] = None,
repeat_penalty: float = 1.1,
presence_penalty: float = 0.0,
frequency_penalty: float = 0.0,
seed: int = None,
mirostat: int = 0,
mirostat_tau: float = 5.0,
mirostat_eta: float = 0.1,
num_ctx: int = 2048,
num_thread: int = 8,
template: str = None,
use_context: bool = True
) -> Dict[str, Any]:
"""
Генерация текста с полным набором параметров
"""
if stop is None:
stop = ["\n", "###"]
payload = {
"model": model,
"prompt": prompt,
"stream": stream,
"format": format,
"options": {
"temperature": temperature,
"top_p": top_p,
"top_k": top_k,
"num_predict": num_predict,
"stop": stop,
"repeat_penalty": repeat_penalty,
"presence_penalty": presence_penalty,
"frequency_penalty": frequency_penalty,
"mirostat": mirostat,
"mirostat_tau": mirostat_tau,
"mirostat_eta": mirostat_eta,
"num_ctx": num_ctx,
"num_thread": num_thread
}
}
# Добавляем опциональные параметры
if seed is not None:
payload["options"]["seed"] = seed
if template:
payload["template"] = template
if use_context and self.context:
payload["context"] = self.context
try:
response = requests.post(
f"{self.base_url}/api/generate",
json=payload,
timeout=30
)
response.raise_for_status()
result = response.json()
# Сохраняем контекст для следующего запроса
if use_context and "context" in result:
self.context = result["context"]
return result
except requests.exceptions.RequestException as e:
print(f"Ошибка запроса: {e}")
return {"error": str(e)}
def chat(
self,
messages: List[Dict[str, str]],
model: str = "qwen3:4b",
**kwargs
) -> Dict[str, Any]:
"""
Чат-интерфейс с поддержкой истории сообщений
"""
payload = {
"model": model,
"messages": messages,
"stream": False,
"options": kwargs.get("options", {})
}
try:
response = requests.post(
f"{self.base_url}/api/chat",
json=payload,
timeout=30
)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as e:
print(f"Ошибка чата: {e}")
return {"error": str(e)}
def clear_context(self):
"""Очистить контекст"""
self.context = None
# Пример использования
def main():
client = OllamaClient()
# Пример 1: Простая генерация
print("=== Пример 1: Простая генерация ===")
result1 = client.generate(
prompt="Расскажи о преимуществах Python для data science",
model="qwen3:4b",
temperature=0.7,
top_p=0.9,
num_predict=150,
seed=42,
format="text"
)
print("Ответ:", result1.get("response", "Ошибка"))
# Пример 2: Продолжение с контекстом
print("\n=== Пример 2: Продолжение с контекстом ===")
result2 = client.generate(
prompt="А какие недостатки у Python?",
temperature=0.5,
top_p=0.8
)
print("Ответ:", result2.get("response", "Ошибка"))
# Пример 3: Чат с историей
print("\n=== Пример 3: Чат-интерфейс ===")
chat_result = client.chat(
messages=[
{"role": "user", "content": "Привет! Как тебя зовут?"},
{"role": "assistant", "content": "Привет! Я помощник на основе AI."},
{"role": "user", "content": "Расскажи о машинном обучении"}
],
model="qwen3:4b",
options={
"temperature": 0.7,
"top_p": 0.9
}
)
print("Чат ответ:", chat_result.get("message", {}).get("content", "Ошибка"))
# Пример 4: Сброс контекста
client.clear_context()
print("\nКонтекст очищен")
if __name__ == "__main__":
main()
advanced_example.py - продвинутый пример:import json
from ollama_client import OllamaClient
def advanced_example():
client = OllamaClient()
# Многошаговый диалог с сохранением контекста
steps = [
"Расскажи о языке программирования Go",
"Какие у него преимущества перед Python?",
"А недостатки какие?",
"Напиши простой HTTP сервер на Go"
]
for i, prompt in enumerate(steps, 1):
print(f"\n--- Шаг {i}: {prompt} ---")
result = client.generate(
prompt=prompt,
model="qwen3:4b",
temperature=0.7 if i > 1 else 0.5,
top_p=0.9,
num_predict=200 if i < 4 else 300,
seed=12345,
format="text" if i < 4 else "code"
)
if "response" in result:
print(f"Ответ: {result['response']}")
else:
print(f"Ошибка: {result.get('error', 'Неизвестная ошибка')}")
# Сохраняем контекст в файл
if client.context:
with open("context.json", "w") as f:
json.dump(client.context, f)
print("\nКонтекст сохранен в context.json")
if __name__ == "__main__":
advanced_example()
Все версии доступны для загрузки. Эта документация пишется для текущей версии — Lua 5.4, а текущий релиз — Lua 5.4.8.
Lua — это бесплатное программное обеспечение, распространяемое в исходном коде. Его можно использовать для любых целей, включая коммерческие, совершенно бесплатно.
Все версии доступны для загрузки. Текущая версия — Lua 5.4, а текущий релиз — Lua 5.4.8.
Основной репозиторий модулей Lua — это LuaRocks. Также смотрите Awesome Lua. Предварительно скомпилированные библиотеки и исполняемые файлы Lua доступны на LuaBinaries. Вики lua-users содержит множество пользовательских дополнений для Lua.
Lua реализован на чистом ANSI C и компилируется без изменений на всех платформах, где есть компилятор ANSI C. Lua также компилируется без проблем как C++.
Lua очень легко собрать и установить. В пакете есть подробные инструкции, но вот простой пример терминальной сессии, которая загружает текущий релиз Lua и собирает его на распространенных платформах:
curl -L -R -O https://www.lua.org/ftp/lua-5.4.8.tar.gz
tar zxf lua-5.4.8.tar.gz
cd lua-5.4.8
make all test
Lua — это мощный, эффективный, легковесный и встраиваемый язык сценариев. Он поддерживает процедурное программирование, объектно-ориентированное программирование, функциональное программирование, программирование на основе данных и описание данных.
Lua сочетает в себе простую процедурную синтаксис с мощными конструкциями описания данных, основанными на ассоциативных массивах и расширяемой семантике. Lua является динамически типизированным языком, работает путем интерпретации байт-кода с помощью виртуальной машины на основе регистров и имеет автоматическое управление памятью с помощью генерационного сборщика мусора, что делает его идеальным для конфигурации, сценариев и быстрого прототипирования.
Lua реализован как библиотека, написанная на чистом C, общепринятом подмножестве стандартного C и C++. Распределение Lua включает в себя хост-программу под названием lua, которая использует библиотеку Lua для предоставления полного, автономного интерпретатора Lua, как для интерактивного, так и для пакетного использования. Lua предназначен как мощный, легковесный, встраиваемый язык сценариев для любой программы, которая в этом нуждается, а также как мощный, но легковесный и эффективный автономный язык.
Как язык расширения, Lua не имеет понятия “главной” программы: он работает встраиваемым в хост-клиент, называемым программой встраивания или просто хостом. (Часто этот хост — это автономная программа lua.) Хост-программа может вызывать функции для выполнения фрагмента кода Lua, может записывать и считывать переменные Lua, а также может регистрировать функции C, которые будут вызываться кодом Lua. С помощью функций C Lua может быть расширен для работы с широким спектром различных областей, создавая таким образом настраиваемые языки программирования, которые разделяют синтаксическую основу.
Lua является бесплатным программным обеспечением и предоставляется, как обычно, без каких-либо гарантий, как указано в его лицензии. Реализация, описанная в этом руководстве, доступна на официальном сайте Lua, www.lua.org.
Как и любой другой справочный мануал, этот документ в некоторых местах может быть сухим. Для обсуждения решений, стоящих за дизайном Lua, смотрите технические статьи, доступные на сайте Lua. Для подробного введения в программирование на Lua смотрите книгу Роберто, “Программирование на Lua”.
Lua — это динамически типизированный язык. Это означает, что переменные не имеют типов; только значения имеют типы. В языке отсутствуют определения типов. Все значения имеют свой собственный тип.
Все значения в Lua являются значениями первого класса. Это означает, что все значения могут храниться в переменных, передаваться в качестве аргументов другим функциям и возвращаться в качестве результатов.
В Lua есть восемь основных типов: nil, boolean, number, string, function, userdata, thread и table.
nil имеет одно единственное значение — nil, основное свойство которого заключается в том, что оно отличается от любого другого значения; оно часто представляет отсутствие полезного значения.boolean имеет два значения: false и true. Оба nil и false делают условие ложным; их вместе называют ложными значениями. Любое другое значение делает условие истинным. Несмотря на свое название, false часто используется как альтернатива nil, с ключевым отличием в том, что false ведет себя как обычное значение в таблице, в то время как nil в таблице представляет отсутствующий ключ.number представляет как целые числа, так и вещественные (числа с плавающей запятой), используя два подтипа: integer и float. Стандартный Lua использует 64-битные целые числа и числа с двойной точностью (64 бита), но вы также можете скомпилировать Lua так, чтобы он использовал 32-битные целые числа и/или числа с одинарной точностью (32 бита). Опция с 32 битами как для целых чисел, так и для чисел с плавающей запятой особенно привлекательна для малых машин и встроенных систем. (Смотрите макрос LUA_32BITS в файле luaconf.h.)Если не указано иное, любое переполнение при манипуляциях с целыми значениями оборачивается, согласно обычным правилам арифметики с дополнительным кодом. (Другими словами, фактический результат — это уникальное представимое целое число, которое равно математическому результату по модулю 2n, где n — это количество битов целого типа.)
Lua имеет явные правила о том, когда используется каждый подтип, но также автоматически выполняет преобразования между ними по мере необходимости (см. §3.4.3). Поэтому программист может в основном игнорировать разницу между целыми числами и числами с плавающей запятой или полностью контролировать представление каждого числа.
string представляет собой неизменяемые последовательности байтов. Lua является 8-битным чистым языком: строки могут содержать любое 8-битное значение, включая встроенные нули (’\0’). Lua также не зависит от кодировки; он не делает предположений о содержимом строки. Длина любой строки в Lua должна помещаться в целое число Lua.Lua может вызывать (и манипулировать) функциями, написанными как на Lua, так и на C (см. §3.4.10). Обе они представлены типом function.
Тип userdata предоставляется для хранения произвольных данных C в переменных Lua. Значение userdata представляет собой блок необработанной памяти. Существует два вида userdata: полное userdata, которое является объектом с блоком памяти, управляемым Lua, и легкое userdata, которое просто представляет собой значение указателя C. У userdata нет предопределенных операций в Lua, кроме присваивания и теста идентичности. С помощью метатаблиц программист может определить операции для значений полного userdata (см. §2.4). Значения userdata не могут быть созданы или изменены в Lua, только через C API. Это гарантирует целостность данных, принадлежащих хост-программе и библиотекам C.
Тип thread представляет собой независимые потоки выполнения и используется для реализации корутин (см. §2.6). Потоки Lua не связаны с потоками операционной системы. Lua поддерживает корутины на всех системах, даже на тех, которые не поддерживают потоки нативно.
Тип table реализует ассоциативные массивы, то есть массивы, которые могут иметь в качестве индексов не только числа, но и любое значение Lua, кроме nil и NaN. (Not a Number — это специальное значение с плавающей запятой, используемое стандартом IEEE 754 для представления неопределенных числовых результатов, таких как 0/0.) Таблицы могут быть гетерогенными; то есть они могут содержать значения всех типов (кроме nil). Любой ключ, связанный со значением nil, не считается частью таблицы. Напротив, любой ключ, который не является частью таблицы, имеет связанное значение nil.
Таблицы являются единственным механизмом структурирования данных в Lua; их можно использовать для представления обычных массивов, списков, символических таблиц, множеств, записей, графов, деревьев и т. д. Для представления записей Lua использует имя поля в качестве индекса. Язык поддерживает это представление, предоставляя a.name как синтаксический сахар для a[“name”]. В Lua есть несколько удобных способов создания таблиц (см. §3.4.9).
Как и индексы, значения полей таблицы могут быть любого типа. В частности, поскольку функции являются значениями первого класса, поля таблицы могут содержать функции. Таким образом, таблицы также могут содержать методы (см. §3.4.11).
Индексирование таблиц следует определению сырого равенства (raw equality) в языке. Выражения a[i] и a[j] обозначают один и тот же элемент таблицы тогда и только тогда, когда i и j сыро равны (то есть равны без учёта метаметодов).
В частности:
1.0 == 1).Пример:
Если написать a[2.0] = true, то фактически в таблицу будет вставлен ключ 2 (целое число), а не 2.0.
raw equality) — сравнение без метаметодов.1.0 и 1 считаются одинаковыми ключами.a[2.0] превращается в a[2].Это важно учитывать при работе с таблицами, чтобы избежать неожиданного поведения.
Таблицы, функции, потоки и значения (полного) userdata являются объектами: переменные на самом деле не содержат эти значения, а только ссылки на них. Присваивание, передача параметров и возвращение функций всегда манипулируют ссылками на такие значения; эти операции не подразумевают никакого рода копирования.
Функция библиотеки type возвращает строку, описывающую тип данного значения (см. type).
Как мы обсудим далее в §3.2 и §3.3.3, любое обращение к свободному имени (то есть имени, не привязанному к какому-либо объявлению) var синтаксически переводится в _ENV.var. Более того, каждый блок компилируется в области внешней локальной переменной с именем _ENV (см. §3.3.2), так что само _ENV никогда не является свободным именем в блоке.
Несмотря на существование этой внешней переменной _ENV и перевод свободных имен, _ENV является совершенно обычным именем. В частности, вы можете определять новые переменные и параметры с этим именем. Каждое обращение к свободному имени использует _ENV, который виден в данной точке программы, следуя обычным правилам видимости Lua (см. §3.5).
Любая таблица, используемая в качестве значения _ENV, называется окружением.
Lua хранит особое окружение, называемое глобальным окружением. Это значение хранится по специальному индексу в C-регистре (см. §4.3). В Lua глобальная переменная _G инициализируется этим же значением. (_G никогда не используется внутренне, поэтому изменение его значения повлияет только на ваш собственный код.)
Когда Lua загружает блок, значение по умолчанию для его переменной _ENV — это глобальное окружение (см. load). Таким образом, по умолчанию свободные имена в коде Lua ссылаются на записи в глобальном окружении и, следовательно, также называются глобальными переменными. Более того, все стандартные библиотеки загружаются в глобальное окружение, и некоторые функции там работают с этим окружением. Вы можете использовать load (или loadfile), чтобы загрузить блок с другим окружением. (В C вам нужно загрузить блок, а затем изменить значение его первого upvalue; см. lua_setupvalue.)
Несколько операций в Lua могут вызывать ошибку. Ошибка прерывает нормальный поток выполнения программы, который может продолжиться, поймав ошибку.
Lua-код может явно вызвать ошибку, вызвав функцию error. (Эта функция никогда не возвращает значение.)
Чтобы поймать ошибки в Lua, вы можете выполнить защищенный вызов, используя pcall (или xpcall). Функция pcall вызывает заданную функцию в защищенном режиме. Любая ошибка во время выполнения функции останавливает ее выполнение, и управление немедленно возвращается в pcall, который возвращает код состояния.
Поскольку Lua является встроенным языком расширения, код Lua начинает выполняться по вызову из C-кода в хост-программе. (Когда вы используете Lua в автономном режиме, приложение lua является хост-программой.) Обычно этот вызов защищен; поэтому, когда происходит незащищенная ошибка во время компиляции или выполнения блока Lua, управление возвращается в хост, который может предпринять соответствующие меры, такие как вывод сообщения об ошибке.
Каждый раз, когда возникает ошибка, объект ошибки передается с информацией об ошибке. Сам Lua генерирует только ошибки, объект ошибки которых является строкой, но программы могут генерировать ошибки с любым значением в качестве объекта ошибки. Обработка таких объектов ошибок зависит от программы Lua или ее хоста. По историческим причинам объект ошибки часто называется сообщением об ошибке, даже если он не обязательно должен быть строкой.
Когда вы используете xpcall (или lua_pcall в C), вы можете передать обработчик сообщений, который будет вызван в случае ошибок. Эта функция вызывается с оригинальным объектом ошибки и возвращает новый объект ошибки. Она вызывается до того, как ошибка развернет стек, чтобы собрать больше информации об ошибке, например, проверяя стек и создавая трассировку стека. Этот обработчик сообщений также защищен защищенным вызовом; поэтому ошибка внутри обработчика сообщений снова вызовет обработчик сообщений. Если этот цикл продолжается слишком долго, Lua прерывает его и возвращает соответствующее сообщение. Обработчик сообщений вызывается только для обычных ошибок времени выполнения. Он не вызывается для ошибок выделения памяти и для ошибок при выполнении финализаторов или других обработчиков сообщений.
Lua также предлагает систему предупреждений (см. warn). В отличие от ошибок, предупреждения никоим образом не мешают выполнению программы. Обычно они просто генерируют сообщение для пользователя, хотя это поведение можно адаптировать из C (см. lua_setwarnf).
Каждое значение в Lua может иметь метатаблицу. Эта метатаблица — это обычная таблица Lua, которая определяет поведение оригинального значения при определенных событиях. Вы можете изменить несколько аспектов поведения значения, установив конкретные поля в его метатаблице. Например, когда нечисловое значение является операндом сложения, Lua проверяет наличие функции в поле __add метатаблицы значения. Если она находит такую функцию, Lua вызывает ее для выполнения сложения.
Ключом для каждого события в метатаблице является строка с именем события, предшествующая двумя подчеркиваниями; соответствующее значение называется метазначением. Для большинства событий метазначение должно быть функцией, которая затем называется метаметодом. В предыдущем примере ключом является строка “__add”, а метаметодом — функция, выполняющая сложение. Если не указано иное, метаметодом может быть любое вызываемое значение, которое является либо функцией, либо значением с метаметодом __call.
Вы можете запросить метатаблицу любого значения, используя функцию getmetatable. Lua запрашивает метаметоды в метатаблицах, используя сырой доступ (см. rawget).
Вы можете заменить метатаблицу таблиц, используя функцию setmetatable. Вы не можете изменить метатаблицу других типов из кода Lua, кроме как с помощью библиотеки debug (§6.10).
Таблицы и полное userdata имеют индивидуальные метатаблицы, хотя несколько таблиц и userdata могут делить свои метатаблицы. Значения всех других типов делят одну единственную метатаблицу на тип; то есть, существует одна единственная метатаблица для всех чисел, одна для всех строк и т. д. По умолчанию значение не имеет метатаблицы, но библиотека строк устанавливает метатаблицу для типа строк (см. §6.4).
Подробный список операций, контролируемых метатаблицами, приведен ниже. Каждое событие идентифицируется своим соответствующим ключом. По соглашению, все ключи метатаблиц, используемые Lua, состоят из двух подчеркиваний, за которыми следуют строчные латинские буквы.
__add: операция сложения (+). Если любой операнд для сложения не является числом, Lua попытается вызвать метаметод. Он начинает с проверки первого операнда (даже если это число); если этот операнд не определяет метаметод для __add, то Lua проверит второй операнд. Если Lua находит метаметод, он вызывает этот метаметод с двумя операндами в качестве аргументов, и результат вызова (приведенный к одному значению) является результатом операции. В противном случае, если метаметод не найден, Lua вызывает ошибку.
__sub: операция вычитания (-). Поведение аналогично операции сложения.
__mul: операция умножения (*). Поведение аналогично операции сложения.
__div: операция деления (/). Поведение аналогично операции сложения.
__mod: операция взятия остатка (%) . Поведение аналогично операции сложения.
__pow: операция возведения в степень (^). Поведение аналогично операции сложения.
__unm: операция отрицания (унарный -). Поведение аналогично операции сложения.
__idiv: операция целочисленного деления (//). Поведение аналогично операции сложения.
__band: побитовая операция И (&). Поведение аналогично операции сложения, за исключением того, что Lua попытается вызвать метаметод, если любой операнд не является ни целым числом, ни числом с плавающей запятой, приводимым к целому (см. §3.4.3).
__bor: побитовая операция ИЛИ (|). Поведение аналогично побитовой операции И.
__bxor: побитовая операция исключающего ИЛИ (двойной ~). Поведение аналогично побитовой операции И.
__bnot: побитовая операция НЕ (унарный ~). Поведение аналогично побитовой операции И.
__shl: побитовый сдвиг влево («). Поведение аналогично побитовой операции И.
__shr: побитовый сдвиг вправо (»). Поведение аналогично побитовой операции И.
__concat: операция конкатенации (..). Поведение аналогично операции сложения, за исключением того, что Lua попытается вызвать метаметод, если любой операнд не является ни строкой, ни числом (которое всегда приводимо к строке).
__len: операция длины (#). Если объект не является строкой, Lua попытается вызвать его метаметод. Если метаметод существует, Lua вызывает его с объектом в качестве аргумента, и результат вызова (всегда приведенный к одному значению) является результатом операции. Если метаметода нет, но объект является таблицей, то Lua использует операцию длины таблицы (см. §3.4.7). В противном случае Lua вызывает ошибку.
__eq: операция равенства (==). Поведение аналогично операции сложения, за исключением того, что Lua попытается вызвать метаметод только тогда, когда сравниваемые значения являются либо обеими таблицами, либо обоими полными userdata и они не равны по примитивному сравнению. Результат вызова всегда преобразуется в логическое значение.
__lt: операция “меньше чем” (<). Поведение аналогично операции сложения, за исключением того, что Lua попытается вызвать метаметод только тогда, когда сравниваемые значения не являются ни обоими числами, ни обеими строками. Более того, результат вызова всегда преобразуется в логическое значение.
__le: операция “меньше или равно” (<=). Поведение аналогично операции “меньше чем”.
__index: операция доступа по индексу table[key]. Это событие происходит, когда table не является таблицей или когда ключ отсутствует в таблице. Метазначение ищется в метатаблице таблицы. Метазначение для этого события может быть либо функцией, либо таблицей, либо любым значением с метазначением __index. Если это функция, она вызывается с таблицей и ключом в качестве аргументов, и результат вызова (приведенный к одному значению) является результатом операции. В противном случае окончательный результат — это результат индексации этого метазначения с ключом. Эта индексация является обычной, а не сырой, и, следовательно, может вызвать другой метаметод __index.
__newindex: операция присваивания по индексу table[key] = value. Как и событие индексации, это событие происходит, когда table не является таблицей или когда ключ отсутствует в таблице. Метазначение ищется в метатаблице таблицы. Как и в случае с индексацией, метазначение для этого события может быть либо функцией, либо таблицей, либо любым значением с метазначением __newindex. Если это функция, она вызывается с таблицей, ключом и значением в качестве аргументов. В противном случае Lua повторяет присваивание индексации для этого метазначения с тем же ключом и значением. Это присваивание является обычным, а не сырым, и, следовательно, может вызвать другой метаметод __newindex.
Каждый раз, когда вызывается метазначение __newindex, Lua не выполняет примитивное присваивание. Если это необходимо, сам метаметод может вызвать rawset для выполнения присваивания.
__call: операция вызова func(args). Это событие происходит, когда Lua пытается вызвать значение, не являющееся функцией (то есть func не является функцией). Метаметод ищется в func. Если он присутствует, метаметод вызывается с func в качестве первого аргумента, за которым следуют аргументы оригинального вызова (args). Все результаты вызова являются результатами операции. Это единственный метаметод, который позволяет возвращать несколько результатов.---
config:
theme: redux
---
flowchart LR
A["Пользователь"] -- Запрос --> B["Reverse Proxy Nginx/Traefik"]
B -- Проверка аутентификации --> C["Authelia"]
C -- Данные пользователей --> D["Хранилище: PostgreSQL/MySQL"]
C -- 2FA/SMS --> E["Провайдер: Twilio/Email"]
C -- Разрешить/Запретить --> B
B -- Доступ разрешен --> F["Защищенный сервис"]
B:::Aqua
C:::Rose
F:::Peach
classDef Aqua stroke-width:1px, stroke-dasharray:none, stroke:#46EDC8, fill:#DEFFF8, color:#378E7A
classDef Rose stroke-width:2px, stroke-dasharray:none, stroke:#FF5978, fill:#FFDFE5, color:#8E2236
classDef Peach stroke-width:1px, stroke-dasharray:none, stroke:#FBB35A, fill:#FFEFDB, color:#8F632D
style D fill:#FFD600
style E fill:#C8E6C9
graph TD
subgraph Authelia
A[Frontend] -->|API| B[Backend]
B --> C[Аутентификация]
B --> D[Авторизация]
B --> E[2FA]
C -->|LDAP/OIDC| F[Identity Provider]
D -->|ACL| G[Политики доступа]
E -->|TOTP/SMS| H[Провайдеры 2FA]
end
I[Reverse Proxy] -->|Запросы| B
B -->|Сессии| J[Redis]
F -->|Пользователи| K[PostgreSQL]
config.template.yml который располагается в каждой секции сайта.Конфигурация оформляется в виде файла config.template.yml который располагается в каждой секции сайта.
docker run authelia/authelia:latest authelia config validate --config /config/configuration.yml
# yamllint disable rule:comments-indentation
---
###############################################################################
## Authelia Configuration ##
###############################################################################
##
## Notes:
##
## - the default location of this file is assumed to be configuration.yml unless otherwise noted
## - when using docker the container expects this by default to be at /config/configuration.yml
## - the default location where this file is loaded from can be overridden with the X_AUTHELIA_CONFIG environment var
## - the comments in this configuration file are helpful but users should consult the official documentation on the
## website at https://www.authelia.com/ or https://www.authelia.com/configuration/prologue/introduction/
## - this configuration file template is not automatically updated
##
## Certificates directory specifies where Authelia will load trusted certificates (public portion) from in addition to
## the system certificates store.
## They should be in base64 format, and have one of the following extensions: *.cer, *.crt, *.pem.
# certificates_directory: '/config/certificates/'
## The theme to display: light, dark, grey, auto.
# theme: 'light'
## Set the default 2FA method for new users and for when a user has a preferred method configured that has been
## disabled. This setting must be a method that is enabled.
## Options are totp, webauthn, mobile_push.
# default_2fa_method: ''
##
## Server Configuration
##
# server:
## The address for the Main server to listen on in the address common syntax.
## Formats:
## - [<scheme>://]<hostname>[:<port>][/<path>]
## - [<scheme>://][hostname]:<port>[/<path>]
## Square brackets indicate optional portions of the format. Scheme must be 'tcp', 'tcp4', 'tcp6', 'unix', or 'fd'.
## The default scheme is 'unix' if the address is an absolute path otherwise it's 'tcp'. The default port is '9091'.
## If the path is specified this configures the router to handle both the `/` path and the configured path.
# address: 'tcp://:9091/'
## Set the path on disk to Authelia assets.
## Useful to allow overriding of specific static assets.
# asset_path: '/config/assets/'
## Disables writing the health check vars to /app/.healthcheck.env which makes healthcheck.sh return exit code 0.
## This is disabled by default if either /app/.healthcheck.env or /app/healthcheck.sh do not exist.
# disable_healthcheck: false
## Authelia by default doesn't accept TLS communication on the server port. This section overrides this behaviour.
# tls:
## The path to the DER base64/PEM format private key.
# key: ''
## The path to the DER base64/PEM format public certificate.
# certificate: ''
## The list of certificates for client authentication.
# client_certificates: []
## Server headers configuration/customization.
# headers:
## The CSP Template. Read the docs.
# csp_template: ''
## Server Buffers configuration.
# buffers:
## Buffers usually should be configured to be the same value.
## Explanation at https://www.authelia.com/c/server#buffer-sizes
## Read buffer size adjusts the server's max incoming request size in bytes.
## Write buffer size does the same for outgoing responses.
## Read buffer.
# read: 4096
## Write buffer.
# write: 4096
## Server Timeouts configuration.
# timeouts:
## Read timeout in the duration common syntax.
# read: '6 seconds'
## Write timeout in the duration common syntax.
# write: '6 seconds'
## Idle timeout in the duration common syntax.
# idle: '30 seconds'
## Server Endpoints configuration.
## This section is considered advanced and it SHOULD NOT be configured unless you've read the relevant documentation.
# endpoints:
## Enables the pprof endpoint.
# enable_pprof: false
## Enables the expvars endpoint.
# enable_expvars: false
## Configure the authz endpoints.
# authz:
# forward-auth:
# implementation: 'ForwardAuth'
# authn_strategies: []
# ext-authz:
# implementation: 'ExtAuthz'
# authn_strategies: []
# auth-request:
# implementation: 'AuthRequest'
# authn_strategies: []
# legacy:
# implementation: 'Legacy'
# authn_strategies: []
##
## Log Configuration
##
# log:
## Level of verbosity for logs: info, debug, trace.
# level: 'debug'
## Format the logs are written as: json, text.
# format: 'json'
## File path where the logs will be written. If not set logs are written to stdout.
# file_path: '/config/authelia.log'
## Whether to also log to stdout when a log_file_path is defined.
# keep_stdout: false
##
## Telemetry Configuration
##
# telemetry:
##
## Metrics Configuration
##
# metrics:
## Enable Metrics.
# enabled: false
## The address for the Metrics server to listen on in the address common syntax.
## Formats:
## - [<scheme>://]<hostname>[:<port>][/<path>]
## - [<scheme>://][hostname]:<port>[/<path>]
## Square brackets indicate optional portions of the format. Scheme must be 'tcp', 'tcp4', 'tcp6', 'unix', or 'fd'.
## The default scheme is 'unix' if the address is an absolute path otherwise it's 'tcp'. The default port is '9959'.
## If the path is not specified it defaults to `/metrics`.
# address: 'tcp://:9959/metrics'
## Metrics Server Buffers configuration.
# buffers:
## Read buffer.
# read: 4096
## Write buffer.
# write: 4096
## Metrics Server Timeouts configuration.
# timeouts:
## Read timeout in the duration common syntax.
# read: '6 seconds'
## Write timeout in the duration common syntax.
# write: '6 seconds'
## Idle timeout in the duration common syntax.
# idle: '30 seconds'
##
## TOTP Configuration
##
## Parameters used for TOTP generation.
# totp:
## Disable TOTP.
# disable: false
## The issuer name displayed in the Authenticator application of your choice.
# issuer: 'authelia.com'
## The TOTP algorithm to use.
## It is CRITICAL you read the documentation before changing this option:
## https://www.authelia.com/c/totp#algorithm
# algorithm: 'SHA1'
## The number of digits a user has to input. Must either be 6 or 8.
## Changing this option only affects newly generated TOTP configurations.
## It is CRITICAL you read the documentation before changing this option:
## https://www.authelia.com/c/totp#digits
# digits: 6
## The period in seconds a Time-based One-Time Password is valid for.
## Changing this option only affects newly generated TOTP configurations.
# period: 30
## The skew controls number of Time-based One-Time Passwords either side of the current one that are valid.
## Warning: before changing skew read the docs link below.
# skew: 1
## See: https://www.authelia.com/c/totp#input-validation to read
## the documentation.
## The size of the generated shared secrets. Default is 32 and is sufficient in most use cases, minimum is 20.
# secret_size: 32
## The allowed algorithms for a user to pick from.
# allowed_algorithms:
# - 'SHA1'
## The allowed digits for a user to pick from.
# allowed_digits:
# - 6
## The allowed periods for a user to pick from.
# allowed_periods:
# - 30
## Disable the reuse security policy which prevents replays of one-time password code values.
# disable_reuse_security_policy: false
##
## WebAuthn Configuration
##
## Parameters used for WebAuthn.
# webauthn:
## Disable WebAuthn.
# disable: false
## Enables logins via a Passkey.
# enable_passkey_login: false
## The display name the browser should show the user for when using WebAuthn to login/register.
# display_name: 'Authelia'
## Conveyance preference controls if we collect the attestation statement including the AAGUID from the device.
## Options are none, indirect, direct.
# attestation_conveyance_preference: 'indirect'
## The interaction timeout for WebAuthn dialogues in the duration common syntax.
# timeout: '60 seconds'
## Authenticator Filtering.
# filtering:
## Prohibits registering Authenticators that claim they can export their credentials in some way.
# prohibit_backup_eligibility: false
## Permitted AAGUID's. If configured specifically only allows the listed AAGUID's.
# permitted_aaguids: []
## Prohibited AAGUID's. If configured prohibits the use of specific AAGUID's.
# prohibited_aaguids: []
## Selection Criteria controls the preferences for registration.
# selection_criteria:
## The attachment preference. Either 'cross-platform' for dedicated authenticators, or 'platform' for embedded
## authenticators.
# attachment: 'cross-platform'
## The discoverability preference. Options are 'discouraged', 'preferred', and 'required'.
# discoverability: 'discouraged'
## User verification controls if the user must make a gesture or action to confirm they are present.
## Options are required, preferred, discouraged.
# user_verification: 'preferred'
## Metadata Service validation via MDS3.
# metadata:
## Enable the metadata fetch behaviour.
# enabled: false
## Enable Validation of the Trust Anchor. This generally should be enabled if you're using the metadata. It
## ensures the attestation certificate presented by the authenticator is valid against the MDS3 certificate that
## issued the attestation certificate.
# validate_trust_anchor: true
## Enable Validation of the Entry. This ensures that the MDS3 actually contains the metadata entry. If not enabled
## attestation certificates which are not formally registered will be skipped. This may potentially exclude some
## virtual authenticators.
# validate_entry: true
## Enabling this allows attestation certificates with a zero AAGUID to pass validation. This is important if you do
## use non-conformant authenticators like Apple ID.
# validate_entry_permit_zero_aaguid: false
## Enable Validation of the Authenticator Status.
# validate_status: true
## List of statuses which are considered permitted when validating an authenticator's metadata. Generally it is
## recommended that this is not configured as any other status the authenticator's metadata has will result in an
## error. This option is ineffectual if validate_status is false.
# validate_status_permitted: ~
## List of statuses that should be prohibited when validating an authenticator's metadata. Generally it is
## recommended that this is not configured as there are safe defaults. This option is ineffectual if validate_status
## is false, or validate_status_permitted has values.
# validate_status_prohibited: ~
##
## Duo Push API Configuration
##
## Parameters used to contact the Duo API. Those are generated when you protect an application of type
## "Partner Auth API" in the management panel.
# duo_api:
# disable: false
# hostname: 'api-123456789.example.com'
# integration_key: 'ABCDEF'
## Secret can also be set using a secret: https://www.authelia.com/c/secrets
# secret_key: '1234567890abcdefghifjkl'
# enable_self_enrollment: false
##
## Identity Validation Configuration
##
## This configuration tunes the identity validation flows.
identity_validation:
## Reset Password flow. Adjusts how the reset password flow operates.
reset_password:
## Maximum allowed time before the JWT is generated and when the user uses it in the duration common syntax.
# jwt_lifespan: '5 minutes'
## The algorithm used for the Reset Password JWT.
# jwt_algorithm: 'HS256'
## The secret key used to sign and verify the JWT.
jwt_secret: 'a_very_important_secret'
## Elevated Session flows. Adjusts the flow which require elevated sessions for example managing credentials, adding,
## removing, etc.
# elevated_session:
## Maximum allowed lifetime after the One-Time Code is generated that it is considered valid.
# code_lifespan: '5 minutes'
## Maximum allowed lifetime after the user uses the One-Time Code and the user must perform the validation again in
## the duration common syntax.
# elevation_lifespan: '10 minutes'
## Number of characters the one-time password contains.
# characters: 8
## In addition to the One-Time Code requires the user performs a second factor authentication.
# require_second_factor: false
## Skips the elevation requirement and entry of the One-Time Code if the user has performed second factor
## authentication.
# skip_second_factor: false
##
## NTP Configuration
##
## This is used to validate the servers time is accurate enough to validate TOTP.
# ntp:
## The address of the NTP server to connect to in the address common syntax.
## Format: [<scheme>://]<hostname>[:<port>].
## Square brackets indicate optional portions of the format. Scheme must be 'udp', 'udp4', or 'udp6'.
## The default scheme is 'udp'. The default port is '123'.
# address: 'udp://time.cloudflare.com:123'
## NTP version.
# version: 4
## Maximum allowed time offset between the host and the NTP server in the duration common syntax.
# max_desync: '3 seconds'
## Disables the NTP check on startup entirely. This means Authelia will not contact a remote service at all if you
## set this to true, and can operate in a truly offline mode.
# disable_startup_check: false
## The default of false will prevent startup only if we can contact the NTP server and the time is out of sync with
## the NTP server more than the configured max_desync. If you set this to true, an error will be logged but startup
## will continue regardless of results.
# disable_failure: false
##
## Definitions
##
## The definitions are used in other areas as reference points to reduce duplication.
##
# definitions:
## The user attribute definitions.
# user_attributes:
## The name of the definition.
# definition_name:
## The common expression language expression for this definition.
# expression: ''
## The network definitions.
# network:
## The name of the definition followed by the list of CIDR network addresses in this definition.
# internal:
# - '10.10.0.0/16'
# - '172.16.0.0/12'
# - '192.168.2.0/24'
# VPN:
# - '10.9.0.0/16'
##
## Authentication Backend Provider Configuration
##
## Used for verifying user passwords and retrieve information such as email address and groups users belong to.
##
## The available providers are: `file`, `ldap`. You must use only one of these providers.
# authentication_backend:
## Password Change Options.
# password_change:
## Disable both the HTML element and the API for password change functionality.
# disable: false
## Password Reset Options.
# password_reset:
## Disable both the HTML element and the API for reset password functionality.
# disable: false
## External reset password url that redirects the user to an external reset portal. This disables the internal reset
## functionality.
# custom_url: ''
## The amount of time to wait before we refresh data from the authentication backend in the duration common syntax.
## To disable this feature set it to 'disable', this will slightly reduce security because for Authelia, users will
## always belong to groups they belonged to at the time of login even if they have been removed from them in LDAP.
## To force update on every request you can set this to '0' or 'always', this will increase processor demand.
## See the below documentation for more information.
## Refresh Interval docs: https://www.authelia.com/c/1fa#refresh-interval
# refresh_interval: '5 minutes'
##
## LDAP (Authentication Provider)
##
## This is the recommended Authentication Provider in production
## because it allows Authelia to offload the stateful operations
## onto the LDAP service.
# ldap:
## The address of the directory server to connect to in the address common syntax.
## Format: [<scheme>://]<hostname>[:<port>].
## Square brackets indicate optional portions of the format. Scheme must be 'ldap', 'ldaps', or 'ldapi`.
## The default scheme is 'ldapi' if the address is an absolute path otherwise it's 'ldaps'.
## The default port is '636', unless the scheme is 'ldap' in which case it's '389'.
# address: 'ldaps://127.0.0.1:636'
## The LDAP implementation, this affects elements like the attribute utilised for resetting a password.
## Acceptable options are as follows:
## - 'activedirectory' - for Microsoft Active Directory.
## - 'freeipa' - for FreeIPA.
## - 'lldap' - for lldap.
## - 'custom' - for custom specifications of attributes and filters.
## This currently defaults to 'custom' to maintain existing behaviour.
##
## Depending on the option here certain other values in this section have a default value, notably all of the
## attribute mappings have a default value that this config overrides, you can read more about these default values
## at https://www.authelia.com/c/ldap#defaults
# implementation: 'custom'
## The dial timeout for LDAP in the duration common syntax.
# timeout: '20 seconds'
## Use StartTLS with the LDAP connection.
# start_tls: false
## TLS configuration.
# tls:
## The server subject name to check the servers certificate against during the validation process.
## This option is not required if the certificate has a SAN which matches the address options hostname.
# server_name: 'ldap.example.com'
## Skip verifying the server certificate entirely. In preference to setting this we strongly recommend you add the
## certificate or the certificate of the authority signing the certificate to the certificates directory which is
## defined by the `certificates_directory` option at the top of the configuration.
## It's important to note the public key should be added to the directory, not the private key.
## This option is strongly discouraged but may be useful in some self-signed situations where validation is not
## important to the administrator.
# skip_verify: false
## Minimum TLS version for the connection.
# minimum_version: 'TLS1.2'
## Maximum TLS version for the connection.
# maximum_version: 'TLS1.3'
## The certificate chain used with the private_key if the server requests TLS Client Authentication
## i.e. Mutual TLS.
# certificate_chain: |
# -----BEGIN CERTIFICATE-----
# ...
# -----END CERTIFICATE-----
# -----BEGIN CERTIFICATE-----
# ...
# -----END CERTIFICATE-----
## The private key used with the certificate_chain if the server requests TLS Client Authentication
## i.e. Mutual TLS.
# private_key: |
# -----BEGIN PRIVATE KEY-----
# ...
# -----END PRIVATE KEY-----
## Connection Pooling configuration.
# pooling:
## Enable Pooling.
# enable: false
## Pool count.
# count: 5
## Retries to obtain a connection during the timeout.
# retries: 2
## Timeout before the attempt to obtain a connection fails.
# timeout: '10 seconds'
## The distinguished name of the container searched for objects in the directory information tree.
## See also: additional_users_dn, additional_groups_dn.
# base_dn: 'dc=example,dc=com'
## The additional_users_dn is prefixed to base_dn and delimited by a comma when searching for users.
## i.e. with this set to OU=Users and base_dn set to DC=a,DC=com; OU=Users,DC=a,DC=com is searched for users.
# additional_users_dn: 'ou=users'
## The users filter used in search queries to find the user profile based on input filled in login form.
## Various placeholders are available in the user filter which you can read about in the documentation which can
## be found at: https://www.authelia.com/c/ldap#users-filter-replacements
##
## Recommended settings are as follows:
## - Microsoft Active Directory: (&({username_attribute}={input})(objectCategory=person)(objectClass=user))
## - OpenLDAP:
## - (&({username_attribute}={input})(objectClass=person))
## - (&({username_attribute}={input})(objectClass=inetOrgPerson))
##
## To allow sign in both with username and email, one can use a filter like
## (&(|({username_attribute}={input})({mail_attribute}={input}))(objectClass=person))
# users_filter: '(&({username_attribute}={input})(objectClass=person))'
## The additional_groups_dn is prefixed to base_dn and delimited by a comma when searching for groups.
## i.e. with this set to OU=Groups and base_dn set to DC=a,DC=com; OU=Groups,DC=a,DC=com is searched for groups.
# additional_groups_dn: 'ou=groups'
## The groups filter used in search queries to find the groups based on relevant authenticated user.
## Various placeholders are available in the groups filter which you can read about in the documentation which can
## be found at: https://www.authelia.com/c/ldap#groups-filter-replacements
##
## If your groups use the `groupOfUniqueNames` structure use this instead:
## (&(uniqueMember={dn})(objectClass=groupOfUniqueNames))
# groups_filter: '(&(member={dn})(objectClass=groupOfNames))'
## The group search mode to use. Options are 'filter' or 'memberof'. It's essential to read the docs if you wish to
## use 'memberof'. Also 'filter' is the best choice for most use cases.
# group_search_mode: 'filter'
## Follow referrals returned by the server.
## This is especially useful for environments where read-only servers exist. Only implemented for write operations.
# permit_referrals: false
## The username and password of the admin user.
# user: 'cn=admin,dc=example,dc=com'
## Password can also be set using a secret: https://www.authelia.com/c/secrets
# password: 'password'
## The attributes for users and objects from the directory server.
# attributes:
## The distinguished name attribute if your directory server supports it. Users should read the docs before
## configuring. Only used for the 'memberof' group search mode.
# distinguished_name: ''
## The attribute holding the username of the user. This attribute is used to populate the username in the session
## information. For your information, Microsoft Active Directory usually uses 'sAMAccountName' and OpenLDAP
## usually uses 'uid'. Beware that this attribute holds the unique identifiers for the users binding the user and
## the configuration stored in database; therefore only single value attributes are allowed and the value must
## never be changed once attributed to a user otherwise it would break the configuration for that user.
## Technically non-unique attributes like 'mail' can also be used but we don't recommend using them, we instead
## advise to use a filter to perform alternative lookups and the attributes mentioned above
## (sAMAccountName and uid) to follow https://datatracker.ietf.org/doc/html/rfc2307.
# username: 'uid'
## The attribute holding the display name of the user. This will be used to greet an authenticated user.
# display_name: 'displayName'
## The attribute holding the mail address of the user. If multiple email addresses are defined for a user, only
## the first one returned by the directory server is used.
# mail: 'mail'
## The attribute which provides distinguished names of groups an object is a member of.
## Only used for the 'memberof' group search mode.
# member_of: 'memberOf'
## The attribute holding the name of the group.
# group_name: 'cn'
##
## File (Authentication Provider)
##
## With this backend, the users database is stored in a file which is updated when users reset their passwords.
## Therefore, this backend is meant to be used in a dev environment and not in production since it prevents Authelia
## to be scaled to more than one instance. The options under 'password' have sane defaults, and as it has security
## implications it is highly recommended you leave the default values. Before considering changing these settings
## please read the docs page below:
## https://www.authelia.com/r/passwords#tuning
##
## Important: Kubernetes (or HA) users must read https://www.authelia.com/t/statelessness
##
# file:
# path: '/config/users_database.yml'
# watch: false
# search:
# email: false
# case_insensitive: false
# password:
# algorithm: 'argon2'
# argon2:
# variant: 'argon2id'
# iterations: 3
# memory: 65536
# parallelism: 4
# key_length: 32
# salt_length: 16
# scrypt:
# variant: 'scrypt'
# iterations: 16
# block_size: 8
# parallelism: 1
# key_length: 32
# salt_length: 16
# pbkdf2:
# variant: 'sha512'
# iterations: 310000
# salt_length: 16
# sha2crypt:
# variant: 'sha512'
# iterations: 50000
# salt_length: 16
# bcrypt:
# variant: 'standard'
# cost: 12
##
## Password Policy Configuration.
##
# password_policy:
## The standard policy allows you to tune individual settings manually.
# standard:
# enabled: false
## Require a minimum length for passwords.
# min_length: 8
## Require a maximum length for passwords.
# max_length: 0
## Require uppercase characters.
# require_uppercase: true
## Require lowercase characters.
# require_lowercase: true
## Require numeric characters.
# require_number: true
## Require special characters.
# require_special: true
## zxcvbn is a well known and used password strength algorithm. It does not have tunable settings.
# zxcvbn:
# enabled: false
## Configures the minimum score allowed.
# min_score: 3
##
## Privacy Policy Configuration
##
## Parameters used for displaying the privacy policy link and drawer.
# privacy_policy:
## Enables the display of the privacy policy using the policy_url.
# enabled: false
## Enables the display of the privacy policy drawer which requires users accept the privacy policy
## on a per-browser basis.
# require_user_acceptance: false
## The URL of the privacy policy document. Must be an absolute URL and must have the 'https://' scheme.
## If the privacy policy enabled option is true, this MUST be provided.
# policy_url: ''
##
## Access Control Configuration
##
## Access control is a list of rules defining the authorizations applied for one resource to users or group of users.
##
## If 'access_control' is not defined, ACL rules are disabled and the 'deny' rule is applied, i.e., access is denied
## to everyone. Otherwise restrictions follow the rules defined.
##
## Note: One can use the wildcard * to match any subdomain.
## It must stand at the beginning of the pattern. (example: *.example.com)
##
## Note: You must put patterns containing wildcards between simple quotes for the YAML to be syntactically correct.
##
## Definition: A 'rule' is an object with the following keys: 'domain', 'subject', 'policy' and 'resources'.
##
## - 'domain' defines which domain or set of domains the rule applies to.
##
## - 'subject' defines the subject to apply authorizations to. This parameter is optional and matching any user if not
## provided. If provided, the parameter represents either a user or a group. It should be of the form
## 'user:<username>' or 'group:<groupname>'.
##
## - 'policy' is the policy to apply to resources. It must be either 'bypass', 'one_factor', 'two_factor' or 'deny'.
##
## - 'resources' is a list of regular expressions that matches a set of resources to apply the policy to. This parameter
## is optional and matches any resource if not provided.
##
## Note: the order of the rules is important. The first policy matching (domain, resource, subject) applies.
# access_control:
## Default policy can either be 'bypass', 'one_factor', 'two_factor' or 'deny'. It is the policy applied to any
## resource if there is no policy to be applied to the user.
# default_policy: 'deny'
# rules:
## Rules applied to everyone
# - domain: 'public.example.com'
# policy: 'bypass'
## Domain Regex examples. Generally we recommend just using a standard domain.
# - domain_regex: '^(?P<User>\w+)\.example\.com$'
# policy: 'one_factor'
# - domain_regex: '^(?P<Group>\w+)\.example\.com$'
# policy: 'one_factor'
# - domain_regex:
# - '^appgroup-.*\.example\.com$'
# - '^appgroup2-.*\.example\.com$'
# policy: 'one_factor'
# - domain_regex: '^.*\.example\.com$'
# policy: 'two_factor'
# - domain: 'secure.example.com'
# policy: 'one_factor'
## Network based rule, if not provided any network matches.
# networks:
# - 'internal'
# - 'VPN'
# - '192.168.1.0/24'
# - '10.0.0.1'
# - domain:
# - 'secure.example.com'
# - 'private.example.com'
# policy: 'two_factor'
# - domain: 'singlefactor.example.com'
# policy: 'one_factor'
## Rules applied to 'admins' group
# - domain: 'mx2.mail.example.com'
# subject: 'group:admins'
# policy: 'deny'
# - domain: '*.example.com'
# subject:
# - 'group:admins'
# - 'group:moderators'
# policy: 'two_factor'
## Rules applied to 'dev' group
# - domain: 'dev.example.com'
# resources:
# - '^/groups/dev/.*$'
# subject: 'group:dev'
# policy: 'two_factor'
## Rules applied to user 'john'
# - domain: 'dev.example.com'
# resources:
# - '^/users/john/.*$'
# subject: 'user:john'
# policy: 'two_factor'
## Rules applied to user 'harry'
# - domain: 'dev.example.com'
# resources:
# - '^/users/harry/.*$'
# subject: 'user:harry'
# policy: 'two_factor'
## Rules applied to user 'bob'
# - domain: '*.mail.example.com'
# subject: 'user:bob'
# policy: 'two_factor'
# - domain: 'dev.example.com'
# resources:
# - '^/users/bob/.*$'
# subject: 'user:bob'
# policy: 'two_factor'
##
## Session Provider Configuration
##
## The session cookies identify the user once logged in.
## The available providers are: `memory`, `redis`. Memory is the provider unless redis is defined.
session:
## The secret to encrypt the session data. This is only used with Redis / Redis Sentinel.
## Secret can also be set using a secret: https://www.authelia.com/c/secrets
secret: 'insecure_session_secret'
## Cookies configures the list of allowed cookie domains for sessions to be created on.
## Undefined values will default to the values below.
# cookies:
# -
## The name of the session cookie.
# name: 'authelia_session'
## The domain to protect.
## Note: the Authelia portal must also be in that domain.
# domain: 'example.com'
## Required. The fully qualified URI of the portal to redirect users to on proxies that support redirections.
## Rules:
## - MUST use the secure scheme 'https://'
## - The above 'domain' option MUST either:
## - Match the host portion of this URI.
## - Match the suffix of the host portion when prefixed with '.'.
# authelia_url: 'https://auth.example.com'
## Optional. The fully qualified URI used as the redirection location if the portal is accessed directly. Not
## configuring this option disables the automatic redirection behaviour.
##
## Note: this parameter is optional. If not provided, user won't be redirected upon successful authentication
## unless they were redirected to Authelia by the proxy.
##
## Rules:
## - MUST use the secure scheme 'https://'
## - MUST not match the 'authelia_url' option.
## - The above 'domain' option MUST either:
## - Match the host portion of this URI.
## - Match the suffix of the host portion when prefixed with '.'.
# default_redirection_url: 'https://www.example.com'
## Sets the Cookie SameSite value. Possible options are none, lax, or strict.
## Please read https://www.authelia.com/c/session#same_site
# same_site: 'lax'
## The value for inactivity, expiration, and remember_me are in seconds or the duration common syntax.
## All three of these values affect the cookie/session validity period. Longer periods are considered less secure
## because a stolen cookie will last longer giving attackers more time to spy or attack.
## The inactivity time before the session is reset. If expiration is set to 1h, and this is set to 5m, if the user
## does not select the remember me option their session will get destroyed after 1h, or after 5m since the last
## time Authelia detected user activity.
# inactivity: '5 minutes'
## The time before the session cookie expires and the session is destroyed if remember me IS NOT selected by the
## user.
# expiration: '1 hour'
## The time before the cookie expires and the session is destroyed if remember me IS selected by the user. Setting
## this value to -1 disables remember me for this session cookie domain. If allowed and the user uses the remember
## me checkbox this overrides the expiration option and disables the inactivity option.
# remember_me: '1 month'
## Cookie Session Domain default 'name' value.
# name: 'authelia_session'
## Cookie Session Domain default 'same_site' value.
# same_site: 'lax'
## Cookie Session Domain default 'inactivity' value.
# inactivity: '5m'
## Cookie Session Domain default 'expiration' value.
# expiration: '1h'
## Cookie Session Domain default 'remember_me' value.
# remember_me: '1M'
##
## Redis Provider
##
## Important: Kubernetes (or HA) users must read https://www.authelia.com/t/statelessness
##
# redis:
# host: '127.0.0.1'
# port: 6379
## Use a unix socket instead
# host: '/var/run/redis/redis.sock'
## The connection timeout in the duration common syntax.
# timeout: '5 seconds'
## The maximum number of retries on a failed command. Set it to 0 to disable retries.
# max_retries: 3
## Username used for redis authentication. This is optional and a new feature in redis 6.0.
# username: 'authelia'
## Password can also be set using a secret: https://www.authelia.com/c/secrets
# password: 'authelia'
## This is the Redis DB Index https://redis.io/commands/select (sometimes referred to as database number, DB, etc).
# database_index: 0
## The maximum number of concurrent active connections to Redis.
# maximum_active_connections: 8
## The target number of idle connections to have open ready for work. Useful when opening connections is slow.
# minimum_idle_connections: 0
## The Redis TLS configuration. If defined will require a TLS connection to the Redis instance(s).
# tls:
## The server subject name to check the servers certificate against during the validation process.
## This option is not required if the certificate has a SAN which matches the host option.
# server_name: 'myredis.example.com'
## Skip verifying the server certificate entirely. In preference to setting this we strongly recommend you add the
## certificate or the certificate of the authority signing the certificate to the certificates directory which is
## defined by the `certificates_directory` option at the top of the configuration.
## It's important to note the public key should be added to the directory, not the private key.
## This option is strongly discouraged but may be useful in some self-signed situations where validation is not
## important to the administrator.
# skip_verify: false
## Minimum TLS version for the connection.
# minimum_version: 'TLS1.2'
## Maximum TLS version for the connection.
# maximum_version: 'TLS1.3'
## The certificate chain used with the private_key if the server requests TLS Client Authentication
## i.e. Mutual TLS.
# certificate_chain: |
# -----BEGIN CERTIFICATE-----
# ...
# -----END CERTIFICATE-----
# -----BEGIN CERTIFICATE-----
# ...
# -----END CERTIFICATE-----
## The private key used with the certificate_chain if the server requests TLS Client Authentication
## i.e. Mutual TLS.
# private_key: |
# -----BEGIN PRIVATE KEY-----
# ...
# -----END PRIVATE KEY-----
## The Redis HA configuration options.
## This provides specific options to Redis Sentinel, sentinel_name must be defined (Master Name).
# high_availability:
## Sentinel Name / Master Name.
# sentinel_name: 'mysentinel'
## Specific username for Redis Sentinel. The node username and password is configured above.
# sentinel_username: 'sentinel_specific_user'
## Specific password for Redis Sentinel. The node username and password is configured above.
# sentinel_password: 'sentinel_specific_pass'
## The additional nodes to pre-seed the redis provider with (for sentinel).
## If the host in the above section is defined, it will be combined with this list to connect to sentinel.
## For high availability to be used you must have either defined; the host above or at least one node below.
# nodes:
# - host: 'sentinel-node1'
# port: 6379
# - host: 'sentinel-node2'
# port: 6379
## Choose the host with the lowest latency.
# route_by_latency: false
## Choose the host randomly.
# route_randomly: false
##
## Regulation Configuration
##
## This mechanism prevents attackers from brute forcing the first factor. It bans the user if too many attempts are made
## in a short period of time.
# regulation:
## Regulation Mode.
# modes:
# - 'user'
## The number of failed login attempts before user is banned. Set it to 0 to disable regulation.
# max_retries: 3
## The time range during which the user can attempt login before being banned in the duration common syntax. The user
## is banned if the authentication failed 'max_retries' times in a 'find_time' seconds window.
# find_time: '2 minutes'
## The length of time before a banned user can login again in the duration common syntax.
# ban_time: '5 minutes'
##
## Storage Provider Configuration
##
## The available providers are: `local`, `mysql`, `postgres`. You must use one and only one of these providers.
# storage:
## The encryption key that is used to encrypt sensitive information in the database. Must be a string with a minimum
## length of 20. Please see the docs if you configure this with an undesirable key and need to change it, you MUST use
## the CLI to change this in the database if you want to change it from a previously configured value.
# encryption_key: 'you_must_generate_a_random_string_of_more_than_twenty_chars_and_configure_this'
##
## Local (Storage Provider)
##
## This stores the data in a SQLite3 Database.
## This is only recommended for lightweight non-stateful installations.
##
## Important: Kubernetes (or HA) users must read https://www.authelia.com/t/statelessness
##
# local:
## Path to the SQLite3 Database.
# path: '/config/db.sqlite3'
##
## MySQL / MariaDB (Storage Provider)
##
# mysql:
## The address of the MySQL server to connect to in the address common syntax.
## Format: [<scheme>://]<hostname>[:<port>].
## Square brackets indicate optional portions of the format. Scheme must be 'tcp', 'tcp4', 'tcp6', or 'unix`.
## The default scheme is 'unix' if the address is an absolute path otherwise it's 'tcp'. The default port is '3306'.
# address: 'tcp://127.0.0.1:3306'
## The database name to use.
# database: 'authelia'
## The username used for SQL authentication.
# username: 'authelia'
## The password used for SQL authentication.
## Can also be set using a secret: https://www.authelia.com/c/secrets
# password: 'mypassword'
## The connection timeout in the duration common syntax.
# timeout: '5 seconds'
## MySQL TLS settings. Configuring this requires TLS.
# tls:
## The server subject name to check the servers certificate against during the validation process.
## This option is not required if the certificate has a SAN which matches the address options hostname.
# server_name: 'mysql.example.com'
## Skip verifying the server certificate entirely. In preference to setting this we strongly recommend you add the
## certificate or the certificate of the authority signing the certificate to the certificates directory which is
## defined by the `certificates_directory` option at the top of the configuration.
## It's important to note the public key should be added to the directory, not the private key.
## This option is strongly discouraged but may be useful in some self-signed situations where validation is not
## important to the administrator.
# skip_verify: false
## Minimum TLS version for the connection.
# minimum_version: 'TLS1.2'
## Maximum TLS version for the connection.
# maximum_version: 'TLS1.3'
## The certificate chain used with the private_key if the server requests TLS Client Authentication
## i.e. Mutual TLS.
# certificate_chain: |
# -----BEGIN CERTIFICATE-----
# ...
# -----END CERTIFICATE-----
# -----BEGIN CERTIFICATE-----
# ...
# -----END CERTIFICATE-----
## The private key used with the certificate_chain if the server requests TLS Client Authentication
## i.e. Mutual TLS.
# private_key: |
# -----BEGIN PRIVATE KEY-----
# ...
# -----END PRIVATE KEY-----
##
## PostgreSQL (Storage Provider)
##
# postgres:
## The address of the PostgreSQL server to connect to in the address common syntax.
## Format: [<scheme>://]<hostname>[:<port>].
## Square brackets indicate optional portions of the format. Scheme must be 'tcp', 'tcp4', 'tcp6', or 'unix`.
## The default scheme is 'unix' if the address is an absolute path otherwise it's 'tcp'. The default port is '5432'.
# address: 'tcp://127.0.0.1:5432'
## List of additional server instance configurations to fallback to when the primary instance is not available.
# servers:
# -
## The Address of this individual instance.
# address: 'tcp://127.0.0.1:5432'
## The TLS configuration for this individual instance.
# tls:
# server_name: 'postgres.example.com'
# skip_verify: false
# minimum_version: 'TLS1.2'
# maximum_version: 'TLS1.3'
# certificate_chain: |
# -----BEGIN CERTIFICATE-----
# ...
# -----END CERTIFICATE-----
# -----BEGIN CERTIFICATE-----
# ...
# -----END CERTIFICATE-----
# private_key: |
# -----BEGIN PRIVATE KEY-----
# ...
# -----END PRIVATE KEY-----
## The database name to use.
# database: 'authelia'
## The schema name to use.
# schema: 'public'
## The username used for SQL authentication.
# username: 'authelia'
## The password used for SQL authentication.
## Can also be set using a secret: https://www.authelia.com/c/secrets
# password: 'mypassword'
## The connection timeout in the duration common syntax.
# timeout: '5 seconds'
## PostgreSQL TLS settings. Configuring this requires TLS.
# tls:
## The server subject name to check the servers certificate against during the validation process.
## This option is not required if the certificate has a SAN which matches the address options hostname.
# server_name: 'postgres.example.com'
## Skip verifying the server certificate entirely. In preference to setting this we strongly recommend you add the
## certificate or the certificate of the authority signing the certificate to the certificates directory which is
## defined by the `certificates_directory` option at the top of the configuration.
## It's important to note the public key should be added to the directory, not the private key.
## This option is strongly discouraged but may be useful in some self-signed situations where validation is not
## important to the administrator.
# skip_verify: false
## Minimum TLS version for the connection.
# minimum_version: 'TLS1.2'
## Maximum TLS version for the connection.
# maximum_version: 'TLS1.3'
## The certificate chain used with the private_key if the server requests TLS Client Authentication
## i.e. Mutual TLS.
# certificate_chain: |
# -----BEGIN CERTIFICATE-----
# ...
# -----END CERTIFICATE-----
# -----BEGIN CERTIFICATE-----
# ...
# -----END CERTIFICATE-----
## The private key used with the certificate_chain if the server requests TLS Client Authentication
## i.e. Mutual TLS.
# private_key: |
# -----BEGIN PRIVATE KEY-----
# ...
# -----END PRIVATE KEY-----
##
## Notification Provider
##
## Notifications are sent to users when they require a password reset, a WebAuthn registration or a TOTP registration.
## The available providers are: filesystem, smtp. You must use only one of these providers.
# notifier:
## You can disable the notifier startup check by setting this to true.
# disable_startup_check: false
##
## File System (Notification Provider)
##
## Important: Kubernetes (or HA) users must read https://www.authelia.com/t/statelessness
##
# filesystem:
# filename: '/config/notification.txt'
##
## SMTP (Notification Provider)
##
## Use a SMTP server for sending notifications. Authelia uses the PLAIN or LOGIN methods to authenticate.
## [Security] By default Authelia will:
## - force all SMTP connections over TLS including unauthenticated connections
## - use the disable_require_tls boolean value to disable this requirement
## (only works for unauthenticated connections)
## - validate the SMTP server x509 certificate during the TLS handshake against the hosts trusted certificates
## (configure in tls section)
# smtp:
## The address of the SMTP server to connect to in the address common syntax.
# address: 'smtp://127.0.0.1:25'
## The connection timeout in the duration common syntax.
# timeout: '5 seconds'
## The username used for SMTP authentication.
# username: 'test'
## The password used for SMTP authentication.
## Can also be set using a secret: https://www.authelia.com/c/secrets
# password: 'password'
## The sender is used to is used for the MAIL FROM command and the FROM header.
## If this is not defined and the username is an email, we use the username as this value. This can either be just
## an email address or the RFC5322 'Name <email address>' format.
# sender: 'Authelia <admin@example.com>'
## HELO/EHLO Identifier. Some SMTP Servers may reject the default of localhost.
# identifier: 'localhost'
## Subject configuration of the emails sent. {title} is replaced by the text from the notifier.
# subject: '[Authelia] {title}'
## This address is used during the startup check to verify the email configuration is correct.
## It's not important what it is except if your email server only allows local delivery.
# startup_check_address: 'test@authelia.com'
## By default we require some form of TLS. This disables this check though is not advised.
# disable_require_tls: false
## Disables sending HTML formatted emails.
# disable_html_emails: false
# tls:
## The server subject name to check the servers certificate against during the validation process.
## This option is not required if the certificate has a SAN which matches the address options hostname.
# server_name: 'smtp.example.com'
## Skip verifying the server certificate entirely. In preference to setting this we strongly recommend you add the
## certificate or the certificate of the authority signing the certificate to the certificates directory which is
## defined by the `certificates_directory` option at the top of the configuration.
## It's important to note the public key should be added to the directory, not the private key.
## This option is strongly discouraged but may be useful in some self-signed situations where validation is not
## important to the administrator.
# skip_verify: false
## Minimum TLS version for the connection.
# minimum_version: 'TLS1.2'
## Maximum TLS version for the connection.
# maximum_version: 'TLS1.3'
## The certificate chain used with the private_key if the server requests TLS Client Authentication
## i.e. Mutual TLS.
# certificate_chain: |
# -----BEGIN CERTIFICATE-----
# ...
# -----END CERTIFICATE-----
# -----BEGIN CERTIFICATE-----
# ...
# -----END CERTIFICATE-----
## The private key used with the certificate_chain if the server requests TLS Client Authentication
## i.e. Mutual TLS.
# private_key: |
# -----BEGIN PRIVATE KEY-----
# ...
# -----END PRIVATE KEY-----
##
## Identity Providers
##
# identity_providers:
##
## OpenID Connect (Identity Provider)
##
## It's recommended you read the documentation before configuration of this section.
## See: https://www.authelia.com/c/oidc/provider
# oidc:
## The hmac_secret is used to sign OAuth2 tokens (authorization code, access tokens and refresh tokens).
## HMAC Secret can also be set using a secret: https://www.authelia.com/c/secrets
# hmac_secret: 'this_is_a_secret_abc123abc123abc'
## The JWK's issuer option configures multiple JSON Web Keys. It's required that at least one of the JWK's
## configured has the RS256 algorithm. For RSA keys (RS or PS) the minimum is a 2048 bit key.
# jwks:
# -
## Key ID embedded into the JWT header for key matching. Must be an alphanumeric string with 7 or less characters.
## This value is automatically generated if not provided. It's recommended to not configure this.
# key_id: 'example'
## The key algorithm used with this key.
# algorithm: 'RS256'
## The key use expected with this key. Currently only 'sig' is supported.
# use: 'sig'
## Required Private Key in PEM DER form.
# key: |
# -----BEGIN PRIVATE KEY-----
# ...
# -----END PRIVATE KEY-----
## Optional matching certificate chain in PEM DER form that matches the key. All certificates within the chain
## must be valid and current, and from top to bottom each certificate must be signed by the subsequent one.
# certificate_chain: |
# -----BEGIN CERTIFICATE-----
# ...
# -----END CERTIFICATE-----
# -----BEGIN CERTIFICATE-----
# ...
# -----END CERTIFICATE-----
## Enables additional debug messages.
# enable_client_debug_messages: false
## SECURITY NOTICE: It's not recommended changing this option and values below 8 are strongly discouraged.
# minimum_parameter_entropy: 8
## SECURITY NOTICE: It's not recommended changing this option, and highly discouraged to have it set to 'never'
## for security reasons.
# enforce_pkce: 'public_clients_only'
## SECURITY NOTICE: It's not recommended changing this option. We encourage you to read the documentation and fully
## understanding it before enabling this option.
# enable_jwt_access_token_stateless_introspection: false
## The signing algorithm used for signing the discovery and metadata responses. An issuer JWK with a matching
## algorithm must be available when configured. Most clients completely ignore this and it has a performance cost.
# discovery_signed_response_alg: 'none'
## The signing key id used for signing the discovery and metadata responses. An issuer JWK with a matching key id
## must be available when configured. Most clients completely ignore this and it has a performance cost.
# discovery_signed_response_key_id: ''
## Authorization Policies which can be utilized by clients. The 'policy_name' is an arbitrary value that you pick
## which is utilized as the value for the 'authorization_policy' on the client.
# authorization_policies:
# policy_name:
# default_policy: 'two_factor'
# rules:
# - policy: 'one_factor'
# subject: 'group:services'
# networks:
# - '192.168.1.0/24'
## The lifespans configure the expiration for these token types in the duration common syntax. In addition to this
## syntax the lifespans can be customized per-client.
# lifespans:
## Configures the default/fallback lifespan for given token types. This behaviour applies to all clients and all
## grant types but you can override this behaviour using the custom lifespans.
# access_token: '1 hour'
# authorize_code: '1 minute'
# id_token: '1 hour'
# refresh_token: '90 minutes'
## Cross-Origin Resource Sharing (CORS) settings.
# cors:
## List of endpoints in addition to the metadata endpoints to permit cross-origin requests on.
# endpoints:
# - 'authorization'
# - 'pushed-authorization-request'
# - 'token'
# - 'revocation'
# - 'introspection'
# - 'userinfo'
## List of allowed origins.
## Any origin with https is permitted unless this option is configured or the
## allowed_origins_from_client_redirect_uris option is enabled.
# allowed_origins:
# - 'https://example.com'
## Automatically adds the origin portion of all redirect URI's on all clients to the list of allowed_origins,
## provided they have the scheme http or https and do not have the hostname of localhost.
# allowed_origins_from_client_redirect_uris: false
## Clients is a list of registered clients and their configuration.
## It's recommended you read the documentation before configuration of a registered client.
## See: https://www.authelia.com/c/oidc/registered-clients
# clients:
# -
## The Client ID is the OAuth 2.0 and OpenID Connect 1.0 Client ID which is used to link an application to a
## configuration.
# client_id: 'myapp'
## The description to show to users when they end up on the consent screen. Defaults to the ID above.
# client_name: 'My Application'
## The client secret is a shared secret between Authelia and the consumer of this client.
# yamllint disable-line rule:line-length
# client_secret: '$pbkdf2-sha512$310000$c8p78n7pUMln0jzvd4aK4Q$JNRBzwAo0ek5qKn50cFzzvE9RXV88h1wJn5KGiHrD0YKtZaR/nCb2CJPOsKaPK0hjf.9yHxzQGZziziccp6Yng' # The digest of 'insecure_secret'.
## Sector Identifiers are occasionally used to generate pairwise subject identifiers. In most cases this is not
## necessary. It is critical to read the documentation for more information.
# sector_identifier_uri: 'https://example.com/sector.json'
## Sets the client to public. This should typically not be set, please see the documentation for usage.
# public: false
## Redirect URI's specifies a list of valid case-sensitive callbacks for this client.
# redirect_uris:
# - 'https://oidc.example.com:8080/oauth2/callback'
## Request URI's specifies a list of valid case-sensitive TLS-secured URIs for this client for use as
## URIs to fetch Request Objects.
# request_uris:
# - 'https://oidc.example.com:8080/oidc/request-object.jwk'
## Audience this client is allowed to request.
# audience: []
## Scopes this client is allowed to request.
# scopes:
# - 'openid'
# - 'groups'
# - 'email'
# - 'profile'
## Grant Types configures which grants this client can obtain.
## It's not recommended to define this unless you know what you're doing.
# grant_types:
# - 'authorization_code'
## Response Types configures which responses this client can be sent.
## It's not recommended to define this unless you know what you're doing.
# response_types:
# - 'code'
## Response Modes configures which response modes this client supports.
# response_modes:
# - 'form_post'
# - 'query'
## The policy to require for this client; one_factor or two_factor. Can also be the key names for the
## authorization policies section.
# authorization_policy: 'two_factor'
## The custom lifespan name to use for this client. This must be configured independent of the client before
## utilization. Custom lifespans are reusable similar to authorization policies.
# lifespan: ''
## The consent mode controls how consent is obtained.
# consent_mode: 'auto'
## This value controls the duration a consent on this client remains remembered when the consent mode is
## configured as 'auto' or 'pre-configured' in the duration common syntax.
# pre_configured_consent_duration: '1 week'
## Requires the use of Pushed Authorization Requests for this client when set to true.
# require_pushed_authorization_requests: false
## Enforces the use of PKCE for this client when set to true.
# require_pkce: false
## Enforces the use of PKCE for this client when configured, and enforces the specified challenge method.
## Options are 'plain' and 'S256'.
# pkce_challenge_method: 'S256'
## The signing algorithm used for signing the authorization responses.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#authorization_signed_response_alg
# authorization_signed_response_alg: 'none'
## The signing key id used for signing the authorization responses.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#authorization_signed_response_key_id
# authorization_signed_response_key_id: ''
## The content encryption algorithm used for encrypting the authorization responses.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#authorization_encrypted_response_alg
# authorization_encrypted_response_alg: 'none'
## The encryption algorithm used for encrypting the authorization responses.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#authorization_encrypted_response_enc
# authorization_encrypted_response_enc: 'A128CBC-HS256'
## The content encryption key id used for encrypting the authorization responses.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#authorization_encrypted_response_key_id
# authorization_encrypted_response_key_id: ''
## The signing algorithm used for signing the ID Tokens in Access Request responses.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#id_token_signed_response_alg
# id_token_signed_response_alg: 'RS256'
## The signing key id used for signing the ID Tokens in Access Request responses.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#id_token_signed_response_key_id
# id_token_signed_response_key_id: ''
## The content encryption algorithm used for encrypting the ID Tokens in Access Request responses.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#id_token_encrypted_response_alg
# id_token_encrypted_response_alg: 'none'
## The encryption algorithm used for encrypting the ID Tokens in Access Request responses.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#id_token_encrypted_response_enc
# id_token_encrypted_response_enc: 'A128CBC-HS256'
## The content encryption key id used for encrypting the ID Tokens in Access Request responses.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#authorization_encrypted_response_key_id
# id_token_encrypted_response_key_id: ''
## The signing algorithm used for signing the Access Tokens in Access Request responses.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#access_token_signed_response_alg
# access_token_signed_response_alg: 'none'
## The signing key id used for signing the Access Tokens in Access Request responses.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#access_token_signed_response_key_id
# access_token_signed_response_key_id: ''
## The content encryption algorithm used for encrypting the Access Tokens in Access Request responses.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#access_token_encrypted_response_alg
# access_token_encrypted_response_alg: 'none'
## The encryption algorithm used for encrypting the Access Tokens in Access Request responses.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#access_token_encrypted_response_enc
# access_token_encrypted_response_enc: 'A128CBC-HS256'
## The content encryption key id used for encrypting the Access Tokens in Access Request responses.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#access_token_encrypted_response_key_id
# access_token_encrypted_response_key_id: ''
## The signing algorithm used for signing the User Info Request responses.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#userinfo_signed_response_alg
# userinfo_signed_response_alg: 'none'
## The signing key id used for signing the User Info Request responses.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#userinfo_signed_response_key_id
# userinfo_signed_response_key_id: ''
## The content encryption algorithm used for encrypting the User Info Request responses.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#userinfo_encrypted_response_alg
# userinfo_encrypted_response_alg: 'none'
## The encryption algorithm used for encrypting the User Info Request responses.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#userinfo_encrypted_response_enc
# userinfo_encrypted_response_enc: 'A128CBC-HS256'
## The content encryption key id used for encrypting the User Info Request responses.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#userinfo_encrypted_response_key_id
# userinfo_encrypted_response_key_id: ''
## The signing algorithm used for signing the Introspection Request responses.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#introspection_signed_response_alg
# introspection_signed_response_alg: 'none'
## The signing key id used for Introspection responses. An issuer JWK with a matching key id must be available
## when configured.
# introspection_signed_response_key_id: ''
## The content encryption algorithm used for encrypting the Introspection Request responses.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#introspection_encrypted_response_alg
# introspection_encrypted_response_alg: 'none'
## The encryption algorithm used for encrypting the Introspection Request responses.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#introspection_encrypted_response_enc
# introspection_encrypted_response_enc: 'A128CBC-HS256'
## The content encryption key id used for encrypting the Introspection Request responses.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#introspection_encrypted_response_key_id
# introspection_encrypted_response_key_id: ''
## The signature algorithm which must be used for request objects.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#request_object_signing_alg
# request_object_signing_alg: 'RS256'
## The content encryption algorithm which must be used for request objects.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#request_object_encryption_alg
# request_object_encryption_alg: ''
## The encryption algorithm which must be used for request objects.
## Please read the documentation before adjusting this option.
## See: https://www.authelia.com/c/oidc/registered-clients#request_object_encryption_enc
# request_object_encryption_enc: ''
## The permitted client authentication method for the Token Endpoint for this client.
## For confidential client types this value defaults to 'client_secret_basic' and for the public client types it
## defaults to 'none' per the specifications.
# token_endpoint_auth_method: 'client_secret_basic'
## The permitted client authentication signing algorithm for the Token Endpoint for this client when using
## the 'client_secret_jwt' or 'private_key_jwt' token_endpoint_auth_method.
# token_endpoint_auth_signing_alg: 'RS256'
## The permitted client authentication method for the Revocation Endpoint for this client.
## For confidential client types this value defaults to 'client_secret_basic' and for the public client types it
## defaults to 'none' per the specifications.
# revocation_endpoint_auth_method: 'client_secret_basic'
## The permitted client authentication signing algorithm for the Revocation Endpoint for this client when using
## the 'client_secret_jwt' or 'private_key_jwt' revocation_endpoint_auth_method.
# revocation_endpoint_auth_signing_alg: 'RS256'
## The permitted client authentication method for the Introspection Endpoint for this client.
## For confidential client types this value defaults to 'client_secret_basic' and for the public client types it
## defaults to 'none' per the specifications.
# introspection_endpoint_auth_method: 'client_secret_basic'
## The permitted client authentication signing algorithm for the Introspection Endpoint for this client when
## using the 'client_secret_jwt' or 'private_key_jwt' introspection_endpoint_auth_method.
# introspection_endpoint_auth_signing_alg: 'RS256'
## The permitted client authentication method for the Pushed Authorization Request Endpoint for this client.
## For confidential client types this value defaults to 'client_secret_basic' and for the public client types it
## defaults to 'none' per the specifications.
# pushed_authorization_request_endpoint_auth_method: 'client_secret_basic'
## The permitted client authentication signing algorithm for the Pushed Authorization Request Endpoint for this
## client when using the 'client_secret_jwt' or 'private_key_jwt'
## pushed_authorization_request_endpoint_auth_method.
# pushed_authorization_request_endpoint_auth_signing_alg: 'RS256'
## Trusted public keys configuration for request object signing for things such as 'private_key_jwt'.
## URL of the HTTPS endpoint which serves the keys. Please note the 'jwks_uri' and the 'jwks' option below
## are mutually exclusive.
# jwks_uri: 'https://app.example.com/jwks.json'
## Trusted public keys configuration for request object signing for things such as 'private_key_jwt'.
## List of JWKs known and registered with this client. It's recommended to use the 'jwks_uri' option if
## available due to key rotation. Please note the 'jwks' and the 'jwks_uri' option above are mutually exclusive.
# jwks:
# -
## Key ID used to match the JWT's to an individual identifier. This option is required if configured.
# key_id: 'example'
## The key algorithm expected with this key.
# algorithm: 'RS256'
## The key use expected with this key. Currently only 'sig' is supported.
# use: 'sig'
## Required Public Key in PEM DER form.
# key: |
# -----BEGIN RSA PUBLIC KEY-----
# ...
# -----END RSA PUBLIC KEY-----
## The matching certificate chain in PEM DER form that matches the key if available.
# certificate_chain: |
# -----BEGIN CERTIFICATE-----
# ...
# -----END CERTIFICATE-----
# -----BEGIN CERTIFICATE-----
# ...
# -----END CERTIFICATE-----
...
policies: # словарь ключа
arbitrary_name: # значение ключа для последующего использования в блоке usage_example
enable: true
usage_example:
- name: 'example'
policy: 'arbitrary_name' # использование ключа policy
| Unit | Short Unit | Human Readable Long Unit |
|---|---|---|
| Years | y | year, years |
| Months | M | month, months |
| Weeks | w | week, weeks |
| Days | d | day, days |
| Hours | h | hour, hours |
| Minutes | m | minute, minutes |
| Seconds | s | second, seconds |
| Milliseconds | ms | millisecond, milliseconds |
В настройках указываются значения в коротком или длинном формате
| Desired Value | Configuration Examples (Short) | Configuration Examples (Long) |
|---|---|---|
| 1 hour and 30 minutes | 90m or 1h30m or 5400 or 5400s | 1 hour and 30 minutes |
| 1 day | 1d or 24h or 86400 or 86400s | 1 day |
| 10 hours | 10h or 600m or 9h60m or 36000 | 10 hours |
Строковая переменная
| Parameter | Listeners | Connectors | Purpose |
|---|---|---|---|
| umask | Да | Нет | Устанавливает umask перед созданием сокета и восстанавливает его после создания. Значение должно быть восьмеричным числом с 3 или 4 цифрами. |
| path | Да | Нет | Устанавливает переменную path для настройки подпути, специально для unix-сокета, но технически работает и для TCP. Обратите внимание, что это должна быть только буквенно-цифровая часть без префикса в виде прямой косой черты. |
Квадратные скобки обозначают необязательные разделы, а угловые скобки - обязательные разделы.
Имя хоста
Следующий формат представляет собой формат имени хоста. В большинстве случаев он подходит как для слушателя, так и для коннектора. В этом формате, согласно обозначениям, схема и порт являются необязательными. Если они не указаны, то используются по умолчанию.
[<scheme>://]<hostname>[:<port>][/<path>]
fd://<file descriptor number>
fd://<file descriptor number>?umask=0022
fd://<file descriptor number>?path=auth
fd://<file descriptor number>?umask=0022&path=auth
unix://<path>
unix://<path>?umask=0022
unix://<path>?path=auth
unix://<path>?umask=0022&path=auth
В большинстве случаев он подходит как для слушателя, так и для коннектора.
Формат Unix Domain Socket также принимает строку запроса.
0.0.0.0
tcp://0.0.0.0
tcp://0.0.0.0/subpath
tcp://0.0.0.0:9091
tcp://0.0.0.0:9091/subpath
tcp://:9091
tcp://:9091/subpath
0.0.0.0:9091
udp://0.0.0.0:123
udp://:123
unix:///var/lib/authelia.sock
Вся схема не является обязательной, но если в строке присутствует разделитель узла схемы ://, то схема должна присутствовать.
| Scheme | Listeners | Connectors | Default Port | Notes |
|---|---|---|---|---|
| tcp | Yes | Yes | N/A | Standard TCP Socket which allows IPv4 and/or IPv6 addresses |
| tcp4 | Yes | Yes | N/A | Standard TCP Socket which allows only IPv4 addresses |
| tcp6 | Yes | Yes | N/A | Standard TCP Socket which allows only IPv6 addresses |
| udp | Yes | Yes | N/A | Standard UDP Socket which allows IPv4 and/or IPv6 addresses |
| udp4 | Yes | Yes | N/A | Standard UDP Socket which allows only IPv4 addresses |
| udp6 | Yes | Yes | N/A | Standard UDP Socket which allows only IPv6 addresses |
| unix | Yes | Yes | N/A | Standard Unix Domain Socket which allows only absolute paths |
| ldap | No | Yes | 389 | Remote LDAP connection via a TCP socket using StartTLS if available |
| ldaps | No | Yes | 636 | Remote LDAP connection via a TLS socket |
| ldapi | No | Yes | N/A | LDAP connection via Unix Domain Socket |
| smtp | No | Yes | 25 | Remote SMTP connection via a TCP socket using StartTLS if available |
| submission | No | Yes | 587 | Remote SMTP Submission connection via a TCP socket using StartTLS if available |
| submissions | No | Yes | 465 | Remote SMTP Submission connection via a TLS socket |
Имя хоста требуется, если схема является одной из схем tcp или udp и не указан порт. Это может быть любой локально адресуемый IP или имя хоста, которое разрешается в локально адресуемый IP.
При указании IPv6 он должен быть заключен в квадратные скобки. Например, для IPv6-адреса ::1 со схемой tcp и портом 80 правильным адресом будет tcp://[::1]:80.
domain_regex: '^(admin|secure)\.example\.com$'
Мы поддерживаем сетевой синтаксис, который разворачивает строки в сетевой диапазон. Формат строк использует стандартную нотацию CIDR и предполагает наличие одного хоста (адаптированного как /32 для IPv4 и /128 для IPv6), если суффикс CIDR отсутствует.
| Example | CIDR | Range |
|---|---|---|
| 192.168.0.1 | 192.168.0.1/32 | 192.168.0.1 |
| 192.168.1.0/24 | 192.168.1.0/24 | 192.168.1.0 - 192.168.1.255 |
| 192.168.2.1/24 | 192.168.2.0/24 | 192.168.2.0 - 192.168.2.255 |
| 2001:db8:3333:4444:5555:6666:7777:8888 | 2001:db8:3333:4444:5555:6666:7777:8888/128 | 2001:db8:3333:4444:5555:6666:7777:8888 |
| 2001:db8:3333:4400::/56 | 2001:db8:3333:4400::/56 | 2001:0db8:3333:4400:0000:0000:0000:0000 - 2001:0db8:3333:44ff:ffff:ffff:ffff:ffff |
| 2001:db8:3333:4444:5555:6666:7777:8888/56 | 2001:db8:3333:4400::/56 | 2001:0db8:3333:4400:0000:0000:0000:0000 - 2001:0db8:3333:44ff:ffff:ffff:ffff:ffff |
Ниже представлены общие структуры данных, используемые в конфигурации, к которым предъявляются особые требования, используемые в различных областях.
В различных разделах конфигурации используется единый раздел конфигурации под названием tls, в котором настраиваются параметры TLS-сокета и TLS-проверки. В этом разделе описаны общие части этой структуры. По умолчанию Authelia использует системный сертификат доверия для проверки сертификата TLS, но вы можете дополнить его с помощью глобальной опции certificates_directory, а также полностью отключить проверку сертификата TLS с помощью опции skip_verify.
tls:
server_name: 'example.com'
skip_verify: false
minimum_version: 'TLS1.2'
maximum_version: 'TLS1.3'
certificate_chain: |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
private_key: |
-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
Ключ server_name переопределяет имя, проверяемое по сертификату в процессе проверки. Полезно, если вам требуется IP-адрес узла внутренней службы, но вы хотите проверить конкретное имя сервера сертификатов.
Ключ skip_verify полностью исключает проверку сертификата внутреннего сервиса. Это не рекомендуется, вместо этого следует настроить параметр server_name и глобальный параметр certificates directory.
Устанавливает минимальную версию TLS, которую Authelia будет использовать при выполнении сопряжений TLS. Возможные значения: TLS1.3, TLS1.2, TLS1.1, TLS1.0, SSL3.0.
Цепочка/набор сертификатов, которые будут использоваться вместе с private_key для выполнения взаимной TLS-аутентификации с сервером.
Значение должно представлять собой один или несколько сертификатов, закодированных в формате PEM с кодировкой DER base64 (RFC4648). Если предоставлено более одного сертификата, то каждый сертификат должен быть подписан следующим сертификатом, если он предоставлен, в порядке сверху вниз.
Закрытый ключ, который будет использоваться с цепочкой_сертификатов для взаимной аутентификации TLS. Материал открытого ключа, связанного с закрытым ключем, должен совпадать с закрытым ключом первого сертификата в цепочке_сертификатов.
Значение должно представлять собой один закрытый ключ, закодированный в формате PEM DER base64 (RFC4648), и должно быть закодировано в соответствии со спецификациями PKCS#8, PKCS#1 или SECG1.
Различные разделы конфигурации используют единый раздел конфигурации под названием buffers, который настраивает буферы HTTP-сервера. В частности, секции сервера и телеметрии метрик. В этом разделе описаны общие части этой структуры.
buffers:
read: 4096
write: 4096
Настройка максимального размера запроса. Значение по умолчанию 4096 обычно достаточно для большинства случаев использования.
Настройка максимального размера ответа. Значение по умолчанию 4096 обычно достаточно для большинства случаев использования.
В различных разделах конфигурации используется единый раздел конфигурации под названием timeouts, в котором настраиваются таймауты HTTP-сервера. В частности, в секциях телеметрии сервера и метрик.
timeouts:
read: '6s'
write: '6s'
idle: '30s'
Настройка таймаута чтения и записи сервера.
Настройка таймаута простоя сервера.
Authelia имеет несколько способов настройки. Порядок приоритета следующий:
Для настройки Authelia требуется несколько секретов и паролей. Даже если они могут быть заданы в конфигурационном файле или стандартных переменных окружения, рекомендуется использовать этот метод настройки, описанный ниже.
Помимо описанных ниже методов, файлы конфигурации можно передавать через фильтры шаблонов. Эти фильтры можно использовать для вставки или изменения содержимого файла. В частности, функция fileContent может быть использована для получения содержимого файла, а nindent - для добавления новой строки и отступа содержимого этого файла.
authentication_backend:
ldap:
address: 'ldap://{{ env "SERVICES_SERVER" }}'
tls:
private_key: |
{{- fileContent "./test_resources/example_filter_rsa_private_key" | nindent 8 }}
{{ и }} ограничители шаблона
вставляем содержимое файла в ключ private_key с отступом 8 пробелов
Этот метод немного улучшает безопасность других методов, поскольку позволяет легко разделить конфигурацию логически безопасным способом.
Секретное значение может быть загружено Authelia, если ключ конфигурации заканчивается одним из следующих слов: key, secret, password, token или certificate_chain.
Если вы возьмете ожидаемую переменную окружения для конфигурационного параметра с суффиксом _FILE в конце. Значение этих переменных окружения должно быть путем к файлу, который может быть прочитан процессом Authelia, если это не так, Authelia не сможет загрузиться. Authelia автоматически удалит новые строки в конце содержимого файлов.
Например, пароль LDAP может быть определен в конфигурации по пути authentication_backend.ldap.password, поэтому в качестве альтернативы этот пароль может быть задан с помощью переменной окружения под названием
AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD_FILE
| Configuration Key | Environment Variable |
|---|---|
| authentication_backend.ldap.password | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD_FILE |
| authentication_backend.ldap.tls.certificate_chain | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_TLS_CERTIFICATE_CHAIN_FILE |
| authentication_backend.ldap.tls.private_key | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_TLS_PRIVATE_KEY_FILE |
| duo_api.integration_key | AUTHELIA_DUO_API_INTEGRATION_KEY_FILE |
| duo_api.secret_key | AUTHELIA_DUO_API_SECRET_KEY_FILE |
| identity_providers.oidc.hmac_secret | AUTHELIA_IDENTITY_PROVIDERS_OIDC_HMAC_SECRET_FILE |
| identity_validation.reset_password.jwt_secret | AUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET_FILE |
| notifier.smtp.password | AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE |
| notifier.smtp.tls.certificate_chain | AUTHELIA_NOTIFIER_SMTP_TLS_CERTIFICATE_CHAIN_FILE |
| notifier.smtp.tls.private_key | AUTHELIA_NOTIFIER_SMTP_TLS_PRIVATE_KEY_FILE |
| session.redis.high_availability.sentinel_password | AUTHELIA_SESSION_REDIS_HIGH_AVAILABILITY_SENTINEL_PASSWORD_FILE |
| session.redis.password | AUTHELIA_SESSION_REDIS_PASSWORD_FILE |
| session.redis.tls.certificate_chain | AUTHELIA_SESSION_REDIS_TLS_CERTIFICATE_CHAIN_FILE |
| session.redis.tls.private_key | AUTHELIA_SESSION_REDIS_TLS_PRIVATE_KEY_FILE |
| session.secret | AUTHELIA_SESSION_SECRET_FILE |
| storage.encryption_key | AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE |
| storage.mysql.password | AUTHELIA_STORAGE_MYSQL_PASSWORD_FILE |
| storage.mysql.tls.certificate_chain | AUTHELIA_STORAGE_MYSQL_TLS_CERTIFICATE_CHAIN_FILE |
| storage.mysql.tls.private_key | AUTHELIA_STORAGE_MYSQL_TLS_PRIVATE_KEY_FILE |
| storage.postgres.password | AUTHELIA_STORAGE_POSTGRES_PASSWORD_FILE |
| storage.postgres.tls.certificate_chain | AUTHELIA_STORAGE_POSTGRES_TLS_CERTIFICATE_CHAIN_FILE |
| storage.postgres.tls.private_key | AUTHELIA_STORAGE_POSTGRES_TLS_PRIVATE_KEY_FILE |
Во всех версиях 4.30.0+ вы можете задать секреты с помощью переменных окружения без суффикса _FILE, установив значение, которое вы хотите задать в конфигурации, однако мы настоятельно рекомендуем не использовать эту возможность и вместо этого использовать файловые секреты, описанные выше.
Существует несколько опций, которые влияют на загрузку файлов:
| Name | Argument | Environment Variable | Описание и назначение переменных |
|---|---|---|---|
| Files/Directories | --config, -c |
X_AUTHELIA_CONFIG |
Список путей к файлам или каталогам (без рекурсии) для загрузки файлов конфигурации |
| Filters | --config.experimental.filters |
X_AUTHELIA_CONFIG_FILTERS |
Список фильтров, применяемых к каждому файлу из опций «Файлы» или «Каталоги». |
Параметры конфигурации могут быть определены либо через аргумент, либо через переменную окружения, но не через оба параметра одновременно. Если указаны оба параметра, приоритет имеет аргумент, а переменная окружения игнорируется. Обычно рекомендуется использовать переменную окружения, если вы используете контейнер, так как это позволит вам легче выполнять другие команды из контекста контейнера.
docker run authelia/authelia:latest authelia --config configuration.yml
docker run -d authelia/authelia:latest authelia --config configuration.yml --config config-acl.yml --config config-other.yml
docker run -d authelia/authelia:latest authelia --config configuration.yml,config-acl.yml,config-other.yml
docker run -d --volume /path/to/config:/config authelia:authelia:latest authelia --config=/config/configuration.yml --config=/config/configuration.acl.yml
services:
authelia:
container_name: 'authelia'
image: 'authelia/authelia:latest'
command:
- 'authelia'
- '--config=/config/configuration.yml'
- '--config=/config/configuration.acl.yml'
пример файла deployment.yaml
kind: Deployment
apiVersion: apps/v1
metadata:
name: authelia
namespace: authelia
labels:
app.kubernetes.io/instance: authelia
app.kubernetes.io/name: authelia
spec:
replicas: 1
selector:
matchLabels:
app.kubernetes.io/instance: authelia
app.kubernetes.io/name: authelia
template:
metadata:
labels:
app.kubernetes.io/instance: authelia
app.kubernetes.io/name: authelia
spec:
enableServiceLinks: false
containers:
- name: authelia
image: docker.io/authelia/authelia:latest
command:
- authelia
args:
- '--config=/configuration.yml'
- '--config=/configuration.acl.yml'
Существуют файловые фильтры, которые позволяют изменять все конфигурационные файлы после их чтения из файловой системы, но до разбора их содержимого. Если эти фильтры не указаны явно, они НЕ подпадают под действие нашей стандартной политики версионирования.
Наступит момент, когда:
Имя аргумента CLI изменится (мы рекомендуем использовать переменную окружения, которая этого не сделает)
Фильтры настраиваются как список имен фильтров с помощью аргумента CLI –config.experimental.filters и переменной окружения X_AUTHELIA_CONFIG_FILTERS. Мы рекомендуем использовать переменную окружения, так как это гарантирует, что команды, выполняемые из контейнера, используют одни и те же фильтры, и, скорее всего, это постоянное значение, в то время как аргумент может меняться. Если используется и аргумент CLI, и переменная окружения, то переменная окружения полностью игнорируется.
Фильтры могут использоваться самостоятельно, в комбинации или вообще не использоваться. Фильтры обрабатываются в порядке их определения. Вы можете просмотреть вывод YAML-файлов при обработке с помощью фильтров, используя команду authelia config template.
docker run -d authelia/authelia:latest authelia --config /config/configuration.yml --config.experimental.filters template
docker run -d -e X_AUTHELIA_CONFIG_FILTERS=template -e X_AUTHELIA_CONFIG=/config/configuration.yml authelia/authelia:latest authelia
Используются функции шаблонизатора GO
AUTHELIA_. Все переменные окружения, начинающиеся с этого префикса, должны быть предназначены для конфигурации. Любые переменные окружения, имеющие этот префикс и не предназначенные для конфигурации, скорее всего, приведут к ошибке или, что еще хуже, к неправильной конфигурации.Переменные окружения должны иметь префикс AUTHELIA_. Все переменные окружения, начинающиеся с этого префикса, должны быть предназначены для конфигурации. Любые переменные окружения, имеющие этот префикс и не предназначенные для конфигурации, скорее всего, приведут к ошибке или, что еще хуже, к неправильной конфигурации.
Параметры конфигурации сопоставляются по их имени. Уровни отступа / подклавиши заменяются символами подчеркивания.
log:
level: 'info'
server:
buffers:
read: 4096
или
AUTHELIA_LOG_LEVEL=info
AUTHELIA_SERVER_BUFFERS_READ=4096
| Configuration Key | Environment Variable |
|---|---|
| access_control.default_policy | AUTHELIA_ACCESS_CONTROL_DEFAULT_POLICY |
| authentication_backend.file.password.algorithm | AUTHELIA_AUTHENTICATION_BACKEND_FILE_PASSWORD_ALGORITHM |
| authentication_backend.file.password.argon2.iterations | AUTHELIA_AUTHENTICATION_BACKEND_FILE_PASSWORD_ARGON2_ITERATIONS |
| authentication_backend.file.password.argon2.key_length | AUTHELIA_AUTHENTICATION_BACKEND_FILE_PASSWORD_ARGON2_KEY_LENGTH |
| authentication_backend.file.password.argon2.memory | AUTHELIA_AUTHENTICATION_BACKEND_FILE_PASSWORD_ARGON2_MEMORY |
| authentication_backend.file.password.argon2.parallelism | AUTHELIA_AUTHENTICATION_BACKEND_FILE_PASSWORD_ARGON2_PARALLELISM |
| authentication_backend.file.password.argon2.salt_length | AUTHELIA_AUTHENTICATION_BACKEND_FILE_PASSWORD_ARGON2_SALT_LENGTH |
| authentication_backend.file.password.argon2.variant | AUTHELIA_AUTHENTICATION_BACKEND_FILE_PASSWORD_ARGON2_VARIANT |
| authentication_backend.file.password.bcrypt.cost | AUTHELIA_AUTHENTICATION_BACKEND_FILE_PASSWORD_BCRYPT_COST |
| authentication_backend.file.password.bcrypt.variant | AUTHELIA_AUTHENTICATION_BACKEND_FILE_PASSWORD_BCRYPT_VARIANT |
| authentication_backend.file.password.pbkdf2.iterations | AUTHELIA_AUTHENTICATION_BACKEND_FILE_PASSWORD_PBKDF2_ITERATIONS |
| authentication_backend.file.password.pbkdf2.salt_length | AUTHELIA_AUTHENTICATION_BACKEND_FILE_PASSWORD_PBKDF2_SALT_LENGTH |
| authentication_backend.file.password.pbkdf2.variant | AUTHELIA_AUTHENTICATION_BACKEND_FILE_PASSWORD_PBKDF2_VARIANT |
| authentication_backend.file.password.scrypt.block_size | AUTHELIA_AUTHENTICATION_BACKEND_FILE_PASSWORD_SCRYPT_BLOCK_SIZE |
| authentication_backend.file.password.scrypt.iterations | AUTHELIA_AUTHENTICATION_BACKEND_FILE_PASSWORD_SCRYPT_ITERATIONS |
| authentication_backend.file.password.scrypt.key_length | AUTHELIA_AUTHENTICATION_BACKEND_FILE_PASSWORD_SCRYPT_KEY_LENGTH |
| authentication_backend.file.password.scrypt.parallelism | AUTHELIA_AUTHENTICATION_BACKEND_FILE_PASSWORD_SCRYPT_PARALLELISM |
| authentication_backend.file.password.scrypt.salt_length | AUTHELIA_AUTHENTICATION_BACKEND_FILE_PASSWORD_SCRYPT_SALT_LENGTH |
| authentication_backend.file.password.scrypt.variant | AUTHELIA_AUTHENTICATION_BACKEND_FILE_PASSWORD_SCRYPT_VARIANT |
| authentication_backend.file.password.sha2crypt.iterations | AUTHELIA_AUTHENTICATION_BACKEND_FILE_PASSWORD_SHA2CRYPT_ITERATIONS |
| authentication_backend.file.password.sha2crypt.salt_length | AUTHELIA_AUTHENTICATION_BACKEND_FILE_PASSWORD_SHA2CRYPT_SALT_LENGTH |
| authentication_backend.file.password.sha2crypt.variant | AUTHELIA_AUTHENTICATION_BACKEND_FILE_PASSWORD_SHA2CRYPT_VARIANT |
| authentication_backend.file.path | AUTHELIA_AUTHENTICATION_BACKEND_FILE_PATH |
| authentication_backend.file.search.case_insensitive | AUTHELIA_AUTHENTICATION_BACKEND_FILE_SEARCH_CASE_INSENSITIVE |
| authentication_backend.file.search.email | AUTHELIA_AUTHENTICATION_BACKEND_FILE_SEARCH_EMAIL |
| authentication_backend.file.watch | AUTHELIA_AUTHENTICATION_BACKEND_FILE_WATCH |
| authentication_backend.ldap.additional_groups_dn | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ADDITIONAL_GROUPS_DN |
| authentication_backend.ldap.additional_users_dn | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ADDITIONAL_USERS_DN |
| authentication_backend.ldap.address | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ADDRESS |
| authentication_backend.ldap.attributes.birthdate | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ATTRIBUTES_BIRTHDATE |
| authentication_backend.ldap.attributes.country | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ATTRIBUTES_COUNTRY |
| authentication_backend.ldap.attributes.display_name | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ATTRIBUTES_DISPLAY_NAME |
| authentication_backend.ldap.attributes.distinguished_name | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ATTRIBUTES_DISTINGUISHED_NAME |
| authentication_backend.ldap.attributes.family_name | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ATTRIBUTES_FAMILY_NAME |
| authentication_backend.ldap.attributes.gender | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ATTRIBUTES_GENDER |
| authentication_backend.ldap.attributes.given_name | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ATTRIBUTES_GIVEN_NAME |
| authentication_backend.ldap.attributes.group_name | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ATTRIBUTES_GROUP_NAME |
| authentication_backend.ldap.attributes.locale | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ATTRIBUTES_LOCALE |
| authentication_backend.ldap.attributes.locality | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ATTRIBUTES_LOCALITY |
| authentication_backend.ldap.attributes.mail | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ATTRIBUTES_MAIL |
| authentication_backend.ldap.attributes.member_of | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ATTRIBUTES_MEMBER_OF |
| authentication_backend.ldap.attributes.middle_name | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ATTRIBUTES_MIDDLE_NAME |
| authentication_backend.ldap.attributes.nickname | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ATTRIBUTES_NICKNAME |
| authentication_backend.ldap.attributes.phone_extension | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ATTRIBUTES_PHONE_EXTENSION |
| authentication_backend.ldap.attributes.phone_number | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ATTRIBUTES_PHONE_NUMBER |
| authentication_backend.ldap.attributes.picture | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ATTRIBUTES_PICTURE |
| authentication_backend.ldap.attributes.postal_code | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ATTRIBUTES_POSTAL_CODE |
| authentication_backend.ldap.attributes.profile | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ATTRIBUTES_PROFILE |
| authentication_backend.ldap.attributes.region | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ATTRIBUTES_REGION |
| authentication_backend.ldap.attributes.street_address | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ATTRIBUTES_STREET_ADDRESS |
| authentication_backend.ldap.attributes.username | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ATTRIBUTES_USERNAME |
| authentication_backend.ldap.attributes.website | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ATTRIBUTES_WEBSITE |
| authentication_backend.ldap.attributes.zoneinfo | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_ATTRIBUTES_ZONEINFO |
| authentication_backend.ldap.base_dn | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_BASE_DN |
| authentication_backend.ldap.group_search_mode | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_GROUP_SEARCH_MODE |
| authentication_backend.ldap.groups_filter | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_GROUPS_FILTER |
| authentication_backend.ldap.implementation | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_IMPLEMENTATION |
| authentication_backend.ldap.permit_feature_detection_failure | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PERMIT_FEATURE_DETECTION_FAILURE |
| authentication_backend.ldap.permit_referrals | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PERMIT_REFERRALS |
| authentication_backend.ldap.permit_unauthenticated_bind | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PERMIT_UNAUTHENTICATED_BIND |
| authentication_backend.ldap.pooling.count | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_POOLING_COUNT |
| authentication_backend.ldap.pooling.enable | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_POOLING_ENABLE |
| authentication_backend.ldap.pooling.retries | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_POOLING_RETRIES |
| authentication_backend.ldap.pooling.timeout | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_POOLING_TIMEOUT |
| authentication_backend.ldap.start_tls | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_START_TLS |
| authentication_backend.ldap.timeout | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_TIMEOUT |
| authentication_backend.ldap.tls.maximum_version | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_TLS_MAXIMUM_VERSION |
| authentication_backend.ldap.tls.minimum_version | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_TLS_MINIMUM_VERSION |
| authentication_backend.ldap.tls.server_name | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_TLS_SERVER_NAME |
| authentication_backend.ldap.tls.skip_verify | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_TLS_SKIP_VERIFY |
| authentication_backend.ldap.user | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_USER |
| authentication_backend.ldap.users_filter | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_USERS_FILTER |
| authentication_backend.password_change.disable | AUTHELIA_AUTHENTICATION_BACKEND_PASSWORD_CHANGE_DISABLE |
| authentication_backend.password_reset.custom_url | AUTHELIA_AUTHENTICATION_BACKEND_PASSWORD_RESET_CUSTOM_URL |
| authentication_backend.password_reset.disable | AUTHELIA_AUTHENTICATION_BACKEND_PASSWORD_RESET_DISABLE |
| authentication_backend.refresh_interval | AUTHELIA_AUTHENTICATION_BACKEND_REFRESH_INTERVAL |
| Configuration Key | Environment Variable |
|---|---|
| certificates_directory | AUTHELIA_CERTIFICATES_DIRECTORY |
| default_2fa_method | AUTHELIA_DEFAULT_2FA_METHOD |
| duo_api.disable | AUTHELIA_DUO_API_DISABLE |
| duo_api.enable_self_enrollment | AUTHELIA_DUO_API_ENABLE_SELF_ENROLLMENT |
| duo_api.hostname | AUTHELIA_DUO_API_HOSTNAME |
| identity_providers.oidc | AUTHELIA_IDENTITY_PROVIDERS_OIDC |
| identity_providers.oidc.cors.allowed_origins_from_client_redirect_uris | AUTHELIA_IDENTITY_PROVIDERS_OIDC_CORS_ALLOWED_ORIGINS_FROM_CLIENT_REDIRECT_URIS |
| identity_providers.oidc.cors.endpoints | AUTHELIA_IDENTITY_PROVIDERS_OIDC_CORS_ENDPOINTS |
| identity_providers.oidc.discovery_signed_response_alg | AUTHELIA_IDENTITY_PROVIDERS_OIDC_DISCOVERY_SIGNED_RESPONSE_ALG |
| identity_providers.oidc.discovery_signed_response_key_id | AUTHELIA_IDENTITY_PROVIDERS_OIDC_DISCOVERY_SIGNED_RESPONSE_KEY_ID |
| identity_providers.oidc.enable_client_debug_messages | AUTHELIA_IDENTITY_PROVIDERS_OIDC_ENABLE_CLIENT_DEBUG_MESSAGES |
| identity_providers.oidc.enable_jwt_access_token_stateless_introspection | AUTHELIA_IDENTITY_PROVIDERS_OIDC_ENABLE_JWT_ACCESS_TOKEN_STATELESS_INTROSPECTION |
| identity_providers.oidc.enable_pkce_plain_challenge | AUTHELIA_IDENTITY_PROVIDERS_OIDC_ENABLE_PKCE_PLAIN_CHALLENGE |
| identity_providers.oidc.enforce_pkce | AUTHELIA_IDENTITY_PROVIDERS_OIDC_ENFORCE_PKCE |
| identity_providers.oidc.lifespans.access_token | AUTHELIA_IDENTITY_PROVIDERS_OIDC_LIFESPANS_ACCESS_TOKEN |
| identity_providers.oidc.lifespans.authorize_code | AUTHELIA_IDENTITY_PROVIDERS_OIDC_LIFESPANS_AUTHORIZE_CODE |
| identity_providers.oidc.lifespans.device_code | AUTHELIA_IDENTITY_PROVIDERS_OIDC_LIFESPANS_DEVICE_CODE |
| identity_providers.oidc.lifespans.id_token | AUTHELIA_IDENTITY_PROVIDERS_OIDC_LIFESPANS_ID_TOKEN |
| identity_providers.oidc.lifespans.jwt_secured_authorization | AUTHELIA_IDENTITY_PROVIDERS_OIDC_LIFESPANS_JWT_SECURED_AUTHORIZATION |
| identity_providers.oidc.lifespans.refresh_token | AUTHELIA_IDENTITY_PROVIDERS_OIDC_LIFESPANS_REFRESH_TOKEN |
| identity_providers.oidc.minimum_parameter_entropy | AUTHELIA_IDENTITY_PROVIDERS_OIDC_MINIMUM_PARAMETER_ENTROPY |
| identity_providers.oidc.require_pushed_authorization_requests | AUTHELIA_IDENTITY_PROVIDERS_OIDC_REQUIRE_PUSHED_AUTHORIZATION_REQUESTS |
| identity_validation.elevated_session.characters | AUTHELIA_IDENTITY_VALIDATION_ELEVATED_SESSION_CHARACTERS |
| identity_validation.elevated_session.code_lifespan | AUTHELIA_IDENTITY_VALIDATION_ELEVATED_SESSION_CODE_LIFESPAN |
| identity_validation.elevated_session.elevation_lifespan | AUTHELIA_IDENTITY_VALIDATION_ELEVATED_SESSION_ELEVATION_LIFESPAN |
| identity_validation.elevated_session.require_second_factor | AUTHELIA_IDENTITY_VALIDATION_ELEVATED_SESSION_REQUIRE_SECOND_FACTOR |
| identity_validation.elevated_session.skip_second_factor | AUTHELIA_IDENTITY_VALIDATION_ELEVATED_SESSION_SKIP_SECOND_FACTOR |
| identity_validation.reset_password.jwt_algorithm | AUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_ALGORITHM |
| identity_validation.reset_password.jwt_lifespan | AUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_LIFESPAN |
| Configuration Key | Environment Variable |
|---|---|
| log.file_path | AUTHELIA_LOG_FILE_PATH |
| log.format | AUTHELIA_LOG_FORMAT |
| log.keep_stdout | AUTHELIA_LOG_KEEP_STDOUT |
| log.level | AUTHELIA_LOG_LEVEL |
| notifier.disable_startup_check | AUTHELIA_NOTIFIER_DISABLE_STARTUP_CHECK |
| notifier.filesystem.filename | AUTHELIA_NOTIFIER_FILESYSTEM_FILENAME |
| notifier.smtp.address | AUTHELIA_NOTIFIER_SMTP_ADDRESS |
| notifier.smtp.disable_html_emails | AUTHELIA_NOTIFIER_SMTP_DISABLE_HTML_EMAILS |
| notifier.smtp.disable_require_tls | AUTHELIA_NOTIFIER_SMTP_DISABLE_REQUIRE_TLS |
| notifier.smtp.disable_starttls | AUTHELIA_NOTIFIER_SMTP_DISABLE_STARTTLS |
| notifier.smtp.identifier | AUTHELIA_NOTIFIER_SMTP_IDENTIFIER |
| notifier.smtp.sender | AUTHELIA_NOTIFIER_SMTP_SENDER |
| notifier.smtp.startup_check_address | AUTHELIA_NOTIFIER_SMTP_STARTUP_CHECK_ADDRESS |
| notifier.smtp.subject | AUTHELIA_NOTIFIER_SMTP_SUBJECT |
| notifier.smtp.timeout | AUTHELIA_NOTIFIER_SMTP_TIMEOUT |
| notifier.smtp.tls.maximum_version | AUTHELIA_NOTIFIER_SMTP_TLS_MAXIMUM_VERSION |
| notifier.smtp.tls.minimum_version | AUTHELIA_NOTIFIER_SMTP_TLS_MINIMUM_VERSION |
| notifier.smtp.tls.server_name | AUTHELIA_NOTIFIER_SMTP_TLS_SERVER_NAME |
| notifier.smtp.tls.skip_verify | AUTHELIA_NOTIFIER_SMTP_TLS_SKIP_VERIFY |
| notifier.smtp.username | AUTHELIA_NOTIFIER_SMTP_USERNAME |
| notifier.template_path | AUTHELIA_NOTIFIER_TEMPLATE_PATH |
| ntp.address | AUTHELIA_NTP_ADDRESS |
| ntp.disable_failure | AUTHELIA_NTP_DISABLE_FAILURE |
| ntp.disable_startup_check | AUTHELIA_NTP_DISABLE_STARTUP_CHECK |
| ntp.max_desync | AUTHELIA_NTP_MAX_DESYNC |
| ntp.version | AUTHELIA_NTP_VERSION |
| password_policy.standard.enabled | AUTHELIA_PASSWORD_POLICY_STANDARD_ENABLED |
| password_policy.standard.max_length | AUTHELIA_PASSWORD_POLICY_STANDARD_MAX_LENGTH |
| password_policy.standard.min_length | AUTHELIA_PASSWORD_POLICY_STANDARD_MIN_LENGTH |
| password_policy.standard.require_lowercase | AUTHELIA_PASSWORD_POLICY_STANDARD_REQUIRE_LOWERCASE |
| password_policy.standard.require_number | AUTHELIA_PASSWORD_POLICY_STANDARD_REQUIRE_NUMBER |
| password_policy.standard.require_special | AUTHELIA_PASSWORD_POLICY_STANDARD_REQUIRE_SPECIAL |
| password_policy.standard.require_uppercase | AUTHELIA_PASSWORD_POLICY_STANDARD_REQUIRE_UPPERCASE |
| password_policy.zxcvbn.enabled | AUTHELIA_PASSWORD_POLICY_ZXCVBN_ENABLED |
| password_policy.zxcvbn.min_score | AUTHELIA_PASSWORD_POLICY_ZXCVBN_MIN_SCORE |
| Configuration Key | Environment Variable |
|---|---|
| privacy_policy.enabled | AUTHELIA_PRIVACY_POLICY_ENABLED |
| privacy_policy.policy_url | AUTHELIA_PRIVACY_POLICY_POLICY_URL |
| privacy_policy.require_user_acceptance | AUTHELIA_PRIVACY_POLICY_REQUIRE_USER_ACCEPTANCE |
| regulation.ban_time | AUTHELIA_REGULATION_BAN_TIME |
| regulation.find_time | AUTHELIA_REGULATION_FIND_TIME |
| regulation.max_retries | AUTHELIA_REGULATION_MAX_RETRIES |
| regulation.modes | AUTHELIA_REGULATION_MODES |
| server.address | AUTHELIA_SERVER_ADDRESS |
| server.asset_path | AUTHELIA_SERVER_ASSET_PATH |
| server.buffers.read | AUTHELIA_SERVER_BUFFERS_READ |
| server.buffers.write | AUTHELIA_SERVER_BUFFERS_WRITE |
| server.disable_healthcheck | AUTHELIA_SERVER_DISABLE_HEALTHCHECK |
| server.endpoints.enable_expvars | AUTHELIA_SERVER_ENDPOINTS_ENABLE_EXPVARS |
| server.endpoints.enable_pprof | AUTHELIA_SERVER_ENDPOINTS_ENABLE_PPROF |
| server.endpoints.rate_limits.reset_password_finish.enable | AUTHELIA_SERVER_ENDPOINTS_RATE_LIMITS_RESET_PASSWORD_FINISH_ENABLE |
| server.endpoints.rate_limits.reset_password_start.enable | AUTHELIA_SERVER_ENDPOINTS_RATE_LIMITS_RESET_PASSWORD_START_ENABLE |
| server.endpoints.rate_limits.second_factor_duo.enable | AUTHELIA_SERVER_ENDPOINTS_RATE_LIMITS_SECOND_FACTOR_DUO_ENABLE |
| server.endpoints.rate_limits.second_factor_totp.enable | AUTHELIA_SERVER_ENDPOINTS_RATE_LIMITS_SECOND_FACTOR_TOTP_ENABLE |
| server.endpoints.rate_limits.session_elevation_finish.enable | AUTHELIA_SERVER_ENDPOINTS_RATE_LIMITS_SESSION_ELEVATION_FINISH_ENABLE |
| server.endpoints.rate_limits.session_elevation_start.enable | AUTHELIA_SERVER_ENDPOINTS_RATE_LIMITS_SESSION_ELEVATION_START_ENABLE |
| server.headers.csp_template | AUTHELIA_SERVER_HEADERS_CSP_TEMPLATE |
| server.timeouts.idle | AUTHELIA_SERVER_TIMEOUTS_IDLE |
| server.timeouts.read | AUTHELIA_SERVER_TIMEOUTS_READ |
| server.timeouts.write | AUTHELIA_SERVER_TIMEOUTS_WRITE |
| server.tls.certificate | AUTHELIA_SERVER_TLS_CERTIFICATE |
| server.tls.client_certificates | AUTHELIA_SERVER_TLS_CLIENT_CERTIFICATES |
| server.tls.key | AUTHELIA_SERVER_TLS_KEY |
| session | AUTHELIA_SESSION |
| session.expiration | AUTHELIA_SESSION_EXPIRATION |
| session.inactivity | AUTHELIA_SESSION_INACTIVITY |
| session.name | AUTHELIA_SESSION_NAME |
| session.redis.database_index | AUTHELIA_SESSION_REDIS_DATABASE_INDEX |
| session.redis.high_availability.route_by_latency | AUTHELIA_SESSION_REDIS_HIGH_AVAILABILITY_ROUTE_BY_LATENCY |
| session.redis.high_availability.route_randomly | AUTHELIA_SESSION_REDIS_HIGH_AVAILABILITY_ROUTE_RANDOMLY |
| session.redis.high_availability.sentinel_name | AUTHELIA_SESSION_REDIS_HIGH_AVAILABILITY_SENTINEL_NAME |
| session.redis.high_availability.sentinel_username | AUTHELIA_SESSION_REDIS_HIGH_AVAILABILITY_SENTINEL_USERNAME |
| session.redis.host | AUTHELIA_SESSION_REDIS_HOST |
| session.redis.max_retries | AUTHELIA_SESSION_REDIS_MAX_RETRIES |
| session.redis.maximum_active_connections | AUTHELIA_SESSION_REDIS_MAXIMUM_ACTIVE_CONNECTIONS |
| session.redis.minimum_idle_connections | AUTHELIA_SESSION_REDIS_MINIMUM_IDLE_CONNECTIONS |
| session.redis.port | AUTHELIA_SESSION_REDIS_PORT |
| session.redis.timeout | AUTHELIA_SESSION_REDIS_TIMEOUT |
| session.redis.tls.maximum_version | AUTHELIA_SESSION_REDIS_TLS_MAXIMUM_VERSION |
| session.redis.tls.minimum_version | AUTHELIA_SESSION_REDIS_TLS_MINIMUM_VERSION |
| session.redis.tls.server_name | AUTHELIA_SESSION_REDIS_TLS_SERVER_NAME |
| session.redis.tls.skip_verify | AUTHELIA_SESSION_REDIS_TLS_SKIP_VERIFY |
| session.redis.username | AUTHELIA_SESSION_REDIS_USERNAME |
| session.remember_me | AUTHELIA_SESSION_REMEMBER_ME |
| session.same_site | AUTHELIA_SESSION_SAME_SITE |
| Configuration Key | Environment Variable |
|---|---|
| storage.local.path | AUTHELIA_STORAGE_LOCAL_PATH |
| storage.mysql.address | AUTHELIA_STORAGE_MYSQL_ADDRESS |
| storage.mysql.database | AUTHELIA_STORAGE_MYSQL_DATABASE |
| storage.mysql.timeout | AUTHELIA_STORAGE_MYSQL_TIMEOUT |
| storage.mysql.tls.maximum_version | AUTHELIA_STORAGE_MYSQL_TLS_MAXIMUM_VERSION |
| storage.mysql.tls.minimum_version | AUTHELIA_STORAGE_MYSQL_TLS_MINIMUM_VERSION |
| storage.mysql.tls.server_name | AUTHELIA_STORAGE_MYSQL_TLS_SERVER_NAME |
| storage.mysql.tls.skip_verify | AUTHELIA_STORAGE_MYSQL_TLS_SKIP_VERIFY |
| storage.mysql.username | AUTHELIA_STORAGE_MYSQL_USERNAME |
| storage.postgres.address | AUTHELIA_STORAGE_POSTGRES_ADDRESS |
| storage.postgres.database | AUTHELIA_STORAGE_POSTGRES_DATABASE |
| storage.postgres.schema | AUTHELIA_STORAGE_POSTGRES_SCHEMA |
| storage.postgres.timeout | AUTHELIA_STORAGE_POSTGRES_TIMEOUT |
| storage.postgres.tls.maximum_version | AUTHELIA_STORAGE_POSTGRES_TLS_MAXIMUM_VERSION |
| storage.postgres.tls.minimum_version | AUTHELIA_STORAGE_POSTGRES_TLS_MINIMUM_VERSION |
| storage.postgres.tls.server_name | AUTHELIA_STORAGE_POSTGRES_TLS_SERVER_NAME |
| storage.postgres.tls.skip_verify | AUTHELIA_STORAGE_POSTGRES_TLS_SKIP_VERIFY |
| storage.postgres.username | AUTHELIA_STORAGE_POSTGRES_USERNAME |
| telemetry.metrics.address | AUTHELIA_TELEMETRY_METRICS_ADDRESS |
| telemetry.metrics.buffers.read | AUTHELIA_TELEMETRY_METRICS_BUFFERS_READ |
| telemetry.metrics.buffers.write | AUTHELIA_TELEMETRY_METRICS_BUFFERS_WRITE |
| telemetry.metrics.enabled | AUTHELIA_TELEMETRY_METRICS_ENABLED |
| telemetry.metrics.timeouts.idle | AUTHELIA_TELEMETRY_METRICS_TIMEOUTS_IDLE |
| telemetry.metrics.timeouts.read | AUTHELIA_TELEMETRY_METRICS_TIMEOUTS_READ |
| telemetry.metrics.timeouts.write | AUTHELIA_TELEMETRY_METRICS_TIMEOUTS_WRITE |
| theme | AUTHELIA_THEME |
| totp.algorithm | AUTHELIA_TOTP_ALGORITHM |
| totp.allowed_algorithms | AUTHELIA_TOTP_ALLOWED_ALGORITHMS |
| totp.allowed_digits | AUTHELIA_TOTP_ALLOWED_DIGITS |
| totp.allowed_periods | AUTHELIA_TOTP_ALLOWED_PERIODS |
| totp.digits | AUTHELIA_TOTP_DIGITS |
| totp.disable | AUTHELIA_TOTP_DISABLE |
| totp.disable_reuse_security_policy | AUTHELIA_TOTP_DISABLE_REUSE_SECURITY_POLICY |
| totp.issuer | AUTHELIA_TOTP_ISSUER |
| totp.period | AUTHELIA_TOTP_PERIOD |
| totp.secret_size | AUTHELIA_TOTP_SECRET_SIZE |
| totp.skew | AUTHELIA_TOTP_SKEW |
| webauthn.attestation_conveyance_preference | AUTHELIA_WEBAUTHN_ATTESTATION_CONVEYANCE_PREFERENCE |
| webauthn.disable | AUTHELIA_WEBAUTHN_DISABLE |
| webauthn.display_name | AUTHELIA_WEBAUTHN_DISPLAY_NAME |
| webauthn.enable_passkey_login | AUTHELIA_WEBAUTHN_ENABLE_PASSKEY_LOGIN |
| webauthn.experimental_enable_passkey_upgrade | AUTHELIA_WEBAUTHN_EXPERIMENTAL_ENABLE_PASSKEY_UPGRADE |
| webauthn.experimental_enable_passkey_uv_two_factors | AUTHELIA_WEBAUTHN_EXPERIMENTAL_ENABLE_PASSKEY_UV_TWO_FACTORS |
| webauthn.filtering.prohibit_backup_eligibility | AUTHELIA_WEBAUTHN_FILTERING_PROHIBIT_BACKUP_ELIGIBILITY |
| webauthn.metadata.enabled | AUTHELIA_WEBAUTHN_METADATA_ENABLED |
| webauthn.metadata.validate_entry | AUTHELIA_WEBAUTHN_METADATA_VALIDATE_ENTRY |
| webauthn.metadata.validate_entry_permit_zero_aaguid | AUTHELIA_WEBAUTHN_METADATA_VALIDATE_ENTRY_PERMIT_ZERO_AAGUID |
| webauthn.metadata.validate_status | AUTHELIA_WEBAUTHN_METADATA_VALIDATE_STATUS |
| webauthn.metadata.validate_status_permitted | AUTHELIA_WEBAUTHN_METADATA_VALIDATE_STATUS_PERMITTED |
| webauthn.metadata.validate_status_prohibited | AUTHELIA_WEBAUTHN_METADATA_VALIDATE_STATUS_PROHIBITED |
| webauthn.metadata.validate_trust_anchor | AUTHELIA_WEBAUTHN_METADATA_VALIDATE_TRUST_ANCHOR |
| webauthn.selection_criteria.attachment | AUTHELIA_WEBAUTHN_SELECTION_CRITERIA_ATTACHMENT |
| webauthn.selection_criteria.discoverability | AUTHELIA_WEBAUTHN_SELECTION_CRITERIA_DISCOVERABILITY |
| webauthn.selection_criteria.user_verification | AUTHELIA_WEBAUTHN_SELECTION_CRITERIA_USER_VERIFICATION |
| webauthn.timeout | AUTHELIA_WEBAUTHN_TIMEOUT |
Существует два способа интеграции Authelia с бэкэндом аутентификации:
authentication_backend:
refresh_interval: '5m'
password_reset:
disable: false
custom_url: ''
password_change:
disable: false
Этот параметр управляет интервалом, через который обновляются данные из бэкэнда. В порядке важности обновляются такие данные, как группы, адрес электронной почты и отображаемое имя. Это особенно полезно для файлового провайдера, когда часы включены или вообще включены в LDAP-провайдере.
В дополнение к значениям длительности этот параметр принимает значения always и disable; при этом always будет всегда обновлять это значение, а disable - никогда не обновлять профиль.
Этот параметр определяет, могут ли пользователи сбрасывать свой пароль через веб-фронтенд или нет.
Пользовательский URL-адрес сброса пароля. Он заменяет встроенную функцию сброса пароля и отключает конечные точки, если он настроен на что-либо, кроме “ничего” или пустой строки.
Этот параметр определяет, могут ли пользователи изменять свой пароль через веб-фронтенд или нет.
Поставщик аутентификации файлов.
Поставщик аутентификации LDAP.
authentication_backend:
ldap:
address: 'ldap://127.0.0.1'
implementation: 'custom'
timeout: '5s'
start_tls: false
tls:
server_name: 'ldap.rabrain.ru'
skip_verify: false
minimum_version: 'TLS1.2'
maximum_version: 'TLS1.3'
certificate_chain: |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
private_key: |
-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
pooling:
enable: false
count: 5
retries: 2
timeout: '10 seconds'
base_dn: 'DC=rabrain,DC=ru'
additional_users_dn: 'OU=users'
users_filter: '(&({username_attribute}={input})(objectClass=person))'
additional_groups_dn: 'OU=groups'
groups_filter: '(&(member={dn})(objectClass=groupOfNames))'
group_search_mode: 'filter'
permit_referrals: false
permit_unauthenticated_bind: false
permit_feature_detection_failure: false
user: 'CN=admin,DC=rabrain,DC=ru'
password: 'password'
attributes:
distinguished_name: 'distinguishedName'
username: 'uid'
display_name: 'displayName'
family_name: 'sn'
given_name: 'givenName'
middle_name: 'middleName'
nickname: ''
gender: ''
birthdate: ''
website: 'wWWHomePage'
profile: ''
picture: ''
zoneinfo: ''
locale: ''
phone_number: 'telephoneNumber'
phone_extension: ''
street_address: 'streetAddress'
locality: 'l'
region: 'st'
postal_code: 'postalCode'
country: 'c'
mail: 'mail'
member_of: 'memberOf'
group_name: 'cn'
extra:
extra_example:
name: ''
multi_valued: false
value_type: 'string'
URL-адрес LDAP, состоящий из схемы, имени хоста и порта. Формат - [<схема>://]<имя хоста>[:<порт>]. По умолчанию используется схема ldapi, если путь абсолютный, иначе - ldaps, а допустимыми схемами являются ldap, ldaps или ldapi (сокет домена unix).
Если схема ldapi, то за ней должен следовать абсолютный путь к существующему сокету домена unix, для доступа к которому у пользователя/группы, от имени которой запущен процесс Authelia, есть соответствующие разрешения. Например, если сокет расположен по адресу /var/run/slapd.sock, то адрес должен быть ldapi:///var/run/slapd.sock.
authentication_backend:
ldap:
address: 'ldaps://dc1.rabrain.ru'
или
authentication_backend:
ldap:
address: 'ldap://[fd00:1111:2222:3333::1]'
Настраивает реализацию LDAP, используемую Authelia.
Тайм-аут для набора номера при подключении к LDAP.
Включает использование процесса LDAP StartTLS, который не часто используется. Настраивать его следует только в том случае, если вы знаете, что он вам нужен. Первоначальное соединение будет осуществляться через обычный текст, и Authelia попытается обновить его с помощью LDAP-сервера. URL-адреса LDAPS немного более безопасны.
Если эта опция определена, она управляет параметрами проверки TLS-соединений для LDAP-сервера.
По умолчанию Authelia использует системный сертификат доверия для проверки TLS-сертификатов TLS-соединений, а глобальная опция certificates_directory может быть использована для дополнения этого параметра.
Включает функцию объединения соединений.
Количество открытых соединений, которые должны быть доступны в пуле в любой момент времени.
Количество попыток получить свободное соединение, предпринятых в течение периода таймаута. Это эффективно разбивает таймаут на части.
Время, в течение которого мы ждем, пока соединение освободится в пуле, прежде чем сдаться и выдать ошибку.
Устанавливает базовый контейнер отличительных имен для всех LDAP-запросов. Если ваш LDAP-домен rabrain.ru, то обычно это DC=rabrain,DC=ru, однако вы можете настроить его более точно, например, чтобы включить только объекты внутри OU authelia: OU=authelia,DC=rabrain,DC=ru. К этому приставке добавляется additional_users_dn для поиска пользователей и additional_groups_dn для поиска групп.
Фильтр LDAP, позволяющий сузить круг пользователей. Это важно установить правильно, чтобы исключить пользователей с ограниченными возможностями.
Аналогично additional_users_dn, но применяется к групповому поиску.
Аналогичен фильтру users_filter, но применяется к поиску по группам. Чтобы включить в поиск группы, в которых участник не является непосредственным членом, но является членом другой группы, которая является членом этих групп (т. е. рекурсивные группы)
(&(member:1.2.840.113556.1.4.1941:={dn})(objectClass=group)(objectCategory=group))
Разрешает следовать за рефералами. Это полезно, если в вашей архитектуре есть серверы, доступные только для чтения, и поэтому требуется, чтобы при выполнении операций записи ссылки выполнялись.
Отличительное имя пользователя в паре с паролем для привязки к операциям поиска и смены пароля.
Пароль, связанный с пользователем, используемый для привязки к LDAP-серверу для операций поиска и смены пароля.
Следующие параметры настраивают сопоставление атрибутов сервера каталогов.
Атрибут сервера каталогов, содержащий отличительное имя, в основном используется для выполнения фильтрованного поиска. Существует четкое различие между реальным отличительным именем и атрибутом отличительного имени, все каталоги имеют отличительные имена для объектов, но не все имеют атрибут, представляющий это имя, по которому можно осуществлять поиск.
Единственная известная поддержка на данный момент - это Active Directory.
Атрибут сервера каталогов, который сопоставляется с именем пользователя в Authelia. Он должен содержать заполнитель {username_attribute}.
Атрибут сервера каталогов для извлечения, который отображается в веб-интерфейсе для пользователя при входе в систему.
Атрибут сервера каталогов, содержащий фамилию, имя, ник, пользователя.
Дополнительные атрибуты для загрузки с сервера каталогов. Эти дополнительные атрибуты могут использоваться в других областях Authelia, таких как OpenID Connect 1.0.
Ключ представляет собой имя атрибута бэкэнда и по умолчанию является именем атрибута в Authelia.
В приведенном ниже примере мы загружаем атрибут сервера каталогов exampleServerAttribute в атрибут Authelia example_authelia_attribute, рассматривая его как однозначный атрибут, имеющий базовый тип integer.
authentication_backend:
ldap:
attributes:
extra:
exampleServerAttribute:
name: 'example_authelia_attribute'
multi_valued: false
value_type: 'integer'
Рекомендуется использовать интервал обновления по умолчанию или настроить его на достаточно низкое значение, чтобы обновлять группы пользователей и их статус (удалены, отключены и т. д.) для адекватной защиты вашей среды.
authentication_backend:
file:
path: '/config/users.yml'
watch: false
search:
email: false
case_insensitive: false
extra_attributes:
extra_example:
multi_valued: false
value_type: 'string'
password:
algorithm: 'argon2'
argon2:
variant: 'argon2id'
iterations: 3
memory: 65536
parallelism: 4
key_length: 32
salt_length: 16
scrypt:
variant: 'scrypt'
iterations: 16
block_size: 8
parallelism: 1
key_length: 32
salt_length: 16
pbkdf2:
variant: 'sha512'
iterations: 310000
salt_length: 16
sha2crypt:
variant: 'sha512'
iterations: 50000
salt_length: 16
bcrypt:
variant: 'standard'
cost: 12
Путь к файлу со списком сведений о пользователе. Поддерживаются типы файлов: YAML-файл
Позволяет перезагрузить базу данных, наблюдая за ее изменениями.
Функциональные возможности поиска по имени пользователя.
Позволяет пользователям входить в систему, используя свой адрес электронной почты. Если эта функция включена, два пользователя не должны иметь одинаковые адреса электронной почты, а их имена пользователей не должны быть адресами электронной почты.
Дополнительные атрибуты для загрузки с сервера каталогов.
Ключ представляет собой имя атрибута бэкэнда. База данных будет проверена с учетом конфигурации multi_valued и value_type.
В приведенном ниже примере мы загружаем атрибут сервера каталогов example_file_attribute в атрибут Authelia example_file_attribute, рассматривая его как однозначный атрибут, имеющий базовый тип integer.
authentication_backend:
file:
extra_attributes:
example_file_attribute:
multi_valued: false
value_type: 'integer'
Управляет алгоритмом хэширования, используемым для хэширования новых паролей. Значение должно быть одним из:
argon2 для алгоритма Argon2
scrypt для алгоритма Scrypt
pbkdf2 для алгоритма PBKDF2
sha2crypt для алгоритма SHA2Crypt
bcrypt для алгоритма Bcrypt.
Реализация алгоритма Argon2. Это один из единственных алгоритмов, который был разработан исключительно для хеширования паролей, и впоследствии является одним из лучших алгоритмов для обеспечения безопасности на сегодняшний день.
Реализация алгоритма Scrypt.
Реализация алгоритма PBKDF2.
Реализация алгоритма SHA2 Crypt.
Реализация алгоритма Bcrypt.
Authelia поддерживает настройку одноразовых паролей, основанных на времени.
Authelia поддерживает настройку ключей безопасности WebAuthn.
Authelia поддерживает настройку Duo для предоставления мобильного push-сервиса.
duo_api:
disable: false
hostname: 'api-123456789.rabrain.ru'
integration_key: 'ABCDEF'
secret_key: '1234567890abcdefghifjkl'
enable_self_enrollment: false
Отключает Duo. Если имена хостов, integration_key и secret_key являются пустыми строками или не определены, это значение автоматически становится истинным.
Имя хоста API Duo. Он указывается на панели управления Duo.
Не секретный ключ интеграции Duo. Аналогичен идентификатору клиента. Он указывается на панели управления Duo.
Секретный ключ Duo, используемый для проверки подлинности вашего приложения. Он предоставляется на панели управления Duo.
Позволяет самостоятельно регистрировать устройства Duo на портале Authelia.
totp:
disable: false
issuer: 'authelia.com'
algorithm: 'sha1'
digits: 6
period: 30
skew: 1
secret_size: 32
allowed_algorithms:
- 'SHA1'
allowed_digits:
- 6
allowed_periods:
- 30
disable_reuse_security_policy: false
Это отключает одноразовый пароль (TOTP), если установлено значение true.
Приложения, генерирующие одноразовые пароли, основанные на времени, обычно отображают эмитента, чтобы отличить приложения, зарегистрированные пользователем.
Authelia позволяет настраивать эмитента, чтобы отличить запись, созданную Authelia, от других.
Алгоритм, используемый для ключа TOTP.
Возможные значения:
Изменение этого значения влияет только на вновь зарегистрированные ключи TOTP.
Количество цифр, которые пользователь должен ввести для аутентификации. Обычно не рекомендуется изменять этот параметр, поскольку многие TOTP-приложения не поддерживают ничего, кроме 6. Хуже того, некоторые TOTP-приложения позволяют добавить ключ, но не используют правильное количество цифр, указанное в ключе.
Правильные значения - 6 или 8.
Период времени в секундах между поворотами клавиш или временной элемент TOTP.
Рекомендуется держать это значение равным 30, минимальное значение - 15.
Количество временных одноразовых паролей по обе стороны от текущего действующего временного одноразового пароля, которые также должны считаться действительными. Значение по умолчанию 1 приводит к 3 действительным одноразовым паролям на основе времени. При значении 2 их будет 5.
Длина в байтах генерируемых общих секретов. Минимальное значение - 20 (или 160 бит), а по умолчанию - 32 (или 256 бит).
Аналогичен алгоритму с теми же ограничениями, за исключением того, что эта опция позволяет пользователям выбирать из этого списка. Этот список всегда будет содержать значение, заданное в опции алгоритма.
Отключает политику, которая предотвращает повторное использование кодов одноразовых паролей, основанных на времени. Это дополнительная мера безопасности, которая предотвращает повторное воспроизведение кодов. Это касается только тех кодов, которые используются в течение срока действия более одного раза.
Когда пользователи впервые регистрируют свое устройство TOTP, текущий эмитент, алгоритм и период используются для генерации ссылки TOTP и QR-кода. Эти значения сохраняются в базе данных для последующих проверок.
Параметры конфигурации периода и перекоса влияют друг на друга. По умолчанию период равен 30, а перекос - 1.
webauthn:
disable: false
enable_passkey_login: false
display_name: 'Authelia'
attestation_conveyance_preference: 'indirect'
timeout: '60 seconds'
filtering:
permitted_aaguids: []
prohibited_aaguids: []
prohibit_backup_eligibility: false
selection_criteria:
attachment: ''
discoverability: 'preferred'
user_verification: 'preferred'
metadata:
enabled: false
validate_trust_anchor: true
validate_entry: true
validate_entry_permit_zero_aaguid: false
validate_status: true
validate_status_permitted: []
validate_status_prohibited:
- 'REVOKED'
- 'USER_KEY_PHYSICAL_COMPROMISE'
- 'USER_KEY_REMOTE_COMPROMISE'
- 'USER_VERIFICATION_BYPASS'
- 'ATTESTATION_KEY_COMPROMISE'
Это отключает WebAuthn, если установлено значение true.
Позволяет входить в систему с помощью Passkey вместо имени пользователя и пароля. Такой вход считается только однофакторным. По умолчанию пользователю будет предложено ввести пароль, если запрос требует многофакторной аутентификации.
Устанавливает отображаемое имя, которое отправляется клиенту для отображения. Отдельные браузеры и, возможно, отдельные операционные системы сами решают, отображать ли эту информацию и каким образом.
Дополнительную информацию см. в документации W3C WebAuthn.
Это настраивает запрошенное время ожидания для взаимодействия с WebAuthn.
В этом разделе настраиваются различные параметры фильтрации при регистрации.
Параметры критериев выбора задают предпочтения для выбора подходящего аутентификатора.
Настраивает службу метаданных, которая используется для проверки подлинности аутентификаторов.
Security в Authelia относится к механизмам защиты, которые обеспечивают безопасную аутентификацию и авторизацию пользователей. Authelia — это менеджер аутентификации и авторизации с открытым исходным кодом, который можно интегрировать с обратными прокси (Nginx, Traefik) для защиты веб-приложений
access_control:
default_policy: 'deny'
rules:
- domain: 'private.rabrain.ru'
domain_regex: '^(\d+\-)?priv-img\.rabrain\.ru$'
policy: 'one_factor'
networks:
- 'internal'
- '1.1.1.1'
subject:
- ['user:adam']
- ['user:fred']
- ['group:admins']
methods:
- 'GET'
- 'HEAD'
resources:
- '^/api.*'
query:
- - operator: 'present'
key: 'secure'
- operator: 'absent'
key: 'insecure'
- - operator: 'pattern'
key: 'token'
value: '^(abc123|zyx789)$'
- operator: 'not pattern'
key: 'random'
value: '^(1|2)$'
Политика по умолчанию определяет политику, применяемую, если к информации, известной о запросе, не применяется ни один раздел правил. По соображениям безопасности рекомендуется настраивать это значение на отказ. Сайты, которые вы не хотите защищать с помощью Authelia, не должны быть настроены в вашем обратном прокси на выполнение аутентификации с помощью Authelia по соображениям производительности.
Правила имеют множество параметров настройки. Правило совпадает, если все критерии правила соответствуют запросу, за исключением политики, которая применяется к запросу.
Правило выполняется, если все критерии правила совпадают. Правила оцениваются в последовательном порядке в соответствии с концепцией 1 сопоставления правил.
Требуется: Этот критерий и/или критерий domain_regex являются обязательными.
Этот критерий соответствует имени домена и имеет два способа настройки: в виде одной строки или в виде списка строк. Если это список строк, правило будет соответствовать любому из доменов в списке, совпадающему с доменом запроса. При использовании в сочетании с domain_regex правило будет соответствовать критериям domain или domain_regex.
access_control:
rules:
- domain: '*.rabrain.ru'
policy: 'bypass'
- domain:
- '*.rabrain.ru'
policy: 'bypass'
access_control:
rules:
- domain: ['apple.rabrain.ru', 'banana.rabrain.ru']
policy: 'bypass'
- domain:
- 'apple.rabrain.ru'
- 'banana.rabrain.ru'
policy: 'bypass'
access_control:
rules:
- domain: 'apple.rabrain.ru'
domain_regex: '^(pub|img)-data\.rabrain\.ru$'
policy: bypass
Требуется: Этот критерий и/или критерий домена являются обязательными.
Этот критерий соответствует имени домена и имеет два способа настройки: в виде одной строки или в виде списка строк. Если это список строк, правило будет соответствовать, когда любой из доменов в списке совпадает с доменом запроса. При использовании в сочетании с domain правило будет соответствовать либо критерию domain, либо критерию domain_regex.
access_control:
rules:
- domain_regex:
- '^user-(?P<User>\w+)\.rabrain\.ru$'
- '^group-(?P<Group>\w+)\.rabrain\.ru$'
policy: 'one_factor'
access_control:
rules:
- domain: 'protected.rabrain.ru'
- domain_regex: '^(img|data)-private\.rabrain\.ru'
policy: 'one_factor'
Конкретная политика, которую следует применить к выбранному правилу. Это не критерии для совпадения, это действие, которое нужно предпринять при совпадении.
Этот критерий соответствует идентифицирующим характеристикам субъекта. В настоящее время это либо пользователь, либо группы, к которым он принадлежит. Это позволяет эффективно контролировать, к чему именно имеет доступ каждый пользователь, или требовать двухфакторной аутентификации для определенных пользователей. Субъекты должны быть снабжены следующими префиксами, чтобы соответствовать определенной части субъекта.
| Тип subject | Префикс | Описание |
|---|---|---|
| User | user: |
Сопоставляет имя пользователя. |
| Group | group: |
Определяет, есть ли у пользователя группа с таким именем. |
| OAuth 2.0 Client | oauth2:client: |
Определяет, был ли запрос авторизован с помощью токена, выданного клиентом с указанным идентификатором, использующим тип гранта client_credentials. |
access_control:
rules:
- domain: 'rabrain.ru'
policy: 'two_factor'
subject:
- 'user:john'
- ['group:admin', 'group:app-name']
- 'group:super-admin'
- domain: 'rabrain.ru'
policy: 'two_factor'
subject:
- ['user:john']
- ['group:admin', 'group:app-name']
- ['group:super-admin']
access_control:
rules:
- domain: 'rabrain.ru'
policy: 'one_factor'
subject: 'group:super-admin'
- domain: 'rabrain.ru'
policy: 'one_factor'
subject:
- 'group:super-admin'
- domain: 'rabrain.ru'
policy: 'one_factor'
subject:
- ['group:super-admin']
Этот критерий соответствует методу запроса HTTP. В первую очередь это полезно при попытке обойти аутентификацию для определенных типов запросов, когда эти запросы могут помешать основной или публичной работе сайта. Например, если вам нужно сделать предварительный CORS-запрос, вы можете применить политику обхода к OPTIONS-запросам.
Важно отметить, что Authelia не может сохранять данные запроса при перенаправлении пользователя.
| RFC | Methods | Additional Documentation |
|---|---|---|
| RFC7231 | GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE | MDN |
| RFC5789 | PATCH | MDN |
| RFC4918 | PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK |
access_control:
rules:
- domain: 'rabrain.ru'
policy: 'bypass'
methods:
- 'OPTIONS'
Обход OPTIONS-запросов к домену rabrain.ru.
Эти критерии состоят из списка значений, которые могут быть IP-адресом, диапазоном сетевых адресов в нотации CIDR или именованным определением сети. Он сопоставляет первый адрес в заголовке X-Forwarded-For, или, если их нет, он возвращается к IP-адресу TCP-источника пакета. По этой причине важно правильно настроить прокси-сервер для точного соответствия запросов этим критериям. Примечание: вы можете комбинировать CIDR-сети с правилами псевдонимов по своему усмотрению.
Основное применение этого критерия - настройка требований безопасности ресурса в зависимости от местоположения пользователя. Теоретически вы можете рассматривать конкретную сеть как один из факторов, участвующих в аутентификации, можете запрещать конкретные сети и т. д.
Например, если у вас есть приложение, открытое как в локальных, так и во внешних сетях, вы можете различать эти запросы и применять к каждому из них разные политики. Либо отказывая в доступе, когда пользователь находится во внешних сетях, и разрешая доступ определенным внешним клиентам, а также внутренним клиентам, либо требуя меньших привилегий, когда пользователь находится в локальных сетях.
definitions:
network:
internal:
- '10.0.0.0/8'
- '172.16.0.0/12'
- '192.168.0.0/18'
access_control:
default_policy: 'two_factor'
rules:
- domain: 'secure.rabrain.ru'
policy: 'one_factor'
networks:
- '10.0.0.0/8'
- '172.16.0.0/12'
- '192.168.0.0/18'
- '112.134.145.167/32'
- domain: 'secure.rabrain.ru'
policy: 'one_factor'
networks:
- 'internal'
- '112.134.145.167/32'
- domain: 'secure.rabrain.ru'
policy: 'two_factor'
Этот критерий соответствует пути и запросу запроса с помощью регулярных выражений. Правило выражается в виде списка строк. Если любое из регулярных выражений в списке соответствует запросу, оно считается совпавшим. Полезный инструмент для отладки этих регулярных выражений называется Regex 101 (убедитесь, что вы выбрали опцию Golang).
access_control:
rules:
- domain: 'app.rabrain.ru'
policy: 'bypass'
resources:
- '^/api([/?].*)?$'
Критерии запроса - это расширенный критерий, который позволяет настраивать правила, сопоставляющие определенные ключи аргументов запроса с различными правилами. Для базовых нужд рекомендуется использовать правила ресурсов.
Формат этого правила уникален тем, что представляет собой список списков. Логика, лежащая в основе этого формата, позволяет использовать логику ИЛИ и И. Первый уровень списка определяет логику ИЛИ, а второй уровень - логику И. Кроме того, каждый уровень этих списков не обязательно должен быть явно определен.
Ключ аргумента запроса для проверки.
Значение, по которому будет выполняться проверка. Оно необходимо, если оператор отсутствует или присутствует. Рекомендуется, чтобы это значение всегда заключалось в кавычки, как показано в примерах.
Оператор правила для этого правила.
access_control:
rules:
- domain: 'app.rabrain.ru'
policy: 'bypass'
query:
- - operator: 'present'
key: 'secure'
- operator: 'absent'
key: 'insecure'
- - operator: 'pattern'
key: 'token'
value: '^(abc123|zyx789)$'
- operator: 'not pattern'
key: 'random'
value: '^(1|2)$'
Политика первого подходящего правила в списке определяет политику, применяемую к запросу, если ни одно правило не соответствует запросу, применяется политика по умолчанию (default_policy).
Это политика, применяемая по умолчанию, и именно ее мы рекомендуем использовать по умолчанию для всех установок. Ее действие заключается в том, чтобы буквально запретить пользователю доступ к ресурсу. Кроме того, вы можете использовать эту политику для условного запрета доступа в нужных ситуациях. В качестве примера можно привести запрет доступа к API, в который не встроен механизм аутентификации.
Эта политика пропускает все проверки подлинности и позволяет любому пользователю использовать ресурс. Эта политика недоступна с правилом, включающим ограничение по субъекту, поскольку минимальный уровень аутентификации, необходимый для получения информации о субъекте, - one_factor.
Эта политика требует, чтобы пользователь как минимум успешно выполнил 1FA (имя пользователя и пароль). Это означает, что если пользователь выполнил 2FA, ему будет разрешен доступ к ресурсу.
Эта политика требует от пользователя успешного выполнения 2FA. В настоящее время это самый высокий уровень политики аутентификации.
Есть две важные концепции, которые необходимо понимать, когда речь идет о сопоставлении правил.
С помощью команды authelia access-control check-policy можно легко определить, соответствует ли раздел правил управления доступом заданному запросу и почему он не соответствует.
Правила сопоставляются в последовательном порядке. Первая запись в списке, в которой совпадают все критерии, является правилом, которое применяется. Некоторые критерии правил дополнительно допускают список критериев, когда один из этих критериев в списке соответствует запросу, этот критерий считается подходящим для данного конкретного правила.
Например, следующее правило будет считать запросы на rabrain.ru или любой поддомен rabrain.ru соответствующими, если они имеют путь /api или если они начинаются с /api/. Это означает, что второе правило для app.rabrain.ru не будет рассматриваться, если запрос будет направлен на https://app.rabrain.ru/api, потому что первое правило совпадает с этим запросом.
- domain:
- 'rabrain.ru'
- '*.rabrain.ru'
policy: 'bypass'
resources:
- '^/api$'
- '^/api/'
- domain:
- 'app.rabrain.ru'
policy: 'two_factor'
Правила, содержащие элементы, зависящие от субъекта, требуют аутентификации для определения их соответствия. Поэтому такие правила не должны использоваться с политикой обхода. Критериями, которые содержат элементы, зависящие от субъекта, являются:
Кроме того, если в правиле есть критерий темы, но все остальные критерии совпадают, пользователь будет немедленно перенаправлен на аутентификацию, если ни одно из предыдущих правил не соответствует запросу в соответствии с концепцией 1 соответствия правил. Это означает, что если у вас есть два одинаковых правила, одно из которых имеет зависимый от темы критерий, а другое является правилом обхода, то правило обхода должно быть первым.
Некоторые критерии допускают совпадение с именованными группами regex. Эти группы мы принимаем: User и Group
Именованные группы regex представлены синтаксисом (?P
definitions:
network:
internal:
- '10.10.0.0/16'
- '192.168.2.0/24'
vpn: '10.9.0.0/16'
access_control:
default_policy: 'deny'
rules:
- domain: 'public.rabrain.ru'
policy: 'bypass'
- domain: '*.rabrain.ru'
policy: 'bypass'
methods:
- 'OPTIONS'
- domain: 'secure.rabrain.ru'
policy: 'one_factor'
networks:
- 'internal'
- 'vpn'
- '192.168.1.0/24'
- '10.0.0.1'
- domain:
- 'secure.rabrain.ru'
- 'private.rabrain.ru'
policy: 'two_factor'
- domain: 'singlefactor.rabrain.ru'
policy: 'one_factor'
- domain: 'mx2.mail.rabrain.ru'
subject: 'group:admins'
policy: 'deny'
- domain: '*.rabrain.ru'
subject:
- 'group:admins'
- 'group:moderators'
policy: 'two_factor'
- domain: 'dev.rabrain.ru'
resources:
- '^/groups/dev/.*$'
subject: 'group:dev'
policy: 'two_factor'
- domain: 'dev.rabrain.ru'
resources:
- '^/users/john/.*$'
subject:
- ['group:dev', 'user:john']
- 'group:admins'
policy: 'two_factor'
regulation:
modes:
- 'user'
- 'ip'
max_retries: 3
find_time: '2m'
ban_time: '5m'
Режимы для регулирования. В таблице ниже описан каждый вариант. Рекомендуемый режим - ip. Следует отметить, что независимо от настроенных в данный момент режимов запрета, если в базе данных существуют запреты, пользователю или IP будет отказано в доступе.
| Режим | Описание |
|---|---|
| user | Учетная запись пользователя является объектом любых автоматических запретов |
| ip | Удаленный ip является объектом любых автоматических запретов |
Количество неудачных попыток входа в систему, после которых пользователь может быть забанен. Установка этого параметра в 0 полностью отключает регулирование.
Период времени, анализируемый на предмет неудачных попыток. Например, если вы установили max_retries в 3, а find_time в 2m, это означает, что у пользователя должно быть 3 неудачных входа в систему за 2 минуты.
Период времени, на который пользователь будет заблокирован после выполнения настроек max_retries и find_time. По истечении этого срока пользователь сможет снова войти в систему.
password_policy:
standard:
enabled: false
min_length: 8
max_length: 0
require_uppercase: false
require_lowercase: false
require_number: false
require_special: false
zxcvbn:
enabled: false
min_score: 3
В этом разделе можно включить стандартные политики безопасности.
Включает стандартную политику паролей.
Определяет минимально допустимую длину пароля.
Определяет максимально допустимую длину пароля.
Указывает, что в пароле должна быть указана хотя бы одна буква UPPERCASE.
Указывает, что в пароле должна быть указана хотя бы одна строчная буква.
Указывает, что в пароле должна быть указана хотя бы одна цифра.
Указывает, что в пароле должен быть указан хотя бы один специальный символ.
Эта политика паролей включает расширенный учет надежности паролей с помощью zxcvbn.
Обратите внимание, что данная политика паролей не ограничивает вход пользователя, а лишь предоставляет ему информацию о том, насколько надежным является его пароль.
Включает политику паролей zxcvbn.
Настраивает минимальный балл zxcvbn, допустимый для новых паролей. В системе баллов zxcvbn существует 5 уровней (взято с github.com/dropbox/zxcvbn):
Мы не допускаем оценку 0, если вы установите значение min_score равным 0, вместо него будет использоваться значение по умолчанию.
identity_validation:
elevated_session: {}
reset_password: {}
Elevated Session, которая не позволяет вошедшему в систему пользователю выполнять привилегированные действия без предварительного подтверждения своей личности.
Reset Password — Сброс пароля, который не позволяет анонимному пользователю выполнить сброс пароля для пользователя без предварительного подтверждения его личности.
Elevated Session (Повышенная сессия) — это механизм безопасности в Authelia, который требует дополнительной проверки личности пользователя при выполнении критически важных действий, связанных с безопасностью аккаунта. Это предотвращает несанкционированные изменения, даже если злоумышленник получил доступ к сессии пользователя.
Создается “повышенная сессия” на ограниченное время (по умолчанию — 5 минут), в течение которой пользователь может выполнять защищенные действия.
identity_validation:
elevated_session:
code_lifespan: '5 minutes'
elevation_lifespan: '10 minutes'
characters: 8
require_second_factor: false
skip_second_factor: false
Срок действия случайно сгенерированного одноразового кода, после которого он считается недействительным
Время жизни возвышения после первоначальной проверки одноразового кода до истечения срока его действия.
Количество символов в случайном одноразовом коде. Максимальное значение на данный момент составляет 20, но мы рекомендуем держать его в диапазоне от 8 до 12. Уменьшать значение ниже 8 крайне не рекомендуется.
Требуется аутентификация по второму фактору для всех защищенных действий в дополнение к повышенному сеансу, если пользователь настроил метод аутентификации по второму фактору.
Пропускает требование повышенной сессии, если пользователь выполнил аутентификацию по второму фактору. Можно комбинировать с параметром require_second_factor, чтобы всегда (и только) требовать аутентификацию по второму фактору.
identity_validation:
reset_password:
jwt_secret: ''
jwt_lifespan: '5 minutes'
jwt_algorithm: 'HS256'
Секрет, используемый алгоритмом HMAC для подписи JWT. Это значение должно представлять собой произвольную случайную строку с печатаемыми символами ASCII.
Настоятельно рекомендуется, чтобы это была случайная буквенно-цифровая строка из 64 или более символов.
Время жизни JSON Web Token после его первоначальной генерации, по истечении которого он считается недействительным.
Алгоритм JSON Web Token, используемый для подписи JWT. Должен быть HS256, HS384 или HS512.
Режим Session контролирует:
session:
secret: 'insecure_session_secret'
name: 'authelia_session'
same_site: 'lax'
inactivity: '5m'
expiration: '1h'
remember_me: '1M'
cookies:
- domain: 'rabrain.ru'
authelia_url: 'https://auth.rabrain.ru'
default_redirection_url: 'https://www.rabrain.ru'
name: 'authelia_session'
same_site: 'lax'
inactivity: '5m'
expiration: '1h'
remember_me: '1d'
session:
secret: 'insecure_session_secret'
name: 'authelia_session'
same_site: 'lax'
inactivity: '5m'
expiration: '1h'
remember_me: '1M'
cookies:
- domain: 'rabrain.ru'
authelia_url: 'https://auth.rabrain.ru'
default_redirection_url: 'https://www.rabrain.ru'
name: 'authelia_session'
same_site: 'lax'
inactivity: '5m'
expiration: '1h'
remember_me: '1d'
В настоящее время существует два провайдера для хранения сессий (три, если считать Redis Sentinel отдельным провайдером):
Важно отметить, что при выборе провайдера не рекомендуется использовать провайдеров с функцией stateless в сценариях High Availability, таких как Kubernetes. Рядом с каждым провайдером есть примечание, указывающее, является ли он государственным или нестационарным, рекомендуется использовать нестационарные провайдеры.
Значение имени по умолчанию для всех конфигураций cookies.
Значение same_site по умолчанию для всех конфигураций cookies.
Значение бездействия по умолчанию для всех конфигураций cookies.
Значение срока действия по умолчанию для всех конфигураций cookies.
Значение remember_me по умолчанию для всех конфигураций cookies.
Список определенных доменов cookie, которые Authelia настроена обрабатывать. Домены, не настроенные должным образом, будут автоматически отклоняться Authelia. Список позволяет администраторам определить несколько конфигураций доменов cookie сеанса с индивидуальными настройками.
Домен, для защиты которого назначается сессионный cookie. Он должен совпадать с доменом, на котором обслуживается Authelia, или корнем домена, и, следовательно, если настроен authelia_url, должен иметь возможность читать и записывать куки для этого домена.
Например, если Authelia доступна по URL https://auth.rabrain.ru, домен должен быть либо auth.rabrain.ru, либо rabrain.ru.
Значение не должно совпадать с доменом из списка публичных суффиксов, поскольку браузеры не разрешают веб-сайтам записывать файлы cookie для таких доменов. Это касается большинства служб динамического DNS, таких как duckdns.org. Вы должны использовать свой домен вместо duckdns.org для этого значения, например example.duckdns.org.
Следовательно, если у вас есть example.duckdns.org и example-auth.duckdns.org, вы не сможете обмениваться файлами cookie между этими доменами.
Это обязательный URL, который является корневым URL вашей установки Authelia для этого домена cookie, который может быть использован для создания соответствующего URL перенаправления, когда требуется аутентификация. Этот URL должен:
Соответствующий параметр запроса или заголовок для соответствующего прокси может отменить это поведение.
Это совершенно необязательный URL, который используется в качестве места перенаправления при прямом посещении Authelia. Эта опция отменяет глобальную опцию default_redirection_url.
Значение по умолчанию: Этот параметр принимает значение по умолчанию из настройки имени, приведенной выше.
Имя куки сеанса. По умолчанию устанавливается значение имени в основном разделе конфигурации сеанса.
Значение по умолчанию: Этот параметр принимает значение по умолчанию из настройки same_site, указанной выше.
Устанавливает значение cookies SameSite. До появления этого параметра по умолчанию было установлено значение None. Новое значение по умолчанию - Lax. Эта опция задается в нижнем регистре. Поэтому, например, если вы хотите установить значение Strict, то в конфигурации оно должно быть строгим.
Подробно о куках SameSite можно прочитать в MDN. Короче говоря, установка SameSite в значение Lax является наиболее предпочтительным вариантом для Authelia. None не рекомендуется, если только вы не знаете, что делаете, и не доверяете всем защищенным приложениям. Strict не будет работать во многих случаях, и мы не тестировали его в этом состоянии, но в любом случае он доступен как опция.
Значение по умолчанию: Этот параметр принимает значение по умолчанию из настройки бездействия, приведенной выше.
Период времени, в течение которого пользователь может быть неактивен, пока сессия не будет уничтожена. Пригодится, если вам нужны длительные таймеры сеансов, но вы не хотите, чтобы неиспользуемые устройства были уязвимы.
Значение по умолчанию: Этот параметр принимает значение по умолчанию из настройки истечения срока действия, указанной выше.
Период времени до истечения срока действия cookie и уничтожения сессии. Это значение переопределяется параметром remember_me, если установлен флажок remember me.
Значение по умолчанию: Этот параметр принимает значение по умолчанию из настройки remember_me, указанной выше.
Период времени до истечения срока действия куки и уничтожения сессии, когда установлен флажок remember me. Установка значения -1 полностью отключает эту функцию для данного домена сессионных cookie.
По умолчанию Authelia хранит сессии в оперативной памяти (in-memory). Это приводит к:
| Проблема | Решение через Redis |
|---|---|
| Потеря сессий при перезагрузке | Сессии хранятся на внешнем сервере и сохраняются после рестарта |
| Несколько экземпляров Authelia | Все ноды читают/пишут сессии в единое хранилище |
| Высокая нагрузка | Redis оптимизирован для частых операций чтения/записи |
session:
redis:
host: '127.0.0.1'
port: 6379
timeout: '5s'
max_retries: 0
username: 'authelia'
password: 'authelia'
database_index: 0
maximum_active_connections: 8
minimum_idle_connections: 0
tls:
server_name: 'myredis.rabrain.ru'
skip_verify: false
minimum_version: 'TLS1.2'
maximum_version: 'TLS1.3'
certificate_chain: |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
private_key: |
-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
high_availability:
sentinel_name: 'mysentinel'
# If `sentinel_username` is supplied, Authelia will connect using ACL-based
# authentication. Otherwise, it will use traditional `requirepass` auth.
sentinel_username: 'sentinel_user'
sentinel_password: 'sentinel_specific_pass'
nodes:
- host: 'sentinel-node1'
port: 26379
- host: 'sentinel-node2'
port: 26379
route_by_latency: false
route_randomly: false
Хост redis или путь к сокету unix. Если используется буквенный адрес IPv6, он должен быть заключен в квадратные скобки и взят в кавычки:
host: '[fd00:1111:2222:3333::1]'
Таймаут соединения с Redis.
Максимальное количество повторных попыток при неудачной команде. Установка этого параметра в 0 полностью отключает повторные попытки.
Порт, на котором прослушивается Redis.
Имя пользователя для аутентификации в redis. Поддерживается только в redis 6.0+, и в настоящее время redis предлагает обратную совместимость с аутентификацией только по паролю. Вероятно, вам не нужно задавать это значение, если вы не проходили через процесс настройки ACL redis.
Пароль для аутентификации в Redis.
Настоятельно рекомендуется, чтобы это была случайная буквенно-цифровая строка из 64 или более символов, и пароль пользователя был изменен на это значение.
Номер индекса базы данных redis, то же значение, что и в команде redis SELECT.
Максимальное количество соединений, открытых к redis в одно и то же время.
Минимальное количество соединений redis, которые следует держать открытыми, пока они не превышают максимальное количество активных соединений. Это полезно, если возникают большие задержки при установлении соединений.
Если определено, включает соединение через TLS-сокет и дополнительно управляет параметрами проверки TLS-соединения для сервера redis.
По умолчанию Authelia использует системный сертификат доверия для проверки TLS-соединений, а глобальная опция certificates_directory может быть использована для дополнения этого параметра.
При определении этой сессии включается соединение с redis sentinel. Возможно, в будущем мы добавим кластер redis.
Имя ведущего сервера redis sentinel. Оно задается в конфигурации redis sentinel, это не имя хоста. Для конфигурации высокой доступности оно должно быть определено в данный момент.
Имя пользователя для подключения к Redis Sentinel. Если оно указано, оно будет использоваться вместе с паролем sentinel_password для аутентификации на основе ACL для Redis Sentinel. Если указан только пароль, соединение с Redis Sentinel будет аутентифицировано с помощью традиционной аутентификации requirepass.
Пароль для подключения к Redis Sentinel. Если указан с именем sentinel_username, Authelia настраивает аутентификацию на Redis Sentinel с помощью аутентификации на основе ACL. В противном случае используется аутентификация по requirepass.
Настоятельно рекомендуется, чтобы это была случайная буквенно-цифровая строка из 64 или более символов, и пароль пользователя был изменен на это значение.
Список узлов redis sentinel для балансировки нагрузки. Этот список добавляется к хосту в разделе redis выше. Необходимо определить либо хост redis, либо один сентинел-узел redis. Хост redis должен быть узлом redis sentinel, а не обычным узлом. Отдельные узлы redis определяются с помощью команд redis sentinel.
- host: redis-sentinel-0
port: 26379
Хост этого узла redis sentinel.
Порт этого узла redis sentinel.
Приоритет отдается узлам redis sentinel с низкой задержкой, если установлено значение true.
Случайным образом выбирает узлы redis sentinel, если установлено значение true.
| Тип данных | Примеры | Важность |
|---|---|---|
| Настройки пользователей | Выбранная тема, язык интерфейса | Низкая |
| 2FA-данные | TOTP-секреты, ключи WebAuthn | Высокая |
| Журналы аутентификации | Входы, попытки сброса пароля | Средняя |
| OAuth2-данные | Токены, authorization codes | Высокая |
| Сессии (если не используется Redis) | Активные сеансы пользователей | Высокая |
Authelia работает с такими базами данных:
| Хранилище | Когда выбирать | Особенности |
|---|---|---|
| PostgreSQL | Production-среда | Высокая производительность, поддержка сложных запросов |
| MySQL/MariaDB | Уже есть инфраструктура MySQL | Совместимость с большинством хостингов |
| SQLite | Тестирование/разработка | Не требует сервера, но не для продакшена |
| Redis (только для сессий) | Высоконагруженные системы | Только key-value, без SQL |
storage:
encryption_key: 'a_very_important_secret'
local: {}
mysql: {}
postgres: {}
Ключ шифрования, используемый для шифрования данных в базе данных. Мы шифруем данные, создавая контрольную сумму sha256 из указанного значения, и используем ее для шифрования данных с помощью 256-битного алгоритма AES-GCM.
Минимальная длина этого ключа - 20 символов.
Настоятельно рекомендуется, чтобы это была случайная буквенно-цифровая строка из 64 или более символов.
| Тип данных | Примеры | Важность |
|---|---|---|
| Учетные данные 2FA | TOTP-секреты, ключи WebAuthn | 🔥 Высокая |
| Журналы аутентификации | Входы, попытки сброса пароля | 🔍 Средняя |
| Настройки пользователей | Язык, тема интерфейса | 📌 Низкая |
| OAuth2-токены | Access/refresh tokens | 🔥 Высокая |
| Данные сессий (если не используется Redis) | Активные сеансы | ⚡ Высокая |
| Критерий | PostgreSQL | MySQL/SQLite | Redis |
|---|---|---|---|
| Поддержка сложных запросов | ✅ Да | ❌ Ограничена | ❌ Нет |
| Надежность транзакций | ✅ ACID | ✅ ACID | ❌ Key-Value |
| Производительность | ⚡ Высокая | ⚡ Средняя | ⚡ Максимальная |
| Масштабируемость | ✅ Горизонтальная | ✅ Вертикальная | ✅ Кластеры |
| Безопасность | 🔒 Row-Level Security | 🔒 Базовые права | 🔒 Нет |
Добавьте в configuration.yml:
storage:
encryption_key: 'a_very_important_secret'
postgres:
address: 'tcp://127.0.0.1:5432'
servers: []
database: 'authelia'
schema: 'public'
username: 'authelia'
password: 'mypassword'
timeout: '5s'
tls:
server_name: 'postgres.rabrain.ru'
skip_verify: false
minimum_version: 'TLS1.2'
maximum_version: 'TLS1.3'
certificate_chain: |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
private_key: |
-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
-- Пример данных в PostgreSQL:
SELECT * FROM totp_secrets WHERE username = 'user@example.com';
Ключ шифрования, используемый для шифрования данных в базе данных. Мы шифруем данные, создавая контрольную сумму sha256 из указанного значения, и используем ее для шифрования данных с помощью 256-битного алгоритма AES-GCM.
Минимальная длина этого ключа - 20 символов.
Настоятельно рекомендуется, чтобы это была случайная буквенно-цифровая строка из 64 или более символов.
Настраивает адрес для сервера PostgreSQL. Сам адрес является коннектором, а схема должна быть либо схемой unix, либо одной из схем tcp.
storage:
postgres:
address: 'tcp://127.0.0.1:5432'
storage:
postgres:
address: 'tcp://[fd00:1111:2222:3333::1]:5432'
storage:
postgres:
address: 'unix:///var/run/postgres.sock'
Здесь указывается список дополнительных резервных экземпляров PostgreSQL, которые будут использоваться в случае возникновения проблем с основным экземпляром, настроенным с помощью опций address и tls.
У каждого экземпляра сервера есть опции address и tls, которые имеют одинаковые требования и влияние, а также одинаковый синтаксис конфигурации. Это означает, что все остальные настройки, включая базу данных, схему, имя пользователя и пароль, должны быть такими же, как у основного экземпляра, и полностью реплицироваться.
storage:
postgres:
address: 'tcp://postgres1:5432'
tls:
server_name: 'postgres1.local'
servers:
- address: 'tcp://postgres2:5432'
tls:
server_name: 'postgres2.local'
- address: 'tcp://postgres3:5432'
tls:
server_name: 'postgres3.local'
Имя базы данных на сервере баз данных, к которой назначенный пользователь имеет доступ для работы с Authelia.
Имя схемы базы данных, используемой на сервере базы данных, к которому назначенный пользователь имеет доступ для Authelia. По умолчанию это публичная схема.
Имя пользователя в паре с паролем, используемые для подключения к базе данных.
Пароль, связанный с именем пользователя, используемым для подключения к базе данных.
Настоятельно рекомендуется, чтобы это была случайная буквенно-цифровая строка из 64 или более символов, и пароль пользователя был изменен на это значение.
Таймаут соединения SQL.
Если этот параметр определен, он включает соединение через сокет TLS и дополнительно управляет параметрами проверки TLS-соединения для сервера PostgreSQL.
По умолчанию Authelia использует системный сертификат доверия для проверки TLS-соединений, а глобальная опция certificates_directory может быть использована для дополнения этого параметра.
Использование этого провайдера хранилища делает Authelia доступной для состояния. В сценариях высокой доступности важно использовать один из других провайдеров, и мы настоятельно рекомендуем использовать его в производственных средах, но это потребует от вас установки внешней базы данных, например PostgreSQL.
Добавьте в configuration.yml:
storage:
encryption_key: 'a_very_important_secret'
local:
path: '/config/db.sqlite3'
Ключ шифрования, используемый для шифрования данных в базе данных. Мы шифруем данные, создавая контрольную сумму sha256 из указанного значения, и используем ее для шифрования данных с помощью 256-битного алгоритма AES-GCM.
Минимальная длина этого ключа - 20 символов.
Настоятельно рекомендуется, чтобы это была случайная буквенно-цифровая строка из 64 или более символов.
Путь, по которому будет храниться файл базы данных SQLite3. Он будет создан, если файл не существует.
| Критерий | PostgreSQL | MySQL/SQLite | Redis |
|---|---|---|---|
| Поддержка сложных запросов | ✅ Да | ❌ Ограничена | ❌ Нет |
| Надежность транзакций | ✅ ACID | ✅ ACID | ❌ Key-Value |
| Производительность | ⚡ Высокая | ⚡ Средняя | ⚡ Максимальная |
| Масштабируемость | ✅ Горизонтальная | ✅ Вертикальная | ✅ Кластеры |
| Безопасность | 🔒 Row-Level Security | 🔒 Базовые права | 🔒 Нет |
Добавьте в configuration.yml:
storage:
encryption_key: 'a_very_important_secret'
mysql:
address: 'tcp://127.0.0.1:3306'
database: 'authelia'
username: 'authelia'
password: 'mypassword'
timeout: '5s'
tls:
server_name: 'mysql.rabrain.ru'
skip_verify: false
minimum_version: 'TLS1.2'
maximum_version: 'TLS1.3'
certificate_chain: |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
private_key: |
-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
Ключ шифрования, используемый для шифрования данных в базе данных. Мы шифруем данные, создавая контрольную сумму sha256 из указанного значения, и используем ее для шифрования данных с помощью 256-битного алгоритма AES-GCM.
Минимальная длина этого ключа - 20 символов.
Настоятельно рекомендуется, чтобы это была случайная буквенно-цифровая строка из 64 или более символов.
Настраивает адрес для сервера PostgreSQL. Сам адрес является коннектором, а схема должна быть либо схемой unix, либо одной из схем tcp.
storage:
mysql:
address: 'tcp://127.0.0.1:3306'
storage:
mysql:
address: 'tcp://[fd00:1111:2222:3333::1]:3306'
storage:
mysql:
address: 'unix:///var/run/mysqld.sock'
Имя базы данных на сервере баз данных, к которой назначенный пользователь имеет доступ для работы с Authelia.
Имя пользователя в паре с паролем, используемые для подключения к базе данных.
Пароль, связанный с именем пользователя, используемым для подключения к базе данных.
Настоятельно рекомендуется, чтобы это была случайная буквенно-цифровая строка из 64 или более символов, и пароль пользователя был изменен на это значение.
Таймаут соединения SQL.
Если этот параметр определен, он включает соединение через сокет TLS и дополнительно управляет параметрами проверки TLS-соединения для сервера MySQL.
По умолчанию Authelia использует системный сертификат доверия для проверки TLS-соединений, а глобальная опция certificates_directory может быть использована для дополнения этого параметра.
| Тип уведомления | Когда отправляется | Метод отправки |
|---|---|---|
| Сброс пароля | При запросе восстановления пароля | Email/SMS |
| Подтверждение 2FA | При добавлении нового устройства | Email/Push |
| Подозрительный вход | При входе с нового IP/устройства | Email/SMS |
| Identity Verification | Для подтверждения личности | Email/SMS |
notifier:
disable_startup_check: false
template_path: ''
filesystem: {}
smtp: {}
В уведомлении предусмотрена проверка запуска, которая проверяет правильность конфигурации указанного провайдера и возможность отправки писем. Эту проверку можно отключить с помощью опции disable_startup_check.
Этот параметр позволяет администратору указать путь к каталогу, в котором будут находиться пользовательские шаблоны уведомлений.
notifier:
disable_startup_check: false
smtp:
address: 'smtp://127.0.0.1:25'
timeout: '5s'
username: 'test'
password: 'password'
sender: "Authelia <admin@rabrain.ru>"
identifier: 'localhost'
subject: "[Authelia] {title}"
startup_check_address: 'test@rabrain.ru'
disable_require_tls: false
disable_starttls: false
disable_html_emails: false
tls:
server_name: 'smtp.rabrain.ru'
skip_verify: false
minimum_version: 'TLS1.2'
maximum_version: 'TLS1.3'
certificate_chain: |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
private_key: |
-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
Настройка адреса для SMTP-сервера. Сам адрес является коннектором, а схема должна быть smtp, submission или submissions. Единственное различие между этими схемами заключается в портах по умолчанию, а для отправки требуется транспорт TLS в соответствии с мерами безопасности портов SMTP, в то время как отправка и smtp используют стандартный транспорт TCP и обычно применяют StartTLS.
notifier:
smtp:
address: 'smtp://127.0.0.1:25'
notifier:
smtp:
address: 'submissions://[fd00:1111:2222:3333::1]:465'
Таймаут соединения SMTP.
Имя пользователя, отправляемое для аутентификации на SMTP-сервере. В паре с паролем.
Пароль в паре с именем пользователя, отправляемый для аутентификации на SMTP-сервере.
Адрес отправителя используется для создания SMTP-команды MAIL FROM и добавления заголовка FROM. Этот адрес должен быть в формате RFC5322. Это означает, что он должен иметь один из двух форматов:
Команда MAIL FROM, отправляемая SMTP-серверам, не будет включать часть имени, она задается только в FROM в соответствии со спецификациями.
Имя, которое нужно отправить SMTP-серверу в качестве идентификатора с помощью команды HELO/EHLO. Некоторые SMTP-провайдеры, такие как Google Mail, отклоняют сообщение, если это localhost.
Это тема, которую Authelia будет использовать в электронном письме. В настоящее время она имеет единственный заполнитель {title}, который должен быть включен во все электронные письма, поскольку это внутренний дескриптор содержимого письма.
При запуске Authelia проверяет действительность SMTP-сервера, одна из проверок требует, чтобы мы спросили SMTP-сервер, может ли он отправить письмо от нас на определенный адрес, и это тот самый адрес. На самом деле никаких писем при этом не отправляется. Можно оставить все как есть, но вы можете настроить это, если у вас возникнут проблемы или вы захотите.
В целях безопасности настройки по умолчанию для Authelia требуют, чтобы SMTP-соединение было зашифровано с помощью TLS. Дополнительные сведения см. в разделе Безопасность. Эта опция отключает данную меру (не рекомендуется).
Некоторые SMTP-серверы игнорируют спецификации SMTP и утверждают, что поддерживают STARTTLS, хотя на самом деле это не так. По соображениям безопасности Authelia отказывается отправлять сообщения на такие серверы. Данная опция отключает эту меру и включается на ВАШ собственный страх и риск.
Эта настройка полностью отключает HTML-форматирование писем и отправляет только текстовые сообщения. По умолчанию Authelia отправляет смешанные письма, содержащие как HTML, так и текст, поэтому эта опция редко бывает необходима.
Если эта опция определена, она управляет параметрами проверки TLS-соединения для SMTP-сервера.
По умолчанию Authelia использует системное доверие к сертификатам для проверки TLS-соединений, а глобальная опция certificates_directory может быть использована для дополнения этого параметра.
notifier:
smtp:
address: 'submission://smtp.gmail.com:587'
username: 'myaccount@gmail.com'
# Password can also be set using a secret: https://www.authelia.com/configuration/methods/secrets/
password: 'yourapppassword'
sender: 'admin@rabrain.ru'
notifier:
disable_startup_check: false
filesystem:
filename: '/config/notification.txt'
Файл, в который нужно добавить текст письма. Если он не существует, он будет создан.
Authelia хранит метрики только в оперативной памяти (не отправляет их автоматически наружу).
Примеры данных:
| Метрика | Описание | Пример значения |
|---|---|---|
| authelia_requests_total | Общее количество запросов | 1523 |
| authelia_2fa_attempts | Попыток 2FA (успешные/неудачные) | success: 120, failed: 5 |
| authelia_session_duration | Длительность сессий пользователей | avg: 5m |
| authelia_storage_queries | Запросы к базе данных | postgres: 42/s |
telemetry:
metrics:
enabled: false
address: 'tcp://:9959/metrics'
buffers:
read: 4096
write: 4096
timeouts:
read: '6s'
write: '6s'
idle: '30s'
Определяет, включен ли Prometheus HTTP Metrics Exporter.
Настраивает адрес слушателя для HTTP-сервера Prometheus Metrics Exporter. Адрес сам по себе является слушателем, а схема должна быть либо схемой unix, либо одной из схем tcp.
Настройка буферов сервера.
Настройка тайм-аутов сервера.
| Настройка | За что отвечает | Пример значения |
|---|---|---|
| Прослушивание интерфейсов | На каких IP и портах доступен сервер | 0.0.0.0:9091 |
| Ограничение доверенных прокси | Какие IP могут передавать заголовки аутентификации | 192.168.1.0/24 |
| Таймауты | Защита от DDoS и медленных соединений | read: 10s |
| TLS/SSL | Шифрование соединений | Сертификаты Let’s Encrypt |
definitions:
network:
network_name:
- '192.168.1.0/24'
- '192.168.2.20'
- '2001:db8::/32'
- '2001:db8:1234:5678::1'
Эти определения используются в качестве сетей управления доступом и сетей политики авторизации OpenID Connect 1.0.
Ключ - это имя политики. В приведенном выше примере ключом является network_name, и это значение должно использоваться в других областях конфигурации для ссылки на нее.
Значения, представляющие CIDR-нотацию IP-адресов, к которым применяется данное определение. В примере значение представляет собой список, содержащий 192.168.1.0/24, 192.168.2.20, 2001:db8::/32 и 2001:db8:1234:5678::1.
Нотация CIDR (например, 192.168.1.0/24) представляет собой диапазон IP-адресов. Число после косой черты указывает, сколько бит используется для сетевой части. Например, /24 означает, что первые 24 бита фиксированы, а последние 8 бит могут изменяться (что дает 256 возможных адресов). Один IP-адрес, например 192.168.2.20, может быть записан как есть или с /32.
definitions:
user_attributes:
# Boolean attribute example
is_admin:
expression: '"admin" in groups'
# String attribute example
department:
expression: 'groups[0]'
# Number attribute example
access_level:
expression: '"admin" in groups ? 10 : 5'
В этом разделе описаны отдельные параметры конфигурации. В настоящее время эти определения атрибутов используются в провайдере OpenID Connect 1.0.
Имя ключа - это имя результирующего атрибута. Важно отметить, что это имя атрибута не должно конфликтовать с дополнительными атрибутами, определенными в бэкенде аутентификации, или с общими атрибутами, которые мы определили.
В приведенном выше примере добавлены следующие атрибуты:
Выражение Common Expression Language для этого атрибута.
certificates_directory: '/config/certs/'
default_redirection_url: 'https://home.example.com:8080/'
theme: 'light'
По умолчанию Authelia использует системное хранилище сертификатов для проверки сертификатов TLS, но вы можете расширить его с помощью этой опции, которая формирует основу для доверия к TLS-соединениям в Authelia. В большинстве случаев, если не во всех TLS-соединениях, TLS-сертификат сервера проверяется с помощью этого расширенного хранилища доверия сертификатов.
Эта опция задает путь к каталогу, который может содержать один или несколько сертификатов, закодированных в формате X.509 PEM. Сами сертификаты должны иметь расширение .pem, .crt или .cer.
Эти сертификаты могут быть либо открытым ключом ЦС, который доверяет данному сертификату и любому подписанному им сертификату, либо отдельным сертификатом листа.
URL перенаправления по умолчанию - это URL, на который перенаправляются пользователи, когда Authelia не может определить целевой URL, на который направлялся пользователь.
В обычном процессе аутентификации пользователь пытается зайти на веб-сайт, и его перенаправляют на портал для входа в систему, чтобы пройти аутентификацию. Поскольку пользователь изначально нацелился на веб-сайт, портал знает, куда он направлялся, и может перенаправить его после процесса аутентификации. Однако, когда пользователь посещает портал регистрации напрямую, портал считает, что целевой веб-сайт - это портал. В этом случае, если настроен URL-адрес перенаправления по умолчанию, пользователь будет перенаправлен на этот URL-адрес. Если он не задан, пользователь не будет перенаправлен после аутентификации.
Устанавливает метод второго фактора по умолчанию для пользователей. Это должно быть пустое значение или один из включенных методов. Для новых пользователей по умолчанию будет выбран этот метод. Кроме того, если для пользователя был выбран метод webauthn, а у него был выбран метод totp, и метод totp был отключен в конфигурации, метод пользователя будет автоматически обновлен до метода webauthn.
Варианты:
В настоящее время для Authelia доступно 3 темы:
Чтобы включить автоматическое переключение между темами, вы можете установить для темы значение auto. Тема будет установлена на темную или светлую в зависимости от системных предпочтений пользователя, которые определяются с помощью медиа-запросов.
| Настройка | Описание | Важность |
|---|---|---|
| address | Интерфейс и порт прослушивания | 🔥 Критично |
| tls | Настройки HTTPS (сертификаты) | 🔥 Критично |
| headers | Безопасность HTTP-заголовков | 🔐 Высокая |
| buffers | Оптимизация производительности | ⚡ Средняя |
| timeouts | Защита от DDoS/подвешенных сессий | 🛡️ Высокая |
| endpoints | Управление служебными API | 🔧 Опционально |
server:
address: 'tcp://:9091/'
disable_healthcheck: false
tls:
key: ''
certificate: ''
client_certificates: []
headers:
csp_template: ''
buffers:
read: 4096
write: 4096
timeouts:
read: '6s'
write: '6s'
idle: '30s'
endpoints:
enable_pprof: false
enable_expvars: false
authz: {} ## See the dedicated "Server Authz Endpoints" configuration guide.
rate_limits: {} ## See the dedicated "Server Endpoint Rate Limits" configuration guide.
server:
address: 'tcp://0.0.0.0:9091' # Слушать все интерфейсы на порту 9091
disable_healthcheck: false # Включить эндпоинт /healthcheck
tls:
key: /etc/ssl/private/key.pem # Приватный ключ
certificate: /etc/ssl/certs/cert.pem # Сертификат
client_certificates: [] # mTLS (опционально)
headers:
csp_template: "default-src 'self'" # Content Security Policy
csp_template: "default-src 'none'; script-src 'self'; style-src 'self'; font-src 'self'; img-src 'self' data:; connect-src 'self'"
buffers:
read: 4096 # Размер буфера чтения (байт)
write: 4096 # Размер буфера записи
timeouts:
read: '6s' # Таймаут чтения запроса
write: '6s' # Таймаут отправки ответа
idle: '30s' # Таймаут неактивного соединения
####Зачем:
endpoints:
enable_pprof: false # Отключить debug-эндпоинты (/debug/pprof)
enable_expvars: false # Отключить метрики runtime (/debug/vars)
authz: {} # Настройки авторизации для API
rate_limits: {} # Лимиты запросов к API
server:
address: 'tcp://127.0.0.1:9091' # Только локальный доступ + Nginx/Traefik
tls:
certificate: /etc/letsencrypt/live/example.com/fullchain.pem
key: /etc/letsencrypt/live/example.com/privkey.pem
headers:
csp_template: "default-src 'self'; script-src 'none'"
timeouts:
read: '10s'
write: '15s'
idle: '1m'
| Проблема | Решение |
|---|---|
| Authelia не запускается на порту | Проверьте address и отсутствие конфликта портов (netstat -tulpn) |
| Ошибки HTTPS (ERR_SSL_PROTOCOL_ERROR) | Убедитесь, что сертификаты не повреждены и имеют права 400 |
| Медленные ответы | Увеличьте buffers (например, до 8192) |
| Атаки на /debug/pprof | Всегда enable_pprof: false в production |
Настройте Authelia на 127.0.0.1:
address: 'tcp://127.0.0.1:9091'
location /authelia {
proxy_pass http://127.0.0.1:9091;
proxy_set_header X-Real-IP $remote_addr;
}
authelia validate-config --config /etc/authelia/configuration.yml
Configuration parsed and validated successfully!
Этот раздел конфигурации позволяет контролировать:
server:
endpoints:
authz:
forward-auth:
implementation: 'ForwardAuth'
authn_strategies:
- name: 'HeaderAuthorization'
schemes:
- 'Basic'
scheme_basic_cache_lifespan: 0
- name: 'CookieSession'
ext-authz:
implementation: 'ExtAuthz'
authn_strategies:
- name: 'HeaderAuthorization'
schemes:
- 'Basic'
scheme_basic_cache_lifespan: 0
- name: 'CookieSession'
auth-request:
implementation: 'AuthRequest'
authn_strategies:
- name: 'HeaderAuthorization'
schemes:
- 'Basic'
scheme_basic_cache_lifespan: 0
- name: 'CookieSession'
legacy:
implementation: 'Legacy'
Первый уровень под директивой authz - это имя конечной точки. В примере это имена forward-auth, ext-authz, auth-request и legacy.
Имя коррелирует с путем к конечной точке. Все конечные точки начинаются с /api/authz/ и заканчиваются именем. В примере конечная точка forward-auth имеет полный путь /api/authz/forward-auth.
Допустимыми символами для имени являются буквенно-цифровые символы, а также -, _ и /. Они ДОЛЖНЫ начинаться и заканчиваться буквенно-цифровым символом.
Базовая реализация для конечной точки. Допустимые значения с учетом регистра: ForwardAuth, ExtAuthz, AuthRequest и Legacy.
Список стратегий аутентификации и параметров их конфигурации. Эти стратегии расположены по порядку, и используется первая из них, оказавшаяся успешной. В случае отказа, кроме отсутствия в запросе информации, достаточной для выполнения стратегии, аутентификация немедленно прекращается, в противном случае выполняется попытка использования следующей стратегии из списка.
Имя стратегии. Допустимые значения с учетом регистра: CookieSession, HeaderAuthorization, HeaderProxyAuthorization, HeaderAuthRequestProxyAuthorization и HeaderLegacy.
Список схем, разрешенных для этой конечной точки. Варианты: Basic и Bearer. Эта опция применима только к стратегиям HeaderAuthorization, HeaderProxyAuthorization и HeaderAuthRequestProxyAuthorization и недоступна для устаревшей конечной точки, которая использует только Basic.
Время жизни для кэширования комбинаций имени пользователя и пароля при использовании схемы Basic. Эта опция позволяет использовать кэширование, которое по умолчанию полностью отключено. Эта опция должна использоваться только при настройке схемы Basic, и, как и все новые опции, не может использоваться при реализации Legacy.
server:
endpoints:
rate_limits:
reset_password_start:
enable: true
buckets:
- period: '10 minutes'
requests: 5
- period: '15 minutes'
requests: 10
- period: '30 minutes'
requests: 15
reset_password_finish:
enable: true
buckets:
- period: '1 minute'
requests: 10
- period: '2 minutes'
requests: 15
second_factor_totp:
enable: true
buckets:
- period: '1 minute'
requests: 30
- period: '2 minutes'
requests: 40
- period: '10 minutes'
requests: 50
second_factor_duo:
enable: true
buckets:
- period: '1 minute'
requests: 10
- period: '2 minutes'
requests: 15
session_elevation_start:
enable: true
buckets:
- period: '5 minutes'
requests: 3
- period: '10 minutes'
requests: 5
- period: '1 hour'
requests: 15
session_elevation_finish:
enable: true
buckets:
- period: '10 minutes'
requests: 3
- period: '20 minutes'
requests: 5
- period: '1 hour'
requests: 15
Включает заданную конфигурацию ограничения скорости. По умолчанию они включены.
Список отдельных buckets, которые необходимо рассмотреть для каждого запроса.
Настраивает период времени, на который распространяется действие токенизированного bucket.
Настраивает количество запросов, к которым применяется токенизированный бакет.
Настраивает ограничитель скорости, который применяется к конечной точке, инициализирующей поток сброса пароля.
Настраивает ограничитель скорости, который применяется к конечным точкам, потребляющим токены для потока сброса пароля.
Настраивает ограничитель скорости, который применяется к представлениям кода конечной точки TOTP для потока второго фактора.
Настраивает ограничитель скорости, применяемый к конечной точке Duo / Mobile Push, которая инициализирует поток авторизации приложения для потока второго фактора.
Настраивает ограничитель скорости, применяемый к конечной точке Elevated Session, которая инициализирует генерацию кода и уведомление для потока elevated session.
Настраивает ограничитель скорости, применяемый к конечной точке Elevated Session, которая потребляет код для потока повышенной сессии.
https://getbootstrap.com/docs/5.3/getting-started/introduction/
.text-primary
.text-primary-emphasis
.text-secondary
.text-secondary-emphasis
.text-success
.text-success-emphasis
.text-danger
.text-danger-emphasis
.text-warning
.text-warning-emphasis
.text-info
.text-info-emphasis
.text-light
.text-light-emphasis
.text-dark
.text-dark-emphasis
.text-body
.text-body-emphasis
.text-body-secondary
.text-body-tertiary
.text-black
.text-white
.text-black-50
.text-white-50
<p class="text-primary">.text-primary</p>
<p class="text-primary-emphasis">.text-primary-emphasis</p>
<p class="text-secondary">.text-secondary</p>
<p class="text-secondary-emphasis">.text-secondary-emphasis</p>
<p class="text-success">.text-success</p>
<p class="text-success-emphasis">.text-success-emphasis</p>
<p class="text-danger">.text-danger</p>
<p class="text-danger-emphasis">.text-danger-emphasis</p>
<p class="text-warning bg-dark">.text-warning</p>
<p class="text-warning-emphasis">.text-warning-emphasis</p>
<p class="text-info bg-dark">.text-info</p>
<p class="text-info-emphasis">.text-info-emphasis</p>
<p class="text-light bg-dark">.text-light</p>
<p class="text-light-emphasis">.text-light-emphasis</p>
<p class="text-dark bg-white">.text-dark</p>
<p class="text-dark-emphasis">.text-dark-emphasis</p>
<p class="text-body">.text-body</p>
<p class="text-body-emphasis">.text-body-emphasis</p>
<p class="text-body-secondary">.text-body-secondary</p>
<p class="text-body-tertiary">.text-body-tertiary</p>
<p class="text-black bg-white">.text-black</p>
<p class="text-white bg-dark">.text-white</p>
<p class="text-black-50 bg-white">.text-black-50</p>
<p class="text-white-50 bg-dark">.text-white-50</p>
$blue: #0d6efd;
$indigo: #6610f2;
$purple: #6f42c1;
$pink: #d63384;
$red: #dc3545;
$orange: #fd7e14;
$yellow: #ffc107;
$green: #198754;
$teal: #20c997;
$cyan: #0dcaf0;
$primary: $blue;
$secondary: $gray-600;
$success: $green;
$info: $cyan;
$warning: $yellow;
$danger: $red;
$light: $gray-100;
$dark: $gray-900;
$white: #fff;
$gray-100: #f8f9fa;
$gray-200: #e9ecef;
$gray-300: #dee2e6;
$gray-400: #ced4da;
$gray-500: #adb5bd;
$gray-600: #6c757d;
$gray-700: #495057;
$gray-800: #343a40;
$gray-900: #212529;
$black: #000;
<div class="p-3 mb-2 bg-primary text-white">.bg-primary</div>
<div class="p-3 mb-2 bg-primary-subtle text-primary-emphasis">.bg-primary-subtle</div>
<div class="p-3 mb-2 bg-secondary text-white">.bg-secondary</div>
<div class="p-3 mb-2 bg-secondary-subtle text-secondary-emphasis">.bg-secondary-subtle</div>
<div class="p-3 mb-2 bg-success text-white">.bg-success</div>
<div class="p-3 mb-2 bg-success-subtle text-success-emphasis">.bg-success-subtle</div>
<div class="p-3 mb-2 bg-danger text-white">.bg-danger</div>
<div class="p-3 mb-2 bg-danger-subtle text-danger-emphasis">.bg-danger-subtle</div>
<div class="p-3 mb-2 bg-warning text-dark">.bg-warning</div>
<div class="p-3 mb-2 bg-warning-subtle text-warning-emphasis">.bg-warning-subtle</div>
<div class="p-3 mb-2 bg-info text-dark">.bg-info</div>
<div class="p-3 mb-2 bg-info-subtle text-info-emphasis">.bg-info-subtle</div>
<div class="p-3 mb-2 bg-light text-dark">.bg-light</div>
<div class="p-3 mb-2 bg-light-subtle text-light-emphasis">.bg-light-subtle</div>
<div class="p-3 mb-2 bg-dark text-white">.bg-dark</div>
<div class="p-3 mb-2 bg-dark-subtle text-dark-emphasis">.bg-dark-subtle</div>
<div class="p-3 mb-2 bg-body-secondary">.bg-body-secondary</div>
<div class="p-3 mb-2 bg-body-tertiary">.bg-body-tertiary</div>
<div class="p-3 mb-2 bg-body text-body">.bg-body</div>
<div class="p-3 mb-2 bg-black text-white">.bg-black</div>
<div class="p-3 mb-2 bg-white text-dark">.bg-white</div>
<div class="p-3 mb-2 bg-transparent text-body">.bg-transparent</div>
<div class="bg-success p-2 text-white">This is default success background</div>
<div class="bg-success p-2 text-white bg-opacity-75">This is 75% opacity success background</div>
<div class="bg-success p-2 text-dark bg-opacity-50">This is 50% opacity success background</div>
<div class="bg-success p-2 text-dark bg-opacity-25">This is 25% opacity success background</div>
<div class="bg-success p-2 text-dark bg-opacity-10">This is 10% opacity success background</div>
Mixins (примеси) — это функции в Sass (SCSS), которые позволяют повторно использовать куски кода в CSS. В Bootstrap они используются для генерации готовых стилей (например, сетки, кнопок, утилит) без дублирования кода.
Bootstrap предоставляет десятки миксинов. Вот основные категории:
// Пример: Создание кастомной колонки
@include make-col(6); // Колонка на 50% ширины (6/12)
// Пример: Flex-контейнер с центрированием
.my-component {
@include d-flex();
@include justify-content(center);
}
// Пример: Добавление margin-top
.element {
@include margin-top(1rem);
}
// Пример: Стили только для экранов ≥768px
@include media-breakpoint-up(md) {
.card { width: 50%; }
}
// Пример: Создание кастомной кнопки
.my-btn {
@include button-variant(
$background: #ff5722,
$border: #ff5722,
$hover-background: darken(#ff5722, 10%)
);
}
Убедитесь, что в вашем проекте есть исходные файлы Bootstrap (SCSS), а не только скомпилированный CSS.
Например, custom.scss:
// Импорт Bootstrap
@import "bootstrap/scss/bootstrap";
// Ваши кастомные стили с миксинами
.my-custom-grid {
@include make-col-ready();
@include make-col(4); // Колонка на 33.3%
}
@include media-breakpoint-down(sm) {
.my-custom-grid {
@include make-col(12); // На мобильных — 100%
}
}
Используйте Sass-компилятор (например, через npm):
sass custom.scss custom.css
| Миксин | Описание | Пример |
|---|---|---|
make-container() |
Создает контейнер | @include make-container(); |
make-col() |
Генерирует колонку | @include make-col(6); |
border-radius() |
Скругление углов | @include border-radius(0.5rem); |
transition() |
Анимация перехода | @include transition(all 0.3s); |
box-shadow() |
Тень | @include box-shadow(0 0 10px rgba(0,0,0,0.1)); |
node_modules/bootstrap/scss/mixins/Mixins в Bootstrap — это мощный инструмент для тех, кто работает с Sass. Они позволяют:
✅ Гибко настраивать компоненты.
✅ Создавать адаптивные стили.
✅ Держать код чистым и модульным.
Пример использования:
// Кастомная кнопка
.my-btn {
@include button-variant(
$background: #17a2b8,
$border: #17a2b8,
$hover-background: darken(#17a2b8, 10%)
);
@include border-radius(2rem);
}
Таблица с основными классами Bootstrap 5 для работы с Flexbox:
| Класс | Описание | Пример |
|---|---|---|
.d-flex |
Включает Flexbox | <div class="d-flex"> |
.d-inline-flex |
Строчный Flex-контейнер | <span class="d-inline-flex"> |
.d-sm-flex |
Адаптивный Flex (на экранах ≥576px) | <div class="d-sm-flex"> |
| Класс | Описание | CSS-аналог |
|---|---|---|
.flex-row |
Горизонтальное (слева направо) | flex-direction: row |
.flex-row-reverse |
Горизонтальное (справа налево) | flex-direction: row-reverse |
.flex-column |
Вертикальное (сверху вниз) | flex-direction: column |
.flex-column-reverse |
Вертикальное (снизу вверх) | flex-direction: column-reverse |
Пример:
<div class="d-flex flex-row"> <!-- По умолчанию -->
<div>1</div><div>2</div>
</div>
| Класс | Описание | CSS-аналог |
|---|---|---|
.justify-content-start |
В начале оси | justify-content: flex-start |
.justify-content-end |
В конце оси | justify-content: flex-end |
.justify-content-center |
По центру | justify-content: center |
.justify-content-between |
Равные промежутки между | justify-content: space-between |
.justify-content-around |
Равные отступы вокруг | justify-content: space-around |
.justify-content-evenly |
Полное равномерное распределение | justify-content: space-evenly |
Пример:
<div class="d-flex justify-content-between">
<div>Лево</div><div>Право</div>
</div>
| Класс | Описание | CSS-аналог |
|---|---|---|
.align-items-start |
В начале оси | align-items: flex-start |
.align-items-end |
В конце оси | align-items: flex-end |
.align-items-center |
По центру | align-items: center |
.align-items-baseline |
По базовой линии | align-items: baseline |
.align-items-stretch |
Растянуть (по умолчанию) | align-items: stretch |
Пример:
<div class="d-flex align-items-center" style="height: 100px;">
<div>По центру высоты</div>
</div>
| Класс | Описание | CSS-аналог |
|---|---|---|
.align-self-start |
Элемент в начале | align-self: flex-start |
.align-self-end |
Элемент в конце | align-self: flex-end |
.align-self-center |
Элемент по центру | align-self: center |
.align-self-stretch |
Растянуть элемент | align-self: stretch |
Пример:
<div class="d-flex">
<div class="align-self-end">Прижат к низу</div>
</div>
| Класс | Описание | CSS-аналог |
|---|---|---|
.flex-nowrap |
Без переноса (по умолчанию) | flex-wrap: nowrap |
.flex-wrap |
С переносом | flex-wrap: wrap |
.flex-wrap-reverse |
Перенос в обратном порядке | flex-wrap: wrap-reverse |
Пример:
<div class="d-flex flex-wrap">
<div class="w-25">1</div><div class="w-25">2</div>...
</div>
| Класс | Описание |
|---|---|
.order-0 – .order-5 |
Приоритет от 0 (высокий) до 5 (низкий) |
.order-first |
Первым (аналог order: -1) |
.order-last |
Последним (аналог order: 6) |
Пример:
<div class="d-flex">
<div class="order-2">Второй</div>
<div class="order-1">Первый</div>
</div>
| Класс | Описание |
|---|---|
.flex-fill |
Элемент растягивается, заполняя пространство |
.flex-grow-1 |
Аналог flex-grow: 1 |
Пример:
<div class="d-flex">
<div class="flex-fill">Занимает всё место</div>
</div>
Все классы работают с breakpoints:
.flex-sm-row, .justify-content-md-center, .align-items-lg-end и т.д.Пример:
<div class="d-flex flex-column flex-md-row">
<!-- На мобильных — вертикально, на десктопе — горизонтально -->
</div>
Bootstrap 5 предоставляет полный контроль над Flexbox через простые классы. Для сложных макетов комбинируйте их с Grid.
Совет: Используйте .gap-* для отступов между элементами:
<div class="d-flex gap-3">
<div>Элемент 1</div>
<div>Элемент 2</div>
</div>
Bootstrap 5 предоставляет удобные классы для управления отступами между блоками (margin и padding).
Вот полная таблица с примерами для горизонтальных и вертикальных отступов.
Bootstrap использует систему {property}{sides}-{size}, где:
property:
m — margin (внешний отступ).p — padding (внутренний отступ).sides:
t — top (верх).b — bottom (низ).s — start (лево для LTR, право для RTL).e — end (право для LTR, лево для RTL).x — горизонтальные (левый + правый).y — вертикальные (верхний + нижний).size:
0 — 0px.1 — 0.25rem (4px).2 — 0.5rem (8px).3 — 1rem (16px).4 — 1.5rem (24px).5 — 3rem (48px).auto — автоматический отступ.| Класс | Описание | Пример |
|---|---|---|
.gap-1 – .gap-5 |
Отступ между flex-элементами (margin) | <div class="d-flex gap-3"> |
.gx-1 – .gx-5 |
Горизонтальный padding (левый + правый) | <div class="row gx-3"> |
.mx-1 – .mx-5 |
Горизонтальный margin (левый + правый) | <div class="mx-auto"> |
.ms-1 – .ms-5 |
Отступ слева (margin-start) | <div class="ms-3"> |
.me-1 – .me-5 |
Отступ справа (margin-end) | <div class="me-2"> |
.px-1 – .px-5 |
Горизонтальный padding (левый + правый) | <div class="px-4"> |
Пример:
<div class="d-flex gap-3"> <!-- Отступы между flex-элементами -->
<div>Блок 1</div>
<div>Блок 2</div>
</div>
<div class="row gx-4"> <!-- Горизонтальные отступы в гриде -->
<div class="col">Колонка 1</div>
<div class="col">Колонка 2</div>
</div>
| Класс | Описание | Пример |
|---|---|---|
.gy-1 – .gy-5 |
Вертикальный padding (верх + низ) | <div class="row gy-3"> |
.my-1 – .my-5 |
Вертикальный margin (верх + низ) | <div class="my-4"> |
.mt-1 – .mt-5 |
Отступ сверху (margin-top) | <div class="mt-2"> |
.mb-1 – .mb-5 |
Отступ снизу (margin-bottom) | <div class="mb-3"> |
.py-1 – .py-5 |
Вертикальный padding (верх + низ) | <div class="py-5"> |
Пример:
<div class="row gy-4"> <!-- Вертикальные отступы в гриде -->
<div class="col-12">Строка 1</div>
<div class="col-12">Строка 2</div>
</div>
<div class="my-5"> <!-- Большой вертикальный margin -->
<p>Контент с отступами сверху и снизу</p>
</div>
| Класс | Описание | Пример |
|---|---|---|
.m-auto |
Автоматический margin (центрирование) | <div class="mx-auto"> |
.p-auto |
Автоматический padding (редко используется) | <div class="p-auto"> |
.m-n1 – m-n5 |
Отрицательный margin | <div class="m-n3"> |
Пример:
<div class="mx-auto" style="width: 200px;"> <!-- Центрирование -->
Этот блок будет по центру
</div>
Все классы поддерживают адаптивность через breakpoints:
sm (≥576px), md (≥768px), lg (≥992px), xl (≥1200px), xxl (≥1400px).Пример:
<div class="mx-3 mx-md-5"> <!-- На мобильных mx-3, на десктопе mx-5 -->
Адаптивный отступ
</div>
✅ Горизонтальные отступы → .gap-*, .gx-*, .mx-*, .ms-*, .me-*.
✅ Вертикальные отступы → .gy-*, .my-*, .mt-*, .mb-*.
✅ Центрирование → .mx-auto.
✅ Адаптивность → .mx-sm-3, .gy-lg-4.
Совет: Для сеток (row/col) лучше использовать .gx-* и .gy-*, а для flex-контейнеров — .gap-*.
| Команда | Описание |
|---|---|
docker ps |
Список работающих контейнеров |
docker ps -a |
Список всех контейнеров (включая остановленные) |
docker images |
Список образов |
docker pull <image> |
Скачать образ (например, docker pull nginx) |
docker run <image> |
Запустить контейнер из образа |
docker run -d <image> |
Запуск в фоновом режиме (detached) |
docker run -p 8080:80 <image> |
Проброс портов (хост:контейнер) |
docker run -v /path:/path <image> |
Подключение тома (volume) |
docker stop <container> |
Остановить контейнер |
docker start <container> |
Запустить остановленный контейнер |
docker restart <container> |
Перезапустить контейнер |
docker rm <container> |
Удалить контейнер |
docker rmi <image> |
Удалить образ |
docker exec -it <container> bash |
Войти в контейнер (интерактивный терминал) |
docker logs <container> |
Просмотр логов контейнера |
docker build -t <name> . |
Собрать образ из Dockerfile |
docker system prune |
Очистка неиспользуемых данных (кэш, остановленные контейнеры) |
docker network ls |
Список сетей |
| Команда | Описание |
|---|---|
docker-compose up |
Запуск сервисов из docker-compose.yml |
docker-compose up -d |
Запуск в фоновом режиме |
docker-compose down |
Остановка и удаление контейнеров |
docker-compose ps |
Список запущенных сервисов |
docker-compose logs |
Просмотр логов |
docker-compose logs <service> |
Логи конкретного сервиса |
docker-compose build |
Пересобрать образы |
docker-compose exec <service> bash |
Войти в контейнер сервиса |
docker-compose restart |
Перезапуск сервисов |
docker-compose pull |
Обновить образы из docker-compose.yml |
-d → Запуск в фоне (detached)-p 80:80 → Проброс портов-v /data:/app → Подключение volume--name my_container → Задать имя контейнеру--rm → Автоудаление контейнера после остановки-e VAR=value → Передача переменных окруженияdocker run -d -p 8080:80 --name my_nginx nginx
docker-compose up -d --build
docker stop $(docker ps -aq)
docker --help и docker-compose --help для справки по командам.
В этом руководстве рассмотрим:
Файл Dockerfile — это инструкция для сборки Docker-образа.
# Базовый образ
FROM ubuntu:22.04
# Установка зависимостей
RUN apt-get update && apt-get install -y curl
# Копирование файлов в образ
COPY ./app /app
# Рабочая директория
WORKDIR /app
# Команда запуска контейнера
CMD ["python", "app.py"]
| Директива | Описание | Пример |
|---|---|---|
FROM |
Базовый образ | FROM python:3.9 |
RUN |
Выполнить команду при сборке | RUN apt-get update |
COPY |
Копировать файлы в образ | COPY ./src /app |
ADD |
Аналог COPY, но с распаковкой архивов и поддержкой URL |
ADD https://example.com/file.tar.gz /tmp |
WORKDIR |
Установить рабочую директорию | WORKDIR /app |
ENV |
Установить переменную окружения | ENV NODE_ENV=production |
ARG |
Переменная, используемая только при сборке | ARG VERSION=1.0 |
EXPOSE |
Объявить порт (не пробрасывает его!) | EXPOSE 80 |
CMD |
Команда по умолчанию при запуске | CMD ["npm", "start"] |
ENTRYPOINT |
Основная команда контейнера | ENTRYPOINT ["/app/start.sh"] |
VOLUME |
Создать точку монтирования | VOLUME /data |
USER |
Задать пользователя | USER nobody |
HEALTHCHECK |
Проверка здоровья контейнера | HEALTHCHECK --interval=30s CMD curl -f http://localhost/health |
Уменьшает размер финального образа.
# 1. Этап сборки
FROM node:18 AS builder
WORKDIR /app
COPY . .
RUN npm install && npm run build
# 2. Финальный образ
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY и ADD инвалидируют кэш, если файлы меняются.RUN кэшируется, если команда не менялась.Совет: Меняющиеся команды (apt-get update) размещайте в начале.
docker build -t myapp:latest .
-t — задать имя и тег (name:tag). — путь к DockerfileARG VERSION=1.0
ENV APP_VERSION=$VERSION
docker build --build-arg VERSION=2.0 -t myapp:2.0 .
docker history myapp:latest
docker save myapp:latest > myapp.tar
docker load < myapp.tar
Исключает файлы из копирования (аналог .gitignore):
node_modules/
*.log
.git/
ENTRYPOINT ["/app/start.sh"]
CMD ["--port=8080"]
Запуск с переопределением:
docker run myapp --port=3000
HEALTHCHECK --interval=5s --timeout=3s \
CMD curl -f http://localhost/ || exit 1
FROM python:3.9
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["uvicorn", "app:app", "--host", "0.0.0.0"]
FROM node:18
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
CMD ["npm", "start"]
FROM golang:1.20 AS builder
WORKDIR /app
COPY . .
RUN go build -o /app/main .
FROM alpine:latest
COPY --from=builder /app/main /main
CMD ["/main"]
| Команда | Описание |
|---|---|
docker buildx build --platform linux/amd64,linux/arm64 -t myapp:multiarch . |
Сборка мультиархитектурного образа |
docker scan myapp:latest |
Проверка на уязвимости (Snyk) |
docker image prune -a |
Удалить неиспользуемые образы |
Итог:
RUN)..dockerignore, чтобы ускорить сборку.python:3.9, а не python:latest).Для очистки кэша Docker можно использовать несколько команд, в зависимости от того, что именно нужно удалить:
docker system prune
docker system prune -a
docker container prune
docker image prune -a
docker builder prune
docker volume prune
Если нужно полностью очистить Docker (все контейнеры, образы, volumes, сети):
docker system prune -a --volumes
⚠️ Будьте осторожны! Эта команда удалит всё, что не используется в данный момент.
docker system df
docker rmi <image_id>
docker rmi $(docker images -q)
Лучший вариант для периодической очистки — docker system prune.
Если нужно освободить максимум места — docker system prune -a --volumes.
🚀 После очистки можно проверить свободное место:
df -h
В современном цифровом мире важно не только создавать качественный контент, но и помогать поисковым системам правильно его интерпретировать. Микроразметка (Schema.org) — это мощный инструмент, который позволяет структурировать данные на сайте, улучшая их отображение в поисковой выдаче. С помощью микроразметки можно выделять рейтинги, цены, события, товары и многое другое, делая сниппеты более информативными и привлекательными для пользователей.
В этом разделе собраны подробные руководства по работе с микроразметкой для разных поисковых систем, включая Google, Яндекс и другие. Вы узнаете, какие форматы поддерживаются, как проверять разметку и какие ошибки стоит избегать.
Оригинал статьи находится здесь
JSON-LD расшифровывается как JavaScript Object Notation for Linked Data, что представляет собой многомерные массивы (представьте себе: список пар атрибут-значение).
Это формат реализации для структурирования данных, аналогичный Microdata и RDFa. Обычно, в контексте SEO, JSON-LD реализуется с использованием словаря Schema.org, совместной инициативы Google, Bing, Yahoo! и Yandex, созданной в 2011 году для создания единого словаря структурированных данных для веба. (Тем не менее, Bing и другие поисковые системы официально не заявили о своей поддержке реализаций JSON-LD для Schema.org.)
JSON-LD считается более простым в реализации, благодаря возможности просто вставить разметку в HTML-документ, в отличие от необходимости оборачивать разметку вокруг HTML-элементов (как это делается с Microdata).
JSON-LD аннотирует элементы на веб-странице, придавая данным структуру. Это позволяет поисковым системам лучше понимать содержимое, устранять неоднозначности и устанавливать связи между сущностями. В результате формируется более упорядоченная и понятная структура данных, что способствует созданию лучше организованного интернета в целом.
Рисунок 1 — Концептуальная визуализация работы JSON-LD: обработка неструктурированного контента в интернете, его аннотирование и структурирование для получения организованного результата.
Таким образом, JSON-LD помогает поисковым системам, таким как Google и Яндекс, точнее интерпретировать информацию на сайте, что может улучшить отображение страницы в результатах поиска (например, с помощью расширенных сниппетов).
Google рекомендует размещать JSON-LD в разделе <head> HTML-документа. Однако допустимо также добавлять его и внутри <body>. Кроме того, Google способен обрабатывать динамически сгенерированные JSON-LD теги в DOM (объектной модели документа).
Коротко:
<head><body>Это означает, что поисковые системы смогут распознать разметку независимо от её расположения в HTML, если она корректно сформирована.
<script type="application/ld+json">
{
...
}
</script>
Когда вы видите JSON-LD, первое, что должно бросаться в глаза — это тег <script>. Атрибут type="application/ld+json" сообщает браузеру: «Эй, здесь JavaScript, содержащий JSON-LD».
{ требуют закрывающих }.{}, он не будет обработан. (Держите его «завёрнутым» в скобки!)Таким образом, правильная структура JSON-LD гарантирует, что поисковые системы смогут корректно прочитать и использовать вашу разметку.
Второй обязательный элемент в JSON-LD разметке — это @context со значением http://schema.org.
Этот параметр сообщает браузеру: «Эй, вот словарь, на который я ссылаюсь — ты можешь найти его по адресу http://schema.org».
Преимущество для SEO-специалиста:
Мы получаем доступ ко всем типам элементов (item types) и их свойствам (item properties), которые определены в Schema.org.
📌 Пример структуры:
{
"@context": "http://schema.org",
"@type": "Article",
"headline": "Пример статьи",
"author": {
"@type": "Person",
"name": "Иван Петров"
}
}
🔍 Обратите внимание:
"http://schema.org"? Она говорит парсеру: «Данные продолжаются, не останавливайся».JSON-LD строго требует правильного синтаксиса, поэтому всегда проверяйте свою разметку перед публикацией!
Третий ключевой элемент JSON-LD разметки — это указание @type. После двоеточия здесь начинается аннотация данных. Параметр @type определяет тип размеченной сущности. Полный список всех доступных типов можно найти в официальной документации: https://schema.org/docs/full.html.
В примере ниже:
{
"@context": "http://schema.org",
"@type": "Person",
"name": "Иван Иванов"
}
@type сообщает: «Эй, здесь используется тип Person (его описание можно найти по адресу http://schema.org/Person)».
Если ввести эту ссылку в браузер, откроется документация Schema.org с:
item properties)При использовании вложенных структур потребуется указывать @type для каждого уровня. Это особенно важно в разметке:
Product)BreadcrumbList)Organization → Employee)Пример вложенности:
{
"@context": "http://schema.org",
"@type": "Product",
"brand": {
"@type": "Brand",
"name": "Nike"
}
}
@type на Schema.org. Например, для Person обязательным может быть name, а для Product — offers.@type или его неверное указание сделает разметку бесполезной для поисковых систем!
Следующий шаг — аннотирование информации о выбранном типе сущности (@type). Допустимые свойства для каждого типа можно найти на соответствующей странице Schema.org.
Каждое свойство в разметке состоит из двух элементов:
Свойство (Item Property)
" ").“ ”) или одинарных (' ') кавычек приведёт к ошибке валидации!@type (указаны в документации Schema.org).Значение (Value)
"пример").42), но допустимо и с ними ("42" — тогда тип данных будет строковым).["значение1", "значение2"]).✅ Корректно:
{
"@type": "Book",
"name": "Война и мир",
"isbn": "978-5-699-12014-7", // Строка в кавычках
"price": 599.99, // Число без кавычек
"author": ["Лев Толстой", "Иван Тургенев"] // Массив значений
}
❌ Ошибки:
“Война и мир” → невалидно.name: Война и мир → синтаксическая ошибка."pageCount": 1225 (если @type не поддерживает это свойство).@type.Запомните:
Правильный синтаксис — это не педантичность, а необходимость. Поисковые системы обрабатывают только безупречно оформленные данные!
Квадратные скобки используются, когда у свойства есть несколько значений.
Несколько значений одного свойства
Например, если у человека два имени:
"givenName": ["Джейсон", "Деруло"]
Здесь скобки говорят: «У этого свойства несколько значений — у Джейсона Деруло два имени».
Ссылки на соцсети (sameAs)
Часто применяется для перечисления профилей в соцсетях:
"sameAs": [
"https://facebook.com/jasonderulo",
"https://twitter.com/jasonderulo",
"https://instagram.com/jasonderulo"
]
Запятая после последнего элемента не ставится
"sameAs": [
"https://facebook.com/jasonderulo", // запятая
"https://twitter.com/jasonderulo" // НЕТ запятой в конце
]
Отсутствие запятой означает конец списка.
Не путать с фигурными скобками {}
Квадратные скобки — только для перечисления однотипных значений, а фигурные — для вложенных объектов (например, адреса или организации).
sameAs для соцсетей).@type множественные значения для конкретного свойства.Пример корректной и некорректной разметки:
✅ Правильно:
"author": ["Лев Толстой", "Фёдор Достоевский"]
❌ Неправильно:
"author": ["Лев Толстой", "Фёдор Достоевский",]
→ Лишняя запятая после последнего элемента.
Для проверки используйте Google’s Structured Data Testing Tool.
Вложенность означает организацию данных слоями, где одни объекты содержат другие объекты. Это можно сравнить с матрешкой, где большая кукла содержит внутри меньшую — так же и данные могут быть структурированы иерархически.
Некоторые свойства относятся только к определенным типам сущностей. Например, в разметке события (Event):
name может означать название события,performer (исполнитель) и venue (место проведения), у которых тоже есть свои name.Без вложенности поисковые системы не поймут, к чему относится каждое свойство.
Начните с основного типа (@type)
Например, Event.
Укажите свойство, требующее вложенности
Например, performer или offers.
Откройте фигурные скобки { } для нового объекта
Внутри укажите:
@type (тип вложенной сущности, например Person или Offer),Закройте вложенный объект
}.} нужна, только если дальше идут другие свойства.Разметка музыкального события:
{
"@context": "http://schema.org",
"@type": "MusicEvent",
"name": "Концерт Jason Aldean",
"performer": { // ← Начало вложенного объекта
"@type": "MusicGroup",
"name": "Jason Aldean",
"sameAs": "https://www.jasonaldean.com"
}, // ← Запятая, потому что дальше есть еще свойства
"location": {
"@type": "Place",
"name": "Мэдисон-Сквер-Гарден",
"address": "Нью-Йорк, США"
} // ← Нет запятой, это последнее свойство
}
✅ Используйте свойства, допустимые для родительского @type (см. Schema.org).
✅ Значение вложенного объекта заключайте в { }.
✅ Указывайте @type для вложенной сущности.
✅ Добавляйте обязательные свойства для вложенного типа (например, price для Offer).
❌ Не ставьте запятую перед } (это вызовет ошибку).
✅ Запятая после }, если дальше идут другие свойства.
Product):
offers (@type: Offer).review (@type: Review).Organization):
@type: PostalAddress),Recipe):
Ошибка → Пропущенный @type во вложенном объекте или лишние/недостающие запятые сделают разметку нерабочей!
Пример ошибки:
❌ Неправильно:
"performer": {
"name": "Jason Aldean" // ← Нет @type!
}
✅ Исправлено:
"performer": {
"@type": "MusicGroup",
"name": "Jason Aldean"
}
Если ваша разметка не проходит валидацию в Google’s Structured Data Testing Tool, проверьте этот список типичных проблем.
"" (прямые двойные кавычки).“” (фигурные кавычки, которые могут появиться при копировании из Word/Excel).✗) слева — он часто указывает на проблему с запятой.Пример:
// ❌ Ошибка (лишняя запятая)
"author": {
"@type": "Person",
"name": "Иван Иванов", // ← Запятая не нужна, это последнее свойство
}
// ✅ Исправлено
"author": {
"@type": "Person",
"name": "Иван Иванов"
}
@type.author не поддерживается для @type: Product.Offer обязательно указание price и priceCurrency.Решение:
@type.Что делать:
“”).Решение:
"").@type.💡 Совет: Для сложных типов (например, Product с Review) используйте пошаговую проверку — сначала базовые свойства, затем вложенные объекты.
Ошибка → Даже одна пропущенная кавычка или запятая может привести к тому, что Google проигнорирует всю разметку!
Создание JSON-LD разметки зависит от вашего уровня знакомства с синтаксисом JSON-LD и словарем Schema.org. Ниже приведен пошаговый процесс для новичков, который поможет вам разобраться в основах и создать эффективную разметку.
@type (например, Product, Article).Начните с базовой структуры:
<script type="application/ld+json">
{
"@context": "http://schema.org",
"@type": "ТипДанных"
}
</script>
<script> обязателен!Product: name, description, image)."".offers в Product) используйте фигурные скобки {} и указывайте @type.Пример для товара:
{
"@context": "http://schema.org",
"@type": "Product",
"name": "Смартфон XYZ",
"image": "https://example.com/image.jpg",
"offers": {
"@type": "Offer",
"price": "299.99",
"priceCurrency": "USD"
}
}
<head> страницы.itemID и itemRef для сложных структур (подробнее в статье Moz).У вас есть вопросы или интересные кейсы по JSON-LD? Делитесь в комментариях!
Итог:
Теперь вы готовы создавать SEO-оптимизированную разметку!
Синтаксис и правила обработки для встраивания RDF через атрибуты
Рекомендация W3C от 17 марта 2015 года
Актуальная версия:
http://www.w3.org/TR/2015/REC-rdfa-core-20150317/
Последняя опубликованная версия:
http://www.w3.org/TR/rdfa-core/
Отчёт о внедрении:
http://www.w3.org/2010/02/rdfa/wiki/CR-ImplementationReport
Предыдущая версия:
http://www.w3.org/TR/2014/PER-rdfa-core-20141216/
Предыдущая рекомендация:
http://www.w3.org/TR/2013/REC-rdfa-core-20130822/
Редакторы:
Английская версия данной спецификации является единственной нормативной. Неофициальные переводы могут быть доступны.
Авторские права: © 2007–2015 W3C® (MIT, ERCIM, Кейо, Бэйхан). Применяются правила W3C об ответственности, товарных знаках и использовании документов.
Современный Интернет в основном состоит из огромного количества документов, созданных с использованием HTML. Эти документы содержат значительный объём структурированных данных, которые в большинстве случаев недоступны для инструментов и приложений. Если издатели смогут выражать эти данные более полно, а инструменты — считывать их, откроются новые возможности для пользователей: структурированные данные можно будет передавать между приложениями и веб-сайтами, а браузеры смогут улучшить пользовательский опыт. Например:
RDFa Core — это спецификация атрибутов для выражения структурированных данных в любом языке разметки. Встроенные данные, уже доступные в языке разметки (например, HTML), часто можно повторно использовать в RDFa, что избавляет издателей от необходимости дублировать информацию в содержимом документа.
Абстрактное представление данных основано на RDF (RDF11-PRIMER), что позволяет издателям создавать собственные словари, расширять чужие и развивать свою терминологию с максимальной совместимостью. Выраженная структура тесно связана с данными, поэтому визуализированную информацию можно копировать вместе с её структурой.
Правила интерпретации данных универсальны и не требуют отдельных инструкций для разных форматов. Это позволяет авторам и издателям данных определять собственные форматы без необходимости обновлять ПО, регистрировать их в централизованном органе или опасаться конфликтов между разными форматами.
RDFa разделяет некоторые цели с микроформатами (MICROFORMATS). Однако если микроформаты задают и синтаксис для встраивания структурированных данных в HTML, и конкретный словарь терминов для каждого микроформата, то RDFa определяет только синтаксис, полагаясь на независимые спецификации терминов (часто называемых словарями или таксономиями). RDFa позволяет свободно комбинировать термины из разных словарей и разработан так, что язык можно анализировать без знания конкретного используемого словаря.
Этот документ представляет собой детальное описание синтаксиса RDFa, предназначенное для:
Для тех, кто ищет введение в RDFa и практические примеры, рекомендуется ознакомиться с RDFA-PRIMER.
Если вы не знакомы ни с RDFa, ни с RDF и просто хотите добавить RDFa в свои документы, то вам может быть полезнее ознакомиться с RDFa Primer, который даёт более простое введение.
Если вы уже знакомы с RDFa и хотите изучить правила обработки (например, для создания собственного процессора RDFa), то наиболее интересным для вас будет раздел «Модель обработки». В нём содержится обзор каждого этапа обработки, а затем более детальные подразделы с описанием отдельных правил.
Если вы не знакомы с RDFa, но знаете RDF, то перед изучением модели обработки полезно прочитать раздел «Обзор синтаксиса», где приведены примеры разметки с использованием RDFa. Примеры помогут легче понять правила обработки.
Если вы не знакомы с RDF, то перед активной работой с RDFa рекомендуется ознакомиться с разделом «Терминология RDF». Хотя RDFa разработан так, чтобы быть простым для авторов (и для его использования не обязательно глубоко разбираться в RDF), разработчикам приложений, обрабатывающих RDFa, понимание RDF необходимо. В интернете есть множество материалов по RDF, а также растущее число инструментов, поддерживающих RDFa. В этом документе содержится лишь минимальный необходимый контекст по RDF, чтобы прояснить цели RDFa.
RDFa — это способ выражения отношений в стиле RDF с помощью простых атрибутов в существующих языках разметки, таких как HTML.
Хотя в данной спецификации упоминаются исключительно IRI, язык-хост (Host Language) может ограничивать синтаксис своих атрибутов подмножеством IRI (например, атрибут @href в HTML5).
Однако, независимо от ограничений валидации в языке-хозяине, процессор RDFa способен обрабатывать полный диапазон IRI.
Данный раздел описывает статус документа на момент его публикации. Другие документы могут заменять текущую версию. Актуальный список публикаций W3C и последнюю редакцию данного технического отчёта можно найти в индексе технических отчётов W3C по адресу: http://www.w3.org/TR/.
Настоящая версия представляет собой редакционную правку Рекомендации, опубликованной 22 августа 2013 года. Указанный документ являлся пересмотренной версией спецификации RDFa Syntax 1.0 [RDFA-SYNTAX]. Между текущей версией и версией 1.0 существует ряд существенных различий, включая:
Более подробный список изменений доступен в разделе Changes (Изменения).
Доступен тестовый набор, который не является исчерпывающим, но может быть полезен как пример использования RDFa.
Документ опубликован Рабочей группой RDFa в качестве Рекомендации. Все замечания и предложения можно направлять по адресу: public-rdfa@w3.org (подписка, архивы). Отзывы приветствуются.
С отчётом о внедрении рабочей группы можно ознакомиться здесь.
Документ был рассмотрен членами W3C, разработчиками программного обеспечения, другими группами W3C и заинтересованными сторонами. Директор W3C утвердил его в качестве официальной Рекомендации. Это стабильный документ, который может использоваться в качестве справочного материала или цитироваться в других документах. Роль W3C заключается в привлечении внимания к спецификации и содействии её широкому внедрению, что способствует улучшению функциональности и совместимости веба.
Документ разработан группой, действующей в соответствии с Патентной политикой W3C от 5 февраля 2004 года. W3C ведёт публичный список патентных заявлений, связанных с результатами работы группы. На этой странице также содержатся инструкции по подаче патентных заявлений. Лица, располагающие информацией о патентах, которые могут содержать существенные пункты (Essential Claims), обязаны раскрыть эту информацию в соответствии с разделом 6 Патентной политики W3C.
Документ регулируется Процессом W3C от 14 октября 2005 года.
(Данный раздел не является нормативным)
Спецификация RDF/XML [RDF-SYNTAX-GRAMMAR] обеспечивает достаточную гибкость для представления всех абстрактных концепций RDF. Однако у неё есть ряд недостатков:
Сложность валидации
Дублирование данных
Контекстная структуризация
Удобство для издателей
@cite для указания источника цитаты.Гибкость вместо «жёсткой» разметки
Снижение нагрузки на разработчиков языков
Для более глубокого изучения рекомендуется ознакомиться с RDFa Primer.
В RDF принято сокращать термины словарей с помощью префиксов и ссылок. Этот механизм подробно описан в разделе Compact URI Expressions. В примерах ниже используются следующие предопределённые префиксы словарей:
В некоторых примерах используются IRI с фрагментными идентификаторами (например, about="#me"), которые ссылаются на сущности внутри текущего документа. Этот подход:
Точная семантика таких IRIs в RDF-графах определена в разделе 7 RDF-SYNTAX-GRAMMAR.
RDFa использует ряд распространённых атрибутов, а также вводит несколько новых. Атрибуты, уже существующие в популярных языках разметки (например, HTML), сохраняют своё исходное значение, хотя в некоторых случаях их синтаксис был немного модифицирован. Например, в (X)HTML нет чёткого способа добавлять новые значения для атрибута @rel; RDFa явно решает эту проблему, разрешая использовать IRI в качестве значений. Также вводятся понятия терминов и “компактных выражений URI” (CURIEs), которые позволяют кратко выражать полные значения IRI. Полный список атрибутов RDFa и их синтаксис приведён в разделе “Атрибуты и синтаксис”.
В (X)HTML авторы могут включать метаданные и отношения, касающиеся текущего документа, используя элементы meta и link (в этих примерах используется XHTML+RDFa [XHTML-RDFA]). Например, автор страницы вместе со ссылками на предыдущую и следующую страницы могут быть выражены следующим образом:
Пример 1
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Страница 7</title>
<meta name="author" content="Марк Бирбек" />
<link rel="prev" href="page6.html" />
<link rel="next" href="page8.html" />
</head>
<body>...</body>
</html>
RDFa использует эту концепцию, расширяя её возможностью работы с различными словарями через полные IRI:
Пример 2
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Моя домашняя страница</title>
<meta property="http://purl.org/dc/terms/creator" content="Марк Бирбек" />
<link rel="http://xmlns.com/foaf/0.1/topic" href="http://www.example.com/#us" />
</head>
<body>...</body>
</html>
Поскольку использование полных IRI, как в примере выше, может быть громоздким, RDFa также разрешает использовать компактные выражения URI (CURIEs), позволяя авторам применять сокращения для ссылок на термины из различных словарей:
Пример 3
<html
xmlns="http://www.w3.org/1999/xhtml"
prefix="foaf: http://xmlns.com/foaf/0.1/
dc: http://purl.org/dc/terms/"
>
<head>
<title>Моя домашняя страница</title>
<meta property="dc:creator" content="Марк Бирбек" />
<link rel="foaf:topic" href="http://www.example.com/#us" />
</head>
<body>...</body>
</html>
RDFa поддерживает использование @rel и @rev на любых элементах. Это становится ещё полезнее с добавлением поддержки различных словарей:
Пример 4
Этот документ распространяется по лицензии
<a prefix="cc: http://creativecommons.org/ns#"
rel="cc:license"
href="http://creativecommons.org/licenses/by-nc-nd/3.0/"
>Creative Commons By-NC-ND License</a>.
RDFa позволяет повторно использовать не только IRI в документе для предоставления метаданных, но и встроенный текст при использовании с @property:
Пример 5
<html
xmlns="http://www.w3.org/1999/xhtml"
prefix="dc: http://purl.org/dc/terms/"
>
<head><title>Моя домашняя страница</title></head>
<body>
<h1 property="dc:title">Моя домашняя страница</h1>
<p>Последнее изменение: 16 сентября 2015</p>
</body>
</html>
Когда отображаемый текст отличается от фактического значения, можно указать точное значение с помощью атрибута @content. Также можно явно указать тип данных через @datatype:
Пример 6
<html
xmlns="http://www.w3.org/1999/xhtml"
prefix="xsd: http://www.w3.org/2001/XMLSchema#
dc: http://purl.org/dc/terms/"
>
<head><title>Моя домашняя страница</title></head>
<body>
<h1 property="dc:title">Моя домашняя страница</h1>
<p>Последнее изменение:
<span property="dc:modified"
content="2015-09-16T16:00:00-05:00"
datatype="xsd:dateTime">16 сентября 2015</span>.
</p>
</body>
</html>
RDFa позволяет описывать метаданные не только для текущего документа, но и для других ресурсов:
Пример 7
<html
xmlns="http://www.w3.org/1999/xhtml"
prefix="bibo: http://purl.org/ontology/bibo/
dc: http://purl.org/dc/terms/"
>
<head>
<title>Книги Марко Пьера Уайта</title>
</head>
<body>
Я считаю, что книга Уайта
«<span about="urn:ISBN:0091808189"
property="dc:title">Кухня столовой</span>»
стоит того, чтобы её приобрести: хотя рецепты сложные,
автор объясняет их очень доступно. Вам также может понравиться
<span about="urn:ISBN:1596913614"
property="dc:description">автобиография Уайта</span>.
</body>
</html>
Для группировки свойств, относящихся к одному объекту, используется атрибут @typeof:
Пример 8
<html
xmlns="http://www.w3.org/1999/xhtml"
prefix="bibo: http://purl.org/ontology/bibo/
dc: http://purl.org/dc/terms/"
>
<head>
<title>Книги Марко Пьера Уайта</title>
</head>
<body>
Я считаю, что книга Уайта
«<span about="urn:ISBN:0091808189" typeof="bibo:Book"
property="dc:title">Кухня столовой</span>»
стоит того, чтобы её приобрести. Также рекомендую
<span about="urn:ISBN:1596913614"
typeof="bibo:Book"
property="dc:description"
>автобиографию Уайта</span>.
</body>
</html>
Для небольших фрагментов разметки иногда удобнее использовать полные IRI:
Пример 9
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Книги Марко Пьера Уайта</title>
</head>
<body>
Книга Уайта
«<span about="urn:ISBN:0091808189"
typeof="http://purl.org/ontology/bibo/Book"
property="http://purl.org/dc/terms/title"
>Кухня столовой</span>»
написана очень доступно. Также обратите внимание на
<span about="urn:ISBN:1596913614"
typeof="http://purl.org/ontology/bibo/Book"
property="http://purl.org/dc/terms/description"
>его автобиографию</span>.
</body>
</html>
Атрибут @vocab позволяет определить словарь по умолчанию для элементов:
Пример 10
<div vocab="http://xmlns.com/foaf/0.1/" about="#me">
Меня зовут <span property="name">Иван Иванов</span>, а мой блог —
<a rel="homepage" href="http://example.org/blog/">«Понимая семантику»</a>.
</div>
Приведённый выше пример (Пример 10) сгенерирует следующие триплеты в формате Turtle:
Пример 11
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
<#me> foaf:name "John Doe" ;
foaf:homepage <http://example.org/blog/> .
В простых случаях атрибут @property может использоваться вместо @rel. Фактически, когда элемент не содержит атрибутов @rel, @datatype или @content, но имеет, например, атрибут @href, эффект от @property аналогичен @rel.
Тот же пример можно переписать следующим образом:
Пример 12
<div vocab="http://xmlns.com/foaf/0.1/" about="#me">
Меня зовут <span property="name">Иван Иванов</span>, а мой блог —
<a property="homepage" href="http://example.org/blog/">«Понимая семантику»</a>.
</div>
Это демонстрирует гибкость RDFa в интерпретации различных вариантов разметки как семантически эквивалентных структур.
Предыдущий раздел иллюстрировал типичную разметку RDFa. Хотя для создания RDFa-разметки глубокое понимание RDF не обязательно, разработчикам систем, обрабатывающих RDF-вывод, необходимо разбираться в концепциях RDF. Далее представлены базовые понятия. Для углублённого изучения обратитесь к:
Структурированные данные в RDFa представляют собой коллекцию утверждений — минимальных единиц информации, оформленных по определённым правилам для упрощения обработки. Даже сложные метаданные можно обрабатывать, разбивая их на такие утверждения.
Альберт родился 14 марта 1879 года в Германской империи. Его фото доступно
по адресу http://en.wikipedia.org/wiki/Image:Albert_Einstein_Head.jpg.
Для машины этот текст неинтерпретируем. В формате утверждений та же информация выглядит так:
Альберт родился 14 марта 1879 года
Альберт родился в Германской империи
Альберт имеет фото http://en.wikipedia.org/...
RDF формализует утверждения как триплеты — структуры из трёх компонентов:
Субъект (Subject)
Предикат (Predicate)
Объект (Object)
<Albert> <wasBornOn> "March 14, 1879" .
<Albert> <wasBornIn> <German_Empire> .
<Albert> <hasPhoto> <http://.../Albert_Einstein_Head.jpg> .
Разбиение сложной информации на управляемые части помогает уточнить данные, но не исключает неоднозначности. Например, о каком именно “Альберте” идёт речь? Если другая система содержит дополнительные факты об “Альберте”, как определить, что они относятся к тому же человеку? Как сопоставить предикаты “родился в” и “место рождения” из разных систем? RDF решает эти проблемы, заменяя расплывчатые термины на ссылки IRI.
Хотя IRI чаще всего используются для идентификации веб-страниц, в RDF они служат уникальными идентификаторами концепций. Например, вместо неоднозначной строки “Альберт” можно использовать IRI из DBPedia:
Пример 15
<http://dbpedia.org/resource/Albert_Einstein>
имеет имя
"Альберт Эйнштейн".
<http://dbpedia.org/resource/Albert_Einstein>
родился
"14 марта 1879".
<http://dbpedia.org/resource/Albert_Einstein>
родился в
<http://dbpedia.org/resource/German_Empire>.
<http://dbpedia.org/resource/Albert_Einstein>
имеет фотографию
<http://.../Albert_Einstein_Head.jpg>.
IRI также используются для однозначного определения объектов (третья часть триплета). Фотография уже имеет IRI, но можно аналогично идентифицировать и “Германскую империю”. Строковые значения (литералы) выделяются кавычками:
Пример 16
<http://dbpedia.org/resource/Albert_Einstein>
<http://xmlns.com/foaf/0.1/name>
"Альберт Эйнштейн".
<http://dbpedia.org/resource/Albert_Einstein>
<http://dbpedia.org/property/dateOfBirth>
"14 марта 1879".
IRI устраняют неоднозначность предикатов, объединяя синонимы (“место рождения”, “birthplace”, “Lieu de naissance”) под одним идентификатором:
Пример 17
<http://dbpedia.org/resource/Albert_Einstein>
<http://dbpedia.org/property/birthPlace>
<http://dbpedia.org/resource/German_Empire>.
Хотя для субъектов и предикатов всегда используются IRI-идентификаторы, объект в триплете может быть как IRI, так и литералом. В примерах имя Эйнштейна представлено простым литералом — строкой без указания типа или языка:
Пример 18
<http://dbpedia.org/resource/Albert_Einstein>
<http://xmlns.com/foaf/0.1/name> "Альберт Эйнштейн".
Для текстов на естественных языках используется тег языка. Например, название Германской империи на разных языках:
Пример 19
<http://dbpedia.org/resource/German_Empire>
rdfs:label "German Empire"@en;
rdfs:label "Deutsches Kaiserreich"@de;
rdfs:label "Германская империя"@ru.
Для специальных значений (даты, числа и т.д.) в RDF предусмотрен механизм указания типа литерала. Типизированный литерал формируется путём добавления IRI типа данных после литерала с использованием символов ^^. Обычно используются типы данных из спецификации XML Schema:
Пример 20
<http://dbpedia.org/resource/Albert_Einstein>
<http://dbpedia.org/property/dateOfBirth>
"1879-03-14"^^<http://www.w3.org/2001/XMLSchema#date>.
Строковые литералы
@"ru")Типизированные значения
"42"^^xsd:integer"2023-05-15"^^xsd:date"true"^^xsd:booleanСтандартные типы данных
xsd:string, xsd:dateTime и др.)# Числовое значение
<http://example.org/product/123>
ex:weight "2.5"^^xsd:decimal.
# Дата и время
ex:event ex:startTime "2023-05-15T19:00:00"^^xsd:dateTime.
# Булево значение
ex:user ex:isActive "true"^^xsd:boolean.
RDF не имеет единого обязательного формата представления триплетов, поскольку ключевыми концепциями являются сами триплеты и использование IRI, а не конкретный синтаксис. Однако существует несколько способов выражения триплетов, включая RDF/XML, Turtle и, конечно, RDFa. В документации часто используется синтаксис Turtle благодаря его компактности.
@prefix dbp: <http://dbpedia.org/property/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
<http://dbpedia.org/resource/Albert_Einstein>
foaf:name "Альберт Эйнштейн" .
<http://dbpedia.org/resource/Albert_Einstein>
dbp:birthPlace <http://dbpedia.org/resource/German_Empire> .
@prefix dbr: <http://dbpedia.org/resource/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
dbr:Albert_Einstein
foaf:name "Альберт Эйнштейн";
dbp:dateOfBirth "1879-03-14"^^xsd:date;
foaf:depiction <http://example.org/einstein.jpg> .
<> - обозначает текущий обрабатываемый документСовокупность триплетов называется графом. Все триплеты, генерируемые согласно этой спецификации, содержатся в выходном графе, создаваемом процессором RDFa.
Для сокращённой записи IRI в разметке RDFa использует механизм CURIEs. Подробное описание - в разделе “Обработка CURIE и IRI”.
Важно: CURIEs используются только в разметке и примерах, в итоговых триплетах всегда присутствуют полные IRI.
При переносе фрагментов разметки между документами (например, через копирование или инструменты) следует учитывать:
Краткое соответствие между RDFa и RDF:
| Компонент RDF | Эквивалент в RDFa |
|---|---|
| Субъект | @about |
| Предикат | @property, @rel, @rev |
| Объект (IRI) | @resource, @href, @src |
| Объект (литерал) | @content или содержимое элемента |
| Тип данных | @datatype |
| Язык | @xml:lang или аналоги |
Пример соответствия:
<div about="#albert"
property="foaf:name"
content="Альберт Эйнштейн"
datatype="xsd:string">
Генерируемый триплет:
<http://example.org/doc#albert>
<http://xmlns.com/foaf/0.1/name>
"Альберт Эйнштейн"^^xsd:string .
Ключевые слова MAY (может), MUST (должен), MUST NOT (не должен), RECOMMENDED (рекомендуется), SHOULD (следует) и SHOULD NOT (не следует) должны интерпретироваться в соответствии с [RFC2119].
В данной спецификации термин выходной граф означает все триплеты, утвержденные документом в соответствии с разделом Модель обработки. Соответствующий требованиям процессор RDFa ДОЛЖЕН предоставить потребляющему приложению единый RDF-граф, содержащий все возможные триплеты, сгенерированные с использованием правил из раздела Модель обработки. Термин граф процессора используется для обозначения всех информационных, предупреждающих и ошибочных триплетов, которые МОГУТ быть сгенерированы процессором RDFa для отчета о своем состоянии. Выходной граф и граф процессора являются отдельными графами, и процессор RDFa НЕ ДОЛЖЕН хранить их в одном графе. Однако процессоры могут разрешать одновременное получение обоих графов; подробности см. в разделе 7.6.1.
Соответствующий требованиям процессор RDFa МОЖЕТ предоставлять дополнительные триплеты, сгенерированные с использованием правил, не описанных здесь, но эти триплеты НЕ ДОЛЖНЫ включаться в выходной граф. (Будут ли эти дополнительные триплеты доступны в одном или нескольких дополнительных RDF-графах, зависит от реализации и здесь не определяется.)
Соответствующий требованиям процессор RDFa ДОЛЖЕН сохранять пробельные символы как в простых литералах, так и в XML-литералах. Однако может случиться так, что архитектура, в которой работает процессор, изменила пробельные символы в документе до того, как он попал в процессор RDFa (например, процессоры [XMLSCHEMA11-1] могут «нормализовать» пробелы в значениях атрибутов — см. раздел 3.1.4). Чтобы обеспечить максимальную согласованность между средами обработки, авторам СЛЕДУЕТ удалять все избыточные пробелы в своих простых и XML-литералах.
Соответствующий требованиям процессор RDFa ДОЛЖЕН анализировать медиатип документа, который он обрабатывает, чтобы определить его язык-хост. Если процессор RDFa не может определить медиатип или не поддерживает его, он ДОЛЖЕН обрабатывать документ так, как если бы его медиатип был application/xml. См. Соответствие документов XML+RDFa. Язык-хост МОЖЕТ определять дополнительные механизмы объявления.
DOCTYPE, расширение файла, корневой элемент, переопределяемый пользовательский параметр) для определения языка-хоста, если медиатип недоступен. Эти механизмы не регламентируются.
Языки-хосты, включающие RDFa, должны соответствовать следующим требованиям:
@href и @src, использовались в соответствующем языке-хостe. Также нет требования, чтобы все обязательные атрибуты были включены в модель содержимого всех элементов. Рабочая группа рекомендует разработчикам языков-хостов обеспечивать включение обязательных атрибутов в модель содержимого элементов, которые часто используются в языке.
<myml:myElement property="license">). Если язык-хост не использует атрибуты «без пространства имен», они ДОЛЖНЫ ссылаться на пространство имен XHTML (http://www.w3.org/1999/xhtml).Данная спецификация не определяет самостоятельный тип документа. Атрибуты здесь предназначены для интеграции в другие языки-хосты (например, HTML+RDFa или XHTML+RDFa). Однако данная спецификация определяет правила обработки для общих XML-документов — то есть документов, доставляемых с медиатипами text/xml или application/xml. Такие документы должны соответствовать всем следующим критериям:
<myml:myElement property="license">).
describedby, license, role), определенные в http://www.w3.org/2011/rdfa-context/rdfa-1.1.dc), определенные в http://www.w3.org/2011/rdfa-context/rdfa-1.1.@xml:base, как определено в [XML10-4e].@xml:lang.aboutSafeCURIEorCURIEorIRI — указывает, о чем именно представлены данные («субъект» в терминологии RDF).contentCDATA-строка — предоставляет машиночитаемое содержимое для литерала («литеральный объект» в терминологии RDF).datatypeTERMorCURIEorAbsIRI — определяет тип данных литерала.href (опциональный)inlistrel или property на том же элементе, должен быть добавлен в список для данного предиката. Значение этого атрибута ДОЛЖНО игнорироваться. Наличие атрибута приводит к созданию списка, если он ещё не существует.prefixNCName ':' ' '+ xsd:anyURI
propertyTERMorCURIEorAbsIRI, разделенных пробелами, — выражает отношения между субъектом и либо ресурсным объектом (если указан), либо текстовым литералом («предикат»).relTERMorCURIEorAbsIRI, разделенных пробелами, — выражает отношения между двумя ресурсами («предикаты» в терминологии RDF).resourceSafeCURIEorCURIEorIRI — выражает связанный ресурс отношения, не предназначенный для навигации (например, не «кликабельная» ссылка) («объект»).revTERMorCURIEorAbsIRI, разделенных пробелами, — выражает обратные отношения между двумя ресурсами («предикаты»).src (опциональный)typeofTERMorCURIEorAbsIRI, разделенных пробелами, — указывает RDF-тип(ы), связываемые с субъектом.vocabПримечание
Во всех случаях возможно использование этих атрибутов без значения (например, @datatype="") или со значением, которое после обработки по правилам CURIE и IRI становится пустым (например, @datatype="[noprefix:foobar]").
Атрибуты RDFa выполняют разные роли в семантически насыщенном документе. Вкратце:
@prefix, @vocab.@about.@property, @rel, @rev.@resource, @href, @src.@datatype, @content, @xml:lang или @lang.@typeof, @inlist.Многие атрибуты принимают список токенов, разделенных пробелами. В данной спецификации пробел определяется как:
whitespace ::= (#x20 | #x9 | #xD | #xA)+
Если атрибут принимает список токенов, разделенных пробелами, процессор RDFa ДОЛЖЕН игнорировать любые ведущие или завершающие пробелы.
Примечание
Рабочая группа в настоящее время анализирует приведённые ниже правила формирования CURIE с учётом недавних замечаний от RDF Working Group и участников RDFa Working Group. Возможны незначительные изменения в правилах в ближайшем будущем, которые могут оказаться обратно несовместимыми. Однако любые такие несовместимости будут ограничены крайними случаями.
Ключевым компонентом RDF является IRI, но такие идентификаторы обычно длинные и неудобные. Поэтому RDFa поддерживает механизм сокращения IRI, называемый компактными URI-выражениями (CURIE).
При раскрытии CURIE ДОЛЖЕН получаться синтаксически корректный IRI ([RFC3987]). Подробнее см. Обработка CURIE и IRI. Лексическое пространство CURIE определяется правилом curie, приведённым ниже. Пространство значений — это множество IRI.
CURIE состоит из двух компонентов: префикса и ссылки. Префикс отделяется от ссылки двоеточием (:). В общем случае префикс можно опустить, создав CURIE, использующий отображение префикса по умолчанию. В RDFa отображение префикса по умолчанию — http://www.w3.org/1999/xhtml/vocab#. Также можно опустить и префикс, и двоеточие, создав CURIE, содержащий только ссылку, использующую отображение без префикса. Данная спецификация НЕ определяет отображение без префикса. Языки-хосты RDFa НЕ ДОЛЖНЫ определять отображение без префикса.
Примечание
Префикс по умолчанию в RDFa не следует путать с пространством имён по умолчанию, определённым в [XML-NAMES]. Процессор RDFa НЕ ДОЛЖЕН обрабатывать объявление пространства имён по умолчанию в XML-NAMES так, как если бы оно устанавливало префикс по умолчанию.
Синтаксис CURIE можно описать следующим образом:
prefix ::= NCName
reference ::= ( ipath-absolute / ipath-rootless / ipath-empty )
[ "?" iquery ] [ "#" ifragment ] (как определено в [[!RFC3987]])
curie ::= [ [ prefix ] ':' ] reference
safe_curie ::= '[' [ [ prefix ] ':' ] reference ']'
safe_curie не является обязательным, даже в ситуациях, когда значение атрибута может быть CURIE или IRI: IRI, использующий схему, не соответствующую текущим отображениям, нельзя спутать с CURIE. Концепция safe_curie сохранена для обратной совместимости.
mailto с http://www.example.com/addresses/. Тогда атрибут @resource со значением mailto:user@example.com может создать триплет с объектом http://www.example.com/addresses/user@example.com. Более того, возможно (хотя и маловероятно), что в будущем появятся схемы, конфликтующие с отображениями префиксов в документе (например, предлагаемая схема widget [WIDGETS-URI]). В обоих случаях такое «перекрытие» не изменит способ обработки IRI другими потребителями, но может привести к неверной интерпретации CURIE автора документа. Рабочая группа считает этот риск минимальным.
При обычной обработке CURIE требуется следующая контекстная информация:
:p).p)._, который используется для генерации уникальных идентификаторов (например, _:p).В RDFa эти значения определяются следующим образом:
_ не указано явно, но, поскольку он используется для генерации blank nodes, его реализация должна быть совместима с определением RDF и правилами из Ссылки на Blank Nodes. Документ НЕ ДОЛЖЕН определять отображение для префикса _. Соответствующий требованиям процессор RDFa ДОЛЖЕН игнорировать любые определения отображений для префикса _.CURIE представляет собой полный IRI. Правила его определения:
(Этот раздел является не нормативным.)
Во многих случаях разработчики языков пытались использовать QNames в качестве механизма расширения [XMLSCHEMA11-2]. QNames действительно позволяют управлять коллекцией имён независимо и могут сопоставлять имена с ресурсами. Однако QNames в большинстве случаев не подходят, потому что:
Пример проблемы: попытка определить коллекцию имён для книг. В QName часть после двоеточия должна быть валидным именем элемента, что делает следующий пример недопустимым:
isbn:0321154991
Это невалидный QName, потому что 0321154991 не является допустимым именем элемента. Однако в данном случае нам и не нужно определять валидное имя элемента — цель использования QName заключалась в ссылке на элемент в частной области видимости (ISBN). Более того, мы хотим, чтобы имена в этой области видимости сопоставлялись с IRI, раскрывающим смысл ISBN. Как видно, определение QNames противоречит этому (довольно распространённому) сценарию.
Данная спецификация решает проблему, вводя CURIE. Синтаксически CURIE являются надмножеством QNames.
Эта спецификация предназначена для разработчиков языков, а не авторов документов. Любой разработчик языка, рассматривающий использование QNames для представления IRI или уникальных токенов, должен вместо этого рассмотреть CURIE:
Сам по себе TEX представляет собой специализированный язык программирования (Кнут не только придумал язык, но и написал для него транслятор, причем таким образом, что он работает совершенно одинаково на самых разных компьютерах), на котором пишутся издательские системы, используемые на практике.
Точнее говоря, каждая издательская система на базе TEX’а представляет собой пакет макроопределений (макропакет) этого языка.
«LaTeX») — это созданная Лесли Лэмпортом (Leslie Lamport) издательская система на базе TEX’а.
Официальное описание пакета по адресу: https://ctan.org/pkg/tcolorbox
tcolorbox – Цветные рамки для примеров и теорем в LaTeX и т. д.
Этот пакет предоставляет среду для цветных текстовых рамок с заголовком. По желанию, такая рамка может быть разделена на верхнюю и нижнюю части; таким образом, пакет может быть использован для настройки примеров LaTeX, где одна часть рамки отображает исходный код, а другая часть показывает результат. Другой распространенный случай использования – настройка теорем. Пакет поддерживает сохранение и повторное использование исходного кода и частей текста.
Пакет зависит от пакетов pgf, verbatim, environ и etoolbox.
\documentclass[a4paper]{article}
\usepackage{tikz}
\usepackage[all]{tcolorbox}
\usepackage{incgraph}
\usepackage{lipsum}
\usepackage{accsupp}
\begin{document}
\begin{inctext}
\begin{tikzpicture}
\definecolorseries{boxcol}{rgb}{last}{blue}{red}
\resetcolorseries[28]{boxcol}
\coordinate (A) at (0,0); \coordinate (B) at (21,29.7);
\path[use as bounding box] (A) rectangle coordinate (C) (B);
\node[transform shape,xslant=0.7,rotate=-10,xshift=0cm] at (C) {%
\BeginAccSupp{method=plain,ActualText={}}%
\begin{tcbraster}[raster columns=4,title=tcolorbox,
fonttitle=\small\bfseries,raster width=50cm]
\foreach \b in {1,...,28} {\begin{tcolorbox}[enhanced,
watermark text=\thetcbrasternum,
colframe=boxcol!30!white,
colback=boxcol!25!white!30!white,
colbacktitle=boxcol!!+!50!black!30!white,
colupper=black!30!white]\lipsum[2]\end{tcolorbox}}
\end{tcbraster}%
\EndAccSupp{}%
};
\node at (C) {%
\begin{tcbitemize}[title=tcolorbox ,fonttitle=\small\bfseries,
enhanced jigsaw,opacityback=0.5,opacitybacktitle=0.75,
halign=center,valign=center,arc=5mm,
raster width=16cm,raster column skip=8mm,raster halign=center,
raster force size=false,
raster row 1/.style={height=6cm},
raster row 2/.style={width=6cm,height=4cm},
raster column 1/.style={flushright title,
frame style={left color=yellow!50!black,right color=green!50!black},
title style={left color=yellow!50!blue,right color=blue!50!green!50!black},
interior style={left color=yellow!70,right color=green!70},
underlay={\draw[line width=6mm,line cap=round,black!60]
([shift={(0.4,-0.15)}]frame.north east)
--([shift={(0.4,0.15)}]frame.south east); }},
raster column 2/.style={
frame style={left color=green!50!black,right color=yellow!50!black},
title style={left color=blue!50!green!50!black,right color=yellow!50!blue},
interior style={left color=green!70,right color=yellow!70}}]
\tcbitem[fontupper=\Huge\bfseries,sharp corners=east,
underlay={\draw[line width=6mm,line cap=round,black!60]
([shift={(0.4,0.30)}]frame.north east)-- coordinate(A) +(0,0.2);
\draw[line width=1mm,line cap=round,black!60](A) -- +(30:1.5cm);
\draw[line width=1mm,line cap=round,black!60](A) -- +(150:1.5cm);}]
tcolorbox
\tcbitem[fontupper=\large\bfseries,sharp corners=west]
Manual for
\tcbitem[sharp corners=northeast]
\tcbitem[sharp corners=northwest] Thomas F.~Sturm
\end{tcbitemize}%
};
\end{tikzpicture}
\end{inctext}
\end{document}
Пакет принимает ключи опций в синтаксисе “ключ-значение”. В качестве альтернативы вы можете использовать эти ключи позже в преамбуле с помощью команды \tcbuselibrary.
\tcbuselibrary{⟨key list⟩}
Вот перевод на русский язык с примерами, обернутыми в latex:
Следующие ключи используются внутри \tcbuselibrary соответственно \usepackage без ключа:
tree path /tcb/library/.
/tcb/library/skins (LIB skins)
Загружает пакет tikzfill.image → CTAN и предоставляет дополнительные стили (skins) для внешнего вида цветных коробок;
\tcbuselibrary{skins}
/tcb/library/vignette (LIB vignette)
Предоставляет код для более орнаментального оформления;
\tcbuselibrary{vignette}
/tcb/library/raster (LIB raster)
Предоставляет дополнительные макросы и опции для наборки нескольких коробок, расположенных в виде растровой сетки;
\tcbuselibrary{raster}
/tcb/library/listings (LIB listings)
Загружает пакет listings → CTAN и предоставляет дополнительные макросы для наборки листингов
\tcbuselibrary{listings}
/tcb/library/listingsutf8 (LIB listingsutf8)
Загружает пакеты listings → CTAN и listingsutf8 для поддержки UTF-8.
\tcbuselibrary{listingsutf8}
/tcb/library/minted (LIB minted)
Загружает пакет minted → CTAN для наборки листингов с помощью инструмента Pygments;
\tcbuselibrary{minted}
/tcb/library/theorems (LIB theorems)
Предоставляет дополнительные макросы для наборки теорем
\tcbuselibrary{theorems}
/tcb/library/breakable (LIB breakable)
Предоставляет поддержку автоматического разбиения коробок с одной страницы на другую;
\tcbuselibrary{breakable}
/tcb/library/magazine (LIB magazine)
Предоставляет поддержку для хранения частей разбитых коробок для последующего использования или в измененном порядке;
\tcbuselibrary{magazine}
/tcb/library/poster (LIB poster)
Предоставляет поддержку для создания постеров;
\tcbuselibrary{poster}
/tcb/library/fitting (LIB fitting)
Предоставляет поддержку адаптации размера шрифта содержимого коробки к размерам коробки;
\tcbuselibrary{fitting}
/tcb/library/hooks (LIB hooks)
Расширяет несколько опций до “hookable” ключей;
\tcbuselibrary{hooks}
/tcb/library/xparse (LIB xparse)
Загружает пакет xparse → CTAN и считается устаревшей библиотекой, сохраненной для совместимости;
\tcbuselibrary{xparse}
/tcb/library/external (LIB external)
Предоставляет поддержку экстернализации для фрагментов документов, которые могут быть самостоятельными;
\tcbuselibrary{external}
/tcb/library/documentation (LIB documentation)
Предоставляет дополнительные макросы для наборки документации LATEX
\begin{tcolorbox}
This is a \textbf{tcolorbox}.
\end{tcolorbox}
\begin{tcolorbox}[colback=red!5!white,colframe=red!75!black,title=My nice heading]
This is another \textbf{tcolorbox}.
\tcblower %разделитель бокса
Here, you see the lower part of the box.
\end{tcolorbox}
Используется внутри tcolorbox для разделения верхней части коробки от необязательной нижней части коробки. Верхняя и нижняя части рассматриваются как отдельные функциональные единицы. Если вы хотите просто провести линию, используйте \tcbline.
Пример использования:
\begin{tcolorbox}
Верхняя часть коробки.
\tcblower
Нижняя часть коробки.
\end{tcolorbox}
Устанавливает параметры для всех последующих tcolorbox внутри текущей группы TEX. По умолчанию это не применяется к вложенным коробкам.
Например, цвета коробок могут быть определены для всего документа следующим образом:
\tcbset{colback=red!5!white, colframe=red!75!black}
После этого все последующие tcolorbox будут использовать указанные цвета фона и рамки.
Устанавливает параметры для всех последующих tcolorbox внутри текущей группы TEX. В отличие от \tcbset, это также применяется к вложенным коробкам. Технически, параметры ⟨options⟩ добавляются к значениям по умолчанию для каждой tcolorbox, которые применяются с помощью /tcb/reset
Не следует использовать этот макрос, если вы не уверены, что хотите применять ⟨options⟩ также для коробок в коробках (в коробках в коробках и т.д.).
Пример использования:
\tcbset{colback=green!10!white}
\tcbsetforeverylayer{colframe=red!75!black}
В этом примере все последующие tcolorbox будут иметь зеленый фон и красную рамку, включая вложенные коробки.
Создает цветную коробку, которая подгоняется по ширине к заданному содержимому ⟨box content⟩. В принципе, большинство ⟨options⟩ для tcolorbox могут быть использованы для \tcbox с некоторыми ограничениями. \tcbox не может иметь нижнюю часть и не может быть разбита.
Пример использования:
\tcbox[colback=blue!10!white, colframe=blue!75!black]{Это содержимое цветной коробки.}
В этом примере создается цветная коробка с заданным фоном и рамкой, подгоняющаяся по ширине к тексту внутри.
Создает цветную коробку на основе \tcbox, которая подгоняется по ширине к заданному содержимому ⟨verbatim box content⟩. Основная \tcbox стилизована с помощью /tcb/verbatim плюс заданные ⟨options⟩. Разница с \tcbox заключается в том, что ⟨verbatim box content⟩ интерпретируется как текст без форматирования. Поэтому \tcboxverb действует аналогично \verb.
Пример использования:
\tcboxverb[colback=yellow!10!white, colframe=yellow!75!black]{\texttt{Это содержимое в verbatim-формате.}}
В этом примере создается цветная коробка с заданным фоном и рамкой, подгоняющаяся по ширине к тексту, который интерпретируется без форматирования.
Создает новое окружение ⟨name⟩ на основе tcolorbox. В принципе, \newtcolorbox работает как \newenvironment. Это означает, что новое окружение ⟨name⟩ может принимать ⟨number⟩ аргументов, где ⟨default⟩ — это значение по умолчанию для необязательного первого аргумента. Параметры ⟨options⟩ передаются основной tcolorbox. Обратите внимание, что /tcb/savedelimiter автоматически устанавливается на заданное ⟨name⟩. Параметры ⟨init options⟩ позволяют настроить автоматическую нумерацию.
Пример использования:
\newtcolorbox[auto numbered]{mybox}[2][default value]{colback=blue!5!white, colframe=blue!75!black, title=Заголовок}
В этом примере создается новое окружение mybox, которое может принимать два аргумента, где первый аргумент имеет значение по умолчанию “default value”. Параметры для tcolorbox задают цвет фона, цвет рамки и заголовок.
\newtcolorbox{mybox}{colback=red!5!white,
colframe=red!75!black}
\begin{mybox}
This is my own box.
\end{mybox}
\newtcolorbox{mybox}[1]{colback=red!5!white,
colframe=red!75!black,fonttitle=\bfseries,
title={#1}}
\begin{mybox}{Hello there}
This is my own box with a mandatory title.
\end{mybox}
\newtcolorbox{mybox}[2][]{colback=red!5!white,
colframe=red!75!black,fonttitle=\bfseries,
colbacktitle=red!85!black,enhanced,
attach boxed title to top center={yshift=-2mm},
title={#2},#1}
\begin{mybox}[colback=yellow]{Hello there}
This is my own box with a mandatory title
and options.
\end{mybox}
\newtcolorbox[auto counter,number within=section]{pabox}[2][]{%
colback=red!5!white,colframe=red!75!black,fonttitle=\bfseries,
title=Examp.~\thetcbcounter: #2,#1}
\begin{pabox}[colback=yellow]{Hello there}
This is my own box with a mandatory
numbered title and options.
\end{pabox}
Работает аналогично \newtcolorbox, но основан на \renewenvironment вместо \newenvironment. Существующее окружение переопределяется.
Пример использования:
\renewtcolorbox[auto numbered]{mybox}[2][default value]{colback=green!5!white, colframe=green!75!black, title=Обновленный заголовок}
В этом примере существующее окружение mybox переопределяется с новыми параметрами, включая цвет фона, цвет рамки и заголовок. Теперь это окружение будет использовать новые настройки при каждом вызове.
Создает новое окружение ⟨name⟩ на основе tcolorbox. В принципе, \NewTColorBox работает как \NewDocumentEnvironment. Это означает, что новое окружение ⟨name⟩ создается с заданным аргументом LATEX3 ⟨specification⟩. Если окружение с именем ⟨name⟩ уже было определено, будет выдана ошибка. Параметры ⟨options⟩ передаются основной tcolorbox. Обратите внимание, что /tcb/savedelimiter автоматически устанавливается на заданное ⟨name⟩. Параметры ⟨init options⟩ позволяют настроить автоматическую нумерацию.
Пример использования:
% counter из предыдущего примера pabox продолжается в этом стиле
\NewTColorBox[use counter from=pabox]{mybox}{ O{red} m d"" !O{} }
{enhanced,colframe=#1!75!black,colback=#1!5!white,
fonttitle=\bfseries,title={\thetcbcounter~#2},
IfValueT={#3}{watermark text={#3}},#4}
\begin{mybox}{My title}
This is a tcolorbox.
\end{mybox}
\begin{mybox}[blue]{My title}
This is a tcolorbox.
\end{mybox}
\begin{mybox}[green]{My title}"My Watermark"
This is a tcolorbox.
\end{mybox}
\begin{mybox}[yellow]{My title}[colbacktitle=yellow!50!white,coltitle=black]
This is a tcolorbox.
\end{mybox}
\begin{mybox}[purple]{My title}"All together"[coltitle=yellow]
This is a tcolorbox.
\end{mybox}
В этом примере создается новое окружение mynewbox с заданной спецификацией и параметрами, включая цвет фона, цвет рамки и заголовок. Если окружение с именем mynewbox уже существует, будет выдана ошибка.
Работает аналогично \NewTColorBox , но основан на \RenewDocumentEnvironment вместо \NewDocumentEnvironment. Существующее окружение переопределяется.
Пример использования:
\RenewTColorBox[auto numbered]{mybox}{m}{colback=red!10!white, colframe=red!75!black, title=Обновленный заголовок}
В этом примере существующее окружение mybox переопределяется с новыми параметрами.
Работает аналогично \NewTColorBox, но основан на \ProvideDocumentEnvironment вместо \NewDocumentEnvironment. Окружение ⟨name⟩ создается только в том случае, если оно еще не определено.
Пример использования:
\ProvideTColorBox[auto numbered]{mybox}{m}{colback=green!10!white, colframe=green!75!black, title=Предоставленный заголовок}
В этом примере окружение mybox будет создано только если оно еще не существует.
Работает аналогично \NewTColorBox, но основан на \DeclareDocumentEnvironment вместо \NewDocumentEnvironment. Новое окружение всегда создается, независимо от того, существует ли уже окружение с тем же именем.
Пример использования:
\DeclareTColorBox[auto numbered]{mybox}{m}{colback=blue!10!white, colframe=blue!75!black, title=Объявленный заголовок}
В этом примере окружение mybox будет создано, даже если оно уже существует, что может привести к ошибке.
Создает новую команду \⟨name⟩ на основе tcolorbox. В отличие от \NewTColorBox, также указывается ⟨content⟩ для tcolorbox. В принципе, \NewTotalTColorBox работает как \NewDocumentCommand. Это означает, что новая команда \⟨name⟩ создается с заданным аргументом LATEX3 ⟨specification⟩. Если \⟨name⟩ уже было определено, будет выдана ошибка. Параметры ⟨options⟩ передаются основной tcolorbox, которая заполняется указанным ⟨content⟩. Обратите внимание, что /tcb/savedelimiter автоматически устанавливается на заданное \⟨name⟩. Также обратите внимание, что /tcb/saveto, /tcb/savelowerto и /tcb/redirectlowerto не могут использоваться с \NewTotalTColorBox и аналогичными командами. Параметры ⟨init options⟩ позволяют настроить автоматическую нумерацию.
Пример использования:
\NewTotalTColorBox{\diabox}{ O{} v m }
{ bicolor,nobeforeafter,equal height group=diabox,width=5.7cm,
fonttitle=\bfseries\ttfamily,adjusted title={#2},center title,
colframe=blue!20!black,leftupper=0mm,rightupper=0mm,colback=black!75!white,#1}
{ \tikz\path[fill zoom image={#2}] (0,0) rectangle (\linewidth,4cm);%
\tcblower#3}
\diabox{blueshade.png}{Created with |GIMP|.\\\url{http://www.gimp.org}}
\diabox{goldshade.png}{Created with |GIMP|.\\\url{http://www.gimp.org}}
В этом примере создается новая команда mytotalbox, которая принимает содержимое и параметры, включая цвет фона и цвет рамки. Если команда с именем mytotalbox уже существует, будет выдана ошибка.
Работает аналогично \NewTotalTColorBox, но основан на \RenewDocumentCommand вместо \NewDocumentCommand. Существующая команда переопределяется.
Пример использования:
\RenewTotalTColorBox[auto numbered]{mytotalbox}{m}{colback=purple!10!white, colframe=purple!75!black}{Обновленное содержимое команды.}
В этом примере существующая команда mytotalbox переопределяется с новыми параметрами и содержимым.
Работает аналогично \NewTotalTColorBox, но основан на \ProvideDocumentCommand вместо \NewDocumentCommand. Команда \⟨name⟩ создается только в том случае, если она еще не определена.
Пример использования:
\ProvideTotalTColorBox[auto numbered]{mytotalbox}{m}{colback=teal!10!white, colframe=teal!75!black}{Предоставленное содержимое команды.}
В этом примере команда mytotalbox будет создана только если она еще не существует.
Работает аналогично \NewTotalTColorBox, но основан на \DeclareDocumentCommand вместо \NewDocumentCommand. Новая команда всегда создается, независимо от того, существует ли уже команда с тем же именем.
Пример использования:
\DeclareTotalTColorBox[auto numbered]{mytotalbox}{m}{colback=cyan!10!white, colframe=cyan!75!black}{Объявленное содержимое команды.}
В этом примере команда mytotalbox будет создана, даже если она уже существует, что может привести к ошибке.
Создает новый макрос \⟨name⟩ на основе \tcbox. В принципе, \newtcbox работает как \newcommand. Новый макрос \⟨name⟩ может принимать ⟨number⟩+1 аргументов (до 10), где ⟨default⟩ — это значение по умолчанию для необязательного первого аргумента. В дополнение к аргументам ⟨number⟩ есть автоматический последний (обязательный) аргумент \⟨name⟩, который принимает содержимое коробки. Параметры ⟨options⟩ передаются основной tcbox. Параметры ⟨init options⟩ позволяют настроить автоматическую нумерацию.
Пример использования:
\newtcbox{\mybox}[1][red]{on line,
arc=0pt,outer arc=0pt,colback=#1!10!white,colframe=#1!50!black,
boxsep=0pt,left=1pt,right=1pt,top=2pt,bottom=2pt,
boxrule=0pt,bottomrule=1pt,toprule=1pt}
\newtcbox{\xmybox}[1][red]{on line,
arc=7pt,colback=#1!10!white,colframe=#1!50!black,
before upper={\rule[-3pt]{0pt}{10pt}},boxrule=1pt,
boxsep=0pt,left=6pt,right=6pt,top=2pt,bottom=2pt}
The \mybox[green]{quick} brown \mybox{fox} \mybox[blue]{jumps} over the \mybox[green]{lazy} \mybox{dog}.\par
The \xmybox[green]{quick} brown \xmybox{fox} \xmybox[blue]{jumps} over the \xmybox[green]{lazy} \xmybox{dog}.
В этом примере создается новый макрос mytcbox, который может принимать два аргумента, где первый аргумент имеет значение по умолчанию “default value”. Параметры для tcbox задают цвет фона и цвет рамки.
Работает аналогично \newtcbox, но основан на \renewcommand вместо \newcommand. Существующий макрос переопределяется.
Пример использования:
\renewtcbox[auto numbered]{mytcbox}[2][default value]{colback=blue!10!white, colframe=blue!75!black}
В этом примере существующий макрос mytcbox переопределяется с новыми параметрами и значением по умолчанию для первого аргумента.
Создает новую команду \⟨name⟩ на основе \tcbox. В принципе, \NewTCBox работает как \NewDocumentCommand. Это означает, что новая команда \⟨name⟩ создается с заданным аргументом LATEX3 ⟨specification⟩. В дополнение к аргументу ⟨specification⟩ есть автоматический последний (обязательный) аргумент \⟨name⟩, который принимает содержимое коробки. Таким образом, \⟨name⟩ может иметь до 10 аргументов в сумме. Если \⟨name⟩ уже было определено, будет выдана ошибка. Параметры ⟨options⟩ передаются основной \tcbox. Обратите внимание, что /tcb/savedelimiter автоматически устанавливается на заданное \⟨name⟩. Параметры ⟨init options⟩ позволяют настроить автоматическую нумерацию.
Пример использования:
\NewTCBox[auto numbered]{mynewtcbox}{m}{colback=green!10!white, colframe=green!75!black}
В этом примере создается новая команда mynewtcbox, которая принимает спецификацию и параметры, включая цвет фона и цвет рамки. Если команда с именем mynewtcbox уже существует, будет выдана ошибка.
Работает аналогично \NewTCBox, но основан на \RenewDocumentCommand вместо \NewDocumentCommand. Существующая команда переопределяется.
Пример использования:
\RenewTCBox[auto numbered]{mytcbox}{m}{colback=red!10!white, colframe=red!75!black}
В этом примере существующая команда mytcbox переопределяется с новыми параметрами.
Работает аналогично \NewTCBox, но основан на \ProvideDocumentCommand вместо \NewDocumentCommand. Команда \⟨name⟩ создается только в том случае, если она еще не определена.
Пример использования:
\ProvideTCBox[auto numbered]{mytcbox}{m}{colback=green!10!white, colframe=green!75!black}
В этом примере команда mytcbox будет создана только если она еще не существует.
Работает аналогично \NewTCBox, но основан на \DeclareDocumentCommand вместо \NewDocumentCommand. Новая команда всегда создается, независимо от того, существует ли уже команда с тем же именем.
Пример использования:
\DeclareTCBox[auto numbered]{mytcbox}{m}{colback=blue!10!white, colframe=blue!75!black}
В этом примере команда mytcbox будет создана, даже если она уже существует, что может привести к ошибке.
Создает новую команду \⟨name⟩ на основе \tcbox. В отличие от \NewTCBox, также указывается ⟨content⟩ для tcbox. В принципе, \NewTotalTCBox работает как \NewDocumentCommand. Это означает, что новая команда \⟨name⟩ создается с заданным аргументом LATEX3 ⟨specification⟩. Если \⟨name⟩ уже было определено, будет выдана ошибка. Параметры ⟨options⟩ передаются основной \tcbox, которая заполняется указанным ⟨content⟩. Обратите внимание, что /tcb/savedelimiter автоматически устанавливается на заданное \⟨name⟩. Параметры ⟨init options⟩ позволяют настроить автоматическую нумерацию.
Пример использования:
\NewTotalTCBox[auto numbered]{mytotaltcbox}{m}{colback=yellow!10!white, colframe=yellow!75!black}{Это содержимое новой команды.}
В этом примере создается новая команда mytotaltcbox, которая принимает спецификацию и параметры, включая цвет фона и цвет рамки, а также содержимое коробки. Если команда с именем mytotaltcbox уже существует, будет выдана ошибка.
\NewTotalTCBox{\myverb}{ O{red} v !O{} }
{ fontupper=\ttfamily,nobeforeafter,tcbox raise base,arc=0pt,outer arc=0pt,
top=0pt,bottom=0pt,left=0mm,right=0mm,
leftrule=0pt,rightrule=0pt,toprule=0.3mm,bottomrule=0.3mm,boxsep=0.5mm,
colback=#1!10!white,colframe=#1!50!black,#3}{#2}
To set a word \textbf{bold} in \myverb{\LaTeX}, use
\myverb[green]{\textbf{bold}}. Alternatively, write
\myverb[yellow]{{\bfseries bold}}.
In \myverb[blue]{\LaTeX}[enhanced,fuzzy halo], other font settings are
done in the same way, e.\,g. \myverb{\textit}, \myverb{\itshape}\\
or \myverb[brown]{\texttt}, \myverb[brown]{\ttfamily}.
% \usepackage{listings} or \tcbuselibrary{listings}
\NewTotalTCBox{\commandbox}{ s v }
{verbatim,colupper=white,colback=black!75!white,colframe=black}
{\IfBooleanT{#1}{\textcolor{red}{\ttfamily\bfseries > }}%
\lstinline[language=command.com,keywordstyle=\color{blue!35!white}\bfseries]^#2^}
\commandbox*{cd "My Documents"} changes to directory \commandbox{My Documents}.
\commandbox*{dir /A} lists the directory content.
\commandbox*{copy example.txt d:\target} copies \commandbox{example.txt} to
\commandbox{d:\target}.
Работает аналогично \NewTotalTCBox, но основан на \RenewDocumentCommand вместо \NewDocumentCommand. Существующая команда переопределяется.
Пример использования:
\RenewTotalTCBox[auto numbered]{mytotaltcbox}{m}{colback=purple!10!white, colframe=purple!75!black}{Обновленное содержимое команды.}
В этом примере существующая команда mytotaltcbox переопределяется с новыми параметрами и содержимым.
\ProvideTotalTCBox[⟨init options⟩]{\⟨name⟩}{⟨specification⟩}{⟨options⟩}{⟨content⟩}
Работает аналогично \NewTotalTCBox, но основан на \ProvideDocumentCommand вместо \NewDocumentCommand. Команда \⟨name⟩ создается только в том случае, если она еще не определена.
Пример использования:
\ProvideTotalTCBox[auto numbered]{mytotaltcbox}{m}{colback=teal!10!white, colframe=teal!75!black}{Предоставленное содержимое команды.}
В этом примере команда mytotaltcbox будет создана только если она еще не существует.
\DeclareTotalTCBox[⟨init options⟩]{\⟨name⟩}{⟨specification⟩}{⟨options⟩}{⟨content⟩}
Работает аналогично \NewTotalTCBox, но основан на \DeclareDocumentCommand вместо \NewDocumentCommand. Новая команда всегда создается, независимо от того, существует ли уже команда с тем же именем.
Пример использования:
\DeclareTotalTCBox[auto numbered]{mytotaltcbox}{m}{colback=cyan!10!white, colframe=cyan!75!black}{Объявленное содержимое команды.}
В этом примере команда mytotaltcbox будет создана, даже если она уже существует, что может привести к ошибке.
\tcolorboxenvironment{⟨name⟩}{⟨options⟩}
Существующая среда ⟨name⟩ переопределяется, чтобы быть обернутой внутри tcolorbox с заданными ⟨options⟩.
% tcbuselibrary{skins}
\newenvironment{myitemize}{%
\begin{itemize}}{\end{itemize}}
\tcolorboxenvironment{myitemize}{blanker,
before skip=6pt,after skip=6pt,
borderline west={3mm}{0pt}{red}}
Some text.
\begin{myitemize}
\item Alpha
\item Beta
\item Gamma
\end{myitemize}
More text.
| Ключ | Синтаксис | Назначение |
|---|---|---|
/tcb/ |
Префикс для ключей | Обозначение пространства имен tcolorbox. |
add to height |
add to height=<length> |
Добавляет фиксированную высоту к общему размеру бокса. |
add to list |
add to list=<text> |
Регистрирует бокс в списке (например, для оглавления). |
add to natural height |
add to natural height=<length> |
Увеличивает “естественную” высоту бокса (без учета boxsep и boxrule). |
add to width |
add to width=<length> |
Добавляет фиксированную ширину к общему размеру бокса. |
adjust text |
adjust text=<options> |
Настраивает параметры текста (например, hyphenation). |
adjusted title |
adjusted title=<text> |
Заголовок с динамическим форматированием (например, для нумерации). |
adjusted title after break |
adjusted title after break=<text> |
Заголовок после разрыва многостраничного бокса. |
after |
after={<code>} |
Код TikZ/LaTeX, выполняемый после рисования бокса. |
after app |
after app={<code>} |
Код, выполняемый после добавления бокса в приложении. |
after doc body |
after doc body={<code>} |
Код, вставляемый после основного содержимого документа. |
after doc body command |
after doc body command=<command> |
Команда LaTeX, выполняемая после тела документа. |
after doc body environment |
after doc body env=<env> |
Окружение LaTeX, добавляемое после тела документа. |
after doc body key |
after doc body key=<key> |
Ключ TikZ, применяемый после тела документа. |
after doc body path |
after doc body path=<path> |
Путь TikZ, рисуемый после тела документа. |
after float |
after float={<code>} |
Код, выполняемый после плавающего бокса (float). |
after float app |
after float app={<code>} |
Аналог after float для приложений. |
after float pre |
after float pre={<code>} |
Код перед плавающим боксом (для приложений). |
after lower |
after lower={<code>} |
Код, выполняемый после нижней части (lower part) бокса. |
after lower app |
after lower app={<code>} |
Аналог after lower для приложений. |
after lower pre |
after lower pre={<code>} |
Код перед нижней частью (для приложений). |
after lower* |
after lower*={<code>} |
Код после нижней части (без группировки в {}). |
after pre |
after pre={<code>} |
Код перед завершением бокса (для приложений). |
after skip |
after skip=<length> |
Вертикальный отступ после бокса. |
after skip balanced |
after skip balanced=<length> |
Сбалансированный отступ (учитывает разрывы страниц). |
after title |
after title={<code>} |
Код, выполняемый после заголовка. |
after title app |
after title app={<code>} |
Аналог after title для приложений. |
after title pre |
after title pre={<code>} |
Код перед заголовком (для приложений). |
after title* |
after title*={<code>} |
Код после заголовка (без группировки в {}). |
after upper |
after upper={<code>} |
Код, выполняемый после верхней части (upper part) бокса. |
after upper app |
after upper app={<code>} |
Аналог after upper для приложений. |
after upper pre |
after upper pre={<code>} |
Код перед верхней частью (для приложений). |
after upper* |
after upper*={<code>} |
Код после верхней части (без группировки в {}). |
alert |
alert |
Стиль для выделенных боксов (например, в Beamer). |
alt |
alt=<text> |
Альтернативный текст (для PDF-тегов или подписей). |
ams align |
ams align |
Включает окружение align из amsmath в основной части. |
ams align lower |
ams align lower |
Аналог ams align для нижней части. |
ams align upper |
ams align upper |
Аналог ams align для верхней части. |
ams align* |
ams align* |
Версия align* (без нумерации). |
ams equation |
ams equation |
Включает окружение equation из amsmath. |
ams equation lower |
ams equation lower |
Аналог ams equation для нижней части. |
ams equation upper |
ams equation upper |
Аналог ams equation для верхней части. |
ams gather |
ams gather |
Включает окружение gather из amsmath. |
ams nodisplayskip |
ams nodisplayskip |
Убирает отступы вокруг формул amsmath. |
arc |
arc=<length> |
Радиус скругления углов. |
arc is angular |
arc is angular |
Делает скругление углов “острым” (стиль TikZ). |
arc is curved |
arc is curved |
Делает скругление плавным (по умолчанию). |
at begin tikz |
at begin tikz={<code>} |
Код TikZ, выполняемый в начале рисования. |
attach boxed title to bottom |
attach boxed title to bottom |
Размещает заголовок внизу бокса. |
attach boxed title to top |
attach boxed title to top |
Размещает заголовок вверху бокса (по умолчанию). |
attach title |
attach title |
Включает прикрепленный заголовок. |
auto outer arc |
auto outer arc |
Автонастройка внешних дуг для сложных рамок. |
autoparskip |
autoparskip |
Автоматически регулирует parskip внутри бокса. |
baseline |
baseline=<length> |
Выравнивание бокса по базовой линии текста. |
beamer |
beamer |
Стиль для презентаций Beamer. |
beamer alerted |
beamer alerted |
Стиль для “alerted” боксов в Beamer. |
beamer hidden |
beamer hidden |
Стиль для скрытых боксов в Beamer. |
bean arc |
bean arc |
Альтернативный стиль скругления углов (“бобовый”). |
before |
before={<code>} |
Код, выполняемый перед рисованием бокса. |
before skip |
before skip=<length> |
Вертикальный отступ перед боксом. |
bicolor |
bicolor |
Двухцветный стиль (разные цвета для верхней/нижней частей). |
blank |
blank |
Пустой стиль (без рамок и фона). |
blanker |
blanker |
Еще более минималистичный стиль, чем blank. |
blankest |
blankest |
Максимально упрощенный стиль (только текст). |
blend before title |
blend before title |
Смешивает фон перед заголовком с основным фоном. |
bookmark |
bookmark=<text> |
Добавляет закладку PDF для бокса. |
borderline |
borderline={<options>} |
Рисует дополнительные границы (например, тени). |
bottomrule |
bottomrule=<length> |
Толщина нижней границы. |
bottomrule at break |
bottomrule at break=<length> |
Толщина нижней границы на разрыве страницы. |
box align |
box align=<baseline/top/bottom> |
Выравнивание содержимого внутри бокса. |
boxed title size |
boxed title size=<options> |
Размеры рамки заголовка. |
boxrule |
boxrule=<length> |
Толщина основной рамки. |
boxsep |
boxsep=<length> |
Внутренний отступ содержимого от границ. |
colback |
colback=<color> |
Цвет фона основной части. |
colbacklower |
colbacklower=<color> |
Цвет фона нижней части (для bicolor). |
colbacktitle |
colbacktitle=<color> |
Цвет фона заголовка. |
colframe |
colframe=<color> |
Цвет рамки бокса. |
collower |
collower=<color> |
Цвет текста в нижней части бокса. |
color color |
color color=<name> |
Настройка цвета (внутренний ключ для управления цветами). |
color command |
color command=<cmd> |
Команда для применения цвета. |
color counter |
color counter=<ctr> |
Счетчик для генерации цветов. |
color definition |
color definition={<code>} |
Определение нового цвета. |
color environment |
color environment=<env> |
Окружение для применения цвета. |
color fade |
color fade={<options>} |
Градиентная заливка фона. |
color hyperlink |
color hyperlink={<options>} |
Цвет гиперссылок внутри бокса. |
color key |
color key=<key> |
Ключ для доступа к цвету. |
color length |
color length=<len> |
Длина цветового перехода. |
color option |
color option={<opt>} |
Опции цвета. |
color path |
color path={<path>} |
Путь TikZ для градиента. |
color value |
color value=<val> |
Значение цвета (например, red!50). |
coltext |
coltext=<color> |
Цвет основного текста. |
coltitle |
coltitle=<color> |
Цвет текста заголовка. |
colupper |
colupper=<color> |
Цвет текста в верхней части бокса. |
comment |
comment={<text>} |
Добавляет комментарий внутри бокса. |
comment above listing |
comment above listing={<text>} |
Комментарий над листингом кода. |
comment above* listing |
comment above* listing={<text>} |
Комментарий над листингом (без форматирования). |
comment and listing |
comment and listing={<text>} |
Комбинация комментария и листинга. |
comment only |
comment only={<text>} |
Только комментарий (без листинга). |
comment outside listing |
comment outside listing={<text>} |
Комментарий вне листинга (например, сбоку). |
comment side listing |
comment side listing={<text>} |
Комментарий сбоку от листинга. |
comment style |
comment style={<style>} |
Стиль оформления комментариев. |
compilable listing |
compilable listing |
Листинг, который можно компилировать. |
compress page |
compress page |
Сжимает страницу для экономии места. |
ctan formatter |
ctan formatter={<code>} |
Форматирование для CTAN-документации. |
default minted options |
default minted options={<opt>} |
Опции по умолчанию для пакета minted. |
description color |
description color=<color> |
Цвет текста в описании. |
description delimiters |
description delimiters={<left><right>} |
Разделители для описаний (например, скобки). |
description delimiters none |
description delimiters none |
Убирает разделители описаний. |
description delimiters parenthesis |
description delimiters parenthesis |
Использует круглые скобки для описаний. |
description font |
description font={<font>} |
Шрифт для описаний. |
description formatter |
description formatter={<code>} |
Функция форматирования описаний. |
detach title |
detach title |
Отделяет заголовок от основного бокса. |
do not store to box array |
do not store to box array |
Запрещает сохранение бокса в массив. |
doc description |
doc description={<text>} |
Описание для документации. |
doc head |
doc head={<text>} |
Заголовок раздела документации. |
doc head command |
doc head command={<cmd>} |
Команда для заголовка документации. |
doc head environment |
doc head environment={<env>} |
Окружение для заголовка документации. |
doc head key |
doc head key={<key>} |
Ключ для заголовка документации. |
doc head path |
doc head path={<path>} |
Путь TikZ для заголовка документации. |
doc index |
doc index={<text>} |
Индекс для документации. |
doc into index |
doc into index={<text>} |
Добавляет запись в индекс документации. |
doc key prefix |
doc key prefix={<prefix>} |
Префикс для ключей документации. |
doc keypath |
doc keypath={<path>} |
Путь к ключу документации. |
doc label |
doc label={<label>} |
Метка для перекрестных ссылок. |
doc left |
doc left={<text>} |
Текст слева в документации. |
doc left indent |
doc left indent={<len>} |
Отступ слева в документации. |
doc marginnote |
doc marginnote={<text>} |
Заметка на полях документации. |
doc name |
doc name={<name>} |
Имя элемента документации. |
doc new |
doc new |
Пометка нового элемента в документации. |
doc new and updated |
doc new and updated |
Пометка нового и обновленного элемента. |
doc no index |
doc no index |
Исключает элемент из индекса. |
doc parameter |
doc parameter={<param>} |
Параметр для документации. |
doc raster |
doc raster={<options>} |
Сетка (raster) для документации. |
doc right |
doc right={<text>} |
Текст справа в документации. |
doc right indent |
doc right indent={<len>} |
Отступ справа в документации. |
doc sort index |
doc sort index={<key>} |
Ключ сортировки индекса. |
doc updated |
doc updated |
Пометка обновленного элемента. |
docexample |
docexample={<code>} |
Пример кода для документации. |
documentation listing options |
documentation listing options={<opt>} |
Опции листинга в документации. |
documentation listing style |
documentation listing style={<style>} |
Стиль листинга в документации. |
documentation minted language |
documentation minted language={<lang>} |
Язык для minted в документации. |
documentation minted options |
documentation minted options={<opt>} |
Опции minted для документации. |
documentation minted style |
documentation minted style={<style>} |
Стиль minted для документации. |
draft |
draft |
Черновой режим (упрощенное отображение). |
draftmode |
draftmode |
Режим черновика с дополнительными опциями. |
drop fuzzy midday shadow |
drop fuzzy midday shadow={<opt>} |
Размытая тень с эффектом “полдень”. |
drop fuzzy shadow |
drop fuzzy shadow={<opt>} |
Размытая тень вокруг бокса. |
drop large lifted shadow |
drop large lifted shadow={<opt>} |
Большая “приподнятая” тень. |
drop lifted shadow |
drop lifted shadow={<opt>} |
Эффект приподнятого бокса с тенью. |
drop midday shadow |
drop midday shadow={<opt>} |
Тень с акцентом на верхнюю границу. |
drop shadow |
drop shadow={<opt>} |
Стандартная тень. |
empty |
empty |
Полностью пустой бокс (без содержимого). |
enforce breakable |
enforce breakable |
Принудительно разрешает разрыв бокса. |
english language |
english language |
Устанавливает английский язык для текста. |
enhanced |
enhanced |
Включает улучшенный режим рисования (с TikZ). |
enhanced jigsaw |
enhanced jigsaw |
Режим “пазла” с закругленными углами. |
enlarge bottom at break by |
enlarge bottom at break by=<len> |
Увеличивает нижний отступ при разрыве. |
enlarge bottom by |
enlarge bottom by=<len> |
Увеличивает нижний отступ. |
enlarge left by |
enlarge left by=<len> |
Увеличивает левый отступ. |
enlarge right by |
enlarge right by=<len> |
Увеличивает правый отступ. |
enlarge top at break by |
enlarge top at break by=<len> |
Увеличивает верхний отступ при разрыве. |
enlarge top by |
enlarge top by=<len> |
Увеличивает верхний отступ. |
enlargepage |
enlargepage |
Расширяет страницу для размещения бокса. |
enlargepage flexible |
enlargepage flexible |
Гибкое расширение страницы. |
environment lower |
environment lower={<env>} |
Окружение для нижней части бокса. |
environment lower app |
environment lower app={<env>} |
Окружение для нижней части (для приложений). |
environment lower args |
environment lower args={<args>} |
Аргументы для окружения нижней части. |
environment lower args app |
environment lower args app={<args>} |
Аргументы окружения нижней части для приложений |
environment lower args pre |
environment lower args pre={<args>} |
Аргументы окружения нижней части (предварительные) |
environment lower pre |
environment lower pre={<env>} |
Окружение нижней части (предварительное) |
environment title |
environment title={<env>} |
Окружение для заголовка |
environment title app |
environment title app={<env>} |
Окружение заголовка для приложений |
environment title args |
environment title args={<args>} |
Аргументы окружения заголовка |
environment title args app |
environment title args app={<args>} |
Аргументы окружения заголовка для приложений |
environment title args pre |
environment title args pre={<args>} |
Аргументы окружения заголовка (предварительные) |
environment title pre |
environment title pre={<env>} |
Окружение заголовка (предварительное) |
environment upper |
environment upper={<env>} |
Окружение верхней части |
environment upper app |
environment upper app={<env>} |
Окружение верхней части для приложений |
environment upper args |
environment upper args={<args>} |
Аргументы окружения верхней части |
environment upper args app |
environment upper args app={<args>} |
Аргументы окружения верхней части для приложений |
environment upper args pre |
environment upper args pre={<args>} |
Аргументы окружения верхней части (предварительные) |
environment upper pre |
environment upper pre={<env>} |
Окружение верхней части (предварительное) |
equal height group |
equal height group=<name> |
Группа боксов с одинаковой высотой |
every box |
every box={<options>} |
Стиль для всех боксов |
every box on higher layers |
every box on higher layers={<options>} |
Стиль для боксов на верхних слоях |
every box on layer n |
every box on layer n={<options>} |
Стиль для боксов на конкретном слое |
every float |
every float={<options>} |
Стиль для плавающих боксов |
every listing line |
every listing line={<options>} |
Стиль для каждой строки листинга |
every listing line* |
every listing line*={<options>} |
Альтернативный стиль строк листинга |
extend freelance |
extend freelance={<options>} |
Расширение freelance-стиля |
extend freelancefirst |
extend freelancefirst={<options>} |
Расширение для первого freelance-бокса |
extend freelancelast |
extend freelancelast={<options>} |
Расширение для последнего freelance-бокса |
extend freelancemiddle |
extend freelancemiddle={<options>} |
Расширение для средних freelance-боксов |
external |
external={<options>} |
Внешнее содержимое бокса |
externalize example |
externalize example |
Внешний пример (без форсирования) |
externalize example! |
externalize example! |
Внешний пример (с форсированием) |
externalize listing |
externalize listing |
Внешний листинг (без форсирования) |
externalize listing! |
externalize listing! |
Внешний листинг (с форсированием) |
extras |
extras={<options>} |
Дополнительные стили |
extras broken |
extras broken={<options>} |
Стили для разорванного бокса |
extras broken pre |
extras broken pre={<options>} |
Предварительные стили для разорванного бокса |
extras first |
extras first={<options>} |
Стили для первой части |
extras first and middle |
extras first and middle={<options>} |
Стили для первой и средней частей |
extras first and middle pre |
extras first and middle pre={<options>} |
Предварительные стили для первой и средней частей |
extras first pre |
extras first pre={<options>} |
Предварительные стили для первой части |
extras last |
extras last={<options>} |
Стили для последней части |
extras last pre |
extras last pre={<options>} |
Предварительные стили для последней части |
extras middle |
extras middle={<options>} |
Стили для средней части |
extras middle and last |
extras middle and last={<options>} |
Стили для средней и последней частей |
extras middle and last pre |
extras middle and last pre={<options>} |
Предварительные стили для средней и последней частей |
extras middle pre |
extras middle pre={<options>} |
Предварительные стили для средней части |
extras pre |
extras pre={<options>} |
Предварительные дополнительные стили |
extras title after break |
extras title after break={<options>} |
Стили заголовка после разрыва |
extras unbroken |
extras unbroken={<options>} |
Стили для неразорванного бокса |
extras unbroken and first |
extras unbroken and first={<options>} |
Стили для неразорванного и первого бокса |
extras unbroken and first pre |
extras unbroken and first pre={<options>} |
Предварительные стили для неразорванного и первого бокса |
extras unbroken and last |
extras unbroken and last={<options>} |
Стили для неразорванного и последнего бокса |
extras unbroken and last pre |
extras unbroken and last pre={<options>} |
Предварительные стили для неразорванного и последнего бокса |
extras unbroken pre |
extras unbroken pre={<options>} |
Предварительные стили для неразорванного бокса |
extrude bottom by |
extrude bottom by=<length> |
Выступ снизу бокса |
extrude by |
extrude by=<length> |
Выступ со всех сторон |
extrude left by |
extrude left by=<length> |
Выступ слева |
extrude right by |
extrude right by=<length> |
Выступ справа |
extrude top by |
extrude top by=<length> |
Выступ сверху |
fill downwards |
fill downwards |
Заполнение содержимого сверху вниз |
finish |
finish={<options>} |
Завершающие стили |
finish broken |
finish broken={<options>} |
Завершающие стили для разорванного бокса |
finish broken pre |
finish broken pre={<options>} |
Предварительные завершающие стили для разорванного бокса |
finish fading vignette |
finish fading vignette={<options>} |
Завершение fading vignette-эффекта |
finish first |
finish first={<options>} |
Завершающие стили для первой части |
finish first and middle |
finish first and middle={<options>} |
Завершающие стили для первой и средней частей |
finish first and middle pre |
finish first and middle pre={<options>} |
Предварительные завершающие стили для первой и средней частей |
finish first pre |
finish first pre={<options>} |
Предварительные завершающие стили для первой части |
finish last |
finish last={<options>} |
Завершающие стили для последней части |
finish last pre |
finish last pre={<options>} |
Предварительные завершающие стили для последней части |
finish middle |
finish middle={<options>} |
Завершающие стили для средней части |
finish middle and last |
finish middle and last={<options>} |
Завершающие стили для средней и последней частей |
finish middle and last pre |
finish middle and last pre={<options>} |
Предварительные завершающие стили для средней и последней частей |
finish middle pre |
finish middle pre={<options>} |
Предварительные завершающие стили для средней части |
finish pre |
finish pre={<options>} |
Предварительные завершающие стили |
finish raised fading vignette |
finish raised fading vignette={<options>} |
Завершение raised fading vignette-эффекта |
finish unbroken |
finish unbroken={<options>} |
Завершающие стили для неразорванного бокса |
finish unbroken and first |
finish unbroken and first={<options>} |
Завершающие стили для неразорванного и первого бокса |
finish unbroken and first pre |
finish unbroken and first pre={<options>} |
Предварительные завершающие стили для неразорванного и первого бокса |
finish unbroken and last |
finish unbroken and last={<options>} |
Завершающие стили для неразорванного и последнего бокса |
finish unbroken and last pre |
finish unbroken and last pre={<options>} |
Предварительные завершающие стили для неразорванного и последнего бокса |
finish unbroken pre |
finish unbroken pre={<options>} |
Предварительные завершающие стили для неразорванного бокса |
finish vignette |
finish vignette={<options>} |
Завершение vignette-эффекта |
fit |
fit={<options>} |
Подгонка размера содержимого |
fit algorithm |
fit algorithm=<name> |
Алгоритм подгонки |
fit basedim |
fit basedim=<length> |
Базовый размер для подгонки |
fit fontsize macros |
fit fontsize macros={<names>} |
Макросы размера шрифта для подгонки |
fit height from |
fit height from={<code>} |
Вычисление высоты из кода |
fit height plus |
fit height plus={<length>} |
Дополнительная высота при подгонке |
fit maxfontdiff |
fit maxfontdiff=<value> |
Максимальная разница шрифтов |
fit maxfontdiffgap |
fit maxfontdiffgap=<value> |
Максимальный промежуток разницы шрифтов |
fit maxstep |
fit maxstep=<value> |
Максимальное количество шагов |
fit maxwidthdiff |
fit maxwidthdiff=<value> |
Максимальная разница ширины |
fit maxwidthdiffgap |
fit maxwidthdiffgap=<value> |
Максимальный промежуток разницы ширины |
fit skip |
fit skip={<options>} |
Пропуск элементов при подгонке |
fit to |
fit to={<dimensions>} |
Подгонка к указанным размерам |
fit to height |
fit to height={<height>} |
Подгонка по высоте |
fit warning |
fit warning={<options>} |
Предупреждения при подгонке |
fit width from |
fit width from={<code>} |
Вычисление ширины из кода |
fit width plus |
fit width plus={<length>} |
Дополнительная ширина при подгонке |
flip title |
flip title |
Переворот заголовка |
float |
float |
Плавающий бокс |
float* |
float* |
Альтернативный плавающий бокс |
floatplacement |
floatplacement={<placement>} |
Позиционирование плавающего бокса |
flush left |
flush left |
Выравнивание по левому краю |
flush right |
flush right |
Выравнивание по правому краю |
flushleft lower |
flushleft lower |
Выравнивание нижней части по левому краю |
flushleft title |
flushleft title |
Выравнивание заголовка по левому краю |
flushleft upper |
flushleft upper |
Выравнивание верхней части по левому краю |
flushright lower |
flushright lower |
Выравнивание нижней части по правому краю |
flushright title |
flushright title |
Выравнивание заголовка по правому краю |
flushright upper |
flushright upper |
Выравнивание верхней части по правому краю |
fontlower |
fontlower={<font>} |
Шрифт нижней части |
fonttitle |
fonttitle={<font>} |
Шрифт заголовка |
fontupper |
fontupper={<font>} |
Шрифт верхней части |
force nobeforeafter |
force nobeforeafter |
Принудительное отключение before/after |
frame code |
frame code={<code>} |
Пользовательский код рамки |
frame code app |
frame code app={<code>} |
Код рамки для приложений |
frame code pre |
frame code pre={<code>} |
Предварительный код рамки |
frame empty |
frame empty |
Пустая рамка |
frame engine |
frame engine=<name> |
Движок отрисовки рамки |
frame hidden |
frame hidden |
Скрытая рамка |
frame style |
frame style={<style>} |
Стиль рамки |
frame style image |
frame style image={<image>} |
Стиль рамки с изображением |
frame style tile |
frame style tile={<options>} |
Стиль рамки с плиткой |
freelance |
freelance={<options>} |
Freelance-стиль |
freeze extension |
freeze extension={<ext>} |
Расширение для замороженных файлов |
freeze file |
freeze file={<name>} |
Имя замороженного файла |
freeze jpg |
freeze jpg |
Заморозка в JPG |
freeze none |
freeze none |
Без заморозки |
freeze pdf |
freeze pdf |
Заморозка в PDF |
freeze png |
freeze png |
Заморозка в PNG |
fuzzy halo |
fuzzy halo={<options>} |
Размытое гало |
fuzzy shadow |
fuzzy shadow={<options>} |
Размытая тень |
geometry nodes |
geometry nodes={<names>} |
Геометрические узлы |
graphics directory |
graphics directory={<path>} |
Директория с графикой |
graphics options |
graphics options={<options>} |
Опции графики |
graphics orientation |
graphics orientation={<angle>} |
Ориентация графики |
graphics pages |
graphics pages={<range>} |
Страницы графики |
grow sidewards by |
grow sidewards by={<length>} |
Рост вбок |
grow to left by |
grow to left by={<length>} |
Рост влево |
grow to right by |
grow to right by={<length>} |
Рост вправо |
halign |
halign=<alignment> |
Горизонтальное выравнивание |
halign code |
halign code={<code>} |
Код горизонтального выравнивания |
halign lower |
halign lower=<alignment> |
Выравнивание нижней части |
halign lower code |
halign lower code={<code>} |
Код выравнивания нижней части |
halign title |
halign title=<alignment> |
Выравнивание заголовка |
halign title code |
halign title code={<code>} |
Код выравнивания заголовка |
halign upper |
halign upper=<alignment> |
Выравнивание верхней части |
halign upper code |
halign upper code={<code>} |
Код выравнивания верхней части |
halo |
halo={<options>} |
Эффект гало |
hbox |
hbox |
Горизонтальная коробка |
hbox boxed title |
hbox boxed title |
Горизонтальная коробка заголовка |
height |
height={<length>} |
Фиксированная высота |
height fill |
height fill |
Заполнение высоты |
height fixed for |
height fixed for={<name>} |
Фиксированная высота для группы |
height from |
height from={<code>} |
Высота из кода |
height plus |
height plus={<length>} |
Дополнительная высота |
hide |
hide |
Скрытый бокс |
highlight math |
highlight math |
Подсветка математики |
highlight math style |
highlight math style={<style>} |
Стиль подсветки математики |
hyperlink |
hyperlink={<name>} |
Гиперссылка |
hyperlink interior |
hyperlink interior={<name>} |
Гиперссылка на внутреннюю часть |
hyperlink node |
hyperlink node={<name>} |
Гиперссылка на узел |
hyperlink title |
hyperlink title={<name>} |
Гиперссылка на заголовок |
hyperref |
hyperref={<options>} |
Настройки hyperref |
hyperref interior |
hyperref interior={<options>} |
Hyperref для внутренней части |
hyperref node |
hyperref node={<options>} |
Hyperref для узла |
hyperref title |
hyperref title={<options>} |
Hyperref для заголовка |
hypertarget |
hypertarget={<name>} |
Цель гиперссылки |
hyperurl |
hyperurl={<url>} |
Гиперссылка-URL |
hyperurl interior |
hyperurl interior={<url>} |
URL для внутренней части |
hyperurl node |
hyperurl node={<url>} |
URL для узла |
hyperurl title |
hyperurl title={<url>} |
URL для заголовка |
hyperurl* |
hyperurl*={<url>} |
Альтернативный гиперurl |
hyperurl* interior |
hyperurl* interior={<url>} |
Альтернативный URL для внутренней части |
hyperurl* node |
hyperurl* node={<url>} |
Альтернативный URL для узла |
hyperurl* title |
hyperurl* title={<url>} |
Альтернативный URL для заголовка |
hyphenationfix |
hyphenationfix |
Исправление переносов |
if odd page |
if odd page={<code>} |
Условие для нечетной страницы |
if odd page or oneside |
if odd page or oneside={<code>} |
Условие для нечетной/односторонней страницы |
if odd page or oneside* |
if odd page or oneside*={<code>} |
Альтернативное условие |
if odd page* |
if odd page*={<code>} |
Альтернативное условие нечетной страницы |
IfBlankF |
IfBlankF={<arg>}{<code>} |
Условный код если аргумент пуст (ложь) |
IfBlankT |
IfBlankT={<arg>}{<code>} |
Условный код если аргумент пуст (истина) |
IfBlankTF |
IfBlankTF={<arg>}{<if>}{<else>} |
Полное условие для пустого аргумента |
IfBooleanF |
IfBooleanF={<arg>}{<code>} |
Условие для булева значения (ложь) |
IfBooleanT |
IfBooleanT={<arg>}{<code>} |
Условие для булева значения (истина) |
IfBooleanTF |
IfBooleanTF={<arg>}{<if>}{<else>} |
Полное булево условие |
IfEmptyF |
IfEmptyF={<arg>}{<code>} |
Условие для пустого значения (ложь) |
IfEmptyT |
IfEmptyT={<arg>}{<code>} |
Условие для пустого значения (истина) |
IfEmptyTF |
IfEmptyTF={<arg>}{<if>}{<else>} |
Полное условие для пустого значения |
IfNoValueF |
IfNoValueF={<arg>}{<code>} |
Условие если нет значения (ложь) |
IfNoValueT |
IfNoValueT={<arg>}{<code>} |
Условие если нет значения (истина) |
IfNoValueTF |
IfNoValueTF={<arg>}{<if>}{<else>} |
Полное условие для отсутствия значения |
IfValueF |
IfValueF={<arg>}{<code>} |
Условие если есть значение (ложь) |
IfValueT |
IfValueT={<arg>}{<code>} |
Условие если есть значение (истина) |
IfValueTF |
IfValueTF={<arg>}{<if>}{<else>} |
Полное условие для наличия значения |
ignore nobreak |
ignore nobreak |
Игнорирование запрета разрыва |
image comment |
image comment={<text>} |
Комментарий к изображению |
index |
index={<entry>} |
Запись в индекс |
index actual |
index actual={<options>} |
Фактические настройки индекса |
index annotate |
index annotate={<options>} |
Аннотации индекса |
index colorize |
index colorize={<options>} |
Раскрашивание индекса |
index command |
index command={<cmd>} |
Команда индекса |
index command name |
index command name={<name>} |
Имя команды индекса |
index default settings |
index default settings |
Настройки индекса по умолчанию |
index format |
index format={<format>} |
Формат индекса |
index gather all |
index gather all |
Сбор всех элементов в индекс |
index gather colors |
index gather colors |
Сбор цветов в индекс |
index gather commands |
index gather commands |
Сбор команд в индекс |
index gather counters |
index gather counters |
Сбор счетчиков в индекс |
index gather environments |
index gather environments |
Сбор окружений в индекс |
index gather keys |
index gather keys |
Сбор ключей в индекс |
index gather lengths |
index gather lengths |
Сбор длин в индекс |
index gather none |
index gather none |
Отключение сбора в индекс |
index gather paths |
index gather paths |
Сбор путей в индекс |
index gather values |
index gather values |
Сбор значений в индекс |
index german settings |
index german settings |
Немецкие настройки индекса |
index key formatter |
index key formatter={<formatter>} |
Форматирование ключей индекса |
index keys formatter |
index keys formatter={<formatter>} |
Форматирование нескольких ключей |
index level |
index level={<level>} |
Уровень индекса |
index quote |
index quote={<text>} |
Цитата в индексе |
index* |
index*={<entry>} |
Альтернативная запись в индекс |
inherit height |
inherit height |
Наследование высоты |
interior code |
interior code={<code>} |
Пользовательский код внутренней части |
interior code app |
interior code app={<code>} |
Код внутренней части для приложений |
interior code pre |
interior code pre={<code>} |
Предварительный код внутренней части |
interior empty |
interior empty |
Пустая внутренняя часть |
interior engine |
interior engine={<name>} |
Движок внутренней части |
interior hidden |
interior hidden |
Скрытая внутренняя часть |
interior style |
interior style={<style>} |
Стиль внутренней части |
interior style image |
interior style image={<image>} |
Стиль внутренней части с изображением |
interior style tile |
interior style tile={<options>} |
Стиль внутренней части с плиткой |
interior titled code |
interior titled code={<code>} |
Код внутренней части с заголовком |
interior titled code app |
interior titled code app={<code>} |
Код внутренней части с заголовком для приложений |
interior titled code pre |
interior titled code pre={<code>} |
Предварительный код внутренней части с заголовком |
interior titled empty |
interior titled empty |
Пустая внутренняя часть с заголовком |
interior titled engine |
interior titled engine=<name> |
Движок для внутренней части с заголовком |
invisible |
invisible |
Делает бокс полностью невидимым (но сохраняет содержимое) |
keywords bold |
keywords bold |
Выделение ключевых слов жирным шрифтом в документации |
label |
label=<text> |
Метка для перекрестных ссылок |
label is label |
label is label |
Использовать стандартные метки LaTeX |
label is zlabel |
label is zlabel |
Использовать zref-метки |
label separator |
label separator=<text> |
Разделитель между меткой и текстом |
label type |
label type=<type> |
Тип метки (например, ’tcb@label') |
left |
left=<length> |
Отступ слева для основного содержимого |
left skip |
left skip=<length> |
Горизонтальный отступ слева |
left* |
left*=<length> |
Альтернативный отступ слева |
lefthand ratio |
lefthand ratio=<value> |
Соотношение для левой части (в split боксах) |
lefthand width |
lefthand width=<length> |
Ширина левой части (в split боксах) |
leftlower |
leftlower=<length> |
Отступ слева для нижней части |
leftright skip |
leftright skip=<length> |
Одновременный отступ слева и справа |
leftrule |
leftrule=<length> |
Толщина левой границы |
lefttitle |
lefttitle=<length> |
Отступ слева для заголовка |
leftupper |
leftupper=<length> |
Отступ слева для верхней части |
lifted shadow |
lifted shadow={<options>} |
Эффект “приподнятой” тени |
lines before break |
lines before break=<number> |
Минимальное количество строк перед разрывом |
list entry |
list entry=<text> |
Запись для списка (оглавления) |
list text |
list text=<text> |
Текст для списка |
listing above comment |
listing above comment={<text>} |
Листинг с комментарием сверху |
listing above text |
listing above text={<text>} |
Листинг с текстом сверху |
listing and comment |
listing and comment={<text>} |
Комбинация листинга и комментария |
listing engine |
listing engine=<name> |
Движок для обработки листингов |
listing file |
listing file={<filename>} |
Файл с кодом для листинга |
listing inputencoding |
listing inputencoding=<encoding> |
Кодировка входного файла листинга |
listing only |
listing only |
Только листинг (без дополнительного текста) |
listing options |
listing options={<options>} |
Опции для листинга |
listing remove caption |
listing remove caption |
Удаление подписи у листинга |
listing side comment |
listing side comment={<text>} |
Листинг с боковым комментарием |
listing side text |
listing side text={<text>} |
Листинг с боковым текстом |
listing style |
listing style={<style>} |
Стиль оформления листинга |
listing utf8 |
listing utf8 |
Использование UTF-8 для листинга |
lower separated |
lower separated |
Разделение нижней части визуальной линией |
lowerbox |
lowerbox |
Обработка нижней части как бокса |
marker |
marker={<options>} |
Маркеры для оформления |
math |
math |
Математический режим в основном содержимом |
math lower |
math lower |
Математический режим в нижней части |
math upper |
math upper |
Математический режим в верхней части |
middle |
middle=<length> |
Вертикальное выравнивание по середине |
minipage |
minipage |
Обработка содержимого как minipage |
minipage boxed title |
minipage boxed title |
Заголовок как minipage |
minted language |
minted language={<lang>} |
Язык для пакета minted |
minted options |
minted options={<options>} |
Опции для minted |
minted style |
minted style={<style>} |
Стиль для minted |
move upwards |
move upwards=<length> |
Сдвиг содержимого вверх |
nameref |
nameref |
Использование nameref для ссылок |
natural height |
natural height |
Естественная высота содержимого |
no borderline |
no borderline |
Удаление дополнительных границ |
no boxed title style |
no boxed title style |
Отключение стиля для заголовка в рамке |
no extras |
no extras |
Отключение дополнительных стилей |
no finish |
no finish |
Отключение завершающих стилей |
no label type |
no label type |
Отключение специального типа метки |
no listing options |
no listing options |
Отключение опций листинга |
no overlay |
no overlay |
Отключение наложений |
no shadow |
no shadow |
Отключение теней |
no underlay |
no underlay |
Отключение подложек |
no watermark |
no watermark |
Отключение водяных знаков |
nobeforeafter |
nobeforeafter |
Отключение отступов before/after |
nofloat |
nofloat |
Запрет плавающего размещения |
noparskip |
noparskip |
Отключение parskip |
notitle |
notitle |
Отключение заголовка |
octogon arc |
octogon arc |
Восьмиугольная форма углов |
on line |
on line |
Размещение в строке текста |
only |
only={<options>} |
Условное отображение содержимого |
opacityback |
opacityback=<value> |
Прозрачность фона |
opacitybacktitle |
opacitybacktitle=<value> |
Прозрачность фона заголовка |
opacityframe |
opacityframe=<value> |
Прозрачность рамки |
opacitytext |
opacitytext=<value> |
Прозрачность текста |
outer arc |
outer arc |
Скругление внешних углов |
overlay |
overlay={<code>} |
Наложение TikZ-кода |
oversize |
oversize |
Разрешение содержимому выходить за границы |
pad at break |
pad at break=<length> |
Заполнение при разрыве |
page ref formatter |
page ref formatter={<code>} |
Форматирование ссылок на страницы |
parbox |
parbox |
Обработка содержимого как parbox |
parskip |
parskip |
Использование parskip между абзацами |
phantom |
phantom |
Невидимый бокс, занимающий место |
process code |
process code={<code>} |
Обработка кода перед вставкой |
raster columns |
raster columns=<number> |
Количество колонок в сетке |
raster equal height |
raster equal height |
Выравнивание высоты элементов сетки |
raster rows |
raster rows=<number> |
Количество строк в сетке |
record |
record |
Запись параметров бокса |
right |
right=<length> |
Отступ справа для основного содержимого |
right skip |
right skip=<length> |
Горизонтальный отступ справа |
rightrule |
rightrule=<length> |
Толщина правой границы |
rotate |
rotate=<angle> |
Вращение бокса |
rounded corners |
rounded corners=<length> |
Скругление углов |
run pdflatex |
run pdflatex |
Запуск pdflatex для обработки содержимого |
savedelimiter |
savedelimiter={<text>} |
Сохранение разделителя |
saveto |
saveto={<filename>} |
Сохранение содержимого в файл |
scale |
scale=<factor> |
Масштабирование содержимого |
segmentation at break |
segmentation at break |
Разделитель при разрыве |
segmentation code |
segmentation code={<code>} |
Пользовательский код разделителя |
segmentation style |
segmentation style={<style>} |
Стиль линии-разделителя между верхней и нижней частями |
separator sign |
separator sign={<char>} |
Символ-разделитель в описаниях |
separator sign colon |
separator sign colon |
Использование двоеточия как разделителя |
separator sign dash |
separator sign dash |
Использование тире как разделителя |
separator sign none |
separator sign none |
Отсутствие разделителя |
set alt |
set alt={<text>} |
Установка альтернативного текста |
set temporal |
set temporal={<text>} |
Временная установка значения |
shadow |
shadow={<options>} |
Настройка тени вокруг бокса |
sharp corners |
sharp corners |
Острые углы (без скругления) |
sharpish corners |
sharpish corners |
Слегка скругленные углы |
shield externalize |
shield externalize |
Защита от externalize |
short title |
short title={<text>} |
Краткий вариант заголовка |
show bounding box |
show bounding box |
Отображение ограничивающей рамки |
shrink break goal |
shrink break goal={<length>} |
Целевое значение сжатия при разрыве |
shrink tight |
shrink tight |
Плотное сжатие содержимого |
sidebyside |
sidebyside |
Размещение содержимого бок о бок |
sidebyside align |
sidebyside align={<option>} |
Выравнивание side-by-side содержимого |
sidebyside gap |
sidebyside gap={<length>} |
Зазор между side-by-side элементами |
sidebyside switch |
sidebyside switch |
Переключение порядка side-by-side |
size |
size={<option>} |
Размер бокса (normal, small, etc.) |
skin |
skin={<name>} |
Скин для оформления бокса |
skin first |
skin first={<name>} |
Скин для первого бокса в группе |
skin last |
skin last={<name>} |
Скин для последнего бокса в группе |
skin middle |
skin middle={<name>} |
Скин для средних боксов в группе |
smart shadow arc |
smart shadow arc |
Умное скругление теней |
space |
space={<length>} |
Вертикальный промежуток |
space to |
space to={<length>} |
Гибкий вертикальный промежуток |
space to lower |
space to lower={<length>} |
Промежуток до нижней части |
space to upper |
space to upper={<length>} |
Промежуток до верхней части |
spartan |
spartan |
Минималистичный стиль оформления |
split |
split={<options>} |
Разделение бокса на части |
spread |
spread |
Равномерное распределение пространства |
spread downwards |
spread downwards |
Распределение вниз |
spread inwards |
spread inwards |
Распределение внутрь |
spread outwards |
spread outwards |
Распределение наружу |
spread upwards |
spread upwards |
Распределение вверх |
square |
square |
Квадратная форма бокса |
squeezed title |
squeezed title |
Сжатый заголовок |
standard |
standard |
Стандартный стиль оформления |
standard jigsaw |
standard jigsaw |
Стандартный стиль с “пазлами” |
step |
step={<counter>} |
Шаг нумерации |
step and label |
step and label |
Автоматическая нумерация и метка |
store to box array |
store to box array={<name>} |
Сохранение в массив боксов |
subtitle style |
subtitle style={<style>} |
Стиль подзаголовка |
tabularx |
tabularx |
Использование tabularx внутри |
tcbimage comment |
tcbimage comment={<text>} |
Комментарий к изображению |
tcbox raise |
tcbox raise={<length>} |
Поднятие бокса |
tempfile |
tempfile |
Использование временного файла |
temporal |
temporal={<text>} |
Временное значение |
terminator sign |
terminator sign={<char>} |
Конечный символ в описаниях |
text above listing |
text above listing={<text>} |
Текст над листингом |
text and listing |
text and listing |
Комбинация текста и листинга |
text fill |
text fill |
Заполнение текстом |
text height |
text height={<length>} |
Высота текстовой области |
text width |
text width={<length>} |
Ширина текстовой области |
theorem |
theorem |
Стиль для теорем |
theorem label supplement |
theorem label supplement={<text>} |
Дополнение к метке теоремы |
theorem style |
theorem style={<name>} |
Стиль оформления теоремы |
tikz |
tikz={<options>} |
Опции TikZ |
tikz lower |
tikz lower={<options>} |
TikZ для нижней части |
tikz upper |
tikz upper={<options>} |
TikZ для верхней части |
tikznode |
tikznode |
Обработка как TikZ-узел |
tile |
tile |
Плиточное оформление фона |
title |
title={<text>} |
Заголовок бокса |
title after break |
title after break={<text>} |
Заголовок после разрыва |
title style |
title style={<style>} |
Стиль заголовка |
titlerule |
titlerule={<length>} |
Линия под заголовком |
toggle enlargement |
toggle enlargement |
Переключение увеличения |
toggle left and right |
toggle left and right |
Переключение левого/правого |
top |
top={<length>} |
Отступ сверху |
toprule |
toprule={<length>} |
Верхняя граница |
unbreakable |
unbreakable |
Запрет разрыва бокса |
underlay |
underlay={<code>} |
Подложка (TikZ-код под содержимым) |
underlay boxed title |
underlay boxed title={<code>} |
Подложка для заголовка |
underlay first |
underlay first={<code>} |
Подложка для первой части |
underlay last |
underlay last={<code>} |
Подложка для последней части |
underlay middle |
underlay middle={<code>} |
Подложка для средней части |
underlay vignette |
underlay vignette={<options>} |
Виньетка в качестве подложки |
upperbox |
upperbox |
Обработка верхней части как бокса |
use alt |
use alt |
Использование альтернативного текста |
use color stack |
use color stack |
Использование стека цветов |
valign |
valign={<option>} |
Вертикальное выравнивание |
varwidth upper |
varwidth upper |
Переменная ширина верхней части |
verbatim |
verbatim |
Режим verbatim |
visible |
visible |
Видимый бокс (антоним invisible) |
watermark graphics |
watermark graphics={<file>} |
Водяной знак из изображения |
watermark opacity |
watermark opacity={<value>} |
Прозрачность водяного знака |
watermark text |
watermark text={<text>} |
Текстовый водяной знак |
watermark tikz |
watermark tikz={<code>} |
Водяной знак TikZ |
width |
width={<length>} |
Ширина бокса |
| Ключ | Синтаксис | Назначение |
|---|---|---|
xshift |
xshift=<length> |
Горизонтальное смещение заголовка |
yshift |
yshift=<length> |
Вертикальное смещение заголовка |
yshift* |
yshift*=<length> |
Альтернативное вертикальное смещение |
yshifttext |
yshifttext=<length> |
Смещение текста заголовка |
| Ключ | Синтаксис | Назначение |
|---|---|---|
color |
color={<name>} |
Цвет для документации |
commands |
commands={<list>} |
Список команд |
counter |
counter={<name>} |
Счетчик для документации |
environment |
environment={<name>} |
Окружение для документации |
index |
index={<options>} |
Настройки индекса |
key |
key={<name>} |
Ключ документации |
length |
length={<name>} |
Длина для документации |
new |
new |
Пометка нового элемента |
path |
path={<name>} |
Путь для документации |
updated |
updated |
Пометка обновленного элемента |
value |
value={<val>} |
Значение для документации |
| Ключ | Синтаксис | Назначение |
|---|---|---|
- |
- |
Стандартный режим externalize |
! |
! |
Форсированный режим externalize |
compiler |
compiler={<name>} |
Компилятор для внешних файлов |
environment |
environment={<name>} |
Окружение для внешнего контента |
externalize |
externalize |
Активация externalize |
name |
name={<base>} |
Базовое имя для файлов |
preamble |
preamble={<code>} |
Преамбула для внешних файлов |
prefix |
prefix={<text>} |
Префикс для имен файлов |
runner |
runner={<command>} |
Команда для запуска |
safety |
safety={<options>} |
Настройки безопасности |
| Ключ | Назначение |
|---|---|
all |
Все библиотеки |
breakable |
Поддержка разрывов |
documentation |
Документационные стили |
external |
Внешний контент |
fitting |
Автоподгонка размеров |
listings |
Поддержка листингов |
minted |
Интеграция с Minted |
raster |
Сеточная компоновка |
skins |
Дополнительные скины |
theorems |
Стили для теорем |
| Ключ | Синтаксис | Назначение |
|---|---|---|
colspacing |
colspacing=<length> |
Расстояние между колонками |
columns |
columns=<number> |
Количество колонок |
height |
height=<length> |
Высота постера |
rowspacing |
rowspacing=<length> |
Расстояние между строками |
showframe |
showframe |
Показать рамки |
width |
width=<length> |
Ширина постера |
| Ключ | Синтаксис | Назначение |
|---|---|---|
base color |
base color={<color>} |
Базовый цвет виньетки |
east size |
east size=<length> |
Размер восточной части |
fade in |
fade in={<options>} |
Эффект плавного появления |
lower left corner |
lower left corner={<coord>} |
Левый нижний угол |
size |
size={<length>} |
Общий размер |
upper right corner |
upper right corner={<coord>} |
Правый верхний угол |
| Ключ | Синтаксис | Назначение |
|---|---|---|
tcb fill frame |
tcb fill frame={<color>} |
Заливка рамки |
tcb fill interior |
tcb fill interior={<color>} |
Заливка внутренней части |
tcb fill title |
tcb fill title={<color>} |
Заливка заголовка |
Каждая группа ключей решает специфические задачи, от базового позиционирования до сложных эффектов оформления.
| Команда | Полный синтаксис | Описание и назначение |
|---|---|---|
title |
/tcb/title=⟨text⟩ |
Создает заголовок с указанным текстом. |
notitle |
/tcb/notitle |
Удаляет строку заголовка, если установлено. |
adjusted title |
/tcb/adjusted title=⟨text⟩ |
Создает заголовок с автоматической подгонкой высоты под текст (полезно для выравнивания высоты боксов в группе). |
adjust text |
/tcb/adjust text=⟨text⟩ |
Устанавливает эталонный текст для подгонки высоты в adjusted title. |
squeezed title |
/tcb/squeezed title=⟨text⟩ |
Создает заголовок, сжимая текст, если он не помещается в доступное пространство. |
squeezed title* |
/tcb/squeezed title*=⟨text⟩ |
Комбинация adjusted title и squeezed title (подгонка высоты и сжатие текста). |
titlebox |
/tcb/titlebox=⟨mode⟩ |
Управляет отображением заголовка (visible — стандартное отображение, invisible — скрывает текст, оставляя пустое место). |
detach title |
/tcb/detach title |
Отделяет заголовок от стандартной позиции, сохраняя его в \tcbtitletext и \tcbtitle. |
attach title |
/tcb/attach title |
Возвращает заголовок в стандартную позицию (отменяет detach title). |
attach title to upper |
/tcb/attach title to upper=⟨text⟩ |
Прикрепляет заголовок к началу верхней части содержимого бокса (с дополнительным текстом между заголовком и содержимым). |
\tcbset{colback=White,arc=0mm,width=(\linewidth-4pt)/4,
equal height group=AT,before=,after=\hfill,fonttitle=\bfseries}
The following titles are not adjusted:\\
\foreach \n in {xxx,ggg,AAA,\"Agypten}
{\begin{tcolorbox}[title=\n,colframe=red!75!black]
Some content.\end{tcolorbox}}
Now, we try again with adjusted titles:\\
\foreach \n in {xxx,ggg,AAA,\"Agypten}
{\begin{tcolorbox}[adjusted title=\n,colframe=blue!75!black]
Some content.\end{tcolorbox}}
tcolorbox| Команда | Полный синтаксис | Описание и назначение |
|---|---|---|
\tcbsubtitle |
\tcbsubtitle[⟨options⟩]{⟨text⟩} |
Добавляет подзаголовок внутри tcolorbox. Наследует стили родительского бокса, но может быть дополнительно настроен через ⟨options⟩. |
subtitle style |
/tcb/subtitle style=⟨options⟩ |
Задает стиль для всех подзаголовков (\tcbsubtitle) внутри бокса. Позволяет централизованно настроить оформление. |
\begin{tcolorbox}[title=Основной заголовок, colback=blue!5!white, colframe=blue!75!black]
Основное содержимое.
\tcbsubtitle{Первый подзаголовок}
Текст под первым подзаголовком.
\tcbsubtitle{Второй подзаголовок}
Текст под вторым подзаголовком.
\end{tcolorbox}
\begin{tcolorbox}[
title=Пример с subtitle style,
colback=green!5!white,
colframe=green!75!black,
subtitle style={
colback=yellow!20!white,
colframe=red!50!black,
fontupper=\bfseries,
boxrule=1pt
}
]
Основной текст.
\tcbsubtitle{Настроенный подзаголовок}
Текст с кастомным оформлением.
\end{tcolorbox}
⟨options⟩\begin{tcolorbox}[title=Локальные настройки, colback=purple!5!white]
\tcbsubtitle[colback=orange!30!white, before skip=10pt]{Особый подзаголовок}
Текст с увеличенным отступом сверху и оранжевым фоном.
\end{tcolorbox}
tcolorbox| Команда | Полный синтаксис | Описание и назначение |
|---|---|---|
upperbox |
/tcb/upperbox=⟨mode⟩ |
Управляет отображением верхней части бокса. Допустимые значения: visible (стандартное отображение), invisible (скрывает содержимое). |
lowerbox |
/tcb/lowerbox=⟨mode⟩ |
Управляет отображением нижней части (после \tcblower). Аналогично upperbox. |
visible |
/tcb/visible |
Сокращение для upperbox=visible, lowerbox=visible, titlebox=visible. |
invisible |
/tcb/invisible |
Сокращение для upperbox=invisible, lowerbox=invisible, titlebox=invisible. |
saveto |
/tcb/saveto=⟨file name⟩ |
Сохраняет весь контент бокса (включая нижнюю часть, если есть) в указанный файл. Несовместимо с savelowerto/redirectlowerto. |
savelowerto |
/tcb/savelowerto=⟨file name⟩ |
Сохраняет только нижнюю часть (после \tcblower) в файл. |
redirectlowerto |
/tcb/redirectlowerto=⟨file name⟩ |
Перенаправляет нижнюю часть в файл (без отображения в документе). |
\begin{tcolorbox}[upperbox=invisible, colback=white]
Этот текст не виден (верхняя часть скрыта).
\end{tcolorbox}
\begin{tcolorbox}[lowerbox=invisible, colback=white]
Виден только верх.
\tcblower
Нижняя часть скрыта.
\end{tcolorbox}
Результат:
\tcblower.visible/invisible\begin{tcolorbox}[invisible, title=Скрытый бокс]
Весь контент (включая заголовок) не виден.
\tcblower
Нижняя часть тоже скрыта.
\end{tcolorbox}
Результат: Пустое место (все части скрыты).
\begin{tcolorbox}[saveto=mybox.tex, title=Сохраненный бокс]
Верхняя часть.
\tcblower
Нижняя часть.
\end{tcolorbox}
Загружаем сохраненное:
\input{mybox.tex}
Результат:
mybox.tex и может быть повторно загружено через \input.\begin{tcolorbox}[savelowerto=lower.tex]
Верхняя часть (отображается).
\tcblower
Нижняя часть (сохраняется в файл).
\end{tcolorbox}
Результат:
lower.tex.Разделение частей:
\tcblower).\tcblower весь контент считается верхней частью.Совместимость:
saveto нельзя использовать с savelowerto или redirectlowerto.Применение:
invisible полезен для скрытия контента (например, при сохранении в файл без отображения).savelowerto удобен для извлечения доп. материалов (решений задач, примечаний).tcolorbox| Команда | Полный синтаксис | Описание и назначение |
|---|---|---|
lowerbox |
/tcb/lowerbox=⟨mode⟩ |
Управляет отображением нижней части. Допустимые значения: visible (стандартное отображение), invisible (скрывает содержимое, оставляя пустое место), ignored (полностью игнорирует нижнюю часть). |
savelowerto |
/tcb/savelowerto=⟨file name⟩ |
Сохраняет содержимое нижней части в указанный файл для последующего использования. Несовместимо с saveto. |
redirectlowerto |
/tcb/redirectlowerto=⟨file name⟩ |
Комбинация savelowerto и lowerbox=ignored. Сохраняет нижнюю часть в файл, но не отображает её в документе. Полезно для работы с счётчиками. |
lower separated |
`/tcb/lower separated=true | false(по умолчаниюtrue`) |
savedelimiter |
/tcb/savedelimiter=⟨name⟩ |
Используется при создании новых окружений на основе tcolorbox для корректной работы с savelowerto или redirectlowerto. ⟨name⟩ должно совпадать с именем нового окружения. |
\begin{tcolorbox}[lowerbox=invisible, colback=white]
Верхняя часть (видна).
\tcblower
Нижняя часть (скрыта, но место остаётся).
\end{tcolorbox}
\begin{tcolorbox}[lowerbox=ignored, colback=white]
Верхняя часть (видна).
\tcblower
Нижняя часть (полностью игнорируется).
\end{tcolorbox}
Результат:
\begin{tcolorbox}[savelowerto=lower_content.tex, lowerbox=invisible]
Верхняя часть.
\tcblower
Нижняя часть (сохранена в файл).
\end{tcolorbox}
Загружаем сохранённое:
\input{lower_content.tex}
Результат:
lower_content.tex и может быть загружена через \input.\setcounter{enumi}{1}
Значение счётчика: \theenumi
\begin{tcolorbox}[redirectlowerto=counter_example.tex]
Верхняя часть.
\tcblower
Нижняя часть. \stepcounter{enumi} Новое значение: \theenumi.
\end{tcolorbox}
Загружаем:
\input{counter_example.tex}
Результат:
counter_example.tex: сохранён текст нижней части с обновлённым счётчиком.\begin{tcolorbox}[title=Разделённые части, lower separated=true]
Верхняя часть.
\tcblower
Нижняя часть (визуально отделена).
\end{tcolorbox}
\begin{tcolorbox}[title=Неразделённые части, lower separated=false]
Верхняя часть.
\tcblower
Нижняя часть (без разделения).
\end{tcolorbox}
Результат:
\newtcolorbox{mybox}[1]{%
savelowerto=#1, lowerbox=ignored,
colback=blue!5!white, colframe=blue!75!black,
title=Мой бокс
}
\begin{mybox}{saved_part.tex}
Верхняя часть.
\tcblower
Сохранённая нижняя часть.
\end{mybox}
Используем сохранённое:
\input{saved_part.tex}
Результат:
saved_part.tex: сохранена нижняя часть.Гибкость:
lowerbox=ignored полностью исключает нижнюю часть из обработки, что полезно для оптимизации.redirectlowerto позволяет сохранять контент без побочных эффектов (например, изменения счётчиков).Совместимость:
savelowerto и redirectlowerto нельзя использовать вместе с saveto.Дизайн:
lower separated) можно настроить для разных стилей (например, beamer или raster).tcolorbox| Параметр | Синтаксис | Описание | Пример |
|---|---|---|---|
colframe |
/tcb/colframe=⟨color⟩ |
Цвет рамки бокса. По умолчанию: black!75!white. |
colframe=red |
colback |
/tcb/colback=⟨color⟩ |
Цвет фона содержимого бокса. По умолчанию: black!5!white. |
colback=blue!10 |
colbacktitle |
/tcb/colbacktitle=⟨color⟩ |
Цвет фона заголовка. По умолчанию: black!50!white. |
colbacktitle=green!20 |
colupper |
/tcb/colupper=⟨color⟩ |
Цвет текста верхней части. По умолчанию: black. |
colupper=red!50 |
collower |
/tcb/collower=⟨color⟩ |
Цвет текста нижней части. По умолчанию: black. |
collower=blue!50 |
coltext |
/tcb/coltext=⟨color⟩ |
Устанавливает одинаковый цвет текста для верхней и нижней части. | coltext=purple |
coltitle |
/tcb/coltitle=⟨color⟩ |
Цвет текста заголовка. По умолчанию: white. |
coltitle=yellow |
| Параметр | Синтаксис | Описание | Пример |
|---|---|---|---|
title filled |
`/tcb/title filled=true | false` | Включает/отключает заливку фона заголовка. По умолчанию: false. |
| Параметр | Синтаксис | Описание | Пример |
|---|---|---|---|
fontupper |
/tcb/fontupper=⟨text⟩ |
Устанавливает шрифт для верхней части. | fontupper=\bfseries |
fontlower |
/tcb/fontlower=⟨text⟩ |
Устанавливает шрифт для нижней части. | fontlower=\itshape |
fonttitle |
/tcb/fonttitle=⟨text⟩ |
Устанавливает шрифт для заголовка. | fonttitle=\sffamily |
\begin{tcolorbox}[colframe=red, colback=yellow!10, colbacktitle=blue!20, coltitle=white, title=Цветной бокс]
Это пример цветного tcolorbox.
\tcblower
Нижняя часть с другим цветом текста.
\end{tcolorbox}
\begin{tcolorbox}[fonttitle=\sffamily\bfseries\large, fontupper=\itshape, fontlower=\bfseries, title=Шрифты]
Верхняя часть курсивом.
\tcblower
Нижняя часть жирным.
\end{tcolorbox}
\begin{tcolorbox}[
colframe=green!50!black,
colback=green!10,
colbacktitle=green!40,
coltitle=white,
fonttitle=\bfseries,
title filled=true,
title=Комбинированный пример,
fontupper=\small,
collower=red
]
Верхняя часть мелким шрифтом.
\tcblower
Нижняя часть красным цветом.
\end{tcolorbox}
red!50!white).\bfseries, \itshape и т.д.).title filled автоматически активируется при установке colbacktitle или других связанных с заголовком параметров.coltext удобен для установки единого цвета текста во всем боксе, тогда как colupper и collower позволяют дифференцировать части.tcolorbox| Параметр | Синтаксис | Допустимые значения | Описание | Пример |
|---|---|---|---|---|
halign / halign upper |
/tcb/halign=⟨alignment⟩ |
justify, left, flush left, right, flush right, center, flush center |
Выравнивание верхней части (или всего содержимого, если нет нижней части) | halign=flush center |
halign lower |
/tcb/halign lower=⟨alignment⟩ |
те же, что для halign |
Выравнивание нижней части | halign lower=right |
halign title |
/tcb/halign title=⟨alignment⟩ |
те же, что для halign |
Выравнивание заголовка | halign title=center |
halign code / halign upper code |
/tcb/halign code={⟨code⟩} |
произвольный LaTeX-код | Произвольное выравнивание верхней части | halign code={\raggedright} |
halign lower code |
/tcb/halign lower code={⟨code⟩} |
произвольный LaTeX-код | Произвольное выравнивание нижней части | halign lower code={\centering} |
halign title code |
/tcb/halign title code={⟨code⟩} |
произвольный LaTeX-код | Произвольное выравнивание заголовка | halign title code={\raggedleft} |
| Параметр | Синтаксис | Допустимые значения | Описание | Пример |
|---|---|---|---|---|
valign / valign upper |
/tcb/valign=⟨alignment⟩ |
top, center, bottom, scale, scale* |
Вертикальное выравнивание верхней части | valign=center |
valign lower |
/tcb/valign lower=⟨alignment⟩ |
те же, что для valign |
Вертикальное выравнивание нижней части | valign lower=bottom |
valign scale limit |
/tcb/valign scale limit=⟨real⟩ |
число (по умолчанию 1.1) | Максимальный коэффициент масштабирования для scale* |
valign scale limit=1.5 |
| Команда | Эквивалент | Описание |
|---|---|---|
flushleft upper |
halign=flush left |
Выравнивание верхней части по левому краю |
center upper |
halign=flush center |
Выравнивание верхней части по центру |
flushright upper |
halign=flush right |
Выравнивание верхней части по правому краю |
flushleft lower |
halign lower=flush left |
Выравнивание нижней части по левому краю |
center lower |
halign lower=flush center |
Выравнивание нижней части по центру |
flushright lower |
halign lower=flush right |
Выравнивание нижней части по правому краю |
flushleft title |
halign title=flush left |
Выравнивание заголовка по левому краю |
center title |
halign title=flush center |
Выравнивание заголовка по центру |
flushright title |
halign title=flush right |
Выравнивание заголовка по правому краю |
\begin{tcolorbox}[halign=flush left, title=Пример выравнивания]
Текст, выровненный по левому краю.
\tcblower
Нижняя часть с выравниванием по правому краю.
\end{tcolorbox}
\begin{tcolorbox}[valign=center, height=4cm]
Текст, выровненный по центру по вертикали.
\end{tcolorbox}
\begin{tcolorbox}[halign title=center, title=Центрированный заголовок]
Содержимое бокса.
\end{tcolorbox}
Разница между flush и не-flush версиями:
flush версии используют стандартные LaTeX-команды (\raggedright, \centering, \raggedleft)flush версии реализованы через TikZ и могут давать более сбалансированное расположение с переносамиВертикальное выравнивание имеет смысл только при явно заданной высоте бокса
Параметры scale и scale* масштабируют текст по вертикали, что может быть полезно для точного заполнения пространства
| Команда | Синтаксис | Описание | Пример |
|---|---|---|---|
width |
/tcb/width=⟨length⟩ |
Устанавливает общую ширину бокса | width=\linewidth/2 |
text width |
/tcb/text width=⟨length⟩ |
Устанавливает ширину текста в верхней части | text width=4cm |
add to width |
/tcb/add to width=⟨length⟩ |
Добавляет значение к текущей ширине бокса | add to width=1cm |
| Команда | Синтаксис | Описание | Пример |
|---|---|---|---|
toprule |
/tcb/toprule=⟨length⟩ |
Толщина верхней границы | toprule=3mm |
bottomrule |
/tcb/bottomrule=⟨length⟩ |
Толщина нижней границы | bottomrule=3mm |
leftrule |
/tcb/leftrule=⟨length⟩ |
Толщина левой границы | leftrule=3mm |
rightrule |
/tcb/rightrule=⟨length⟩ |
Толщина правой границы | rightrule=3mm |
titlerule |
/tcb/titlerule=⟨length⟩ |
Толщина линии под заголовком | titlerule=3mm |
boxrule |
/tcb/boxrule=⟨length⟩ |
Устанавливает толщину всех границ | boxrule=3mm |
| Команда | Синтаксис | Описание | Пример |
|---|---|---|---|
arc |
/tcb/arc=⟨length⟩ |
Радиус скругления углов | arc=3mm |
circular arc |
/tcb/circular arc |
Делает бокс круглым (при равных ширине и высоте) | circular arc |
bean arc |
/tcb/bean arc |
Автоматический радиус скругления | bean arc |
octogon arc |
/tcb/octogon arc |
Создает восьмиугольник | octogon arc |
arc is angular |
/tcb/arc is angular |
Заменяет скругления на углы | arc is angular |
arc is curved |
/tcb/arc is curved |
Восстанавливает скругления (по умолчанию) | arc is curved |
outer arc |
/tcb/outer arc=⟨length⟩ |
Внешний радиус скругления | outer arc=1mm |
auto outer arc |
/tcb/auto outer arc |
Автоматический внешний радиус | auto outer arc |
| Команда | Синтаксис | Описание | Пример |
|---|---|---|---|
boxsep |
/tcb/boxsep=⟨length⟩ |
Общий внутренний отступ | boxsep=5mm |
left |
/tcb/left=⟨length⟩ |
Левый отступ для всех частей | left=0mm |
left* |
/tcb/left*=⟨length⟩ |
Левый отступ от границы | left*=0mm |
lefttitle |
/tcb/lefttitle=⟨length⟩ |
Левый отступ заголовка | lefttitle=3cm |
leftupper |
/tcb/leftupper=⟨length⟩ |
Левый отступ верхней части | leftupper=3cm |
leftlower |
/tcb/leftlower=⟨length⟩ |
Левый отступ нижней части | leftlower=3cm |
right |
/tcb/right=⟨length⟩ |
Правый отступ для всех частей | right=2cm |
right* |
/tcb/right*=⟨length⟩ |
Правый отступ от границы | right*=0mm |
righttitle |
/tcb/righttitle=⟨length⟩ |
Правый отступ заголовка | righttitle=2cm |
rightupper |
/tcb/rightupper=⟨length⟩ |
Правый отступ верхней части | rightupper=2cm |
rightlower |
/tcb/rightlower=⟨length⟩ |
Правый отступ нижней части | rightlower=2cm |
top |
/tcb/top=⟨length⟩ |
Верхний отступ | top=0mm |
toptitle |
/tcb/toptitle=⟨length⟩ |
Верхний отступ заголовка | toptitle=3mm |
bottom |
/tcb/bottom=⟨length⟩ |
Нижний отступ | bottom=0mm |
bottomtitle |
/tcb/bottomtitle=⟨length⟩ |
Нижний отступ заголовка | bottomtitle=3mm |
middle |
/tcb/middle=⟨length⟩ |
Отступ между частями | middle=0mm |
| Команда | Синтаксис | Описание | Пример |
|---|---|---|---|
size |
/tcb/size=⟨name⟩ |
Предустановленные размеры: normal, title, small, fbox, tight, minimal |
size=small |
oversize |
/tcb/oversize=⟨length⟩ |
Расширяет ширину за пределы страницы | oversize |
| Команда | Синтаксис | Описание | Пример |
|---|---|---|---|
toggle left and right |
/tcb/toggle left and right=⟨toggle preset⟩ |
Переключает левую и правую стороны (none, forced, evenpage) |
toggle left and right=evenpage |
\begin{tcolorbox}[width=0.5\linewidth, text width=4cm]
Бокс с ограниченной шириной текста
\end{tcolorbox}
\begin{tcolorbox}[
boxrule=2mm,
arc=5mm,
arc is angular,
toprule=3mm,
bottomrule=1mm
]
Бокс с нестандартными границами
\end{tcolorbox}
\begin{tcolorbox}[
boxsep=2mm,
left=1cm,
right*=0mm,
toptitle=5mm
]
Бокс с кастомными отступами
\end{tcolorbox}
\begin{tcolorbox}[size=small, oversize]
Компактный бокс, расширенный за поля
\end{tcolorbox}
\begin{tcolorbox}[
toggle left and right=evenpage,
leftrule=1cm,
rightrule=1mm
]
Бокс с переключением границ на четных страницах
\end{tcolorbox}
| Команда | Синтаксис | Допустимые значения | Описание | Пример |
|---|---|---|---|---|
sharp corners |
/tcb/sharp corners=⟨position⟩ |
northwest, northeast, southwest, southeast, north, south, east, west, downhill, uphill, all |
Делает указанные углы острыми | sharp corners=northwest |
rounded corners |
/tcb/rounded corners=⟨position⟩ |
Те же, что для sharp corners |
Делает указанные углы скругленными (по умолчанию) | rounded corners=all |
sharpish corners |
/tcb/sharpish corners |
- | Делает углы визуально острыми (технически остаются скругленными) | sharpish corners |
rounded corners=all)sharpish corners - это компромиссный вариант, когда углы выглядят острыми, но технически остаются скругленными (влияет на тени и границы)\begin{tcolorbox}[
colback=white,
colframe=blue,
sharp corners=northwest, % только северо-западный угол острый
title=Бокс с острым углом
]
Содержимое бокса
\end{tcolorbox}
\begin{tcolorbox}[
colback=white,
colframe=red,
sharp corners, % все углы острые
title=Полностью острый бокс
]
Содержимое бокса
\end{tcolorbox}
\begin{tcolorbox}[
colback=white,
colframe=green,
sharp corners=north, % верхние углы острые
rounded corners=south, % нижние углы скругленные
title=Комбинированный бокс
]
Содержимое бокса
\end{tcolorbox}
\begin{tcolorbox}[
colback=white,
colframe=purple,
sharpish corners, # углы выглядят острыми
title=Бокс с sharpish corners
]
Содержимое бокса
\end{tcolorbox}
Обычные скругленные углы (rounded corners):
Sharpish corners:
Полностью острые углы (sharp corners):
sharp corners или rounded cornerssharpish corners, если нужен компромисс между внешним видом и поведением тенейborderline)shadow)| Параметр | Синтаксис | Описание | Диапазон значений | Пример |
|---|---|---|---|---|
opacityframe |
/tcb/opacityframe=⟨fraction⟩ |
Прозрачность рамки | 0.0 (полная прозрачность) - 1.0 (непрозрачный) | opacityframe=0.5 |
opacityback |
/tcb/opacityback=⟨fraction⟩ |
Прозрачность фона содержимого | 0.0-1.0 | opacityback=0.3 |
opacitybacktitle |
/tcb/opacitybacktitle=⟨fraction⟩ |
Прозрачность фона заголовка | 0.0-1.0 | opacitybacktitle=0.7 |
opacityfill |
/tcb/opacityfill=⟨fraction⟩ |
Прозрачность заливки (рамка + фон + заголовок) | 0.0-1.0 | opacityfill=0.6 |
opacityupper |
/tcb/opacityupper=⟨fraction⟩ |
Прозрачность текста верхней части | 0.0-1.0 | opacityupper=0.4 |
opacitylower |
/tcb/opacitylower=⟨fraction⟩ |
Прозрачность текста нижней части | 0.0-1.0 | opacitylower=0.8 |
opacitytext |
/tcb/opacitytext=⟨fraction⟩ |
Прозрачность всего текста (верх + низ) | 0.0-1.0 | opacitytext=0.5 |
opacitytitle |
/tcb/opacitytitle=⟨fraction⟩ |
Прозрачность текста заголовка | 0.0-1.0 | opacitytitle=0.9 |
\begin{tcolorbox}[
colframe=blue,
colback=white,
opacityframe=0.3,
opacityback=0.7,
title=Пример прозрачности
]
Этот бокс имеет полупрозрачную рамку и фон
\end{tcolorbox}
\begin{tcolorbox}[
colframe=red,
colbacktitle=yellow,
opacitybacktitle=0.5,
opacitytitle=0.8,
title=Прозрачный заголовок
]
Текст содержимого
\end{tcolorbox}
\begin{tcolorbox}[
opacityupper=0.9,
opacitylower=0.5,
opacityframe=0.6,
opacityback=0.8
]
Верхний текст более непрозрачный
\tcblower
Нижний текст более прозрачный
\end{tcolorbox}
\begin{tcolorbox}[
enhanced jigsaw,
colframe=green!75!black,
colback=green!10!white,
opacityframe=0.4,
opacityback=0.6,
opacitybacktitle=0.8,
opacitytitle=1.0,
title=Сложный пример
]
Бокс с различными настройками прозрачности
\end{tcolorbox}
Визуальные эффекты:
Рекомендации:
Технические ограничения:
Комбинации:
Эти параметры позволяют создавать сложные визуальные эффекты и гибко управлять внешним видом элементов tcolorbox.
| Параметр | Синтаксис | Описание | Пример |
|---|---|---|---|
natural height |
/tcb/natural height |
Естественная высота по содержимому | natural height |
height |
/tcb/height=⟨length⟩ |
Фиксированная высота бокса | height=3cm |
height plus |
/tcb/height plus=⟨length⟩ |
Максимальное увеличение высоты | height plus=1cm |
height from |
/tcb/height from=⟨min⟩ to ⟨max⟩ |
Диапазон высот | height from=2cm to 5cm |
text height |
/tcb/text height=⟨length⟩ |
Высота текстовой области | text height=4cm |
add to height |
/tcb/add to height=⟨length⟩ |
Добавление к текущей высоте | add to height=0.5cm |
add to natural height |
/tcb/add to natural height=⟨length⟩ |
Добавление к естественной высоте | add to natural height=1cm |
height fill |
/tcb/height fill=true|false|maximum |
Заполнение оставшегося пространства | height fill=true |
inherit height |
/tcb/inherit height=⟨fraction⟩ |
Наследование высоты от родителя | inherit height=0.8 |
square |
/tcb/square |
Квадратный бокс (высота=ширине) | square |
| Параметр | Синтаксис | Описание | Пример |
|---|---|---|---|
space |
/tcb/space=⟨fraction⟩ |
Распределение пространства (0-1) | space=0.3 |
space to upper |
/tcb/space to upper |
Все пространство в верхнюю часть | space to upper |
space to lower |
/tcb/space to lower |
Все пространство в нижнюю часть | space to lower |
space to both |
/tcb/space to both |
Равное распределение | space to both |
space to |
/tcb/space to=⟨macro⟩ |
Сохранение пространства в макрос | space to=\myspace |
split |
/tcb/split=⟨fraction⟩ |
Позиция разделителя (0-1) | split=0.7 |
| Параметр | Синтаксис | Описание | Пример |
|---|---|---|---|
equal height group |
/tcb/equal height group=⟨id⟩ |
Группа с одинаковой высотой | equal height group=A |
minimum for equal height group |
/tcb/minimum for equal height group=⟨id⟩:⟨length⟩ |
Минимальная высота группы | minimum for equal height group=A:3cm |
minimum for current equal height group |
/tcb/minimum for current equal height group=⟨length⟩ |
Минимальная высота текущей группы | minimum for current equal height group=2cm |
use height from group |
/tcb/use height from group=⟨id⟩ |
Использование высоты группы | use height from group=A |
\tcbheightfromgroup |
\tcbheightfromgroup{⟨macro⟩}{⟨id⟩} |
Получение высоты группы | \tcbheightfromgroup{\myheight}{A} |
\begin{tcolorbox}[height=4cm, valign=center]
Бокс с фиксированной высотой 4cm
\end{tcolorbox}
\begin{tcolorbox}[equal height group=A]
Первый бокс
\end{tcolorbox}
\begin{tcolorbox}[equal height group=A]
Второй бокс с большим количеством текста, который делает высоту больше
\end{tcolorbox}
\begin{tcolorbox}[height fill]
Бокс заполнит все доступное вертикальное пространство
\end{tcolorbox}
\begin{tcolorbox}[width=3cm, square]
Квадратный бокс 3x3cm
\end{tcolorbox}
\begin{tcolorbox}[height=5cm]
\begin{tcolorbox}[inherit height=0.5]
Бокс с половиной высоты родителя
\end{tcolorbox}
\end{tcolorbox}
height fill) требуется библиотека breakablenatural height - это высота по умолчанию, рассчитываемая автоматическиequal height group все боксы в группе получают высоту самого высокого боксаheight plus позволяет задать максимально возможное увеличение высоты при необходимости| Параметр | Синтаксис | Описание | Пример |
|---|---|---|---|
before title |
/tcb/before title=⟨code⟩ |
Код перед заголовком (с \ignorespaces) |
before title={\textbf{Важно:}~} |
before title* |
/tcb/before title*=⟨code⟩ |
Код перед заголовком (без \ignorespaces) |
before title*={\textbf{Важно:}} |
after title |
/tcb/after title=⟨code⟩ |
Код после заголовка (с \unskip) |
after title={\hfill\small[подпись]} |
after title* |
/tcb/after title*=⟨code⟩ |
Код после заголовка (без \unskip) |
after title*={\quad[подпись]} |
before upper |
/tcb/before upper=⟨code⟩ |
Код перед верхней частью (с \ignorespaces) |
before upper={\begin{quote}} |
before upper* |
/tcb/before upper*=⟨code⟩ |
Код перед верхней частью (без \ignorespaces) |
before upper*=\begin{tabular} |
after upper |
/tcb/after upper=⟨code⟩ |
Код после верхней части (с \unskip) |
after upper={\end{quote}} |
after upper* |
/tcb/after upper*=⟨code⟩ |
Код после верхней части (без \unskip) |
after upper*=\end{tabular} |
before lower |
/tcb/before lower=⟨code⟩ |
Код перед нижней частью (с \ignorespaces) |
before lower={\textbf{Примечание:}} |
before lower* |
/tcb/before lower*=⟨code⟩ |
Код перед нижней частью (без \ignorespaces) |
before lower*=\begin{itemize} |
after lower |
/tcb/after lower=⟨code⟩ |
Код после нижней части (с \unskip) |
after lower={\hfill\footnotesize*} |
after lower* |
/tcb/after lower*=⟨code⟩ |
Код после нижней части (без \unskip) |
after lower*=\end{itemize} |
| Параметр | Синтаксис | Описание | Пример |
|---|---|---|---|
text fill |
/tcb/text fill |
Включает minipage для вертикального выравнивания | text fill |
tabulars |
/tcb/tabulars=⟨preamble⟩ |
Окружает контент tabular* | tabulars={lcr} |
tabulars* |
/tcb/tabulars*={⟨code⟩}{⟨preamble⟩} |
Tabular* с дополнительным кодом | tabulars*={\small}{lcr} |
tabularx |
/tcb/tabularx=⟨preamble⟩ |
Окружает контент tabularx | `tabularx={X |
tabularx* |
/tcb/tabularx*={⟨code⟩}{⟨preamble⟩} |
Tabularx с дополнительным кодом | `tabularx*={\footnotesize}{X |
tikz upper |
/tcb/tikz upper=⟨options⟩ |
Окружает верхнюю часть tikzpicture | tikz upper={scale=0.5} |
tikz lower |
/tcb/tikz lower=⟨options⟩ |
Окружает нижнюю часть tikzpicture | tikz lower={rotate=30} |
tikznode upper |
/tcb/tikznode upper=⟨options⟩ |
Помещает контент в TikZ node | tikznode upper={draw} |
tikznode lower |
/tcb/tikznode lower=⟨options⟩ |
Помещает нижнюю часть в TikZ node | tikznode lower={fill=yellow} |
tikznode |
/tcb/tikznode=⟨options⟩ |
Применяет tikznode к обеим частям | tikznode={shape=circle} |
varwidth upper |
/tcb/varwidth upper=⟨length⟩ |
Окружает varwidth окружением | varwidth upper=5cm |
environment upper |
/tcb/environment upper=⟨name⟩ |
Окружает верхнюю часть указанным окружением | environment upper=itemize |
environment upper args |
/tcb/environment upper args={⟨name⟩}{⟨code⟩} |
Окружение с дополнительными параметрами | environment upper args={tabular}{{cc}} |
environment lower |
/tcb/environment lower=⟨name⟩ |
Окружает нижнюю часть указанным окружением | environment lower=enumerate |
environment lower args |
/tcb/environment lower args={⟨name⟩}{⟨code⟩} |
Окружение с дополнительными параметрами | environment lower args={tabular}{{lr}} |
environment title |
/tcb/environment title=⟨name⟩ |
Окружает заголовок указанным окружением | environment title=center |
environment title args |
/tcb/environment title args={⟨name⟩}{⟨code⟩} |
Окружение с дополнительными параметрами | environment title args={flushright}{} |
\begin{tcolorbox}[
before title={\textbf{Внимание:}~},
after title={\hfill\footnotesize[источник]},
before upper={\textit{Начало текста:}\par},
after upper={\par\hfill\textit{окончание}}
]
Заголовок
\tcblower
Основное содержимое бокса
\end{tcolorbox}
\begin{tcolorbox}[
environment upper=itemize,
environment lower args={tabular}{{ll}}
\item Первый пункт
\item Второй пункт
\tcblower
A & B \\
C & D
\end{tcolorbox}
\begin{tcolorbox}[
tabulars={|l|c|r|},
title=Таблица в боксе
]
Левый & Центр & Правый \\
A & B & C
\end{tcolorbox}
\begin{tcolorbox}[
tikz upper={scale=0.8},
title=TikZ рисунок
]
\draw (0,0) circle (1cm);
\fill (0,0) circle (2pt);
\end{tcolorbox}
* (например, before upper*) не добавляют автоматические пробелы (\ignorespaces/\unskip)tabulars/tabularx требуются соответствующие пакетыtext fill полезен для вертикального выравнивания с \vfillenvironment не работают с другими tcolorbox-окружениями| Параметр | Синтаксис | Описание | Пример |
|---|---|---|---|
overlay |
/tcb/overlay=⟨graphical code⟩ |
Графическое наложение для всех состояний бокса | overlay={\draw[red] (frame.south west) rectangle (frame.north east);} |
no overlay |
/tcb/no overlay |
Отключает все наложения | no overlay |
overlay broken |
/tcb/overlay broken=⟨graphical code⟩ |
Наложение только для разорванных боксов | overlay broken={\draw[dashed] (frame.south west) -- (frame.north east);} |
overlay unbroken |
/tcb/overlay unbroken=⟨graphical code⟩ |
Наложение только для целых боксов | overlay unbroken={\fill[yellow] (frame.center) circle (5mm);} |
overlay first |
/tcb/overlay first=⟨graphical code⟩ |
Наложение для первой части разорванного бокса | overlay first={\node at (frame.center) {First};} |
overlay middle |
/tcb/overlay middle=⟨graphical code⟩ |
Наложение для средних частей разорванного бокса | overlay middle={\node at (frame.center) {Middle};} |
overlay last |
/tcb/overlay last=⟨graphical code⟩ |
Наложение для последней части разорванного бокса | overlay last={\node at (frame.center) {Last};} |
| Параметр | Синтаксис | Описание | Пример |
|---|---|---|---|
overlay unbroken and first |
/tcb/overlay unbroken and first=⟨graphical code⟩ |
Комбинация unbroken и first | overlay unbroken and first={\draw[blue] (frame.south west) -- (frame.north east);} |
overlay middle and last |
/tcb/overlay middle and last=⟨graphical code⟩ |
Комбинация middle и last | overlay middle and last={\draw[green] (frame.south west) -- (frame.north east);} |
overlay unbroken and last |
/tcb/overlay unbroken and last=⟨graphical code⟩ |
Комбинация unbroken и last | overlay unbroken and last={\draw[red] (frame.south west) -- (frame.north east);} |
overlay first and middle |
/tcb/overlay first and middle=⟨graphical code⟩ |
Комбинация first и middle | overlay first and middle={\draw[yellow] (frame.south west) -- (frame.north east);} |
\begin{tcolorbox}[
enhanced,
overlay={\draw[red, line width=2pt] (frame.south west) rectangle (frame.north east);},
title=Пример с наложением
]
Содержимое бокса с красной рамкой
\end{tcolorbox}
\begin{tcolorbox}[
breakable,
overlay first={\node[rotate=45] at (frame.center) {Начало};},
overlay middle={\node[rotate=45] at (frame.center) {Продолжение};},
overlay last={\node[rotate=45] at (frame.center) {Конец};},
title=Разорванный бокс
]
Много текста, который будет разорван на несколько частей...
\end{tcolorbox}
\begin{tcolorbox}[
enhanced,
overlay unbroken and first={\fill[yellow!50] (frame.north west) rectangle ([xshift=2cm]frame.north east);},
title=Комбинированный пример
]
Содержимое бокса с желтой полосой вверху для unbroken/first состояний
\end{tcolorbox}
\begin{tcolorbox}[
enhanced,
overlay={\node[rotate=45,scale=10,text=gray!20] at (frame.center) {ЧЕРНОВИК};},
title=Документ с водяным знаком
]
Текст документа с полупрозрачным водяным знаком
\end{tcolorbox}
enhanced режим из библиотеки skinsframe.north west, title.south и т.д.)breakable) можно задавать разные наложения для разных частейoverlay для элементов, которые должны отображаться всегдаoverlay first/middle/last для разных частейunbroken and first и т.д.) помогают избежать дублирования кода| Параметр | Синтаксис | Описание | Пример |
|---|---|---|---|
floatplacement |
/tcb/floatplacement=⟨values⟩ |
Устанавливает параметры размещения по умолчанию | floatplacement=tbp |
float |
/tcb/float=⟨values⟩ |
Превращает бокс в плавающий объект | float=ht |
float* |
/tcb/float*=⟨values⟩ |
Плавающий объект на всю ширину страницы | float*=b, width=\textwidth |
nofloat |
/tcb/nofloat |
Отключает плавающее поведение | nofloat |
every float |
/tcb/every float={⟨code⟩} |
Код, выполняемый перед каждым плавающим объектом | every float=\centering |
before float |
/tcb/before float={⟨code⟩} |
Код перед началом float-окружения | before float=\small |
after float |
/tcb/after float={⟨code⟩} |
Код после окончания float-окружения | after float=\vspace{1cm} |
\begin{tcolorbox}[
float=htb,
title=Пример плавающего бокса,
colback=blue!5!white,
colframe=blue!75!black
]
Этот бокс будет автоматически размещен в подходящем месте документа
(обычно вверху страницы, если возможно).
\end{tcolorbox}
\begin{tcolorbox}[
float*=t,
width=\textwidth,
title=Широкий плавающий бокс,
colback=green!5!white,
colframe=green!75!black
]
Этот бокс занимает всю ширину страницы и будет размещен вверху.
\end{tcolorbox}
\begin{tcolorbox}[
float,
every float=\centering,
title=Центрированный плавающий бокс,
colback=red!5!white,
colframe=red!75!black
]
Этот плавающий бокс будет центрирован на странице.
\end{tcolorbox}
\begin{tcolorbox}[
float,
before float={\small Начало float-окружения},
after float={\vspace{5mm} Конец float-окружения},
title=Бокс с дополнительным кодом,
colback=yellow!5!white,
colframe=yellow!75!black
]
Этот плавающий бокс имеет дополнительный код до и после.
\end{tcolorbox}
Параметры размещения (для float и float*):
h - здесь (если возможно)t - вверху страницыb - внизу страницыp - на отдельной странице! - принудительное размещениеРазличия между float и float*:
float работает как стандартное плавающее окружениеfloat* предназначен для:
width=\textwidth)Отключение плавающего поведения:
nofloat для возврата к обычному поведениюОсобые случаи:
breakable) every float выполняется перед каждой частьюbefore float и after float позволяют вставить код до/после float-окруженияfloat*every float=\centering полезна для центрирования содержимогоwidth=\textwidthfloat=!b для принудительного размещения внизу)| Параметр | Синтаксис | Описание | Пример |
|---|---|---|---|
before |
/tcb/before=⟨code⟩ |
Код, выполняемый перед боксом | before={\par\medskip} |
after |
/tcb/after=⟨code⟩ |
Код, выполняемый после бокса | after={\par\medskip} |
nobeforeafter |
/tcb/nobeforeafter |
Отключает пробелы до/после бокса | nobeforeafter |
force nobeforeafter |
/tcb/force nobeforeafter |
Принудительно отключает пробелы | force nobeforeafter |
| Параметр | Синтаксис | Описание | Пример |
|---|---|---|---|
before skip balanced |
/tcb/before skip balanced=⟨glue⟩ |
Вертикальный отступ с учетом базовой линии | before skip balanced=1cm |
after skip balanced |
/tcb/after skip balanced=⟨glue⟩ |
Вертикальный отступ после с базовой линией | after skip balanced=1cm |
beforeafter skip balanced |
/tcb/beforeafter skip balanced=⟨glue⟩ |
Отступы до/после с базовой линией | beforeafter skip balanced=0.5cm |
before skip |
/tcb/before skip=⟨glue⟩ |
Простой вертикальный отступ перед | before skip=10pt |
after skip |
/tcb/after skip=⟨glue⟩ |
Простой вертикальный отступ после | after skip=10pt |
beforeafter skip |
/tcb/beforeafter skip=⟨glue⟩ |
Простые отступы до/после | beforeafter skip=10pt |
| Параметр | Синтаксис | Описание | Пример |
|---|---|---|---|
left skip |
/tcb/left skip=⟨length⟩ |
Горизонтальный отступ слева | left skip=1cm |
right skip |
/tcb/right skip=⟨length⟩ |
Горизонтальный отступ справа | right skip=1cm |
leftright skip |
/tcb/leftright skip=⟨length⟩ |
Отступы слева и справа | leftright skip=1cm |
| Параметр | Синтаксис | Описание | Пример |
|---|---|---|---|
baseline |
/tcb/baseline=⟨length⟩ |
Установка базовой линии | baseline=3mm |
box align |
/tcb/box align=⟨alignment⟩ |
Выравнивание бокса (bottom, top, center, base) |
box align=top |
| Параметр | Синтаксис | Описание | Пример |
|---|---|---|---|
ignore nobreak |
`/tcb/ignore nobreak=true | false` | Игнорировать запрет разрыва после заголовка |
before nobreak |
/tcb/before nobreak=⟨code⟩ |
Код перед боксом при запрете разрыва | before nobreak={\noindent} |
parfillskip restore |
`/tcb/parfillskip restore=true | false` | Восстанавливать значение \parfillskip |
\begin{tcolorbox}[
before skip balanced=1cm,
after skip balanced=0.5cm,
colframe=blue
]
Бокс с кастомными отступами
\end{tcolorbox}
\begin{tcolorbox}[
left skip=2cm,
right skip=1cm,
colframe=red
]
Бокс со смещением по горизонтали
\end{tcolorbox}
Текст \begin{tcolorbox}[nobeforeafter, box align=base, colframe=green]
Выровнено по базовой линии
\end{tcolorbox} продолжение текста
\begin{tcolorbox}[
nobeforeafter,
box align=base,
colback=yellow,
colframe=orange
]
Встроенный в текст бокс
\end{tcolorbox} продолжение текста.
*balanced учитывают базовую линию текста для более точного выравниванияnobeforeafter полностью убирает бокс из отдельного абзацаbaseline и box alignskip изменяют bounding box, что может влиять на общий макетnobeforeafter + box align=base*balanced версии отступовignore nobreak\parfillskip используйте parfillskip restore| Параметр | Синтаксис | Описание | Пример |
|---|---|---|---|
enlarge top initially by |
/tcb/enlarge top initially by=⟨length⟩ |
Расширение верхней границы (только для первого бокса) | enlarge top initially by=5mm |
enlarge bottom finally by |
/tcb/enlarge bottom finally by=⟨length⟩ |
Расширение нижней границы (только для последнего бокса) | enlarge bottom finally by=5mm |
enlarge top at break by |
/tcb/enlarge top at break by=⟨length⟩ |
Расширение верхней границы для разорванных частей | enlarge top at break by=3mm |
enlarge bottom at break by |
/tcb/enlarge bottom at break by=⟨length⟩ |
Расширение нижней границы для разорванных частей | enlarge bottom at break by=3mm |
enlarge top by |
/tcb/enlarge top by=⟨length⟩ |
Расширение верхней границы для всех случаев | enlarge top by=5mm |
enlarge bottom by |
/tcb/enlarge bottom by=⟨length⟩ |
Расширение нижней границы для всех случаев | enlarge bottom by=5mm |
enlarge left by |
/tcb/enlarge left by=⟨length⟩ |
Расширение левой границы | enlarge left by=2cm |
enlarge right by |
/tcb/enlarge right by=⟨length⟩ |
Расширение правой границы | enlarge right by=2cm |
enlarge by |
/tcb/enlarge by=⟨length⟩ |
Расширение всех границ | enlarge by=5mm |
| Параметр | Синтаксис | Описание | Пример |
|---|---|---|---|
grow to left by |
/tcb/grow to left by=⟨length⟩ |
Увеличение ширины влево | grow to left by=2cm |
grow to right by |
/tcb/grow to right by=⟨length⟩ |
Увеличение ширины вправо | grow to right by=2cm |
grow sidewards by |
/tcb/grow sidewards by=⟨length⟩ |
Увеличение ширины в обе стороны | grow sidewards by=2cm |
flush left |
/tcb/flush left |
Выравнивание влево | flush left |
flush right |
/tcb/flush right |
Выравнивание вправо | flush right |
center |
/tcb/center |
Центрирование | center |
| Параметр | Синтаксис | Описание | Пример |
|---|---|---|---|
toggle enlargement |
/tcb/toggle enlargement=⟨toggle preset⟩ |
Переключение расширений (none, forced, evenpage) |
toggle enlargement=evenpage |
| Параметр | Синтаксис | Описание | Пример |
|---|---|---|---|
spread inwards |
/tcb/spread inwards=⟨length⟩ |
Растягивание к внутреннему краю страницы | spread inwards=5mm |
spread outwards |
/tcb/spread outwards=⟨length⟩ |
Растягивание к внешнему краю страницы | spread outwards=5mm |
move upwards |
/tcb/move upwards=⟨length⟩ |
Перемещение к верхнему краю (с новой страницы) | move upwards=5mm |
move upwards* |
/tcb/move upwards*=⟨length⟩ |
Перемещение к верхнему краю (без новой страницы) | move upwards*=5mm |
fill downwards |
/tcb/fill downwards=⟨length⟩ |
Заполнение до нижнего края | fill downwards=5mm |
spread upwards |
/tcb/spread upwards=⟨length⟩ |
Комбинация: вверх + внутрь + наружу | spread upwards=5mm |
spread upwards* |
/tcb/spread upwards*=⟨length⟩ |
То же без новой страницы | spread upwards*=5mm |
spread sidewards |
/tcb/spread sidewards=⟨length⟩ |
Растягивание в стороны | spread sidewards=5mm |
spread |
/tcb/spread=⟨length⟩ |
Заполнение всей страницы | spread=5mm |
spread downwards |
/tcb/spread downwards=⟨length⟩ |
Комбинация: вниз + внутрь + наружу | spread downwards=5mm |
| Параметр | Синтаксис | Описание | Пример |
|---|---|---|---|
shrink tight |
/tcb/shrink tight |
Плотное облегание содержимого | shrink tight |
extrude left by |
/tcb/extrude left by=⟨length⟩ |
Выступание влево | extrude left by=1cm |
extrude right by |
/tcb/extrude right by=⟨length⟩ |
Выступание вправо | extrude right by=1cm |
extrude top by |
/tcb/extrude top by=⟨length⟩ |
Выступание вверх | extrude top by=1cm |
extrude bottom by |
/tcb/extrude bottom by=⟨length⟩ |
Выступание вниз | extrude bottom by=1cm |
extrude by |
/tcb/extrude by=⟨length⟩ |
Выступание во все стороны | extrude by=5mm |
\begin{tcolorbox}[
enlarge left by=2cm,
enlarge top by=5mm,
enhanced,
show bounding box
]
Бокс с расширенными границами
\end{tcolorbox}
\begin{tcolorbox}[
spread sidewards,
spread upwards,
height=3cm,
colframe=blue,
sharp corners=north
]
Бокс, растянутый до краев страницы
\end{tcolorbox}
Текст \tcbox[shrink tight, extrude right by=5mm]{с выступающим} элементом
* не создают новую страницуshow bounding boxspread и др.) экономят время настройкиextrude) не изменяют bounding box| Команда / Стиль | Синтаксис | Описание |
|---|---|---|
every box |
\tcbset{every box/.style={...}} |
Стиль, применяемый ко всем tcolorbox (по умолчанию пуст). |
every box on layer n |
\tcbset{every box on layer 1/.style={...}} |
Стиль для конкретного слоя (1-4 по умолчанию). |
every box on higher layers |
\tcbset{every box on higher layers/.style={...}} |
Стиль для слоёв выше управляемых (по умолчанию reset,every box). |
\tcbsetmanagedlayers |
\tcbsetmanagedlayers{<число>} |
Устанавливает максимальный номер управляемого слоя (только в преамбуле). |
\usepackage{tcolorbox}
\tcbset{
every box/.style={enhanced, colframe=blue}, % Базовый стиль
every box on layer 2/.style={colback=yellow}, % Стиль для второго слоя
every box on higher layers/.style={colframe=red} % Стиль для вложенных
}
\begin{tcolorbox}[title=Layer 1]
Внешний блок.
\begin{tcolorbox}[title=Layer 2]
Вложенный блок (жёлтый фон).
\begin{tcolorbox}[title=Layer 3]
Ещё глубже (красная рамка).
\end{tcolorbox}
\end{tcolorbox}
\end{tcolorbox}
reset)\tcbset{
every box/.style={fonttitle=\bfseries},
every box on layer 2/.style={reset, colback=green} % Сброс стилей перед применением
}
\begin{tcolorbox}[title=Layer 1]
Заголовок жирный.
\begin{tcolorbox}[title=Layer 2]
Заголовок НЕ жирный (сброшен), фон зелёный.
\end{tcolorbox}
\end{tcolorbox}
\usepackage{tcolorbox}
\tcbsetmanagedlayers{5} % В преамбуле
\tcbset{
every box on layer 5/.style={colframe=purple}
}
\begin{tcolorbox}[title=Layer 1]
\begin{tcolorbox}[title=Layer 2]
\begin{tcolorbox}[title=Layer 3]
\begin{tcolorbox}[title=Layer 4]
\begin{tcolorbox}[title=Layer 5]
Фиолетовая рамка (5-й слой).
\end{tcolorbox}
\end{tcolorbox}
\end{tcolorbox}
\end{tcolorbox}
\end{tcolorbox}
\tcbsetmanagedlayers работает только в преамбуле.reset, что сбрасывает стили родительского блока.\tcbsetforeverylayer{...}.Capture Mode определяет, как содержимое tcolorbox обрабатывается и отображается.
Доступные режимы:
minipage (по умолчанию для tcolorbox)hbox (по умолчанию для \tcbox)fitbox (требует библиотеку fitting)| Команда / Опция | Синтаксис | Описание |
|---|---|---|
capture=<mode> |
\begin{tcolorbox}[capture=minipage] ... \end{tcolorbox} |
Устанавливает режим обработки содержимого (minipage, hbox, fitbox). |
hbox (стиль) |
\begin{tcolorbox}[hbox] ... \end{tcolorbox} |
Короткая запись для capture=hbox. |
minipage (стиль) |
\begin{tcolorbox}[minipage] ... \end{tcolorbox} |
Короткая запись для capture=minipage. |
fitbox (стиль) |
\begin{tcolorbox}[fitbox] ... \end{tcolorbox} |
Короткая запись для capture=fitbox (требует \tcbuselibrary{fitting}). |
minipage (по умолчанию)\begin{tcolorbox}[
capture=minipage, % можно опустить (стоит по умолчанию)
colframe=blue,
colback=white,
title=Minipage Mode
]
Этот блок ведёт себя как `minipage`.
Можно разбивать на части (`breakable`), добавлять верхнюю и нижнюю части.
\end{tcolorbox}
Особенности:
breakable (разрыв на страницах).upper и lower части.hbox (как \tcbox)\begin{tcolorbox}[
hbox, % короткая запись для capture=hbox
colframe=red,
colback=white,
title=HBox Mode
]
Этот блок ведёт себя как `\hbox` (аналогично `\tcbox`).
\end{tcolorbox}
Особенности:
breakable не работает).fitbox (требует fitting)\usepackage{tcolorbox}
\tcbuselibrary{fitting} % обязательно подключить
\begin{tcolorbox}[
fitbox, % короткая запись для capture=fitbox
height=2cm,
width=6cm,
colframe=green,
colback=white,
title=FitBox Mode
]
Содержимое масштабируется под размер блока.
\end{tcolorbox}
Особенности:
| Режим | Разрыв (breakable) |
Размер | Использование |
|---|---|---|---|
minipage |
Да | Под содержимое | Основные блоки с текстом |
hbox |
Нет | Под содержимое | Компактные блоки (\tcbox) |
fitbox |
Нет | Фиксированный | Блоки с жёсткими размерами |
\documentclass{article}
\usepackage{tcolorbox}
\tcbuselibrary{fitting} % для fitbox
\begin{document}
\begin{tcolorbox}[
minipage, % или capture=minipage
colframe=blue,
title=Minipage Mode,
breakable % можно разрывать
]
Этот блок ведёт себя как `minipage`.
Можно разбивать на страницы и использовать `lower` и `upper` части.
\end{tcolorbox}
\begin{tcolorbox}[
hbox,
colframe=red,
title=HBox Mode
]
Это компактный блок (`\hbox`).
\end{tcolorbox}
\begin{tcolorbox}[
fitbox,
width=5cm,
height=3cm,
colframe=green,
title=FitBox Mode
]
Содержимое подгоняется под размер блока.
\end{tcolorbox}
\end{document}
Результат:
minipage) может быть разорван на страницы.hbox) компактный, без разрывов.fitbox) имеет фиксированный размер.Настройки оформления текста внутри tcolorbox позволяют управлять поведением абзацев, переносом слов и другими текстовыми характеристиками.
| Опция | Синтаксис | Описание | Значение по умолчанию |
|---|---|---|---|
parbox |
parbox=true / parbox=false |
Определяет, будет ли текст обрабатываться как в minipage/parbox (влияет на форматирование абзацев). |
true |
hyphenationfix |
hyphenationfix=true / hyphenationfix=false |
Включает исправление проблем с переносом длинных слов в узких блоках. | false |
parboxВключает/отключает режим parbox (аналогично minipage).
parbox=true (по умолчанию)\begin{tcolorbox}[
parbox=true, % можно не указывать (стоит по умолчанию)
width=0.45\linewidth,
colframe=blue,
title=parbox=true (стандартное поведение)
]
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
\end{tcolorbox}
Особенности:
minipage.parbox=false\begin{tcolorbox}[
parbox=false,
width=0.45\linewidth,
colframe=red,
title=parbox=false (обычный текст)
]
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
\end{tcolorbox}
Особенности:
minipage).hyphenationfixИсправляет проблемы с переносом длинных слов в узких блоках.
hyphenationfix (по умолчанию)\begin{tcolorbox}[
width=3cm,
colframe=green,
title=Без hyphenationfix
]
Rechnungsadjunktentochter.\par
Statthaltereikonzipist.
\end{tcolorbox}
Проблема:
hyphenationfix=true\begin{tcolorbox}[
hyphenationfix=true,
width=3cm,
colframe=green,
title=С hyphenationfix
]
Rechnungsadjunktentochter.\par
Statthaltereikonzipist.
\end{tcolorbox}
Результат:
parbox=false и hyphenationfix вместе — они предназначены для разных типов блоков и могут конфликтовать.parbox=false — экспериментальная опция, применяйте её только при необходимости.hyphenationfix полезен в узких блоках, где pdflatex не справляется с переносом.\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage{tcolorbox}
\usepackage{lipsum} % для демонстрации текста
\begin{document}
\begin{tcolorbox}[
parbox=true,
width=0.45\linewidth,
colframe=blue,
title=parbox=true (стандартное поведение)
]
\lipsum[1][1-3] % Первые три предложения из lipsum
\end{tcolorbox}
\hfill
\begin{tcolorbox}[
parbox=false,
width=0.45\linewidth,
colframe=red,
title=parbox=false (обычный текст)
]
\lipsum[1][1-3]
\end{tcolorbox}
\vspace{1cm}
\begin{tcolorbox}[
width=3cm,
colframe=green,
title=Без hyphenationfix
]
Rechnungsadjunktentochter.\par
Statthaltereikonzipist.
\end{tcolorbox}
\hfill
\begin{tcolorbox}[
hyphenationfix=true,
width=3cm,
colframe=green,
title=С hyphenationfix
]
Rechnungsadjunktentochter.\par
Statthaltereikonzipist.
\end{tcolorbox}
\end{document}
Результат:
parbox=true и parbox=false.hyphenationfix.parbox=true — стандартное поведение (рекомендуется).parbox=false — экспериментальная опция (используйте осторожно).hyphenationfix=true — решает проблемы с переносом длинных слов.Если нужно что-то уточнить или добавить, дайте знать!
В этом разделе рассматривается управление временными файлами, которые используются при работе с tcbwritetemp и \tcbusetemp.
| Опция / Команда | Синтаксис | Описание |
|---|---|---|
tempfile |
tempfile=<имя_файла> |
Устанавливает имя временного файла (по умолчанию: \jobname.tcbtemp). |
\tcbwritetemp |
\tcbwritetemp{<содержимое>} |
Записывает содержимое во временный файл. |
\tcbusetemp |
\tcbusetemp |
Вставляет содержимое временного файла в документ. |
\documentclass{article}
\usepackage{tcolorbox}
\begin{document}
\tcbset{tempfile=mytempfile.tmp} % меняем имя временного файла
\begin{tcolorbox}[title=Пример с временным файлом]
Содержимое блока будет записано в \texttt{mytempfile.tmp} вместо \texttt{\jobname.tcbtemp}.
\end{tcolorbox}
\end{document}
Результат:
Временный файл будет называться mytempfile.tmp вместо стандартного <имя_документа>.tcbtemp.
\documentclass{article}
\usepackage{tcolorbox}
\begin{document}
% Записываем текст во временный файл
\tcbwritetemp{Этот текст будет сохранён во временный файл.}
% Вставляем содержимое временного файла в документ
\begin{tcolorbox}[title=Содержимое временного файла]
\tcbusetemp
\end{tcolorbox}
\end{document}
Результат:
В блоке tcolorbox отобразится текст, записанный через \tcbwritetemp.
Имя файла по умолчанию
Если не указать tempfile, будет использоваться <имя_документа>.tcbtemp (например, document.tcbtemp).
Автоматическое управление
\tcbwritetemp автоматически записывает содержимое в указанный временный файл.\tcbusetemp автоматически вставляет его в документ.Очистка временных файлов
LaTeX не удаляет временные файлы автоматически - их нужно удалять вручную или с помощью скриптов сборки.
\documentclass{article}
\usepackage{tcolorbox}
\begin{document}
% Устанавливаем кастомное имя файла
\tcbset{tempfile=my_custom_tempfile.tmp}
% Пишем текст во временный файл
\tcbwritetemp{
Этот текст был записан во временный файл \texttt{my\_custom\_tempfile.tmp}.
}
% Вставляем содержимое файла в бокс
\begin{tcolorbox}[
colframe=blue,
colback=white,
title=Пример работы с временными файлами,
fonttitle=\bfseries
]
Содержимое временного файла:\\
\tcbusetemp
\end{tcolorbox}
\end{document}
Результат:
my_custom_tempfile.tmpОпция tempfile позволяет:
Команды \tcbwritetemp и \tcbusetemp предоставляют удобный способ:
Для сложных документов рекомендуется явно указывать tempfile, чтобы избежать неожиданных перезаписей.
В этом разделе рассматриваются специальные параметры, которые работают только с командами \tcbox и \tcboxmath.
| Опция / Стиль | Синтаксис | Описание |
|---|---|---|
tcbox raise |
tcbox raise=<длина> |
Поднимает \tcbox на указанную высоту (например, 5mm). |
tcbox raise base |
tcbox raise base |
Выравнивает \tcbox по базовой линии текста. |
on line |
on line |
Комбинация tcbox raise base + nobeforeafter (аналог \fbox). |
\tcbset{colframe=blue!50!black, colback=white}
Test\tcbox[tcbox raise base]{Выровнено по базовой линии} и \tcbox[tcbox raise=2mm]{Приподнято на 2mm}.
| Опция / Стиль | Синтаксис | Описание |
|---|---|---|
verbatim |
verbatim |
Уменьшает размеры \tcbox и включает nobeforeafter + tcbox raise base. |
\DeclareTotalTCBox{\myverb}{ v }{verbatim, colframe=red!75!black}{#1}
Команда \myverb{\textbf} выделяет текст.
tcbox width)| Режим | Описание |
|---|---|
auto |
Ширина определяется содержимым (по умолчанию). |
auto limited |
Ширина как у содержимого, но не больше заданной (width). |
forced center |
Фиксированная ширина (width), текст по центру (может выходить за границы). |
forced left |
Фиксированная ширина, текст по левому краю. |
forced right |
Фиксированная ширина, текст по правому краю. |
minimum center |
Минимальная ширина (width), может увеличиваться. |
minimum left |
Минимальная ширина, текст по левому краю. |
minimum right |
Минимальная ширина, текст по правому краю. |
\tcbset{width=3cm, colframe=blue!75!black}
\tcbox[tcbox width=auto]{auto} \\
\tcbox[tcbox width=forced center]{forced center} \\
\tcbox[tcbox width=minimum left]{minimum left}
Обычный текст \tcbox[tcbox raise base, colframe=green]{Выровнено} и \tcbox[colframe=red]{Не выровнено}.
Результат:
Первая рамка выровнена с текстом, вторая — смещена вниз.
\tcbset{width=4cm, colframe=blue!50!black}
\begin{itemize}
\item \tcbox[tcbox width=auto]{auto} — ширина по содержимому
\item \tcbox[tcbox width=forced center]{forced center} — фиксированная ширина
\item \tcbox[tcbox width=minimum right]{minimum right} — минимальная ширина
\end{itemize}
\DeclareTotalTCBox{\code}{ v }{verbatim, colframe=black}{#1}
Используйте \code{\textbackslash LaTeX} для красивого набора.
\documentclass{article}
\usepackage{tcolorbox}
\begin{document}
\section{Выравнивание}
Обычный текст \tcbox[on line, colframe=blue]{on line} и \tcbox[tcbox raise=3mm, colframe=red]{raise=3mm}.
\section{Управление шириной}
\tcbset{width=5cm, colframe=green!70!black}
\begin{tabular}{ll}
\textbf{Режим} & \textbf{Пример} \\
auto & \tcbox[tcbox width=auto]{Короткий текст} \\
forced center & \tcbox[tcbox width=forced center]{Очень длинный текст, который не помещается} \\
minimum left & \tcbox[tcbox width=minimum left]{Адаптивная ширина} \\
\end{tabular}
\section{Verbatim}
\DeclareTotalTCBox{\cmd}{ v }{verbatim, colframe=black}{#1}
Команда \cmd{\textbf} делает текст жирным.
\end{document}
tcbox raise работает только с \tcbox и \tcboxmath.verbatim стиль уменьшает отступы — используйте для коротких команд.forced режимы могут обрезать текст — применяйте осторожно.on line или tcbox raise base.tcbox width режим.verbatim стиль.Эти настройки дают полный контроль над встроенными цветными рамками в LaTeX!
В этом разделе рассматриваются механизмы работы с нумерацией, перекрёстными ссылками и гиперссылками в рамках tcolorbox.
| Опция | Синтаксис | Описание |
|---|---|---|
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}
| Опция | Синтаксис | Описание |
|---|---|---|
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}
| Опция | Синтаксис | Описание |
|---|---|---|
nameref |
nameref=Моё название |
Текст для \nameref |
short title |
short title=Краткое название |
Устанавливает nameref и list entry |
hypertarget |
hypertarget=mytarget |
Создаёт якорь для гиперссылок |
bookmark |
bookmark=Название |
Добавляет закладку PDF |
index |
index=Термин |
Добавляет запись в индекс |
\newtcolorbox[auto counter]{mybox}[1][]{
colback=white,
title=Блок \thetcbcounter,
#1
}
\begin{mybox}[label=box1]
Первый блок. Ссылка: \ref{box1}.
\end{mybox}
\usepackage{hyperref}
\begin{tcolorbox}[
hypertarget=target1,
title=Кликабельный блок
]
\hyperlink{target2}{Перейти к другому блоку}.
\end{tcolorbox}
\begin{tcolorbox}[
hypertarget=target2,
title=Целевой блок
]
Этот блок будет целью ссылки.
\end{tcolorbox}
\usepackage{imakeidx,bookmark}
\makeindex
\begin{tcolorbox}[
bookmark=Важная теорема,
index=Теоремы,
title=Теорема Пифагора
]
$a^2 + b^2 = c^2$
\end{tcolorbox}
\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}
zlabel требуется пакет zrefphantom код выполняется в группе - используйте \global для глобальных измененийbookmark и index требуют соответствующих пакетовlabel и phantom для перекрёстных ссылокlabel type улучшает работу с cleverefhypertarget и bookmark добавляют интерактивности PDFindex интегрирует боксы в предметный указательВ этом разделе рассматриваются механизмы для различного оформления tcolorbox на чётных и нечётных страницах документа.
| Опция/Команда | Синтаксис | Описание |
|---|---|---|
check odd page |
check odd page=true/false |
Включает точную проверку чётности страницы (требует 2-х компиляций) |
if odd page |
if odd page={нечётные}{чётные} |
Разные стили для чётных/нечётных страниц |
if odd page or oneside |
if odd page or oneside={нечётные}{чётные} |
Для односторонней печати всегда применяет “нечётные” стили |
if odd page* |
if odd page*={нечётные}{чётные} |
Аналог if odd page для breakable-боксов (требует библиотеку breakable) |
\tcbifoddpage |
\tcbifoddpage{нечётный код}{чётный код} |
Условный оператор в коде |
\thetcolorboxnumber |
\thetcolorboxnumber |
Уникальный номер бокса (внутри бокса) |
\thetcolorboxpage |
\thetcolorboxpage |
Номер страницы бокса (требует check odd page=true) |
\begin{tcolorbox}[
if odd page={colback=yellow!30}{colback=blue!30},
title=Блок на \tcbifoddpage{нечётной}{чётной} странице
]
Этот блок будет жёлтым на нечётных и синим на чётных страницах.
Текущая страница: \thetcolorboxpage.
\end{tcolorbox}
\usepackage{tcolorbox}
\tcbuselibrary{breakable}
\begin{tcolorbox}[
breakable,
if odd page*={colback=red!20}{colback=green!20},
title=Разрываемый блок
]
Длинный текст, который может занимать несколько страниц...
Каждая часть будет окрашена в зависимости от чётности страницы.
\end{tcolorbox}
\begin{tcolorbox}[
enhanced,
check odd page,
watermark text={\tcbifoddpage{НЕЧЁТНАЯ}{ЧЁТНАЯ}},
title=Пример с водяным знаком
]
Содержимое блока. Водяной знак покажет чётность страницы.
\end{tcolorbox}
Точность проверки:
check odd page=trueРазрываемые боксы:
if odd page* вместо if odd pageif odd page в extras:\begin{tcolorbox}[
breakable,
check odd page,
extras={if odd page={colback=yellow}{colback=blue}}
]
...
\end{tcolorbox}
oneside используйте if odd page or oneside\documentclass[twoside]{article}
\usepackage{tcolorbox}
\tcbuselibrary{breakable}
\usepackage{lipsum}
\newtcolorbox{smartbox}[1][]{
check odd page,
if odd page*={colback=yellow!10}{colback=blue!10},
colframe=black,
title=Блок на странице \thetcolorboxpage,
#1
}
\begin{document}
\section{Разное оформление для чётных/нечётных страниц}
\begin{smartbox}
Этот блок автоматически меняет цвет в зависимости от страницы.
\begin{itemize}
\item Номер бокса: \thetcolorboxnumber
\item Номер страницы: \thetcolorboxpage
\end{itemize}
\end{smartbox}
\begin{smartbox}[breakable]
\lipsum[1-4]
Длинное содержимое, которое может переноситься на несколько страниц.
Каждая часть будет окрашена соответствующим образом.
\end{smartbox}
\end{document}
Для разного оформления на чётных/нечётных страницах:
if odd page для обычных боксовif odd page* для breakable-боксовcheck odd page=trueСпециальные команды:
\tcbifoddpage - условный оператор в коде\thetcolorboxnumber - уникальный номер бокса\thetcolorboxpage - точный номер страницыДля односторонней печати используйте варианты с or oneside.
В этом разделе рассматривается взаимодействие tcolorbox с системой внешних файлов (externalization) пакета TikZ.
| Опция/Команда | Синтаксис | Описание |
|---|---|---|
shield externalize |
shield externalize=true/false |
Защищает tcolorbox от внешнего экспорта (по умолчанию false) |
external |
external=имя_файла |
Устанавливает имя файла для экспорта TikZ-рисунков внутри бокса |
remake |
remake=true/false |
Форсирует пересоздание внешнего файла для TikZ-рисунка |
\documentclass{article}
\usepackage{tcolorbox}
\usetikzlibrary{external}
\tikzexternalize % Включаем систему внешних файлов
\begin{document}
\begin{tcolorbox}[
shield externalize, % Защищаем сам бокс от экспорта
title=Защищённый бокс
]
Этот tcolorbox не будет экспортирован как внешний файл.
\begin{tikzpicture}
\draw (0,0) circle (1cm); % Этот рисунок БУДЕТ экспортирован
\end{tikzpicture}
\end{tcolorbox}
\end{document}
\begin{tcolorbox}[
external=myplot, % Устанавливаем имя файла для экспорта
remake=true, % Форсируем пересоздание
title=Бокс с управляемым экспортом
]
\begin{tikzpicture}
\draw[red] (0,0) rectangle (2,2); % Экспортируется в myplot.pdf
\end{tikzpicture}
\end{tcolorbox}
Автоматическое отключение в TikZ-окружении:
tikzpicture опция shield externalize автоматически отключается\tikzexternaldisable перед tcolorbox в этом случаеРекомендуемые паттерны использования:
\tikzexternalenable
% Рисунки для экспорта
\tikzexternaldisable
% Обычные tcolorbox
Требования:
\usetikzlibrary{external}
\tikzexternalize
Ограничения:
tikz upper и аналогичные опции, не экспортируются\documentclass{article}
\usepackage{tcolorbox}
\usetikzlibrary{external}
\tikzexternalize % Активируем систему внешних файлов
\tcbset{shield externalize} % Глобально защищаем все tcolorbox
\begin{document}
\section{Пример интеграции с внешними файлами}
\begin{tcolorbox}[title=Обычный защищённый бокс]
Этот блок не будет экспортирован как внешний файл.
\end{tcolorbox}
\begin{tcolorbox}[
external=mycircle,
title=Бокс с экспортируемым рисунком
]
\begin{tikzpicture}
\draw[blue, thick] (0,0) circle (1.5cm);
\node at (0,0) {Экспортируется};
\end{tikzpicture}
\end{tcolorbox}
\tikzexternaldisable % Временно отключаем экспорт
\begin{tcolorbox}[title=Временный незащищённый бокс]
Этот блок создан при отключённом экспорте.
\end{tcolorbox}
\tikzexternalenable % Возобновляем экспорт
\end{document}
Защита боксов:
shield externalize для предотвращения экспорта tcolorbox\tcbset, если не нужен экспортУправление экспортом:
external=имя_файлаremake=trueЛучшие практики:
\tikzexternalenable/disable для группировки экспортируемых элементовЭти механизмы позволяют эффективно комбинировать tcolorbox с системой внешних файлов TikZ, оптимизируя процесс сборки сложных документов.
В этом разделе рассматриваются различные дополнительные функции tcolorbox, которые не вошли в предыдущие категории.
| Опция | Синтаксис | Описание |
|---|---|---|
reset |
reset |
Сбрасывает все настройки tcolorbox к значениям по умолчанию |
\begin{tcolorbox}[reset, title=Блок со сброшенными настройками]
Этот блок игнорирует все предыдущие \tcbset{}
\end{tcolorbox}
| Опция | Синтаксис | Описание |
|---|---|---|
IfBlankTF |
IfBlankTF={текст}{опции если пусто}{опции если не пусто} |
Проверяет на пустоту (пробелы считаются пустотой) |
IfEmptyTF |
IfEmptyTF={текст}{опции если пусто}{опции если не пусто} |
Проверяет на полную пустоту |
IfNoValueTF |
IfNoValueTF={аргумент}{опции если нет значения}{опции если есть} |
Для обработки необязательных аргументов |
IfValueTF |
IfValueTF={аргумент}{опции если есть значение}{опции если нет} |
Обратная версия IfNoValueTF |
IfBooleanTF |
IfBooleanTF={аргумент}{опции если true}{опции если false} |
Для булевых значений |
\DeclareTColorBox{mybox}{o}{%
IfValueTF={#1}{title=#1}{title=Без названия},
colframe=blue
}
\begin{mybox}
Блок без названия
\end{mybox}
\begin{mybox}[Мой заголовок]
Блок с названием
\end{mybox}
| Опция | Синтаксис | Описание |
|---|---|---|
void |
void |
Полностью удаляет бокс (как комментарий) |
nirvana |
nirvana |
Обрабатывает содержимое, но не отображает бокс |
Текст до
\begin{tcolorbox}[void]
Этот блок полностью исчезнет
\end{tcolorbox}
Текст после
\newtcolorbox{smartbox}[1][]{
IfBlankTF={#1}{colback=red!10}{colback=green!10},
title=Умный бокс
}
\begin{smartbox}[]
Будет красным (аргумент пуст)
\end{smartbox}
\begin{smartbox}[X]
Будет зелёным (аргумент не пуст)
\end{smartbox}
\DeclareTColorBox{mybox}{o}{
IfNoValueTF={#1}{title=Стандартный}{title=#1},
colframe=black
}
\begin{mybox}
Стандартный заголовок
\end{mybox}
\begin{mybox}[Кастомный]
Специальный заголовок
\end{mybox}
Текст до
\begin{tcolorbox}[nirvana]
Этот блок обработается, но не будет виден
\begin{tcolorbox}
Вложенный блок (будет виден)
\end{tcolorbox}
\end{tcolorbox}
Текст после
reset:
capture, shield externalize и настройки rasterУсловные операторы:
expl3 и xparsevoid vs nirvana:
void полностью удаляет бокс (как если бы его закомментировали)nirvana обрабатывает содержимое (счётчики и пр.), но не отображаетОграничения:
void нельзя использовать для вложенных боксов с одинаковыми именамиvoid не работает с \tcolorboxenvironment\documentclass{article}
\usepackage{tcolorbox}
\usepackage{xcolor}
% Бокс с условным форматированием
\newtcolorbox{condbox}[1][]{
IfBlankTF={#1}{colback=gray!20}{colback=#1!20},
title=Условный бокс
}
\begin{document}
\section{Примеры разных возможностей}
\begin{condbox}[]
Стандартный серый фон (аргумент пуст)
\end{condbox}
\begin{condbox}[red]
Красный фон (аргумент указан)
\end{condbox}
% Пример с void
Текст до \begin{tcolorbox}[void]Невидимый блок\end{tcolorbox} текст после
% Пример с nirvana
Текст до \begin{tcolorbox}[nirvana]
Невидимый но обработанный блок
\begin{tcolorbox}[colback=yellow]
Вложенный видимый блок
\end{tcolorbox}
\end{tcolorbox} текст после
\end{document}
resetIfBlankTF/IfEmptyTF - проверка на пустотуIfNoValueTF/IfValueTF - работа с аргументамиIfBooleanTF - для булевых флаговvoid - полное удалениеnirvana - скрытие с обработкой содержимогоfontencНазначение: Выбор кодировки шрифтов.
T1 – для западноевропейских языков.T2A – для кириллицы (русский текст).\usepackage[T1,T2A]{fontenc}
inputencНазначение: Указывает кодировку исходного файла.
utf8x – поддержка UTF-8.\usepackage[utf8x]{inputenc}
babelНазначение: Поддержка многоязычных документов (переносы, автоимена разделов).
russian – активирует русскую локализацию.english – резервный язык.\usepackage[english, russian]{babel}
geometryНазначение: Настройка полей и размеров страницы.
Основные параметры:
tmargin, bmargin, lmargin, rmargin – отступы.headsep, headheight – расстояние до верхнего колонтитула.\usepackage{geometry}
\geometry{tmargin=25mm, bmargin=20mm, lmargin=20mm, rmargin=20mm}
fancyhdrНазначение: Настройка колонтитулов.
\pagestyle{fancy} – активирует стиль.\lhead, \chead, \rhead – левый/центральный/правый верхний колонтитул.\lfoot, \cfoot, \rfoot – нижний колонтитул.\usepackage{fancyhdr}
\pagestyle{fancy}
\lhead{Левый заголовок}
\rfoot{Страница \thepage}
amsmath, amsthm, amssymbНазначение: Расширенная математическая вёрстка.
amsmath – улучшенные уравнения (align, gather).amssymb – дополнительные символы (\mathbb, \mathcal).amsthm – теоремы (\newtheorem).\begin{align}
a &= b + c \\
E &= mc^2
\end{align}
wasysymНазначение: Дополнительные символы (например, \diameter для диаметра).
graphicxНазначение: Вставка изображений.
\includegraphics[width=5cm]{image.png} – вставка с масштабированием.\usepackage{graphicx}
\graphicspath{{images/}} % путь к изображениям
floatНазначение: Улучшенное управление позиционированием плавающих объектов (рисунков, таблиц).
subcaptionНазначение: Подписи к нескольким изображениям в одной фигуре.
Пример:
\begin{figure}
\begin{subfigure}{0.5\textwidth}
\includegraphics{img1.png}
\caption{Первое изображение}
\end{subfigure}
\begin{subfigure}{0.5\textwidth}
\includegraphics{img2.png}
\caption{Второе изображение}
\end{subfigure}
\caption{Два изображения}
\end{figure}
multirow, colortbl, hhlineНазначение: Сложные таблицы.
\multirow – объединение строк.\colortbl – цветные ячейки.\hhline – двойные линии.\begin{tabular}{|c|c|}
\hline
\multirow{2}{*}{Объединённые строки} & Текст \\ \cline{2-2}
& Ещё текст \\ \hline
\end{tabular}
hyperrefНазначение: Интерактивные ссылки в PDF.
\href{url}{текст} – гиперссылка.\autoref{label} – автоматические подписи (“Рисунок 1”).\usepackage{hyperref}
\hypersetup{colorlinks=true, linkcolor=blue}
variorefНазначение: Умные ссылки (“на стр. 5”).
imakeidxНазначение: Создание индекса.
\makeindex – активация.\index{ключ} – добавление записи.\usepackage{imakeidx}
\makeindex
...
\printindex
ulemНазначение: Дополнительное оформление текста.
\sout{текст} – зачёркивание.\uline{текст} – подчёркивание.indentfirstНазначение: Автоматический отступ у первого абзаца.
multicolНазначение: Многоколоночная вёрстка.
Пример:
\begin{multicols}{2}
Текст в две колонки...
\end{multicols}
tikzНазначение: Создание векторной графики прямо в LaTeX.
Пример:
\begin{tikzpicture}
\draw (0,0) -- (1,1);
\end{tikzpicture}
xcolorНазначение: Работа с цветами.
\textcolor{red}{текст} – цвет текста.LaTeX 2ε был выпущен в 1994 году и добавил ряд новых концепций, которые на тот момент были актуальны. Эти концепции описаны в документе usrguide-historic, который в значительной степени остался неизменным. С тех пор команда LaTeX работала над рядом идей, в первую очередь над языком программирования для LaTeX (expl3), а затем над рядом инструментов для авторов документов, которые основываются на этом языке. Здесь мы описываем стабильные и широко используемые концепции, которые стали результатом этой работы. Эти «новые» идеи были перенесены из пакетов разработки в ядро LaTeX 2ε. Таким образом, они теперь доступны всем пользователям LaTeX и имеют такую же стабильность, как и любая другая часть ядра. Тот факт, что «за кулисами» они построены на основе expl3, полезен для команды разработчиков, но не имеет прямого значения для пользователей.
Создание команд и окружений документа с использованием инструментария LaTeX3 основано на идее, что общий набор описаний может быть использован для охвата почти всех типов аргументов, используемых в реальных документах. Таким образом, парсинг сводится к простому описанию того, какие аргументы принимает команда: это описание обеспечивает «связь» между синтаксисом документа и реализацией команды.
Сначала мы опишем типы аргументов, затем перейдем к объяснению того, как их можно использовать для создания как команд документа, так и окружений. Затем будут описаны различные более специализированные функции, которые позволяют еще более богатое применение простого интерфейса.
Детали, приведенные здесь, предназначены для помощи пользователям в создании команд документа в общем. Более технические детали, подходящие для программистов TeX, включены в раздел interface3.
Для того чтобы каждый аргумент можно было определить независимо, парсеру необходимо знать не только количество аргументов для функции, но и природу каждого из них. Это достигается путем построения спецификации аргумента, которая определяет количество аргументов, тип каждого аргумента и любую дополнительную информацию, необходимую парсеру для чтения пользовательского ввода и правильной передачи его во внутренние функции.
Основная форма спецификатора аргумента — это список букв, где каждая буква определяет тип аргумента. Как будет описано ниже, некоторые типы требуют дополнительной информации, такой как значения по умолчанию. Типы аргументов можно разделить на две категории: те, которые определяют обязательные аргументы (возможно, вызывая ошибку, если они не найдены), и те, которые определяют необязательные аргументы.
m
Стандартный обязательный аргумент, который может быть либо единственным токеном, либо несколькими токенами, заключенными в фигурные скобки {}. Независимо от ввода, аргумент будет передан во внутренний код без внешних скобок. Это спецификатор типа для обычного аргумента TeX.
r
Указывается как r⟨token1⟩⟨token2⟩, это обозначает «обязательный» аргумент с разделителями, где разделителями являются ⟨token1⟩ и ⟨token2⟩. Если открывающий разделитель ⟨token1⟩ отсутствует, будет вставлен маркер по умолчанию -NoValue- после соответствующей ошибки.
R
Указывается как R⟨token1⟩⟨token2⟩{⟨default⟩}, это «обязательный» аргумент с разделителями, как и r, но он имеет определяемое пользователем значение по умолчанию ⟨default⟩ вместо -NoValue-.
v
Читает аргумент «дословно» между следующим символом и его следующим вхождением, аналогично аргументу команды LaTeX 2ε \verb. Таким образом, аргумент типа v читается между двумя одинаковыми символами, которые не могут быть %, , #, {, } или ␣. Дословный аргумент также может быть заключен в фигурные скобки { и }. Команда с дословным аргументом вызовет ошибку, если она появится внутри аргумента другой команды.
b
Подходит только в спецификации аргумента окружения, обозначает тело окружения, между \begin{⟨environment⟩} и \end{⟨environment⟩}. См. раздел 2.11 для подробностей.
o
Стандартный необязательный аргумент LaTeX, заключенный в квадратные скобки, который будет предоставлять специальный маркер -NoValue-, если не указан (как будет описано позже).
d
Указывается как d⟨token1⟩⟨token2⟩, необязательный аргумент, который ограничен ⟨token1⟩ и ⟨token2⟩. Как и в случае с o, если значение не указано, возвращается специальный маркер -NoValue-.
O
Указывается как O{⟨default⟩}, аналогично o, но возвращает ⟨default⟩, если значение не указано.
D
Указывается как D⟨token1⟩⟨token2⟩{⟨default⟩}, аналогично d, но возвращает ⟨default⟩, если значение не указано. Внутренне типы o, d и O являются сокращениями для соответствующим образом сконструированного аргумента типа D.
s
Необязательная звезда(*), которая приведет к значению \BooleanTrue, если звезда присутствует, и \BooleanFalse в противном случае (как будет описано позже).
t
Необязательный ⟨token⟩, который приведет к значению \BooleanTrue, если ⟨token⟩ присутствует, и \BooleanFalse в противном случае. Указывается как t⟨token⟩.
e
Указывается как e{⟨tokens⟩}, набор необязательных украшений, каждое из которых требует значения. Если украшение отсутствует, возвращается -NoValue-. Каждое украшение дает один аргумент, упорядоченный в соответствии со списком ⟨tokens⟩ в спецификации аргумента. Все ⟨tokens⟩ должны быть различными.
E
Аналогично e, но возвращает одно или несколько ⟨defaults⟩, если значения не указаны: E{⟨tokens⟩}{⟨defaults⟩}. См. раздел 2.7 для получения дополнительных деталей.
В дополнение к типам аргументов, обсужденным выше, описание аргументов также придает специальное значение трем другим символам.
Во-первых, + используется для того, чтобы сделать аргумент длинным (принимать параграфные токены). В отличие от \newcommand, это применяется на основе каждого отдельного аргумента. Таким образом, модификация примера на «s o o +m O{default}» означает, что обязательный аргумент теперь является \long, в то время как необязательные аргументы таковыми не являются.
Во-вторых, ! используется для управления тем, разрешены ли пробелы перед необязательными аргументами. Здесь есть некоторые тонкости, так как сам TeX имеет ограничения на то, где пробелы могут быть «обнаружены»: более подробная информация приведена в разделе 2.6.
В-третьих, = используется для объявления того, что следующий аргумент должен интерпретироваться как серия ключевых значений (keyvals). См. раздел 2.9 для получения дополнительных деталей.
Наконец, символ > используется для объявления так называемых «процессоров аргументов», которые могут быть использованы для модификации содержимого аргумента перед его передачей в определение макроса. Использование процессоров аргументов является несколько продвинутой темой (или, по крайней мере, менее часто используемой функцией) и рассматривается в разделе 2.10.
Вот перевод раздела 2.4 “Создание команд и окружений документа”:
\NewDocumentCommand {⟨cmd⟩} {⟨arg spec⟩} {⟨code⟩}
\RenewDocumentCommand {⟨cmd⟩} {⟨arg spec⟩} {⟨code⟩}
\ProvideDocumentCommand {⟨cmd⟩} {⟨arg spec⟩} {⟨code⟩}
\DeclareDocumentCommand {⟨cmd⟩} {⟨arg spec⟩} {⟨code⟩}
Эта группа команд используется для создания команды ⟨cmd⟩. Спецификация аргумента для функции задается с помощью ⟨arg spec⟩, а команда использует ⟨code⟩, где #1, #2 и т. д. заменяются на аргументы, найденные парсером.
Пример:
\NewDocumentCommand\chapter{s o m} {
\IfBooleanTF{#1}
{\typesetstarchapter{#3}}
{\typesetnormalchapter{#2}{#3}}
}
Это способ определения команды \chapter, которая будет вести себя аналогично текущей команде LaTeX 2ε (за исключением того, что она будет принимать необязательный аргумент, даже когда был распарсен символ *). Команда \typesetnormalchapter может проверить свой первый аргумент на наличие значения -NoValue-, чтобы определить, присутствует ли необязательный аргумент. (См. раздел 2.8 для деталей о \IfBooleanTF и проверке на -NoValue-.)
Разница между версиями \New…, \Renew…, \Provide… и \Declare… заключается в поведении, если ⟨cmd⟩ уже определена.
Если ⟨cmd⟩ не может быть предоставлена как единый токен, но требует «конструирования», вы можете использовать \ExpandArgs, как объясняется в разделе 4, который также дает пример, в котором это необходимо.
\NewDocumentEnvironment {⟨env⟩} {⟨arg spec⟩} {⟨beg-code⟩} {⟨end-code⟩}
\RenewDocumentEnvironment {⟨env⟩} {⟨arg spec⟩} {⟨beg-code⟩} {⟨end-code⟩}
\ProvideDocumentEnvironment {⟨env⟩} {⟨arg spec⟩} {⟨beg-code⟩} {⟨end-code⟩}
\DeclareDocumentEnvironment {⟨env⟩} {⟨arg spec⟩} {⟨beg-code⟩} {⟨end-code⟩}
Эти команды работают так же, как \NewDocumentCommand и т. д., но создают окружения (\begin{⟨env⟩} … \end{⟨env⟩}). Как ⟨beg-code⟩, так и ⟨end-code⟩ могут получать доступ к аргументам, как определено в ⟨arg spec⟩. Аргументы будут переданы после \begin{⟨env⟩}. Все пробелы в начале и в конце {⟨env⟩} удаляются перед определением, таким образом:
\NewDocumentEnvironment{foo}
и
\NewDocumentEnvironment{ foo }
оба создают одно и то же окружение «foo».
В отличие от команд, созданных с помощью \newcommand в LaTeX 2ε, необязательные аргументы, созданные с помощью \NewDocumentCommand, могут безопасно вкладываться. Таким образом, например, после
\NewDocumentCommand\foo{om}{I grabbed ‘#1’ and ‘#2’}
\NewDocumentCommand\baz{o}{#1-#1}
использование команды как
\foo[\baz[stuff]]{more stuff}
выведет
I grabbed ‘stuff-stuff’ and ‘more stuff’
Это особенно полезно, когда команда с необязательным аргументом помещается внутри необязательного аргумента второй команды.
Когда необязательный аргумент следует за обязательным аргументом с тем же разделителем, парсер выдает предупреждение, поскольку необязательный аргумент не может быть опущен пользователем, тем самым фактически становясь обязательным. Это может касаться аргументов типов o, d, O, D, s, t, e и E, за которыми следуют обязательные аргументы типа r или R.
Значение по умолчанию для аргументов O, D и E может быть результатом захвата другого аргумента. Таким образом, например,
\NewDocumentCommand\foo{O{#2} m}
будет использовать обязательный аргумент в качестве значения по умолчанию для ведущего необязательного аргумента.
TeX найдет первый аргумент после имени функции независимо от любых промежуточных пробелов. Это верно как для обязательных, так и для необязательных аргументов. Таким образом, \foo[arg] и \foo␣[arg] эквивалентны. Пробелы также игнорируются при сборе аргументов до последнего обязательного аргумента, который должен существовать. Поэтому после
\NewDocumentCommand\foo{m o m}{ ... }
ввод пользователя \foo{arg1}[arg2]{arg3} и \foo{arg1}␣[arg2]␣{arg3} будут парситься одинаково.
Поведение необязательных аргументов после любых обязательных аргументов можно настроить. Стандартные настройки позволят пробелы здесь, и таким образом, с
\NewDocumentCommand\foobar{m o}{ ... }
как \foobar{arg1}[arg2], так и \foobar{arg1}␣[arg2] найдут необязательный аргумент. Это можно изменить, добавив модификатор ! в спецификацию аргументов:
\NewDocumentCommand\foobar{m !o}{ ... }
где \foobar{arg1}␣[arg2] не найдет необязательный аргумент.
Существует одна тонкость, связанная с различием в обработке TeX «управляющих символов», когда имя команды состоит из одного символа, например, ‘\’. Пробелы здесь не игнорируются TeX, и, таким образом, возможно, чтобы необязательный аргумент следовал непосредственно за такой командой. Наиболее распространенный пример — использование \ в окружениях amsmath, которое в терминах здесь будет определено как
\NewDocumentCommand\\{!s !o}{ ... }
Также стоит отметить, что при использовании необязательных аргументов в последней позиции TeX обязательно будет заглядывать вперед для открытия токена аргумента. Это означает, что значение \inputlineno будет «сдвинуто на один», если такой завершающий необязательный аргумент отсутствует и команда заканчивает строку; оно будет на единицу больше, чем номер строки, содержащей последний обязательный аргумент.
Аргумент типа E позволяет задавать одно значение по умолчанию для каждого тестового токена. Это достигается путем указания списка значений по умолчанию для каждой записи в списке, например:
E{^_}{{UP}{DOWN}}
Если список значений по умолчанию короче списка тестовых токенов, будет возвращен специальный маркер -NoValue- (как и для аргумента типа e). Таким образом, например:
E{^_}{{UP}}
имеет значение по умолчанию UP для тестового символа ^, но вернет маркер -NoValue- в качестве значения по умолчанию для _. Это позволяет смешивать явные значения по умолчанию с проверкой на отсутствие значений.
Необязательные аргументы используют специальные переменные для возврата информации о природе полученного аргумента.
\IfNoValueTF {⟨arg⟩} {⟨true code⟩} {⟨false code⟩}
\IfNoValueT {⟨arg⟩} {⟨true code⟩}
\IfNoValueF {⟨arg⟩} {⟨false code⟩}
Команды \IfNoValue(TF) используются для проверки, является ли ⟨argument⟩ (#1, #2 и т. д.) специальным маркером -NoValue-. Например:
\NewDocumentCommand\foo{o m} {
\IfNoValueTF {#1}
{\DoSomethingJustWithMandatoryArgument{#2}}
{\DoSomethingWithBothArguments{#1}{#2}}
}
будет использовать другую внутреннюю функцию, если необязательный аргумент задан, чем если он отсутствует.
Обратите внимание, что доступны три теста, в зависимости от того, какие ветви результата требуются: \IfNoValueTF, \IfNoValueT и \IfNoValueF. Поскольку тесты \IfNoValue(TF) являются расширяемыми, возможно проверять эти значения позже, например, в момент верстки или в контексте расширения.
Важно отметить, что -NoValue- сконструирован таким образом, что он не будет соответствовать простому текстовому вводу -NoValue-, т.е.
\IfNoValueTF{-NoValue-}
будет логически ложным. Когда два необязательных аргумента следуют друг за другом (синтаксис, который мы обычно не рекомендуем), может иметь смысл позволить пользователям команды указывать только второй аргумент, предоставив пустой первый аргумент. Вместо того чтобы отдельно проверять на пустоту и на -NoValue-, лучше использовать тип аргумента O с пустым значением по умолчанию, а затем проверять на пустоту, используя условие \IfBlankTF (описанное ниже).
\IfValueTF {⟨arg⟩} {⟨true code⟩} {⟨false code⟩}
\IfValueT {⟨arg⟩} {⟨true code⟩}
\IfValueF {⟨arg⟩} {⟨false code⟩}
Обратная форма тестов \IfNoValue(TF) также доступна как \IfValue(TF). Контекст определит, какая логическая форма имеет наибольший смысл для данного сценария кода.
\IfBlankTF {⟨arg⟩} {⟨true code⟩} {⟨false code⟩}
\IfBlankT {⟨arg⟩} {⟨true code⟩}
\IfBlankF {⟨arg⟩} {⟨false code⟩}
Команда \IfNoValueTF выбирает ⟨true code⟩, если необязательный аргумент вообще не использовался (и возвращает специальный маркер -NoValue-), но не если ему было дано пустое значение. В отличие от этого, \IfBlankTF возвращает true, если его аргумент либо действительно пуст, либо содержит один или несколько обычных пробелов. Например:
\NewDocumentCommand\foo{m!o}{\par #1:
\IfNoValueTF{#2}
{No optional}%
{%
\IfBlankTF{#2}
{Blanks in or empty}%
{Real content in}%
}%
\space argument!}
\foo{1}[bar] \foo{2}[ ] \foo{3}[] \foo{4}[\space] \foo{5}[x]
результирует в следующем выводе:
1: Real content in argument!
2: Blanks in or empty argument!
3: Blanks in or empty argument!
4: Real content in argument!
5: No optional argument! [x]
Обратите внимание, что \space в (4) считается реальным содержимым — потому что это команда, а не символ «пробел» — даже если это приводит к созданию пробела. Вы также можете наблюдать в (5) эффект спецификатора !, предотвращающего последнюю \foo от интерпретации [x] как своего необязательного аргумента.
\BooleanFalse
\BooleanTrue
Флаги истинности и ложности, устанавливаемые при поиске необязательного символа (с использованием s или t⟨char⟩), имеют имена, которые доступны вне блоков кода.
\IfBooleanTF {⟨arg⟩} {⟨true code⟩} {⟨false code⟩}
\IfBooleanT {⟨arg⟩} {⟨true code⟩}
\IfBooleanF {⟨arg⟩} {⟨false code⟩}
Эти команды используются для проверки, является ли ⟨argument⟩ (#1, #2 и т. д.) равным \BooleanTrue или \BooleanFalse. Например:
\NewDocumentCommand\foo{sm} {
\IfBooleanTF {#1}
{\DoSomethingWithStar{#2}}
{\DoSomethingWithoutStar{#2}}
}
Этот код проверяет наличие звезды в качестве первого аргумента, а затем выбирает действие на основе этой информации.
Некоторые команды документа имеют долгую историю принятия необязательного аргумента в виде «свободного текста», например, \caption и команды секционирования \section и т.д. Введение более сложных (keyval) опций для этих команд требует метода интерпретации необязательного аргумента как свободного текста или как серии ключевых значений. Это должно происходить во время захвата аргумента, так как необходимо аккуратно обрабатывать фигурные скобки для получения правильного результата.
Модификатор = доступен для того, чтобы позволить ltcmd правильно реализовать этот процесс. Модификатор гарантирует, что аргумент будет передан в дальнейший код как серия ключевых значений. Для этого = должен быть за ним, за которым следует аргумент, содержащий имя ключа по умолчанию. Это используется как ключ в паре ключ-значение, если «сырой» аргумент не имеет правильной формы для интерпретации как набора ключевых значений.
\captionРассмотрим \caption в качестве примера с демонстрационной реализацией:
\DeclareDocumentCommand \caption {s ={short-text} +O{#3} +m} {%
\showtokens{Grabbed arguments:^^J(#2)^^Jand^^J(#3)}%
}
Имя ключа по умолчанию — short-text. Когда команда \caption используется, если необязательный аргумент является свободным текстом, например:
\caption[Некоторый короткий текст]{Длинный и более детализированный текст для демонстрационных целей}
то вывод будет:
Grabbed arguments: (short-text={Некоторый короткий текст}) and (Длинный и более детализированный текст для демонстрационных целей)
С другой стороны, если заголовок задан с аргументом в формате ключ-значение:
\caption[label = cap:demo]{Длинный и более детализированный текст для демонстрационных целей}
то это будет учтено:
Grabbed arguments: (label = cap:demo) and (Длинный и более детализированный текст для демонстрационных целей)
Интерпретация как ключ-значение определяется наличием символов = в аргументе. Символы в режиме встроенной математики (включенные в $...$ или \(...\)) игнорируются. Аргумент можно заставить быть прочитанным как ключ-значение, включив пустую запись в начале:
\caption[=,Это теперь ключ-значение]%
\caption[Это не $=$ ключ-значение]%
Эта пустая запись не передается в основной код, поэтому не приведет к проблемам с парсерами ключ-значение, которые не допускают пустое имя ключа. Любые знаки = в текстовом режиме необходимо обрамлять фигурными скобками, чтобы избежать неправильной интерпретации: это, вероятно, наиболее удобно обрабатывать, обрамляя весь аргумент:
\caption[{Не = ключ-значение!}]%
что будет правильно передано как:
Grabbed arguments: (short-text = {Не = ключ-значение!})
Процессоры аргументов применяются к аргументу после его захвата основной системой, но перед передачей в ⟨код⟩. Таким образом, процессор аргументов может использоваться для нормализации ввода на ранней стадии, позволяя внутренним функциям быть полностью независимыми от формы ввода. Процессоры применяются к пользовательскому вводу и к значениям по умолчанию для необязательных аргументов, но не к специальному маркеру -NoValue-.
Каждый процессор аргументов указывается синтаксисом >{⟨процессор⟩} в спецификации аргумента. Процессоры применяются справа налево, так что >{\ProcessorB} >{\ProcessorA} m применит \ProcessorA, а затем \ProcessorB к токенам, захваченным аргументом m.
Этот процессор разделяет аргумент, заданный при каждом вхождении ⟨tokens⟩, до максимума ⟨number⟩ токенов (тем самым деля ввод на ⟨number⟩ + 1 частей). Ошибка будет выдана, если в вводе присутствует слишком много ⟨токенов⟩. Обработанный ввод помещается внутри ⟨number⟩ + 1 наборов фигурных скобок для дальнейшего использования. Если в аргументе меньше, чем ⟨number⟩, то в конце обработанного аргумента добавляются маркеры -NoValue-.
\NewDocumentCommand \foo {>{\SplitArgument{2}{;}} m} {\InternalFunctionOfThreeArguments#1}
Если для разделения используется только один символ ⟨токен⟩, любой символ с кодом категории 13 (активный) совпадающий с ⟨токеном⟩ будет заменен до того, как произойдет разделение. Пробелы обрезаются в начале и в конце каждого элемента, который разбирается.
Тип аргумента E несколько особенный, потому что с одним E в объявлении команды вы можете получить несколько аргументов в команде (по одному формальному аргументу на каждый токен украшения). Поэтому, когда процессор аргументов применяется к аргументу типа e/E, все аргументы проходят через этот процессор перед тем, как быть переданными в ⟨код⟩. Например, эта команда:
\NewDocumentCommand \foo { >{\TrimSpaces} e{_^} } { [#1](#2) }
применяет \TrimSpaces к обоим аргументам.
Этот процессор разделяет аргумент, заданный при каждом вхождении ⟨токенов⟩, где количество элементов не фиксировано. Каждый элемент затем оборачивается в фигурные скобки внутри #1. Результат заключается в том, что обработанный аргумент может быть дополнительно обработан с использованием функции отображения (см. ниже).
\NewDocumentCommand \foo {>{\SplitList{;}} m} {\MappingFunction#1}
Если для разделения используется только один символ ⟨токен⟩, он учтет возможность того, что ⟨токен⟩ был активирован (код категории 13) и будет разделять по таким токенам. Пробелы обрезаются в начале и в конце каждого элемента, который разбирается. Точно один набор фигурных скобок будет удален, если весь элемент окружен ими, т.е. следующие вводы и выводы приводят к результату (каждый отдельный элемент как группа фигурных скобок):
a ==> {a}
{a} ==> {a}
{a}b ==> {{a}b}
a,b ==> {a}{b}
{a},b ==> {a}{b}
a,{b} ==> {a}{b}
a,{b}c ==> {a}{{b}c}
Чтобы поддержать \SplitList, доступна функция \ProcessList, которая применяет ⟨токены⟩ ко всем элементам в ⟨списке⟩. ⟨Токены⟩ могут содержать произвольные данные, которые ожидают один аргумент после них: элемент списка. Например:
\NewDocumentCommand \foo {>{\SplitList{;}} m}
{\ProcessList{#1}{\SomeDocumentCommand}}
или
\NewDocumentCommand \foo {>{\SplitList{;}} m}
{\ProcessList{#1}{Abc \SomeDocumentCommand}}
Этот процессор изменяет логику \BooleanTrue и \BooleanFalse, так что пример из предыдущего раздела будет выглядеть следующим образом:
\NewDocumentCommand\foo{>{\ReverseBoolean} s m} {%
\IfBooleanTF#1%
{\DoSomethingWithoutStar{#2}}%
{\DoSomethingWithStar{#2}}%
}
Удаляет любые ведущие и завершающие пробелы (токены с кодом символа 32 и кодом категории 10) на концах аргумента. Таким образом, например, объявление функции:
\NewDocumentCommand\foo {>{\TrimSpaces} m}
{\showtokens{#1}}
и использование ее в документе как:
\foo{␣hello␣world␣}
покажет «hello␣world» в терминале, при этом пробелы в начале и в конце будут удалены. \TrimSpaces удалит множественные пробелы с концов ввода в случаях, когда они были включены так, что стандартное преобразование TEX, которое сводит множественные пробелы к одному, не применяется.
Хотя окружения \begin{⟨окружение⟩} ... \end{⟨окружение⟩} обычно используются в случаях, когда код, реализующий ⟨окружение⟩, не нуждается в доступе к содержимому окружения (его «телу»), иногда полезно иметь тело в качестве стандартного аргумента. Это достигается путем завершения спецификации аргумента с помощью b, который является специальным типом аргумента для этой ситуации. Например:
\NewDocumentEnvironment{twice} {O{\ttfamily} +b} {#2#1#2} {}
\begin{twice}[\itshape]
Hello world!
\end{twice}
выводит «Hello world!Hello world!».
Префикс + используется для разрешения нескольких абзацев в теле окружения. Процессоры аргументов также могут применяться к аргументам типа b. По умолчанию пробелы обрезаются в начале и в конце тела: в приведенном примере в противном случае будут пробелы, исходящие из концов строк после [\itshape] и world!. Добавление префикса ! перед b подавляет обрезку пробелов.
Когда b используется в спецификации аргумента, последний аргумент объявления окружения (например, \NewDocumentEnvironment), который состоит из ⟨кода завершения⟩ для вставки в \end{⟨окружение⟩}, является избыточным, так как можно просто поместить этот код в конец ⟨кода начала⟩. Тем не менее, этот (пустой) ⟨код завершения⟩ должен быть предоставлен.
Окружения, использующие эту функцию, могут быть вложенными.
Команды документа, созданные с помощью \NewDocumentCommand и т.д., обычно создаются так, чтобы они не расширялись неожиданно. Это достигается с использованием возможностей движка, поэтому это более мощно, чем механизм \protect в LATEX 2ε. Существуют очень редкие случаи, когда может быть полезно создать функции с использованием захватчика, который работает только на расширении. Это накладывает ряд ограничений на природу аргументов, принимаемых функцией, и на код, который она реализует. Эта возможность должна использоваться только в случае необходимости.
\NewExpandableDocumentCommand {⟨cmd⟩} {⟨arg spec⟩} {⟨code⟩}
\RenewExpandableDocumentCommand {⟨cmd⟩} {⟨arg spec⟩} {⟨code⟩}
\ProvideExpandableDocumentCommand {⟨cmd⟩} {⟨arg spec⟩} {⟨code⟩}
\DeclareExpandableDocumentCommand {⟨cmd⟩} {⟨arg spec⟩} {⟨code⟩}
Эта группа команд используется для создания команды документа уровня ⟨cmd⟩, которая будет захватывать свои аргументы в полностью расширяемом режиме. Спецификация аргументов для функции задается с помощью ⟨arg spec⟩, а ⟨cmd⟩ будет выполнять ⟨code⟩. В общем, ⟨code⟩ также будет полностью расширяемым, хотя возможно, что это не так (например, функция для использования в таблице может расширяться так, что \omit будет первым нерасширяемым не-пробельным токеном).
Парсинг аргументов с помощью чистого расширения накладывает ряд ограничений как на типы аргументов, которые могут быть прочитаны, так и на доступную проверку ошибок:
m, r или R.v недоступен.>) недоступны.\foo[ и \foo{[}: в обоих случаях [ будет интерпретироваться как начало необязательного аргумента. В результате проверка на необязательные аргументы менее надежна, чем в стандартной версии.Создание команд, которые используются в начале ячеек таблицы, накладывает некоторые ограничения на основную реализацию. Стандартные окружения LATEX для таблиц (такие как tabular и т.д.) используют механизм, который требует, чтобы любая команда, оборачивающая \multicolumn или подобные команды, была «расширяемой». Это не относится к командам, созданным с помощью \NewDocumentCommand и т.д., которые, как описано в разделе 2.12, используют функцию движка, предотвращающую такое «расширение».
Поэтому, чтобы создать такие обертки для использования в начале ячеек таблицы, необходимо использовать \NewExpandableDocumentCommand. Например:
\NewExpandableDocumentCommand\MyMultiCol{m}{\multicolumn{3}{c}{#1}}
\begin{tabular}{lcr}
a & b & c \\
\MyMultiCol{stuff} \\
\end{tabular}
В этом примере команда \MyMultiCol позволяет использовать \multicolumn в ячейках таблицы, обеспечивая необходимую расширяемость.
Как описано выше, аргумент типа v можно рассматривать как аналог команды \verb. Прежде чем рассмотреть, что это именно означает, важно выделить некоторые ключевые различия. Прежде всего, захват аргумента, подобного verbatim, отделен от его наборки: последнее будет рассмотрено в следующем разделе.
При захвате аргумента типа v LATEX сначала использует команду ядра \dospecials, чтобы отключить «специальный» характер символов. Затем он делает как пробелы, так и табуляции «активными», чтобы им можно было задать пользовательское определение. Все остальные символы захватываются как есть: это означает, что если какие-либо символы были сделаны «специальными» и не перечислены в \dospecials, возникнет ошибка (см. ниже).
Символы, которые захватываются как аргумент, — это все те, что находятся между двумя одинаковыми символами: в отличие от \verb, символы \,, {, } и % не могут использоваться в качестве разделителей. Если любой из захваченных токенов имеет «специальное» значение, будет выдана ошибка.
Для аргумента типа +v, который позволяет переносить строки внутри аргумента, символы новой строки преобразуются в команды \obeyedline. Стандартное определение \obeyedline — это простая команда \par, что позволяет захваченным токенам использоваться непосредственно в наборе. Локальное переопределение \obeyedline может быть использовано для достижения других результатов. Например, чтобы сохранить пустые строки при наборе, можно использовать:
\renewcommand*\obeyedline{\mbox{}\par}
Дополнительная информация о использовании этих аргументов в наборе представлена в следующем подразделе.
Некоторые дополнительные детали, которые могут быть полезны для тех, кто имеет больше знаний о TEX: не беспокойтесь, если это не имеет смысла для вас! Пробелы и табуляции хранятся как активные символы. В 8-битных движках не-ASCII символы являются «активными», в то время как все символы ASCII, кроме букв a–zA–Z, являются «другими». В Юникодных движках не-ASCII кодовые точки будут либо буквами, либо «другими», в зависимости от стандартных настроек LATEX, основанных на данных Юникода. Для сравнений на основе токенов, вероятно, активные пробелы и табуляции должны быть заменены: это можно удобно сделать с помощью расширения.
В отличие от \verb, аргумент типа (+)v касается только захвата аргумента, а не его набора. Таким образом, функции, которые пользователи часто ассоциируют с «verbatim», не активируются автоматически, например, выбор моноширинного шрифта. Материал, захваченный аргументом типа v, не подавляет автоматически лигатуры: с современными движками TEX это в значительной степени можно сделать без манипуляций с токенами, которые использует \verb. (В \verb лигатуры подавляются путем активации символов и вставки нулевой ширины керна перед самим символом.)
Команда \verb также выбирает моноширинный шрифт: это не является внутренним для verbatim-материала, поэтому его нужно настраивать, например, с помощью \ttfamily. Аналогично, окружение verbatim настраивает значение \par, подходящее для переноса строк.
В некоторых случаях, когда вы захватываете тело окружения, вы захотите, чтобы содержимое обрабатывалось как verbatim. Это доступно с использованием спецификации аргумента c. Как и спецификация b, это должно быть последним. Таким образом, например:
\NewDocumentEnvironment{MyVerbatim}{!O{\ttfamily} c} {\begin{center} #1 #2\end{center}} {}
\begin{MyVerbatim}[\ttfamily\itshape]
% Some code is shown here
$y = mx + c$
\end{MyVerbatim}
будет выводить содержимое verbatim, таким образом:
␣␣%␣Some␣code␣is␣shown␣here
␣␣$y␣=␣mx␣+␣c$
Поскольку захват всего содержимого verbatim приведет к отсутствию токенов \par, новые строки всегда разрешены: здесь нет необходимости в модификаторе +. Как и в спецификации v, новые строки хранятся как \obeyedline. Аналогично спецификации b, по умолчанию новые строки обрезаются в начале и в конце тела. Добавление префикса ! перед c подавляет эту обрезку.
Сбор тела происходит построчно: содержимое собирается до конца строки в исходном коде, затем проверяется перед хранением. Это означает, что строка, завершающая окружение (содержащая в приведенном выше примере \end{MyVerbatim}), не может содержать текст после конца окружения. Текст перед концом окружения обрабатывается нормально, но обратите внимание, что если здесь есть текст, то не добавляется завершающий \obeyedline. Кроме необязательных аргументов, текст не допускается на открывающей строке окружения.
Специальная обработка применяется к аргументам с спецификацией o, O, d или D, которые идут сразу перед спецификацией c. Это означает, что когда необязательный аргумент отсутствует, первый символ следующей строки будет прочитан с правильно примененным кодом категории verbatim. Проблемы могут возникнуть, если несколько необязательных аргументов используются перед спецификацией c: это будет работать надежно только в тех случаях, когда необязательные токены являются «другими» символами.
По техническим причинам мы рекомендуем не игнорировать пробелы при поиске необязательного аргумента перед спецификацией c: это можно сделать, добавив модификатор !, как показано в примере. Однако это оставлено на усмотрение пользователя.
Для команд документа, где спецификация аргументов полностью состоит из записей m или +m (или полностью пуста), внутренняя структура, создаваемая с помощью \NewDocumentCommand, по сути, так же эффективна, как и предоставляемая \newcommand(*). Таким образом, команды документа могут заменять конструкции, возникающие из \newcommand и т.д., без необходимости беспокоиться о производительности. Следует отметить, что \newcommand(*) производит расширяемые результаты, поэтому прямой заменой является \NewExpandableDocumentCommand; однако в большинстве случаев лучше использовать \NewDocumentCommand, чтобы обеспечить более надежные структуры.
В обычных (нерасширяемых) командах делимитированные типы ищут начальный разделитель, заглядывая вперед (с использованием функций \peek_... из expl3), ища токен-разделитель. Токен должен иметь то же значение и «форму», что и токен, определенный как разделитель. Существует три возможных случая разделителей: символы, управляющие последовательности и активные символы. Для всех практических целей этого описания активные символы будут вести себя точно так же, как управляющие последовательности.
Символьный токен характеризуется своим кодом символа, а его значение — кодом категории (\catcode). Когда команда определяется, значение символьного токена фиксируется в определении команды и не может изменяться. Команда правильно увидит разделитель аргумента, если открывающий разделитель имеет те же коды символа и категории, что и в момент определения. Например:
\NewDocumentCommand { \foobar } { D<>{default} } {(#1)}
\foobar <hello> \par
\char_set_catcode_letter:N <
\foobar <hello>
вывод будет:
(hello)
(default)<hello>
так как открывающий разделитель < изменил свое значение между двумя вызовами \foobar, поэтому второй вызов не видит < как допустимый разделитель. Команды предполагают, что если был найден допустимый открывающий разделитель, то также будет соответствующий закрывающий разделитель. Если его нет (либо из-за пропуска, либо из-за изменения значения), возникает ошибка низкого уровня TEX, и вызов команды прерывается.
Токен управляющей последовательности (или управляющего символа) характеризуется своим именем, а его значение — это его определение. Токен не может иметь два разных значения одновременно. Когда управляющая последовательность определяется как разделитель в команде, она будет обнаружена как разделитель всякий раз, когда имя управляющей последовательности встречается в документе, независимо от ее текущего определения. Например:
\cs_set:Npn \x { abc }
\NewDocumentCommand { \foobar } { D\x\y{default} } {(#1)}
\foobar \x hello\y \par
\cs_set:Npn \x { def }
\foobar \x hello\y
вывод будет:
(hello)
(hello)
при этом оба вызова команды видят разделитель \x.
Процессоры аргументов позволяют манипулировать захваченным аргументом перед его передачей в основной код. Новые реализации процессоров могут быть созданы в виде функций, которые принимают один завершающий аргумент и оставляют свой результат в переменной \ProcessedArgument.
Например, \ReverseBoolean определяется следующим образом:
\ExplSyntaxOn
\cs_new_protected:Npn \ReverseBoolean #1 {
\bool_if:NTF #1 {
\tl_set:Nn \ProcessedArgument { \c_false_bool }
} {
\tl_set:Nn \ProcessedArgument { \c_true_bool }
}
}
\ExplSyntaxOff
Примечание: Код написан на языке expl3, поэтому нам не нужно беспокоиться о том, что пробелы могут попасть в определение.
Если вы хотите (слегка) изменить существующую команду, вам может понадобиться сохранить текущее определение под новым именем, а затем использовать его в новом определении. Если существующая команда является робустной, то старый трюк с использованием низкоуровневой команды \let не сработает, потому что он копирует только верхнее определение, но не ту часть, которая фактически выполняет работу. Поскольку большинство команд LATEX в настоящее время являются робустными, LATEX предлагает некоторые высокоуровневые объявления для этого.
Однако, пожалуйста, обратите внимание, что обычно лучше использовать доступные хуки (например, хуки для общих команд или окружений), вместо того чтобы копировать текущее определение и тем самым замораживать его; смотрите документацию по управлению хуками lthooks-doc.pdf для получения подробной информации.
\NewCommandCopy {⟨cmd⟩} {⟨existing-cmd⟩}
\RenewCommandCopy {⟨cmd⟩} {⟨existing-cmd⟩}
\DeclareCommandCopy {⟨cmd⟩} {⟨existing-cmd⟩}
Эти команды копируют определение ⟨existing-cmd⟩ в ⟨cmd⟩. После этого ⟨existing-cmd⟩ может быть переопределен, и ⟨cmd⟩ все еще будет работать! Это позволяет вам предоставить новое определение для ⟨existing-cmd⟩, которое использует ⟨cmd⟩ (т.е. его старое определение). Например, после
\NewCommandCopy\LaTeXorig\LaTeX
\RenewDocumentCommand\LaTeX{}{\textcolor{blue}{\LaTeXorig}}
все логотипы LATEX, сгенерированные с помощью \LaTeX, будут отображаться синим цветом (при условии, что у вас загружен пакет цвета).
Различия между \New... и \Renew... такие же, как и в других случаях: вы получите ошибку в зависимости от того, существует ли уже ⟨cmd⟩, или в случае \Declare... оно будет скопировано независимо от этого. Обратите внимание, что нет объявления \Provide..., потому что это было бы ограниченной ценностью.
Если ⟨cmd⟩ или ⟨existing-cmd⟩ не могут быть предоставлены как единый токен, а требуют “конструирования”, вы можете использовать \ExpandArgs, как объясняется в разделе 4.
Эта команда отображает значение ⟨cmd⟩ в терминале и затем останавливается (так же, как и примитивная \show). Разница в том, что она правильно показывает значение более сложных команд, например, в случае робустных команд она отображает не только верхнее определение, но и фактический код нагрузки, а в случае команд, объявленных с помощью \NewDocumentCommand и т.д., она также предоставляет подробную информацию о сигнатуре аргументов.
\NewEnvironmentCopy {⟨env⟩} {⟨existing-env⟩}
\RenewEnvironmentCopy {⟨env⟩} {⟨existing-env⟩}
\DeclareEnvironmentCopy {⟨env⟩} {⟨existing-env⟩}
Эти команды копируют определение окружения ⟨existing-env⟩ в ⟨env⟩ (как начальный, так и конечный код), т.е. это просто применение \NewCommandCopy дважды к внутренним командам, которые определяют окружение, т.е. \⟨env⟩ и \end⟨env⟩. Различия между \New..., \Renew... и \Declare... являются обычными.
Эта команда отображает значение начального и конечного кода для окружения ⟨env⟩.
При объявлении новых команд с помощью \NewDocumentCommand, \NewCommandCopy или аналогичных команд иногда необходимо “построить” имя команды. В качестве общего механизма L3 программный уровень предлагает \exp_args:N... для этой цели, но нет механизма для этого, если \ExplSyntaxOn не активен (и смешивание команд программного и пользовательского уровней не является хорошим подходом). Поэтому мы предлагаем механизм для доступа к этой возможности с использованием именования в стиле CamelCase.
\UseName {⟨string⟩}
\ExpandArgs {⟨spec⟩} {⟨cmd⟩} {⟨arg1⟩} . . .
\UseName преобразует ⟨string⟩ непосредственно в имя команды и затем выполняет его: это эквивалентно давно существующей внутренней команде LATEX 2ε \@nameuse или эквиваленту L3 программирования \use:c. \ExpandArgs принимает ⟨spec⟩, который описывает, как расширять ⟨arguments⟩, выполняет эти операции, а затем выполняет ⟨cmd⟩. ⟨spec⟩ использует описания, предлагаемые L3 программным уровнем, и соответствующая функция \exp_args:N... должна существовать. Общие случаи будут иметь ⟨spec⟩ в виде c, cc или Nc: см. ниже.
В качестве примера, следующее объявление предоставляет метод для генерации команд редактирования:
\NewDocumentCommand\newcopyedit{mO{red}} {
\newcounter{todo#1}%
\ExpandArgs{c}\NewDocumentCommand{#1}{s m} {
\stepcounter{todo#1}%
\IfBooleanTF {##1} {
\todo[color=#2!10]{\UseName{thetodo#1}: ##2}%
} {
\todo[inline,color=#2!10]{\UseName{thetodo#1}: ##2}%
}%
}%
}
С учетом этого объявления вы можете написать \newcopyedit{note}[blue], что определит команду \note и соответствующий счетчик для вас.
Второй пример — это копирование команды по строковому имени с использованием \NewCommandCopy: здесь нам может понадобиться построить оба имени команд.
\NewDocumentCommand\savebyname{m} {
\ExpandArgs{cc}\NewCommandCopy{saved#1}{#1}
}
В ⟨spec⟩ каждая c обозначает один аргумент, который преобразуется в команду. n представляет собой “нормальный” аргумент, который не изменяется, а N обозначает “нормальный” аргумент, который также остается неизменным, но состоит только из одного токена (и обычно не заключен в фигурные скобки). Таким образом, чтобы построить команду из строки только для второго аргумента \NewCommandCopy, вы бы написали:
\ExpandArgs{Nc}\NewCommandCopy\mysectionctr{c@section}
Существует несколько других одиночных букв, поддерживаемых в L3 программном уровне, которые могут быть использованы в ⟨spec⟩ для манипуляции аргументами другими способами. Если вас это интересует, ознакомьтесь с разделом “Расширение аргументов” в документации L3 программного уровня в файле interface3.pdf.
Программный уровень LATEX3, который является частью формата, предлагает богатый интерфейс для манипуляции переменными и значениями с плавающей точкой. Чтобы позволить (более простым) приложениям использовать это на уровне документа или в пакетах, которые иначе не используют L3 программный уровень, предоставляется несколько интерфейсных команд.
Расширяемая команда \fpeval принимает в качестве аргумента выражение с плавающей точкой и производит результат, используя обычные правила математики. Поскольку эта команда является расширяемой, ее можно использовать там, где TEX требует числа, например, в низкоуровневой операции \edef, чтобы получить чисто числовой результат.
Кратко, выражения с плавающей точкой могут включать:
x + y, вычитание x - y, умножение x * y, деление x / y, квадратный корень sqrt x и скобки.x < y, x <= y, x > y, x != y и т.д. Отношение x ? y истинно, если один или оба операнда являются NaN или являются кортежем, если только они не равны кортежам. Каждое ⟨отношение⟩ может быть любой (непустой) комбинацией <, =, >, и ?, плюс необязательный ведущий ! (который отрицает ⟨отношение⟩), с ограничением, что отрицательное ⟨отношение⟩ не может начинаться с ?.sign x, отрицание ! x, конъюнкция x && y, дизъюнкция x || y, тернарный оператор x ? y : z.exp x, ln x, xˆy.fact x.sin x, cos x, tan x, cot x, sec x, csc x, ожидая, что их аргументы будут в радианах, и sind x, cosd x, tand x, cotd x, secd x, cscd x, ожидая, что их аргументы будут в градусах.asin x, acos x, atan x, acot x, asec x, acsc x, дающие результат в радианах, и asind x, acosd x, atand x, acotd x, asecd x, acscd x, дающие результат в градусах.max(x1, x2, ...), min(x1, x2, ...), abs(x).n (количество знаков, по умолчанию 0) и t (поведение при равенстве, по умолчанию NaN):
trunc(x, n) округляет к нулю,floor(x, n) округляет к −∞,ceil(x, n) округляет к +∞,round(x, n, t) округляет к ближайшему значению, при равенстве округляя к четному значению по умолчанию, к нулю, если t = 0, к +∞, если t > 0, и к −∞, если t < 0.rand(), randint(m, n).pi, deg (один градус в радианах).pc равен 12.\number) целочисленных, размерных и пропускных переменных в числа с плавающей точкой, выражая размерности в пунктах и игнорируя компоненты растяжения и сжатия пропусков.(x1, ..., xn), которые могут быть сложены, умножены или разделены на число с плавающей точкой, а также могут быть вложенными. Пример использования может быть следующим:\LaTeX{} может теперь вычислить: $ \frac{\sin (3.5)}{2} + 2\cdot 10^{-3} = \fpeval{sin(3.5)/2 + 2e-3} $.
Это приводит к следующему результату:
LATEX может теперь вычислить: sin(3.5) / 2 + 2 · 10−3 = −0.1733916138448099.
Расширяемая команда \inteval принимает в качестве аргумента целочисленное выражение и производит результат, используя обычные правила математики с некоторыми ограничениями, см. ниже. Признаваемые операции: +, -, * и /, а также скобки. Поскольку эта команда является расширяемой, ее можно использовать там, где TEX требует числа, например, в низкоуровневой операции \edef, чтобы получить чисто числовой результат.
Это, по сути, тонкая оболочка для примитивной команды \numexpr, и поэтому имеет некоторые синтаксические ограничения. Эти ограничения следующие:
/ обозначает деление, округленное до ближайшего целого числа, при этом при равенстве округление происходит от нуля;+ или -, а именно, размещение +( или -( в начале выражения или после +, -, *, / или ( приводит к ошибке.Пример использования может быть следующим:
\LaTeX{} может теперь вычислить: Сумма чисел равна $\inteval{1 + 2 + 3}$.
Это приводит к результату:
LATEX может теперь вычислить: Сумма чисел равна 6.
\dimeval {⟨dimen expression⟩}
\skipeval {⟨skip expression⟩}
Эти команды аналогичны \inteval, но вычисляют длину (dimen) или значение резинки (skip). Обе команды являются тонкими оболочками вокруг соответствующих примитивов движка, что делает их быстрыми, но, следовательно, они имеют те же синтаксические особенности, как обсуждалось выше. Тем не менее, на практике они обычно достаточно эффективны. Например:
\NewDocumentCommand\calculateheight{m}{%
\setlength\textheight{\dimeval{\topskip+\baselineskip*\inteval{#1-1}}}
}
Эта команда устанавливает \textheight на соответствующее значение, если страница должна содержать определенное количество строк текста. Таким образом, после вызова \calculateheight{40} значение будет установлено на 478.0pt, учитывая значения \topskip (10.0pt) и \baselineskip (12.0pt) в текущем документе.
Определение \input в LATEX не может быть использовано в местах, где TEX выполняет расширение: классический пример — в начале ячейки таблицы. Существует несколько причин для этого: ключевыми являются то, что \input фиксирует, какие файлы были прочитаны, и предоставляет хуки до и после чтения файла.
Чтобы поддержать необходимость выполнения ввода файла в контекстах расширения, доступна команда \expandableinput: она пропускает запись имени файла и не применяет никакие хуки для файлов, но в остальном ведет себя как \input. В частности, она по-прежнему использует \input@path при выполнении поиска файла.
\MakeUppercase [⟨keyvals⟩] {⟨text⟩}
\MakeLowercase [⟨keyvals⟩] {⟨text⟩}
\MakeTitlecase [⟨keyvals⟩] {⟨text⟩}
TEX предоставляет две примитивные команды \uppercase и \lowercase для изменения регистра текста. Однако у них есть ряд ограничений: они изменяют регистр только явных символов, не учитывают окружающий контекст, не поддерживают ввод UTF-8 с 8-битными движками и т.д. Чтобы преодолеть эту проблему, LATEX предоставляет команды \MakeUppercase, \MakeLowercase и \MakeTitlecase: они предлагают значительное улучшение по сравнению с примитивами TEX. Эти команды являются робустными (\protected) и могут использоваться в движущихся аргументах.
Изменение регистра в общем смысле хорошо понимается в разговорной речи. Заглавный регистр здесь следует определению, данному Консорциумом Unicode: первый символ входных данных будет преобразован в (широком смысле) заглавный регистр, а остальные символы — в строчный. Полный диапазон ввода Unicode UTF-8 может быть поддержан.
\MakeUppercase{hello WORLD ßüé} % HELLO WORLD SSÜÉ
\MakeLowercase{hello WORLD ßüé} % hello world ßüé
\MakeTitlecase{hello WORLD ßüé} % Hello WORLD ßüé
Команды изменения регистра принимают необязательный аргумент, который можно использовать для настройки вывода. Этот необязательный аргумент принимает ключ locale, также доступный под псевдонимом lang, который можно использовать для указания идентификатора языка в формате BCP-47. Это затем применяется для выбора языковых особенностей при изменении регистра.
Для заглавного регистра также могут использоваться ключевые слова: это выбор между first или all. Стандартная настройка — first, что означает, что только самый первый “буквенный” символ будет (широком смысле) преобразован в заглавный регистр. Альтернатива, all, означает, что входные данные делятся по каждому пробелу, и для каждого полученного слова первый символ будет преобразован в заглавный регистр. Например:
\MakeTitlecase[words=first]{some words} % Some words
\MakeTitlecase[words=all]{some words} % Some Words
Входные данные, переданные этим командам, “расширяются” перед применением изменения регистра. Это означает, что любые команды внутри входных данных, которые преобразуются в чистый текст, будут изменены по регистру. Математическое содержимое автоматически исключается, как и аргументы команд \label, \ref, \cite, \begin и \end. Дополнительные исключения могут быть добавлены с помощью команды \AddToNoCaseChangeList. Входные данные могут быть исключены из изменения регистра с помощью команды \NoCaseChange.
\MakeUppercase{Some text $y = mx + c$} % SOME TEXT y = mx + c
\MakeUppercase{\NoCaseChange{iPhone}} % iPhone
Чтобы позволить использовать робустные команды внутри изменения регистра и получить ожидаемый вывод, доступны две дополнительные управляющие команды. \CaseSwitch позволяет пользователю указать результат для четырех возможных случаев:
Команда \DeclareCaseChangeEquivalent предоставляет способ заменить команду альтернативной версией, когда она встречается внутри ситуации изменения регистра. Существуют три команды для настройки изменения регистра кодовых точек:
\DeclareLowercaseMapping [⟨locale⟩] {⟨codepoint⟩} {⟨output⟩}
\DeclareTitlecaseMapping [⟨locale⟩] {⟨codepoint⟩} {⟨output⟩}
\DeclareUppercaseMapping [⟨locale⟩] {⟨codepoint⟩} {⟨output⟩}
Все три принимают ⟨codepoint⟩ (в виде целочисленного выражения) и приводят к тому, что
Если эта команда помещена в преамбулу, то в конце выполнения документа на терминале (и в лог-файле) будет отображен список прочитанных файлов (в результате обработки документа). При возможности также будет предоставлено краткое описание. Эти описания, надеемся, будут включать описания, даты и номера версий для файлов пакетов и классов.
Иногда может случиться так, что в файл пакета или класса (или, скорее, в его копию) были внесены локальные изменения. Чтобы позволить идентифицировать такие случаи, \listfiles принимает необязательный аргумент, который позволяет настроить выводимую информацию с использованием подхода ключ-значение:
hashes — добавляет MD5-хеш для каждого файла в выводимую информацию.sizes — добавляет размер файла для каждого файла в выводимую информацию.Обратите внимание, что так как Windows и Unix используют разные окончания строк (LF против LF CR), хеши и размеры файлов из двух систем не будут одинаковыми. Поэтому следует сравнивать эти значения между операционными системами одного типа.
Предупреждение: эта команда будет перечислять только файлы, которые были прочитаны с использованием команд LATEX, таких как \input{⟨file⟩} или \include{⟨file⟩}. Если файл был прочитан с использованием примитивного синтаксиса TEX \input file (без фигурных скобок вокруг имени файла), то он не будет перечислен; несоблюдение формата LATEX с фигурными скобками может вызвать более серьезные проблемы, возможно, приведя к перезаписи важных файлов, поэтому всегда используйте фигурные скобки.
| Ключ | Краткое описание |
|------|----------------------------------------------------------------------------------|
| **m** | Обычный обязательный аргумент (один токен или `{...}`). |
| **r** | Обязательный аргумент с разделителями (формат: `r⟨t1⟩⟨t2⟩`). |
| **R** | Как `r`, но с значением по умолчанию (формат: `R⟨t1⟩⟨t2⟩{⟨default⟩}`). |
| **v** | Дословный аргумент (аналог `\verb` в LaTeX). |
| **b** | Тело окружения (только для `\begin{...}...\end{...}`). |
| **o** | Необязательный аргумент в `[...]`, возвращает `-NoValue-` если отсутствует. |
| **d** | Необязательный аргумент с разделителями (формат: `d⟨t1⟩⟨t2⟩`). |
| **O** | Как `o`, но с значением по умолчанию (формат: `O{⟨default⟩}`). |
| **D** | Как `d`, но с значением по умолчанию (формат: `D⟨t1⟩⟨t2⟩{⟨default⟩}`). |
| **s** | Необязательная звезда (`*`), возвращает `\BooleanTrue`/`\BooleanFalse`. |
| **t** | Необязательный токен (формат: `t⟨token⟩`), возвращает `\BooleanTrue`/`False`. |
| **e** | Необязательные "украшения" (формат: `e{⟨tokens⟩}`), возвращает `-NoValue-`. |
| **E** | Как `e`, но с значениями по умолчанию (формат: `E{⟨tokens⟩}{⟨defaults⟩}`). |
| **+** | Модификатор: делает аргумент "длинным" (параграфным). |
| **!** | Модификатор: управляет пробелами перед необязательными аргументами. |
| **=** | Модификатор: аргумент интерпретируется как ключ-значение (keyvals). |
| **>** | Модификатор: применяет "процессор аргументов" для преобразования ввода. |
\NewDocumentCommand {⟨cmd⟩} {⟨arg spec⟩} {⟨code⟩}
\RenewDocumentCommand {⟨cmd⟩} {⟨arg spec⟩} {⟨code⟩}
\ProvideDocumentCommand {⟨cmd⟩} {⟨arg spec⟩} {⟨code⟩}
\DeclareDocumentCommand {⟨cmd⟩} {⟨arg spec⟩} {⟨code⟩}
Эта группа команд используется для создания команды ⟨cmd⟩. Спецификация аргумента для функции задается с помощью ⟨arg spec⟩, а команда использует ⟨code⟩, где #1, #2 и т. д. заменяются на аргументы, найденные парсером.
Пример:
\NewDocumentCommand\chapter{s o m} {
\IfBooleanTF{#1}
{\typesetstarchapter{#3}}
{\typesetnormalchapter{#2}{#3}}
}
\NewDocumentEnvironment {⟨env⟩} {⟨arg spec⟩} {⟨beg-code⟩} {⟨end-code⟩}
\RenewDocumentEnvironment {⟨env⟩} {⟨arg spec⟩} {⟨beg-code⟩} {⟨end-code⟩}
\ProvideDocumentEnvironment {⟨env⟩} {⟨arg spec⟩} {⟨beg-code⟩} {⟨end-code⟩}
\DeclareDocumentEnvironment {⟨env⟩} {⟨arg spec⟩} {⟨beg-code⟩} {⟨end-code⟩}
Эти команды работают так же, как \NewDocumentCommand и т. д., но создают окружения (\begin{⟨env⟩} … \end{⟨env⟩}). Как ⟨beg-code⟩, так и ⟨end-code⟩ могут получать доступ к аргументам, как определено в ⟨arg spec⟩. Аргументы будут переданы после \begin{⟨env⟩}. Все пробелы в начале и в конце {⟨env⟩} удаляются перед определением, таким образом:
\IfNoValueTF {⟨arg⟩} {⟨true code⟩} {⟨false code⟩}
\IfNoValueT {⟨arg⟩} {⟨true code⟩}
\IfNoValueF {⟨arg⟩} {⟨false code⟩}
Команды \IfNoValue(TF) используются для проверки, является ли ⟨argument⟩ (#1, #2 и т. д.) специальным маркером -NoValue-. Например:
\NewDocumentCommand\foo{o m} {
\IfNoValueTF {#1}
{\DoSomethingJustWithMandatoryArgument{#2}}
{\DoSomethingWithBothArguments{#1}{#2}}
}
\IfValueTF {⟨arg⟩} {⟨true code⟩} {⟨false code⟩}
\IfValueT {⟨arg⟩} {⟨true code⟩}
\IfValueF {⟨arg⟩} {⟨false code⟩}
Обратная форма тестов \IfNoValue(TF) также доступна как \IfValue(TF). Контекст определит, какая логическая форма имеет наибольший смысл для данного сценария кода.
\IfBlankTF {⟨arg⟩} {⟨true code⟩} {⟨false code⟩}
\IfBlankT {⟨arg⟩} {⟨true code⟩}
\IfBlankF {⟨arg⟩} {⟨false code⟩}
| Команда | Краткое описание |
|-----------------------------|----------------------------------------------------------------------------------|
| `\BooleanFalse` | Логическое значение "ложь" (используется с аргументами `s`/`t`). |
| `\BooleanTrue` | Логическое значение "истина" (используется с аргументами `s`/`t`). |
| `\IfBooleanTF{arg}{true}{false}` | Проверяет, является ли `arg` булевым значением (`\BooleanTrue`/`\BooleanFalse`). |
| `\IfBooleanT{arg}{true}` | Выполняет `true` код, если `arg` равно `\BooleanTrue`. |
| `\IfBooleanF{arg}{false}` | Выполняет `false` код, если `arg` равно `\BooleanFalse`. |
| `\IfNoValueTF{arg}{true}{false}` | Проверяет, равен ли `arg` маркеру `-NoValue-`. |
| `\IfNoValueT{arg}{true}` | Выполняет `true` код, если `arg` равен `-NoValue-`. |
| `\IfNoValueF{arg}{false}` | Выполняет `false` код, если `arg` **не** равен `-NoValue-`. |
| `\IfValueTF{arg}{true}{false}` | Обратная логика: `true` если `arg` **имеет** значение. |
| `\IfValueT{arg}{true}` | Выполняет `true` код, если `arg` **имеет** значение. |
| `\IfValueF{arg}{false}` | Выполняет `false` код, если `arg` **не имеет** значения. |
| `\IfBlankTF{arg}{true}{false}` | Проверяет, является ли `arg` пустым или содержит только пробелы. |
| `\IfBlankT{arg}{true}` | Выполняет `true` код, если `arg` пустой/пробельный. |
| `\IfBlankF{arg}{false}` | Выполняет `false` код, если `arg` **не** пустой. |
\NewDocumentCommand\foo{o m}{
\IfNoValueTF{#1}
{Команда без опции: #2}
{Команда с опцией [#1] и аргументом #2}
}
| Процессор | Описание | Пример использования |
|--------------------------------|--------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| **`\SplitArgument{n}{sep}`** | Разделяет аргумент по `sep` на `n+1` частей, оборачивая в `{}`. | `\NewDocumentCommand\foo{>{\SplitArgument{2}{;}}m}{#1}` → `\foo{a;b;c}` → `{a}{b}{c}` |
| **`\SplitList{sep}`** | Разделяет аргумент по `sep` на неограниченное число частей. | `\NewDocumentCommand\foo{>{\SplitList{,}}m}{\ProcessList{#1}{\textbf}}` → `\foo{a,b}` → **a** **b** |
| **`\ProcessList{list}{cmd}`** | Применяет `cmd` к каждому элементу `list` (используется с `\SplitList`). | `\ProcessList{{a}{b}}{\textbf}` → **a****b** |
| **`\ReverseBoolean`** | Инвертирует булевы значения (`\BooleanTrue` ↔ `\BooleanFalse`). | `\NewDocumentCommand\foo{>{\ReverseBoolean}s}{Star: \IfBooleanT{#1}{YES}}` → `\foo*` выведет "Star: NO" |
| **`\TrimSpaces`** | Удаляет пробелы в начале/конце аргумента. | `\NewDocumentCommand\foo{>{\TrimSpaces}m}{[#1]}` → `\foo{ text }` → `[text]` |
| **Комбинация процессоров** | Процессоры применяются справа налево. | `>{\TrimSpaces} >{\SplitList{,}} m` → сначала разделит запятыми, затем обрежет пробелы. |
Разделение аргументов с обработкой:
\NewDocumentCommand\formatlist{>{\SplitList{,}}m}{
\ProcessList{#1}{\textbf}
}
\formatlist{a, b, c} % → **a** **b** **c**
Обработка ключевых значений:
\NewDocumentCommand\setoptions{>{\TrimSpaces}m}{
\keys_set:nn {my-module} {#1}
}
\setoptions{ key1 = value1 , key2 = value2 }
Инверсия логики звездочки:
\NewDocumentCommand\checkstar{>{\ReverseBoolean}s}{
\IfBooleanT{#1}{Звезды НЕТ} \IfBooleanF{#1}{Звезда ЕСТЬ}
}
\checkstar* % Выведет "Звезда ЕСТЬ"
Многоэтапная обработка:
\NewDocumentCommand\process{>{\TrimSpaces} >{\SplitList{;}} m}{
\ProcessList{#1}{\SomeCommand}
}
\process{ a; b; c } % → обработает как `{a}{b}{c}`
longtableПакет longtable позволяет создавать таблицы, которые могут разбиваться на несколько страниц. Это особенно полезно для длинных таблиц, которые не помещаются на одной странице.
\usepackage{longtable}
% Настройка отступов в таблицах
\renewcommand{\tabcolsep}{0.05cm} % Горизонтальный отступ между колонками
\renewcommand{\arraystretch}{1.7} % Вертикальное растяжение строк
\begin{center}
% Настройка цветов таблицы
\rowcolors{2}{gray!10}{white} % Чередование цветов строк (начиная со 2-й)
\arrayrulecolor{gray!20} % Цвет линий таблицы
% Начало длинной таблицы (может переноситься на несколько страниц)
% Формат колонок: B{2} - жирная шириной 2cm, L{8} и L{5} - обычные шириной 8cm и 5cm
\begin{longtable}{B{2}|L{8}|L{5}}
%%% ЗАГОЛОВОК НА ПЕРВОЙ СТРАНИЦЕ %%%
\caption[Технические характеристики]{Основные характеристики \label{tab:tech-character}}\\
\rowcolor{black!90} % Цвет фона заголовка
% Названия колонок (белый текст на темном фоне)
\multicolumn{1}{c}{\color{white}{№}} &
\multicolumn{1}{c}{\color{white}{Характеристика}} &
\multicolumn{1}{c}{\color{white}{Значение}} \\
\endfirsthead % Конец заголовка для первой страницы
%%% ЗАГОЛОВОК НА СЛЕДУЮЩИХ СТРАНИЦАХ %%%
\caption[]{Продолжение таблицы}\\
\rowcolor{black!90}
\multicolumn{1}{c}{№} &
\multicolumn{1}{c}{Характеристика} &
\multicolumn{1}{c}{Значение} \\
\endhead % Конец заголовка для последующих страниц
%%% ТЕЛО ТАБЛИЦЫ %%%
1 & Вес: & 80кг \\
2 & Габаритные размеры: & 730мм * 530мм * 850мм \\
3 & Напряжение управляющего питания (низковольтное): & 9-30 Вольт \\
\end{longtable}
\end{center}
Настройка внешнего вида таблицы:
\tabcolsep - расстояние между колонками\arraystretch - коэффициент растяжения строк по вертикали\rowcolors - чередование цветов строк\arrayrulecolor - цвет линий таблицыСтруктура таблицы:
\begin{longtable}{формат_колонок} - начало длинной таблицыB{2}|L{8}|L{5} - три колонки с заданной шириной и выравниваниемЗаголовки:
\caption - название таблицы (в квадратных скобках - для списка таблиц)\endfirsthead - заголовок только для первой страницы\endhead - заголовок для последующих страницФорматирование содержимого:
\rowcolor - цвет фона строки\multicolumn - объединение ячеек по горизонтали\color - цвет текстаСпециальные символы:
\diameter - символ диаметра (из пакета wasysym)Этот пример создает профессионально оформленную таблицу с:
\newcolumntype{C}[1]{>{\columncolor{white}\ttfamily\centering\arraybackslash}p{#1cm}}
\newcolumntype{R}[1]{>{\columncolor{white}\ttfamily\raggedleft\arraybackslash}p{#1cm}}
\newcolumntype{L}[1]{>{\columncolor{white}\ttfamily\raggedright\arraybackslash}p{#1cm}}
\newcolumntype{B}[1]{>{\columncolor{white}\ttfamily\bfseries\raggedright\arraybackslash}p{#1cm}}
Эти определения создают новые типы колонок:
C - центрированное содержимоеR - выравнивание по правому краюL - выравнивание по левому краюB - полужирное содержимое с выравниванием по левому краюtabbingСреда tabbing предоставляет простой способ создания таблиц с выравниванием по табуляции. Полезен для простых таблиц без рамок.
\begin{tabbing}
Первая колонка \= Вторая колонка \= Третья колонка \kill
Заголовок 1 \> Заголовок 2 \> Заголовок 3 \\
Данные 1 \> Данные 2 \> Данные 3 \\
Выровнено \> по \> табуляторам \\
\end{tabbing}
\= - установка табулятора\> - переход к следующему табулятору\kill - строка используется для установки табуляторов, но не печатаетсяarrayПакет array расширяет возможности работы с таблицами, предоставляя дополнительные функции для форматирования колонок и строк.
\begin{tabular}{>{$}l<{$} >{\centering\arraybackslash}m{2cm}}
\alpha & Буква альфа \\
\beta & Буква бета \\
\end{tabular}
\begin{tabular}{|>{\ifnum\value{rownum}=1 \bfseries\fi}l|l|}
\hline
Строка 1 & Данные 1 \\
Строка 2 & Данные 2 \\
\hline
\end{tabular}
\newcolumntype{M}[1]{>{\centering\arraybackslash}m{#1}}
\begin{tabular}{|M{2cm}|M{3cm}|}
Центрированная & колонка \\
ячейка & с заданной шириной \\
\end{tabular}
\extrarowheight - добавление дополнительного пространства в строках\newcolumntype - определение новых типов колонок\multicolumn - объединение колонок (также доступно без array)Эти пакеты предоставляют мощные инструменты для создания профессионально оформленных таблиц в LaTeX, от простых до самых сложных.
fancyhdr и fancybox, включая ваши настройки и дополнительные примеры.fancyhdr и fancyboxНазначение: Оформление колонтитулов (fancyhdr) и декоративных рамок (fancybox).
fancyhdrhead) и нижних (foot) колонтитулов.twoside).\usepackage[twoside,headings]{fancyhdr} % twoside — разные колонтитулы для чётных/нечётных страниц
\pagestyle{fancy} % Активирует стиль fancy
\fancyhf{} % Очистка текущих настроек
\fancyhead[позиция]{содержимое} – верхний колонтитул.\fancyfoot[позиция]{содержимое} – нижний колонтитул.Позиции:
L – слева, C – центр, R – справа.E – чётная страница, O – нечётная.LE, RO, CE и т.д.Пример:
\fancyhead[LE,RO]{\leftmark} % Название раздела (для чётных и нечётных)
\fancyfoot[C]{\thepage} % Номер страницы по центру
tikz для фона\AddEverypageHook{
\begin{tikzpicture}[remember picture,overlay]
\fill[black!90] (current page.north west) rectangle ($(current page.north east)+(0,-22mm)$);
\fill[black!90] (current page.south west) rectangle ($(current page.south east)+(0,15mm)$);
\end{tikzpicture}
}
\fancyhead[LE,RO]{\raisebox{1.2em}{\color{white}{\Large\leftmark}}}
\fancyfoot[LE,RO]{\color{white}{\textbf{\thepage}}}
\renewcommand{\headrulewidth}{0pt} % Убирает линию под верхним колонтитулом
\renewcommand{\footrulewidth}{0pt} % Убирает линию над нижним колонтитулом
fancyboxНазначение: Создание декоративных рамок вокруг текста.
\shadowbox{текст} – рамка с тенью.\doublebox{текст} – двойная рамка.\ovalbox{текст} – овальная рамка.Пример:
\usepackage{fancybox}
...
\shadowbox{\parbox{10cm}{Это текст в рамке с тенью.}}
\doublebox{\parbox{10cm}{Это текст в двойной рамке.}}
\setlength{\shadowrule}{1pt} % Толщина тени
\setlength{\shadowsize}{4pt} % Размер тени
\fancyhead[LE]{\color{white}Глава \thechapter}
\fancyhead[RO]{\color{white}\nouppercase{\rightmark}}
\fancyfoot[CO,CE]{\color{white}\thepage}
\fancyhead[L]{\includegraphics[width=2cm]{logo}}
\fancyfoot[R]{\thepage}
\ovalbox{
\begin{minipage}{0.9\linewidth}
Важное замечание: этот текст выделен овальной рамкой.
\end{minipage}
}
fancyhdr идеален для сложных колонтитулов с графикой и динамическим содержимым.fancybox полезен для визуального выделения блоков текста.Я от части пожалел, что сначала изучил Latex, а потом взялся за TeX.
https://tug.org/texlive/doc/texlive-ru/texlive-ru.html
Установите Tex Live для полного удовлетворения своих запросов в издательской системе TeX и LaTeX.
На этой странице полная инструкция по установке https://tug.org/texlive/acquire-netinstall.html
или набрать в командной строке:
sudo pacman -S texlive
#manjaro
или
pkg install texlive
#freebsd
{\char65} {\char `A} {\char `\A}
| наименование | Tex input | Tex output | Compose |
|---|---|---|---|
| grave | \`o | ò | cmp+` o |
| acute | \’o | ó | cmp+’ o |
| circumflex | \^o | ô | cmp+^ o |
| umlaut/dieresis/tr ́emat | \“o | ö | cmp+” o |
| tilde | \~o | õ | cmp+~ o |
| macron | \=o | ő | cmp+= o |
| dot | \.o | ȯ | cmp+. o |
Продолжение для символов требующих пробела
| наименование | Tex input | Tex output | Compose |
|---|---|---|---|
| cedilla | \c o | ǫ | cmp+, o |
| underdot | \d o | ọ | cmp+! o |
| underbar | \b o | o᤻ | o C-x 8 RET 193b |
| h ́acˇek | \v o | ǒ | cmp+v o |
| breve | \u o | ŏ | cmp+u o |
| tie | \t oo | o͡o | o C-x 8 RET 0361 o |
| Hungarian umlaut | \H o | ő | cmp+= o |
| ơ | cmp++ o | ||
| ° | cmp+o o | ||
| § | cmp+s o | ||
| ø | cmp+? o |
или команда \accent94 или номер в таблице шрифта
| имя | описание |
|---|---|
| \fivebf | use 5-point bold font |
| \fivei | use 5-point math italic font |
| \fiverm | use 5-point roman font |
| \fivesy | use 5-point math symbol font |
| \sevenbf | use 7-point bold font |
| \seveni | use 7-point math italic font |
| \sevenrm | use 7-point roman font |
| \sevensy | use 7-point math symbol font |
| \tenbf | use 10-point bold text font |
| \tenex | use 10-point math extension font |
| \teni | use 10-point math italic font |
| \tenrm | use 10-point roman text font |
| \tensl | use 10-point slanted roman font |
| \tensy | use 10-point math symbol font |
| \tenit | use 10-point italic font |
| \tentt | use 10-point typewriter font |
\nullfont — отменить шрифты (пусто)
В Tex по умолчанию доступны 16 шрифтов
| Наименование | команда |
|---|---|
| Roman | \rm |
| Boldface | \bf |
| Italic | \it |
| Slanted | \sl |
| Typewriter | \tt |
| Math symbol5 | \cal |
\lccode 〈charcode〉 [ 〈number〉 table entry ]\uccode 〈charcode〉 [ 〈number〉 table entry ]\char\uccode`s \char\lccode`a \char\lccode`M — выдаст Sam
Строка в верхний или нижний регистр
\lowercase { 〈token list〉 }
\uppercase { 〈token list〉 }
\ — вставит пробел после команды~ — неразрывный пробел\/ — курсивный пробел\obeyspaces — не сжимает пробелы, а сохраняет их как есть\centerline 〈argument〉 \leftline 〈argument〉 \rightline 〈argument〉\line{} — выровняет по левому и правому краю\llap{} — печатает влево от курсора\rlap{} — печатает вправо от курсора\noindent
\llap{off left }
\line{\vrule $\Leftarrow$ left margin of examples\hfil right margin of examples $\Rightarrow$\vrule}
\rlap{ off right}
\par — новый абзац\parskip=\parindent=\endgraf — синоним \par\parfillskip [ 〈glue〉 parameter ] — \parfillskip = 0pt plus 1fil по умолчанию, определяет последнюю строку в абзаце.\indent — Если TEX находится в вертикальном режиме, как это происходит после окончания абзаца, эта команда вставляет межабзацную связку \parskip, переводит TEX в горизонтальный режим, начинает абзац и делает отступ в этом абзаце на \parindent. Если TEX уже находится в горизонтальном режиме, эта команда просто создает пробел шириной \parindent. Два \indent подряд создают два отступа.\noindent — запрещает отступ в начале абзаца\textindent 〈argument〉 — используется для печатания сносок и пунктов списков\everypar [ 〈token list〉 parameter ] — назначает команды для выполнения перед началом нового абзаца\everypar = {$\Longrightarrow$\enspace}
Now pay attention!\par I said,
"Pay attention!".\par
I'll say it again! Pay attention!
на выходе получим:
⇒ Now pay attention!
⇒ I said, “Pay attention!”.
⇒ I’ll say it again! Pay attention!
\hsize — ширина печатной области\leftline{\raggedright\vtop{\hsize = 2.5in Here is some text that we put into a paragraph that is an inch and a half wide.}\qquad \vtop{\hsize = 1.5in Here is some more text that we put into another paragraph that is an inch and a half wide.}}
шикарный пример как печатать в 2 колонки без мути в Latex
\narrower — сужает абзац слева и справа на \parindent\leftskip [ 〈glue〉 parameter ] — отступ слева\rightskip [ 〈glue〉 parameter ] — отступ справа\raggedright — убирает выравнивание справа\ttraggedright — тоже для мониширинного текста\hang — Эта команда устанавливает отступ во второй и последующих строках абзаца на \parindent, отступ абзаца\hangafter [ 〈number〉 parameter ] — определяет, какие строки имеют отступ: Если n < 0, первые −n строк абзаца будут иметь отступ. Если n ≥ 0, все строки абзаца, кроме первых n, будут иметь отступ.\hangindent [ 〈dimen〉 parameter ] — определяет величину отступа и то, находится ли он слева или справа: Если x ≥ 0, строки будут иметь отступ x слева. Если x < 0, строки будут иметь отступ -x справа.\prevgraf [ 〈number〉 parameter ] — количество строк в абзаце\vadjust { 〈vertical mode material〉 } — Эта команда вставляет указанный 〈материал вертикального режима〉 сразу после выходной строки, содержащей позицию, в которой встречается команда. Вы можете использовать его, например, чтобы вызвать выброс страницы или вставить дополнительное пространство после определенной строки.Полезная штука для вставки указателей и линий:
Some of these words are \vadjust{\kern8pt\hrule} to be found above the line and others are to be found below it.
Выдаст линиюпод строкой:
Some of these words are to be found above the line and others are to be found
below it.
Эта команда определяет форму первых n строк абзаца, следующего абзаца, если вы находитесь в вертикальном режиме, и текущего абзаца, если вы находитесь в горизонтальном режиме. «i» — это отступ слева и справа, а «l» — это длина строки, n — это количество строк, на которые будет выполнено воздействие.
\break — просто прервет строку\nobreak\allowbreak — для математики полезен\penalty 〈number〉 — штраф 10000 или -10000 управляет разрывом строк\obeylines — концу строки присваивает значение конец абзаца (полезно для стихов и программного кода)\slash — поставит /, но $\backslash$ работает в математической моде\pretolerance [ 〈number〉 parameter ] — (по умолчанию 100)\tolerance [ 〈number〉 parameter ] — (200) это как штрафы \penalty определяют плохость для абзацев, чтобы их разрывать на странице.\emergencystretch [ 〈dimen〉 parameter ] — Если TEX не может набрать абзац, не превысив \tolerance, он попытается еще раз, добавив \emergencystretch к растягиванию каждой строки.\looseness [ 〈number〉 parameter ] — Этот параметр дает вам возможность изменить общее количество строк в абзаце по сравнению с оптимальным.\linepenalty [ 〈number〉 parameter ] — Этот параметр определяет штраф, который TEX начисляет за каждый перенос строки при разбиении абзаца на строки.\adjdemerits [ 〈number〉 parameter ] — Этот параметр определяет дополнительные недостатки, которые TEX прикрепляет к точке останова между двумя соседними строками, которые «визуально несовместимы».\exhyphenpenalty [ 〈number〉 parameter ] — Увеличение этого параметра препятствует тому, чтобы TEX заканчивал строку явным дефисом. Обычный TEX устанавливает \exhyphenpenalty равным 50.\hyphenpenalty [ 〈number〉 parameter ] — Увеличение этого параметра препятствует использованию в TEX переноса слов. Обычный TEX устанавливает \hyphenpenalty равным 50.\doublehyphendemerits [ 〈number〉 parameter ] — Увеличение значения этого параметра препятствует TEXу расставлять переносы в двух строках подряд.\finalhyphendemerits [ 〈number〉 parameter ] — Увеличение значения этого параметра препятствует тому, чтобы TEX заканчивал предпоследнюю строку дефисом.\- — расставить в тех местах слов, где допускается перенос.\discretionary { 〈pre-break text〉 } { 〈post-break text〉 } { 〈no-break text〉 } — Эта команда определяет «дискреционный разрыв», а именно место, где TEX может разорвать строку. Он также сообщает TEXу, какой текст поместить по обе стороны от разрыва.% Accounts for German usage: ‘flicken’, but ‘flik% ken’: German
"fli\discretionary{k-}{k}{ck}en"
\hyphenation { 〈word〉 . . . 〈word〉 } — TEX хранит словарь исключений из своих правил расстановки переносов. В каждой словарной статье указано, как следует писать через дефис то или иное слово.\hyphenation{Gry-phon my-co-phagy}
\hyphenation{man-u-script man-u-scripts piz-za}
\uchyph [ 〈number〉 parameter ] — разрешает перенос в верхнем регистре\language [ 〈number〉 parameter ] — устанавливает язык для переносов в абзаце\setlanguage 〈number〉 — установит текущий язык\lefthyphenmin [ 〈number〉 parameter ] \righthyphenmin [ 〈number〉 parameter ] — левое и правое количество слогов при переносе\hyphenchar 〈font〉 [ 〈number〉 parameter ] — установит символ переноса\hyphenchar\tenrm = ‘% Set hyphenation for tenrm font to ‘-’.
\hyphenchar\tentt = -1 % Don’t hyphenate words in font tentt.% нет переноса
- `\beginsection 〈argument〉 \par` --- заголовок секции
- `\item 〈argument〉 \itemitem 〈argument〉` --- отступ для списков
- `\proclaim 〈argument〉. 〈general text〉 \par` --- теоремы
\proclaim Theorem 1.
What I say is not to be believed.
\proclaim Corollary 1. Theorem 1 is false.\par
\baselineskip [ 〈glue〉 parameter ] — расстояние от базовой линии одного блока до другой
\lineskiplimit [ 〈dimen〉 parameter ] — минимальное значение межстрочного клея
\lineskip [ 〈glue〉 parameter ] — расстояние между низом верхнего блока и верхом нижнего блока
\prevdepth [ 〈dimen〉 parameter ] — глубина блока
\normalbaselineskip [ 〈glue〉 parameter ] — хранит значение baselineskip
\normallineskiplimit [ 〈dimen〉 parameter ] — хранит значение lineskiplimit
\normallineskip [ 〈glue〉 parameter ] — хранит значение lineskip
\normalbaselines — устанавливает значатения, хранящиеся в параметрах normal…
\offinterlineskip — отключает вставку межстрочного клея
\nointerlineskip — Эта команда сообщает TEXу не вставлять межстрочный клей перед следующей строкой. На последующие строки это не влияет.
\openup 〈dimen〉 — Эта команда увеличивает \baselineskip на 〈dimen〉.
\break —\nobreak —\allowbreak —\penalty 〈number〉 —\goodbreak — Эта команда завершает абзац, а также указывает TEXу, что это подходящее место для разрыва страницы.\smallbreak \medbreak \bigbreak —\eject \supereject — Эти команды вызывают разрыв страницы в текущей позиции и завершают текущий абзац. Если нет vfill будет пытаться сам растянуть страницу.\filbreak — Эта команда обеспечивает своего рода условный разрыв страницы. Он сообщает TEXу разбить страницу, но не в том случае, если текст до более позднего \filbreak также помещается на той же странице.\raggedbottom \normalbottom — сообщает TEXу, что нужно разрешить некоторую вариативность нижних полей на разных страницах.\interlinepenalty [ 〈number〉 parameter ] — Этот параметр определяет штраф за разрыв страницы между строками абзаца.\clubpenalty [ 〈number〉 parameter ] — Этот параметр определяет штраф за разрыв страницы сразу после первой строки абзаца.\widowpenalty [ 〈number〉 parameter ] — Этот параметр определяет штраф за разрыв страницы непосредственно перед последней строкой абзаца.\displaywidowpenalty [ 〈number〉 parameter ] — Этот параметр определяет штраф за разрыв страницы непосредственно перед последней строкой частичного абзаца, который непосредственно предшествует математическому отображению.\predisplaypenalty [ 〈number〉 parameter ] — Этот параметр определяет штраф за разрыв страницы непосредственно перед математическим отображением. Обычный TEX устанавливает \predisplaypenalty равным 10000.\postdisplaypenalty [ 〈number〉 parameter ] — Этот параметр определяет штраф за разрыв страницы сразу после математического отображения.\brokenpenalty [ 〈number〉 parameter ] — Этот параметр определяет штраф за разрыв страницы сразу после строки, которая заканчивается произвольным элементом (обычно дефисом).\insertpenalties [ 〈number〉 parameter ] — Этот параметр содержит сумму определенных штрафов, которые накапливает TEX при размещении вставок на текущей странице.\floatingpenalty [ 〈number〉 parameter ] — Этот параметр определяет штраф, который TEX добавляет к \insertpenalties, когда построитель страниц добавляет вставку на текущую страницу и обнаруживает, что предыдущая вставка того же типа на этой странице была разделена, оставив ее часть для последующих страниц.\pagegoal [ 〈dimen〉 parameter ] — Этот параметр определяет желаемую высоту текущей страницы. TEX устанавливает \pagegoal в текущее значение \vsize, когда он впервые помещает блок или вставку на текущую страницу.\pagetotal [ 〈dimen〉 parameter ] — Этот параметр определяет накопленную естественную высоту текущей страницы. TEX обновляет \pagetotal по мере добавления элементов в основной вертикальный список.\pagedepth [ 〈dimen〉 parameter ] — Этот параметр определяет глубину текущей страницы.\pageshrink [ 〈dimen〉 parameter ] — Этот параметр определяет степень сжатия накопленного клея на текущей странице.\pagestretch [ 〈dimen〉 parameter ] \pagefilstretch [ 〈dimen〉 parameter ] \pagefillstretch [ 〈dimen〉 parameter ] \pagefilllstretch [ 〈dimen〉 parameter ] — Эти четыре параметра вместе определяют степень растяжения клея на текущей странице. n0 + n1fil + n2fill + n3filll\hsize [ 〈dimen〉 parameter ] — горизонтальный размер текста\vsize [ 〈dimen〉 parameter ] — вертикальный размер текста\hoffset [ 〈dimen〉 parameter ] \voffset [ 〈dimen〉 parameter ] — отступ слева и сверху\topskip [ 〈glue〉 parameter ] — TEX вставляет клей вверху каждой страницы, чтобы гарантировать, что базовая линия первого блока на странице всегда находится на одинаковом расстоянии d от верха страницы.\parskip [ 〈glue〉 parameter ] — Этот параметр определяет «пропуск абзаца», то есть вертикальную склейку, которую TEX вставляет в начало абзаца.\maxdepth [ 〈dimen〉 parameter ] — Этот параметр определяет максимальную глубину нижнего поля на странице.\pageno [ 〈number〉 parameter ] — Этот параметр содержит номер текущей страницы в виде целого числа. Номер страницы обычно является отрицательным для страниц титульной страницы, которые нумеруются маленькими римскими цифрами, а не арабскими цифрами.\pageno = 30 % Number the next page as 30. Don’t look for this explanation on page \number\pageno.
\advancepageno — Эта команда добавляет 1 к номеру страницы n в \pageno, если n ≥ 0, и вычитает из него 1, если n < 0.\nopagenumbers — создает пустой нижний колонтитул\folio — Эта команда создает номер текущей страницы, значением которого является число n, содержащееся в \pageno. Если n ≥ 0, TEX выдает n как десятичное число, а если n < 0, TEX выдает −n в виде строчных римских цифр.\headline [ 〈token list〉 parameter ] — заголовок\footline [ 〈token list〉 parameter ] — подвал\mark { 〈text〉 } — Эта команда заставляет TEX добавлять метку, содержащую 〈текст метки〉, к любому списку, который он в данный момент создает.\firstmark \botmark \topmark — Эти команды расширяются до текста метки в элементе, созданном предыдущей командой \mark.\splitfirstmark \splitbotmark — Эти команды расширяются до текста метки, сгенерированного более ранней командой \mark, которая создала элемент в списке элементов vbox V .\footnote 〈argument1 〉 〈argument2 〉 —To quote the mathematician P\’olya is a ploy.\footnote *{This is an example of an anagram, but not a strict one.}
\vfootnote 〈argument1 〉 〈argument2 〉 — \footnote, и \vfootnote вставляют знак ссылки перед самой сноской, но \vfootnote не вставляет знак ссылки в текст.\topinsert 〈vertical mode material〉 \endinsert — пытается разместить материал вверху текущей страницы.\midinsert 〈vertical mode material〉 \endinsert — пытается поместить материал в текущую позицию.\pageinsert 〈vertical mode material〉 \endinsert — помещает материал отдельно на следующую страницу.\insert 〈number〉 { 〈vertical mode material〉 } — Эта примитивная команда обеспечивает базовый механизм создания вставок, но она почти никогда не используется за пределами определения макроса. Необходимо три элемента для insert\output [ 〈token list〉 parameter ] — Этот параметр содержит текущую процедуру вывода, т. е. список токенов, который TEX расширяет, когда находит разрыв страницы.\plainoutput — Эта команда вызывает обычную процедуру вывода TEXа.\shipout 〈box〉 — Эта команда инструктирует TEX отправить 〈box〉 в файл .dvi.\deadcycles [ 〈number〉 parameter ] — Этот параметр содержит количество раз, когда TEX инициировал процедуру вывода с момента последнего выполнения команды \shipout.\maxdeadcycles [ 〈number〉 parameter ] — Если значение \deadcycles превышает значение \maxdeadcycles, TEX предполагает, что процедура вывода зациклилась.\outputpenalty [ 〈number〉 parameter ] — TEX устанавливает этот параметр, когда разрывает страницу.\holdinginserts [ 〈number〉 parameter ] — Если этот параметр больше 0, когда TEX обрабатывает разрыв страницы, TEX воздержится от обработки вставок.\vsplit 〈number〉 to 〈dimen〉 — Эта команда заставляет TEX разделить блок с номером 〈number〉, который мы назовем B2, на две части.\splitmaxdepth [ 〈dimen〉 parameter ] — Этот параметр определяет максимально допустимую глубину поля, полученного в результате \vsplit.\splittopskip [ 〈glue〉 parameter ] — Этот параметр определяет клей, который TEX вставляет в верхнюю часть блока, полученного в результате \vsplit.\thinspace — Эта команда создает положительный керн, ширина которого составляет одну шестую em, т.е. она заставляет TEX смещать свою позицию вправо на эту величину. Полезно при использовании одиночных и двойных ковычек.\negthinspace — Эта команда создает отрицательный керн, ширина которого составляет одну шестую em, т. е. заставляет TEX смещать свою позицию влево на эту величину.\enspace — Эта команда создает керн, ширина которого равна 1em.\enskip \quad \qquad — Каждая из этих команд создает шарик горизонтального клея, который не может ни растягиваться, ни сжиматься. 1/2em, 1em, 2em.\smallskip \medskip \bigskip — вертикальный отступ.\smallskipamount [ 〈glue〉 parameter ] — Эти параметры определяют количество клея, производимого командами \smallskip, \medskip и \bigskip.\medskipamount [ 〈glue〉 parameter ] \bigskipamount [ 〈glue〉 parameter ]\hskip 〈dimen1 〉 plus 〈dimen2 〉 minus 〈dimen3 〉 — горизонтальная\vskip 〈dimen1 〉 plus 〈dimen2 〉 minus 〈dimen3 〉 — вертикальная\hbox to 2in{one\hskip 0pt plus .5in two}
\hglue 〈glue〉 — Команда \hglue создает горизонтальное склеивание, которое не исчезает при разрыве строки\vglue 〈glue〉 — команда \vglue создает вертикальную склейку, которая не исчезает при разрыве страницы.\topglue 〈glue〉 — Эта команда заставляет пространство от верха страницы до верха первого поля на странице быть склеенным.\kern 〈dimen〉 — В горизонтальном режиме TEX перемещает свое положение вправо (при положительном керне) или влево (при отрицательном керне). В вертикальном режиме TEX перемещает свою позицию вниз по странице (при положительном керне) или вверх (при отрицательном керне).\centerline{$\Downarrow$}\kern 3pt % a vertical kern
\centerline{$\Longrightarrow$\kern 6pt % a horizontal kern
{\bf Heed my warning!}\kern 6pt % another horizontal kern
$\Longleftarrow$}
\kern 3pt % another vertical kern
\centerline{$\Uparrow$}
\hfil \hfill — Эти команды создают бесконечно растягиваемый горизонтальный и вертикальный клей, который подавляет любое конечное растяжение, которое может присутствовать.\vfil \vfill\hss \vss — Эти команды создают горизонтальный и вертикальный клей, который одновременно бесконечно растягивается и бесконечно сжимается.\hfilneg \vfilneg — Эти команды отменяют эффект предыдущего \hfil или \vfil. В то время как \hfil и \vfil производят бесконечно растягиваемый позитивный клей, \hfilneg и \vfilneg производят бесконечно растягиваемый негативный клей.\hbox { 〈horizontal mode material〉 }
\hbox to 〈dimen〉 { 〈horizontal mode material〉 }
\hbox spread 〈dimen〉 { 〈horizontal mode material〉 }
Эта команда создает hbox (горизонтальный прямоугольник), содержащий 〈материал горизонтального режима〉.
\vtop 〈vertical mode material〉
\vtop to 〈dimen〉 { 〈vertical mode material〉 }
\vtop spread 〈dimen〉 { 〈vertical mode material〉 }
\vbox { 〈vertical mode material〉 }
\vbox to 〈dimen〉 { 〈vertical mode material〉 }
\vbox spread 〈dimen〉 { 〈vertical mode material〉 }
Эти команды создают vbox (вертикальный блок), содержащий 〈материал вертикального режима〉.
\boxmaxdepth [ 〈dimen〉 parameter ] — Этот параметр содержит размер D. TEX не будет создавать блок, глубина которого превышает D.\underbar 〈argument〉 — Эта команда помещает 〈аргумент〉 в hbox и подчеркивает его, не обращая внимания на все, что выступает за базовую линию блока.\everyhbox [ 〈token list〉 parameter ] — Эти параметры содержат списки токенов, которые TEX расширяет в начале каждого создаваемого им hbox или vbox.\everyvbox [ 〈token list〉 parameter ]\setbox 〈register〉 = 〈box〉 — команда устанавливают содержимое регистра, номер которого равен 〈register〉.\box 〈register〉 — команда выводит содержимое регистра\setbox0 = \hbox{mushroom}
\setbox1 = \vbox{\copy0\box0\box0}
\box1 %выведет box1 и забудет его содержимое
\copy 〈register〉 — копирует содержимое box n не стирая его содержимого\unhbox 〈register〉 — Эти команды создают список, содержащийся в регистре ящика 〈register〉, и делают этот регистр ящика недействительным.\unvbox 〈register〉 — эти команды освобождают память и очищают box с выбранным номером\unhcopy 〈register〉 \unvcopy 〈register〉 — Эти команды создают список, содержащийся в блочном регистре 〈register〉, и оставляют содержимое регистра нетронутым.\moveleft 〈dimen〉 〈box〉 \moveright 〈dimen〉 〈box〉 — сдвинуть влево, сдвинуть вправо\lower 〈dimen〉 〈box〉 \raise 〈dimen〉 〈box〉 — сдвинуть вниз, сдвинуть вниз.\ht 〈register〉 [ 〈dimen〉 parameter ] — высота\dp 〈register〉 [ 〈dimen〉 parameter ] — глубина\wd 〈register〉 [ 〈dimen〉 parameter ] — ширинаЭти команды хранят размеры box-ов
\setbox0 = \vtop{\hbox{a}\hbox{beige}\hbox{bunny}}%
The box has width \the\wd0, height \the\ht0, and depth \the\dp0.
\strut — Эта команда создает блок, ширина которого равна нулю, а высота (8,5 пт) и глубина (3,5 пт) соответствуют более или менее типичной строке текста в cmr10, простом шрифте TEX по умолчанию.\mathstrut — Эта команда создает фантомную формулу, ширина которой равна нулю, а высота и глубина такие же, как у левой круглой скобки.\phantom 〈argument〉 — Эта команда создает пустое поле того же размера и размещения, что и 〈аргумент〉, если бы он был набран.\hphantom 〈argument〉 —hphantom создает блок той же ширины, что и 〈аргумент〉, но с нулевой высотой и глубиной.\vphantom 〈argument〉 — vphantom создает блок той же высоты и глубины, что и 〈аргумент〉, но нулевой ширины.\smash 〈argument〉 — Эта команда вводит 〈аргумент〉, но заставляет высоту и глубину содержащего его поля равняться нулю.\null — Эта команда создает пустой hbox. \setbox0 = \null\overfullrule [ 〈dimen〉 parameter ] — Этот параметр определяет ширину правила, которое TEX добавляет к переполненному hbox. Plain TEX устанавливает значение 5pt.\hbadness [ 〈number〉 parameter ] \vbadness [ 〈number〉 parameter ] — Эти параметры определяют пороговые значения горизонтальной и вертикальной неисправности для сообщения о недостаточном или переполненном ящиках.\badness — Эта команда возвращает числовое значение дефектности блока (горизонтального или вертикального), созданного TEX в последний раз.\hfuzz [ 〈dimen〉 parameter ] \vfuzz [ 〈dimen〉 parameter ] — Эти параметры определяют величину, на которую ящик может превысить свой естественный размер, прежде чем TEX сочтет его переполненным.\hfuzz = .5in \hbox to 2in{This box is longer than two inches.}
Эти управляющие последовательности возвращают значение последнего элемента в текущем списке. Это не настоящие команды, поскольку они могут появляться только как часть аргумента.
Эти управляющие последовательности наиболее полезны после вызовов макросов, в которые могли быть вставлены объекты указанных типов.
Если последний элемент в текущем списке имеет тип керн, клей или пенальти соответственно, эти команды удаляют его из этого списка. Если элемент не того типа, эти команды не имеют никакого эффекта.
\hrule
\hrule height 〈dimen〉 width 〈dimen〉 depth 〈dimen〉
\vrule
\vrule width 〈dimen〉 height 〈dimen〉 depth 〈dimen〉
Команда \hrule создает горизонтальную линию; команда \vrule создает вертикальное линию.
По умолчанию \hrule будет расширено по горизонтали до границ самого внутреннего поля или выравнивания. Высота 0,4 пт; Глубина 0pt.
\leaders 〈box or rule〉 〈skip command〉
\cleaders 〈box or rule〉 〈skip command〉
\xleaders 〈box or rule〉 〈skip command〉
заполняют горизонтальное или вертикальное пространство копиями узора
〈box or rule〉 — указывает шаблон〈skip command — указывает команду для заполнения, т.е. пространство\def\pattern{\hbox to 15pt{\hfil.\hfil}}
\line{Down the Rabbit-Hole {\leaders\pattern\hfil} 1}
\line{The Pool of Tears {\leaders\pattern\hfil} 9}
\line{A Caucus-Race and a Long Tale {\cleaders\pattern \hfil} 19}
\line{Pig and Pepper {\xleaders\pattern\hfil} 27}
\dotfill \hrulefill — Эти команды соответственно заполняют окружающее горизонтальное пространство рядом точек на базовой линии и горизонтальной линией на базовой линии.\hbox to 3in{Start {\dotfill} Finish}
\hbox to 3in{Swedish {\hrulefill} Finnish}
\leftarrowfill \rightarrowfill — Эти команды заполняют окружающее горизонтальное пространство стрелками, указывающими влево или вправо.\hbox to 3in{\vrule \rightarrowfill \ 3 in \leftarrowfill\vrule}
\+ 〈text〉 & 〈text〉 & · · · \cr\tabalign — Эти команды начинаются с одной строки с выравниванием по вкладкам.\cleartabs % обнуляет установки предыдущих settabs
\+ {\bf if }$a[i] < a[i+1]$ &{\bf then}&\cr
\+&&$a[i] := a[i+1]$;\cr
\+&&{\it found }$:=$ {\bf true};\cr
\+&{\bf else}\cr
\+&&{\it found }$:=$ {\bf false};\cr
\+&{\bf end if};\cr
\settabs 〈number〉 \columns — задает одинаковый размер колонкам\settabs \+ 〈sample line〉 \cr — задает шаблон с образцом\cleartabs — очищает предыдущие settabs\halign { 〈preamble〉 \cr 〈row〉 \cr . . . 〈row〉 \cr }
\halign to 〈dimen〉{ 〈preamble〉 \cr 〈row〉 \cr . . . 〈row〉 \cr }
\halign spread 〈dimen〉{ 〈preamble〉 \cr 〈row〉 \cr . . . 〈row〉 \cr }
Эта команда создает горизонтальное выравнивание, состоящее из последовательности строк, где каждая строка, в свою очередь, содержит последовательность записей столбцов. TEX регулирует ширину записей столбца, чтобы разместить самую широкую запись в каждом столбце.
\valign { 〈preamble〉\cr 〈column〉\cr . . . 〈column〉\cr }
\valign to 〈dimen〉{ 〈preamble〉\cr 〈column〉\cr . . . 〈column〉\cr }
\valign spread 〈dimen〉{ 〈preamble〉\cr 〈column〉\cr . . . 〈column〉\cr }
делает вертикальную таблицу
\ialign — Эта команда ведет себя так же, как \halign, за исключением того, что она сначала устанавливает клей \tabskip равным нулю, а \everycr — пустым.\cr — Эта команда завершает преамбулу горизонтального или вертикального выравнивания.\endline — Эта команда является синонимом команды \cr.\crcr — Эта команда ведет себя так же, как \cr, за исключением того, что TEX игнорирует ее, если она идет сразу после \cr или \noalign.\omit — Эта команда сообщает TEX игнорировать шаблон при горизонтальном или вертикальном выравнивании\span — Значение этой команды зависит от того, появляется ли она в преамбуле или в записи выравнивания. Помещение \span перед токеном в преамбуле приводит к немедленному расширению этого токена в соответствии с обычными правилами расширения макросов TEXа. Размещение \span вместо «&» между двумя записями столбца или строки приводит к объединению этих столбцов или строк.\multispan 〈number〉 — Эта команда сообщает TEX, что следующие столбцы 〈number〉 в строке с горизонтальным выравниванием или строки 〈number〉 в столбце с вертикальным выравниванием должны быть объединены в один столбец или строку.\noalign { 〈vertical mode material〉 } \noalign { 〈horizontal mode material〉 } — Чаще всего \noalign используется для добавления дополнительного пробела после строки или столбца.\tabskip [ 〈glue〉 parameter ] — Этот параметр определяет количество горизонтального или вертикального клея, который TEX накладывает между столбцами горизонтального выравнивания или между строками вертикального выравнивания.\hidewidth — Эта команда сообщает TEX игнорировать ширину следующей записи столбца при горизонтальном выравнивании.\everycr [ 〈token list〉 parameter ] — TEX расширяет 〈список токенов〉 всякий раз, когда он выполняет \cr — в конце каждой преамбулы. Т.е. выполняет список команд после \cr.\lbrace { \{
} \rbrace } \}
[ \lbrack
] \rbrack
〈 \langle
〉 \rangle
← \leftarrow
← \gets
⇐ \Leftarrow
→ \rightarrow
→ \to
⇒ \Rightarrow
↔ \leftrightarrow
⇔ \Leftrightarrow
←− \longleftarrow
⇐= \Longleftarrow
−→ \longrightarrow
=⇒ \Longrightarrow
←→ \longleftrightarrow
⇐⇒ \Longleftrightarrow
⇐⇒ \iff
←↩ \hookleftarrow
↪→ \hookrightarrow
↽ \leftharpoondown
⇁ \rightharpoondown
↼ \leftharpoonup
⇀ \rightharpoonup
⇀↽ \rightleftharpoons
7→ \mapsto
7−→ \longmapsto
↓ \downarrow
⇓ \Downarrow
↑ \uparrow
⇑ \Uparrow
l \updownarrow
m \Updownarrow
↗ \nearrow
↘ \searrow
↖ \nwarrow
↙ \swarrow
\font
\font 〈control sequence〉 = 〈fontname〉
\font 〈control sequence〉 = 〈fontname〉 scaled 〈number〉
\font 〈control sequence〉 = 〈fontname〉 at 〈dimen〉
Это заставляет TEX загружать файл метрик шрифта (файл .tfm) для 〈fontname〉.
Если ни масштабированный 〈number〉, ни 〈dimen〉 отсутствуют, шрифт используется в его дизайнерском размере — размере, в котором он обычно выглядит лучше всего. В противном случае загружается увеличенная версия шрифта.
Scaled — 〈number〉, шрифт увеличивается в 〈number〉/1000.
Если присутствует 〈dimen〉, шрифт масштабируется до 〈dimen〉
\font\tentt = cmtt10
\font\bigttfont = cmtt10 scaled \magstep2
\font\eleventtfont = cmtt10 at 11pt
\fontdimen 〈number〉 〈font〉 [ 〈dimen〉 parameter ] — изменяет различные параметры шрифта| номер | значение |
|---|---|
| 1 | slant per point |
| 2 | interword space |
| 3 | interword stretch |
| 4 | interword shrink |
| 5 | x-height (size of 1ex) |
| 6 | quad width (size of 1em) |
| 7 | extra space |
Here’s a line printed normally.\par
\dimen0=\fontdimen2\font %сохранить значение пробела в dimen0
\fontdimen2\font=3\fontdimen2\font % увеличить пробел в 3 раза
\noindent Here’s a really spaced-out line.
\fontdimen2\font=\dimen0 %восстановить первоначальные значения
\magnification = 〈number〉 — масштабирование\mag [ 〈number〉 parameter ] — лучше использовать первое\magstep 〈number〉 — Эта команда расширяется до коэффициента увеличения, необходимого для увеличения всего документа (кроме истинных размеров) на 1,2r, где r — значение 〈number〉. 〈число〉 должно быть от 0 до 5.\magstephalf — маштабирование в полразмера\number 〈number〉 — Эта команда создает представление числа в виде последовательности токенов символов.\number 24 \quad \count13 = -10000 \number\count13
выдаст: 24 -10000
\romannumeral 〈number〉 — Эта команда создает представление числа римскими цифрами в виде последовательности токенов символов.\time [ 〈number〉 parameter ] — TEX устанавливает этот параметр равным количеству минут, прошедших с полуночи (текущего дня).\day [ 〈number〉 parameter ] — TEX устанавливает этот параметр на текущий день месяца. Это число от 1 до 31.\month [ 〈number〉 parameter ] — TEX устанавливает для этого параметра текущий месяц. Это число от 1 до 12.\year [ 〈number〉 parameter ] — TEX устанавливает для этого параметра текущий год\fmtname \fmtversion — Эти команды создают имя и номер версии формата TEX, например, обычного TEX или LATEX, который вы используете.\jobname — Эта команда создает базовое имя файла, с которым был вызван TEX.\meaning 〈token〉 — Эта команда определяет значение 〈токена〉.[{\tt \meaning\eject}] [\meaning\tenrm] [\meaning Y]
вернет:
[macro:->\par \break ] [select font cmr10] [the letter Y]
\string 〈control sequence〉 — Эта команда создает символы, составляющие имя control sequence\escapechar [ 〈number〉 parameter ] — Этот параметр определяет код ASCII символа, который TEX использует для представления escape-символа\fontname 〈font〉 — Эта команда создает имя файла для 〈font〉. Имя файла — это 〈имя шрифта〉, которое использовалось для определения 〈font〉.\font\myfive=cmr5
[\fontname\myfive]
вернет [cmr5]
\begingroup \endgroup — Эти две команды начинают и завершают группу.\global — Эта команда делает следующее определение или назначение глобальным\globaldefs [ 〈number〉 parameter ] — тоже, что \global\def\aftergroup 〈token〉 — Когда TEX встречает эту команду во время ввода, он сохраняет 〈токен〉. После окончания текущей группы он вставляет 〈token〉 обратно во входные данные и расширяет их.\afterassignment 〈token〉 — Когда TEX встречает эту команду, он сохраняет 〈token〉 в специальном месте. После следующего выполнения присваивания он вставляет 〈token〉 во входные данные и расширяет их.\def 〈control sequence〉 〈parameter text〉 { 〈replacement text〉 } — Эта команда определяет 〈последовательность управления〉 как макрос с указанным 〈текстом параметра〉 и 〈текстом замены〉.\edef 〈control sequence〉 〈parameter text〉 { 〈replacement text〉 } — Эта команда определяет макрос таким же общим способом, как и \def. Разница в том, что TEX немедленно расширяет 〈текст замены〉 \edef (но при этом ничего не выполняя).Вы можете запретить расширение управляющей последовательности, которая в противном случае была бы расширена, используя \noexpand или можете отложить раскрытие управляющей последовательности, используя команду \expandafter.
Команды \write, \message, \errmessage, \wlog и \csname расширяют свои списки токенов, используя те же правила, которые \edef использует для расширения замещающего текста.
\gdef 〈control sequence〉 〈parameter text〉 { 〈replacement text〉 } — эквивалентно \global\def.\xdef 〈control sequence〉 〈parameter text〉 { 〈replacement text〉 } — эквивалентно \global\edef\long — Эта команда используется как префикс к определению макроса. Он сообщает TEX, что аргументы макроса могут включать токены \par\long\def\aa#1{\par\hrule\smallskip#1\par\smallskip\hrule}
\aa{This is the first line.\par
This is the second line.} % without \long, TeX would complain
\outer — Эта команда используется как префикс к определению макроса. Он сообщает TEX, что макрос является внешним (стр. 83) и не может использоваться в определенных контекстах.\outer\def\chapterhead#1{%
\eject\topglue 2in \centerline{\bf #1}\bigskip}
% Using \chapterhead in a forbidden context causes an
% error message.
\chardef 〈control sequence〉=〈charcode〉 — Эта команда определяет 〈последовательность управления〉 как 〈символьный код〉. Хотя \chardef чаще всего используется для определения символов, его также можно использовать для присвоения имени числу в диапазоне 0–255, даже если вы не используете это число в качестве кода символа.\chardef\percent = ‘\%
21\percent, {\it 19\percent}
% Get the percent character in roman and in italic
выдаст: 21%, 19%
\mathchardef 〈control sequence〉=〈mathcode〉 — определит математический символ\let 〈control sequence〉 = 〈token〉 — определит синоним команды\futurelet 〈control sequence〉 〈token1 〉 〈token2 〉 —\csname 〈token list〉 \endcsname — Эта команда создает управляющую последовательность из 〈списка токенов〉. Он обеспечивает способ синтеза управляющих последовательностей, в том числе тех, которые вы обычно не можете написать. 〈список токенов〉 сам может включать в себя управляющие последовательности; он расширяется так же, как заменяющий текст определения \edef\def\capTe{Te} This book purports to be about \csname\capTe X\endcsname.
\expandafter 〈token1 〉 〈token2 〉 — Эта команда сообщает TEXу расширить 〈token1〉 в соответствии со своими правилами расширения макросов после расширения 〈token2〉 на один уровень.\def\aa{xyz}
\tt % Use this font so ‘\’ prints that way.
[\string\aa] [\expandafter\string\aa] [\expandafter\string\csname TeX\endcsname]
%выводит: [\aa] [xyz] [\TeX]
\noexpand 〈token〉 — Эта команда сообщает TEX о подавлении расширения 〈token〉, если 〈token〉 является управляющей последовательностью, которую можно расширить.\the 〈token〉 — Эта команда обычно расширяется до списка токенов символов, представляющих 〈токен〉. Это могут быть регистры, переменные и т.д. \parindent \deadcycles \count0 \catcode \fontdimen3\sevenbf \hyphenchar \skewchar \skewchar\teni \lastpenalty, \lastskip, \lastkern \chardef \mathchardefКроме того, \the может расширяться до несимвольных токенов в следующих двух случаях:
\if 〈token1 〉 〈token2 〉 — Эта команда проверяет, имеют ли 〈token1 〉 и 〈token2 〉 одинаковый код символа, независимо от кодов их категорий.\ifcat 〈token1 〉 〈token2 〉 — Эта команда проверяет, имеют ли 〈token1〉 и 〈token2〉 одинаковый код категории.\ifx 〈token1 〉 〈token2 〉 — Эта команда проверяет, совпадают ли 〈token1〉 и 〈token2〉. В отличие от \if и \ifcat, \ifx не расширяет токены, следующие за \ifx, поэтому 〈token1 〉 и 〈token2 〉 — это два токена сразу после \ifx.\ifnum 〈number1 〉 〈relation〉 〈number2 〉 — Эта команда проверяет, удовлетворяют ли 〈номер1〉 и 〈номер2〉 〈отношению〉, которое должно быть либо «<», «=» или «>».\ifodd 〈number〉 — Эта команда проверяет, является ли 〈число〉 нечетным.\ifdim 〈dimen1 〉 〈relation〉 〈dimen2 〉 — Эта команда проверяет, удовлетворяют ли 〈dimen1 〉 и 〈dimen2 〉 〈отношению〉, которое должно быть либо «<», «=» или «>».\ifhmode \ifvmode \ifmmode \ifinner — определяет в какой моде находится Tex\ifhbox 〈register〉 \ifvbox 〈register〉 \ifvoid 〈register〉 — Эти команды проверяют содержимое ящика-регистра с номером 〈register〉.\ifeof 〈number〉 — Эта команда проверяет входной поток на конец файла.\ifcase 〈number〉〈case0 text〉 \or 〈case1 text〉 \or . . . \or 〈casen text〉 \else 〈otherwise text〉 \fi — Эта команда представляет тест с пронумерованными несколькими случаями. Если 〈number〉 имеет значение k, TEX расширит 〈casek text〉, если он существует, и 〈иначе text〉, если его нет.\iftrue \iffalse — Эти команды эквивалентны тестам, которые всегда верны или всегда ложны.\else — Эта команда представляет «ложную» альтернативу условной проверки.\fi — Эта команда завершает текст условной проверки.\newif \if〈test name〉 — Эта команда называет три управляющих последовательности именами \alphatrue, \alphafalse и \ifalpha, где alpha — это 〈имя теста〉\loop α \ifΩ β \repeat — Эти команды предоставляют конструкцию цикла для TEXа. Здесь α и β — произвольные последовательности команд, а \ifΩ — любой из условных тестов. \repeat заменяет \fi, соответствующий тесту, поэтому вам не нужно явно писать \fi для завершения теста.\count255 = 6
\loop
\number\count255\
\ifnum\count255 > 0
\advance\count255 by -1
\repeat
\relax — Эта команда сообщает TEXу ничего не делать.\empty — Эта команда вообще не требует токенов. Он отличается от \relax тем, что исчезает после раскрытия макроса.\count 〈register〉 = 〈number〉
\dimen 〈register〉 = 〈dimen〉
\skip 〈register〉 = 〈glue〉
\muskip 〈register〉 = 〈muglue〉
\toks 〈register〉 = 〈token variable〉
\toks 〈register〉 = { 〈token list〉 }
%Регистру \toks можно назначить либо переменную токена (регистр или параметр),
%либо список токенов. Когда вы назначаете список токенов регистру токенов,
%токены в списке токенов не расширяются.
\count 〈register〉
\dimen 〈register〉
\skip 〈register〉
\muskip 〈register〉
\toks 〈register>
Первые шесть команд, перечисленных здесь, присваивают что-то регистру. Остальные пять управляющих последовательностей не являются настоящими командами, поскольку могут появляться только как часть аргумента. Они возвращают содержимое указанного регистра. Хотя вы не можете использовать эти управляющие последовательности сами по себе в качестве текстовых команд, вы можете использовать \the для преобразования их в текст и набора их значений.
\newcount — Резервирование регистров\maxdimen — Эта последовательность управления дает 〈размер〉, который является наибольшим размером, приемлемым для TEXОперации над регистрами: \advance, \multiply, \divide, \setbox, \box.
\newcount %каждый резервирует регистр указанного типа.
\newdimen
\newskip
\newmuskip
\newtoks
\newbox
\newread %зарезервируйте входной поток и выходной поток соответственно.
\newwrite
\newfam %резервирует семейство математических шрифтов.
\newinsert %резервирует тип вставки.
\newlanguage %резервирует набор шаблонов расстановки переносов.
\countdef 〈control sequence〉 = 〈register〉
\dimendef 〈control sequence〉 = 〈register〉
\skipdef 〈control sequence〉 = 〈register〉
\muskipdef 〈control sequence〉 = 〈register〉
\toksdef 〈control sequence〉 = 〈register〉
Эти команды определяют 〈последовательность управления〉 для ссылки на регистр указанной категории, номер которого равен 〈register〉.
\advance 〈count register〉 by 〈number〉
\advance 〈dimen register〉 by 〈dimen〉
\advance 〈skip register〉 by 〈glue〉
\advance 〈muskip register〉 by 〈muglue〉
Эта команда добавляет совместимое количество в регистр.
\multiply 〈register〉 by 〈number〉
\divide 〈register〉 by 〈number〉
Эти команды умножают и делят значение в 〈register〉 на 〈number〉 (которое может быть отрицательным).
\bye — заканчивается документ\end — Эта команда сообщает TEX создать последнюю страницу и завершить задание. Однако он не заполняет страницу, поэтому обычно лучше использовать \bye, а не \end.\input 〈filename〉 — Эта команда сообщает TEX прочитать входные данные из файла 〈имя файла〉. Когда этот файл исчерпан, TEX возвращается к чтению из предыдущего источника ввода.\endinput — Эта команда сообщает TEXу прекратить чтение ввода из текущего файла, когда он в следующий раз достигнет конца строки.\inputlineno — Эта команда возвращает число (не строку), задающее номер текущей строки, определенный как номер, который будет отображаться в сообщении об ошибке, если ошибка произойдет в этот момент.\openin 〈number〉 = 〈filename〉 — Эта команда сообщает TEXу открыть файл с именем 〈имя файла〉 и сделать его доступным для чтения через входной поток, обозначенный 〈number〉 . Number от 0 до 15. Чтение из файла выполняется командой \read. Номера потоков определяются с помощью команды \newread.\closein 〈number〉 — Эта команда сообщает TEXу закрыть входной поток с номером 〈number〉, т. е. прекратить связь между входным потоком и его файлом.\read 〈number〉 to 〈control sequence〉 — Эта команда сообщает TEX прочитать строку из файла, связанного с входным потоком, обозначенным 〈номером〉, и назначить токены в этой строке 〈управляющей последовательности〉.\openout 〈number〉 = 〈filename〉 — Эта команда сообщает TEXу открыть файл с именем 〈имя файла〉 и сделать его доступным для записи через выходной поток, обозначенный 〈номер〉. 〈число〉 должно быть от 0 до 15.\closeout 〈number〉 — Эта команда сообщает TEXу закрыть выходной поток с номером 〈number〉.\write 〈number〉 { 〈token list〉 } — Эта команда сообщает TEX записать 〈список токенов〉 в файл, связанный с выходным потоком, обозначенным 〈номер〉.\immediate — Эта команда должна предшествовать командам \openout, \closeout или \write. Он сообщает TEXу выполнить указанную операцию с файлом без задержки.\special { 〈token list〉 } — Эта команда сообщает TEX записать 〈список токенов〉 непосредственно в файл .dvi при следующей отправке страницы.\newlinechar [ 〈number〉 parameter ] — Этот параметр содержит символ, обозначающий новую строку на выходе. Когда TEX встречает этот символ при чтении аргумента команды \write, \message или \errmessage, он начинает новую строку.\catcode 〈charcode〉 [ 〈number〉 table entry ] — Эта запись таблицы содержит код категории символа, код ASCII которого равен 〈charcode〉.\active — Эта команда содержит код категории для активного символа, а именно цифру 13.\mathcode 〈charcode〉 [ 〈number〉 table entry ] — Эта запись таблицы содержит математический код символа, ASCII-код которого равен 〈charcode〉\delcode 〈charcode〉 [ 〈number〉 table entry ] — Эта запись таблицы определяет код-разделитель для входного символа, код ASCII которого равен 〈charcode〉.\endlinechar [ 〈number〉 parameter ] — Этот параметр содержит код символа, который TEX добавляет в конец каждой входной строки.\ignorespaces — Эта команда сообщает TEXу читать и расширять токены, пока не найдет тот, который не является токеном пространства, игнорируя любые токены пространства, которые он находит на своем пути.\show 〈token〉 \showthe 〈argument〉 \showbox 〈number〉 \showlists — Эти команды записывают информацию в журнал вашего запуска TEXа\tracingonline [ 〈number〉 parameter ] — Если этот параметр больше нуля, TEX будет отображать результаты трассировки (включая \showbox и \showlists) на вашем терминале в дополнение к записи их в файл журнала.\message { 〈token list〉 } \errmessage { 〈token list〉 } — Эти команды отображают сообщение, заданное 〈списком токенов〉, на вашем терминале, а также записывают его в журнал. Все макросы в сообщении раскрываются, но команды не выполняются.\wlog { 〈token list〉 } — Эта команда записывает 〈список токенов〉 в файл журнала.\errhelp [ 〈token list〉 parameter ] — Этот параметр содержит список токенов, который TEX отображает, когда вы запрашиваете помощь в ответ на команду \errmessage.\newhelp 〈control sequence〉 { 〈help text〉 } — Эта команда назначает справочное сообщение, заданное 〈текстом помощи〉, 〈последовательности управления〉.\dump — Эта команда, которая не должна появляться внутри группы, сбрасывает содержимое памяти TEXа в файл формата (стр. 65). Используя virtex, специальную «чистую» форму TEXа, вы можете затем перезагрузить файл формата на высокой скорости и продолжить работу в том же состоянии, в котором находился TEX на момент создания дампа. \dump также завершает выполнение. Поскольку \dump можно использовать только в initex, а не в рабочих формах TEXа, он полезен только тем, кто устанавливает TEX.\everyjob [ 〈token list〉 parameter ] — Этот параметр содержит список токенов, который TEX расширяет в начале каждого задания. Поскольку назначение \everyjob не может повлиять на текущий запуск (к тому времени, когда вы выполните назначение, будет уже слишком поздно), оно полезно только для людей, которые подготавливают файлы форматирования.Ставится после большой буквы,чтобы Tex мог понять, что точку нужно воспринимать не как после большой буквы.
Поставить две одинарные, а чтобы разделить одинарную от двойной между ними поставить команду ’text’\thinspace"
\def\xmpheader#1/#2{% Now here’s the title.
\leftline{\xmplbx Example #1:\quad\xmplbxti #2}%
\vglue .5\baselineskip % skip an extra half line
}
Какие особенности?
при объявлении между параметрами указывается разделитель,которым будут отделяться параметры, это может быть пробел или как у меня #1/#2. Сложные данные передаются просто в группе {}.
Но определению \def я еще посвящу отдельную главу.
\chardef \\ = `\\ — определили \\ как backslash
\char `\^ — выводит символ по его коду
\`
\'
\"
\^
...
через backslash ставим знак и дальше нужную букву.
Макрос дробилка. На вход две цифири через слеш.
\def\frac#1/#2{\leavevmode
\kern.1em \raise .5ex \hbox{\the\scriptfont0 #1}%
\kern-.1em $/$%
\kern-.15em \lower .25ex \hbox{\the\scriptfont0 #2}%
}%
`\kern` --- сдвигает символ вправо или влево
`\raise` --- сдвигает вверх
`\lower` --- сдвигает вниз
`\leavevmode` --- переключается из вертикальной моды
Нужно для правильной разметки пространства
\newdimen\descindent
\descindent = 8pc
rlap — делает тоже, но вправо. Позицию курсора при этом не меняет.
\llap{\hbox to \descindent{\bf Queen of Hearts\hfil}}%
замечательный прием:
У этих замечательных box-ов есть переменные:
\hbox spread 8pt{\hfil\vbox spread 8pt{\vfil
Для различных строк с подчеркиванием или точками, а также любые пространства для заполнения однообразным элементом
\line{\hfil\hbox to 3in{\leaders\hbox{ * }\hfil}\hfil}
Заполнит 3in звездочками и выровняет их по центру
У него есть 2 брата: \cleaders и \xleaders — которые заполняют не выравнивая элементы заполнения относительно разных строк.
Печатает первое предложение выделенным жирным, а остальной абзац курсивом.
footer и header
{\xmpheader 8/{A ruled table}% see p. 21
\bigskip \offinterlineskip % So the vertical rules are connected.
% \tablerule constructs a thin rule across the table.
\def\tablerule{\noalign{\hrule}}
% \tableskip creates 9pt of space between entries.
\def\tableskip{\omit&height 9pt&&&\omit\cr}
% & separates templates for each column. TeX substitutes
% the text of the entries for #. We must have a strut
% present in every row of the table; otherwise, the boxes
% won’t butt together properly, and the rules won’t join.
\halign{\tabskip = .7em plus 1em % glue between columns
% Use \vtop for whole paragraphs in the first column.
% Typeset the lines ragged right, without hyphenation.
\vtop{\hsize=6pc\pretolerance = 10000\hbadness = 10000
\normalbaselines\noindent\it#\strut}%
&\vrule #&#\hfil &\vrule #% the rules and middle column
% Use \vtop for whole paragraphs in the last column.
&\vtop{\hsize=11pc \parindent=0pt \normalbaselineskip=12pt
\normalbaselines \rightskip=3pt plus2em #}\cr
Очень большой раздел и пока им не интересуюсь
Это символ, которому будет назначено действие в TEX
Если символ не будет \active до определения, назначить ему команду не удастся
Например: \catcode ‘~ = \active \def~{\penalty10000\ }
{\hsize = 1.7 in \settabs 2 \columns
\+cattle&herd\cr
\+fish&school\cr
\+lions&pride\cr}
выравнивание с учетом настроек преамбулы
\halign{\hfil#\hfil &\hfil#\hfil &\hfil#\hfil \cr
{\hsize=0.6in \parindent=0pt
\valign{#\strut&#\strut&#\strut\cr
one&two&three\cr
four&five&six\cr
seven&eight&nine\cr
ten&eleven\cr}}
Текс расширяет макросы слева направо, но команда \expandafter может изменить порядокраскрытия макросов
| Code | Назначение |
|---|---|
| 0 | \ |
| 1 | { |
| 2 | } |
| 3 | $ |
| 4 | & |
| 5 | ^^M= |
| 6 | # |
| 7 | ^ и ^^K |
| 8 | _ и ^^A |
| 9 | ^^@ (ignored) |
| 10 | пробел ^^I |
| 11 | a..z A..Z |
| 12 | другие символы |
| 13 | ~ и ^^L активный |
| 14 | % |
| 15 | ^^? ошибка |
Категория 11 и 12
команда (напечатать символ) \char `h тоже самое, что \char104 напечатает h
Используется в математической моде и влияет на выделение места для каждого символа
Все, что должен выполнить TEX:
\ifα〈true text〉\else〈false text〉\fi или \ifα〈true text〉\fi
проверка выполняется до расширения макросов
Обычно начинаетяс с \ и имя последовательности, определенное в \def
Заканчивается, когда TEX видит небукву. Или когда заканчивается управляющий символ.
состоит из \ и символа
обычно скобки в математической моде
| код | значение |
|---|---|
| pt | point (72.27 points = 1 inch) |
| pc | pica (1 pica = 12 points) |
| bp | big point (72 big points = 1 inch) |
| in | inch |
| cm | centimeter (2.54 centimeters = 1 inch) |
| mm | millimeter (10 millimeters = 1 centimeter) |
| dd | didˆot point (1157 didˆot points = 1238 points) |
| cc | cicero (1 cicero = 12 didoˆt points) |
| sp | scaled point (65536 scaled points = 1 point) |
| em | ширина M |
| ex | высота x |
бесконечность: fil, fill, filll
Множитель перед размерами f/1000
\kern 8 true pt — сделает неизменным размер при масштабировании
\font\имя=шрифт в системе
\font\twelvebf=cmbx12
распространяется на весь документ
или сокращенный вариант: \gdef или \xdef вместо \global\def и \global\edef
есть вертикальный и горизонтальный
\hskip 6pt plus 2pt minus 3pt — клей может растягиваться и сжиматься
у клея есть свойства stretch — plus и shrink — minus
определяет расстояние между строк и определяется параметрами:
\baselineskip, \lineskip, \lineskiplimit
текст с отступом
\leftskip, \rightskip, \raggedright — установит размеры горизонтального бокса
смещает символы горизонтально
заполнит пространство символами (нужно для оглавления)
\topmark, \firstmark, \botmark размещаются на странице и используются командой \mark
\def\section#1{\medskip{\bf#1}\smallskip\mark{#1}} % #1 is the name of the section
Определение section устанавливает метку с именем секции
Но нежелательно при использовании команды \edef и \write
78 +078 "4E '116 `N `\N — это один и тот же код
число печатается командой \number78 или \romannumeral78 — получим 78lxxviii
в этот box помещается готовая страница
готовый box255 отправляется командой \shipout в файл .dvi
В Tex разрывом страницы управляет штраф:
\penalty 10000 = \nobreak
\penalty -10000 = \break
| тип | контент |
|---|---|
| box | a box |
| count | a number |
| dimen | a dimension |
| muskip | muglue |
| skip | glue |
| toks | a token list |
Все регистры имеют нумерацию от 0 до 255
Вызов регистра \box0 или \box100, \skip0 или \skip20
setbox3 = \hbox{text} — присвоит значение регистру box3
count255 = -1 — присвоит -1
для резервирования регистров используются команды:
Просмотреть содержимое регистра можно с помощью команды \showthe\dimen0
действия для TeX когда, что-то пошло не так
% A small font and close interline spacing make this work
\smallskip\font\sixrm=cmr6 \sixrm \baselineskip=7pt
\dimen0=\fontdimen3\font \dimen2=\fontdimen4\font
\fontdimen3\font=1.8pt \fontdimen4\font=.9pt
\noindent \hfuzz=.1pt
\parshape 30 0pt 120pt 1pt 118pt 2pt 116pt 4pt 112pt 6pt
108pt 9pt 102pt 12pt 96pt 15pt 90pt 19pt 84pt 23pt 77pt
27pt 68pt 30.5pt 60pt 35pt 52pt 39pt 45pt 43pt 36pt 48pt
27pt 51.5pt 21pt 53pt 16.75pt 53pt 16.75pt 53pt 16.75pt 53pt
16.75pt 53pt 16.75pt 53pt 16.75pt 53pt 16.75pt 53pt 16.75pt
53pt 14.6pt 48pt 24pt 45pt 30.67pt 36.5pt 51pt 23pt 76.3pt
The wines of France and California may be the best known,
but they are not the only fine wines. Spanish wines are
often underestimated, and quite old ones may be available at
reasonable prices. For Spanish wines the vintage is not so
critical, but the climate of the Bordeaux region varies
greatly from year to year. Some vintages are not as good as
others, so these years ought to be s\kern -.1pt p\kern -.1pt
e\kern -.1pt c\hfil ially n\kern .1pt o\kern .1pt
t\kern .1pt e\kern .1pt d\hfil: 1962, 1964, 1966. 1958,
1959, 1960, 1961, 1964, 1966 are also good California
vintages. Good luck finding them!
\fontdimen3\font=\dimen0 \fontdimen4\font=\dimen2
Я это делаю в своем любимом Emacs
Here is my first \TeX\ sentence.
\bye
и сохранил с именем test.tex
tex test.tex
Получилось два файла на выходе: test.dvi и test.log
В test.log
This is TeX, Version 3.141592653 (TeX Live 2024) (preloaded format=tex 2024.10.2) 5 JAN 2025 20:03
**test.tex
(./test.tex [1] )
Output written on test.dvi (1 page, 292 bytes).
А файл dvi вполне себе просматривается emacs, в том виде, как и должно быть.
| символ | назначение | как вывести в tex |
|---|---|---|
| \ | спец символ и инструкции | $\backslash$ |
| { | открывает группу | ${$ |
| } | закрывает группу | $}$ |
| % | комментарии | % |
| & | разграничение колонок в таблице | & |
| ~ | неразрываемый пробел | ~{} |
| $ | начало и окончание математической моды | $ |
| ^ | надстрочник | ^{} |
| _ | подстрочник | _{} |
| # | определение заменяемого символа | # |
Акцент — это надстрочники и подстрочники над и под буквами
| наименование | Tex input | Tex output | Compose |
|---|---|---|---|
| grave | \`o | ò | cmp+` o |
| acute | \’o | ó | cmp+’ o |
| circumflex | \^o | ô | cmp+^ o |
| umlaut/dieresis/tr ́emat | \“o | ö | cmp+” o |
| tilde | \~o | õ | cmp+~ o |
| macron | \=o | ő | cmp+= o |
| dot | \.o | ȯ | cmp+. o |
Продолжение для символов требующих пробела
| наименование | Tex input | Tex output | Compose |
|---|---|---|---|
| cedilla | \c o | ǫ | cmp+, o |
| underdot | \d o | ọ | cmp+! o |
| underbar | \b o | o᤻ | o C-x 8 RET 193b |
| h ́acˇek | \v o | ǒ | cmp+v o |
| breve | \u o | ŏ | cmp+u o |
| tie | \t oo | o͡o | o C-x 8 RET 0361 o |
| Hungarian umlaut | \H o | ő | cmp+= o |
| ơ | cmp++ o | ||
| ° | cmp+o o | ||
| § | cmp+s o | ||
| ø | cmp+? o |
По этой ссылке весь unicode а в Emacs C-x 8 RET в помощь. ⤖ https://www.compart.com/en/unicode/
Но и это еще не всё!
Это нужно при оформлении HTML документации просто пишем имя через &Rarrtl и получаем результат.
Можно создать собственную комбинацию клавиш
Создайте пустой ~/.XCompose и включите в него содержимое стандартного файла, используя директиву include “%L”, например:
# ~/.XCompose
include "%L"
<Multi_key> <g> <a> : "α"
<Multi_key> <g> <b> : "β"
<Multi_key> <g> <g> : "γ"
В Tex по умолчанию доступны 16 шрифтов
| Наименование | команда |
|---|---|
| Roman | \rm |
| Boldface | \bf |
| Italic | \it |
| Slanted | \sl |
| Typewriter | \tt |
| Math symbol5 | \cal |
используем команду \magstep 0...5 или \magstephalf
\font\bigrm = cmr10 scaled \magstep 5 %объявим свой шрифт crm10 и смасштабируем 5 magstep
\font\bigbigrm = cmr14 scaled \magstep 3
| CMBSY10 | CMBXSL10 | CMBXTI10 | CMBX10 | CMBX12 | CMBX5 |
|---|---|---|---|---|---|
| CMBX6 | CMBX7 | CMBX8 | CMBX9 | CMB10 | CMCSC10 |
| CMDUNH10 | CMEX10 | CMFF10 | CMFIB8 | CMFI10 | CMITT10 |
| CMMIB10 | CMMI10 | CMMI12 | CMMI5 | CMMI6 | CMMI7 |
| CMMI8 | CMMI9 | CMR10 | CMR12 | CMR17 | CMR5 |
| CMR6 | CMR7 | CMR8 | CMR9 | CMSLTT10 | CMSL10 |
| CMSL12 | CMSL8 | CMSL9 | CMSSBX10 | CMSSDC10 | CMSSI10 |
| CMSSI12 | CMSSI17 | CMSSI8 | CMSSI9 | CMSSQI8 | CMSSQ8 |
| CMSS10 | CMSS12 | CMSS17 | CMSS8 | CMSS9 | CMSY10 |
| CMSY5 | CMSY6 | CMSY7 | CMSY8 | CMSY9 | CMTCSC10 |
| CMTEX10 | CMTEX8 | CMTEX9 | CMTI10 | CMTI12 | CMTI7 |
| CMTI8 | CMTI9 | CMTT10 | CMTT12 | CMTT8 | CMTT9 |
| CMU10 | CMVTT10 |
Tex понимает различные единицы измерения:
и другие
Три части:
| наименование | команда | значение |
|---|---|---|
| ширина | \hsize | 6.5in |
| высота | \vsize | 8.9in |
| горизонтальный отступ | \hoffset | 0 |
| вертикальный отступ | \voffset | 0 |
\vfill \eject — оборвет страницу и начнет новую
\hsize = 4in — определяет горизонтальный размер текста в текущем абзаце
0.75\hsize установит размер \hsize 0.75 от последнего значения
\vsize — задает вертикальный размер страницы
\hoffset \voffset — задают смещение текста относительно левого верхнего угла страницы. По умолчанию они равны 1in.
Для \hoffset и \voffset нет пределов страницы. Спокойно выведет текст за его пределами
Ставится в самом начале документа до начала первого символа и увеличивает весь документ, вместе с \hsize и \vsize
чтобы сохранить неизменными \hsize и \vsize используем true
\hsize = 5 true in
На размер абзаца влияет \hsize
Tex всегда читает весь абзац целиком и применяет последние настройки.
| функция | команда | значение |
|---|---|---|
| ширина | \hsize | 6.5in |
| отступ первой линии | \parindent | 20pt |
| расстояние между линиями | \baselineskip | 12pt |
| расстояние между абзацами | \parskip | 0pt |
команда \noindent убирает первый отступ линии, тоже,что и \parindent= 0pt
это команды margin отступов слева и справа от обзаца
\narrower — изменяет оба значения сразу значением равным \parindent
первую строку заполняет полностью на всю ширину, а следующую с отступом. Если положительное, то слева, если отрицательное, то справа.
\hangafter указывает после какой строки начинать отступ.
По умолчанию равно 1. Если поставлю 0, то отступ начнется с первой строки. Если отрицательное, то первые строки будут с отступом, а следующие на полную ширину.
еще есть команда \hang — которая сделает отступ абзаца на длину \parindent
Создает абзацы любой формы
Начинает абзац с отступом \parindent и вначале указывает значение, которое в {}
Команда \itemitem сделает двойной отступ
\parskip = 0pt \parindent = 30 pt \noindent
Answer all the following questions:
\item{(1)} What is question 1?
\item{(2)} What is question 2?
\item{(3)} What is question 3?
\itemitem{(3a)} What is question 3a?
\itemitem{(3b)} What is question 3b?
расстояние между параграфами
и его друг \vskip 1 in — задают интервал между абзацами (у него нет знака равно)
\vglue 1 in — вставляет 1 in куда угодно, даже в начале страницы.
Эта команда поставит на текущей странице все, что находится между командами \topinsert и \endinsert
Я умышленно поставил \vskip -2 in и весь текстстраницы улетел вверх.
Для смещений между абзацами. Действует только на текущий абзац.
\hfill \break — разорвет строку
\hfill — заполнит пространство
\line{} — выведет строку
\liftline{} \rightline{} \centerline{} выравнивает строку
\hfil — заполняет пространство для выравнивания
\raggedrigth — обрыв правого выравнивания
\hskip 1 in — горизонтальный отступ
\footnote{}{}
в первой части {} могут быть знаки \dag, \ddag, \S, \P или номер ссылки в формате Tex {${}^{21}$} но сейчас работает {$^{21}$}
в Latex немного измененный формат \footnote{}
определяется командами
\headline{} — header
\footline{} — footer
аналогично как при заполнении \line{}
\headline={\hfil \tenrm Page \the\pageno}
\tenrm — это шрифт roman 10pt
\the\pageno — номер страницы
\folio — тоже номер страницы, но выводит римские буквы когда \pageno отрицательный
\pageno=-1 может быть любого значения
\headline={\ifodd \pageno {...}\else {...}\fi}
При переполнении или недоборе в строках появляется slug — слизень █ который показывает проблему в этой строке.
Так Tex делит на блоки всю страницу и заполняет ее
vbox — вертикальные блоки абзацев
hbox — горизонтальные блоки строк
Это параметр плохости строки — по умолчанию 1000
Накапливается от количества пробелов, вставленных в строку для ее выравнивания.
Увеличения параметра до 10000 подавляет все сообщения о плохости блока.
Это параметр устанавливает на сколько строка может превышать допустимый размер
По умолчанию = 200. 10000 также стирает все предупреждения.
Параметр, который определяет, на сколько может выступать переполнение строки \hfuzz = 0.1 pt
это толщина слизняка slug, появляющегося на полях.
Если установить его 0pt то маркеры будут незаметны
установка переносов для лучшего форматирования боксов
параметры для вертикального наполнения текста на странице
При наборе текст можно упаковать в группы {}
При выходе из группы, все настройки возвращаются к тем, которые были до входа в группу.
{ \hsize = 4 in \parindent = 0 pt \leftskip = 1 in will produce a paragraph that is four ... (this is an easy mistake to make). \par }
Третий режим Tex математический. Задается $…$ в строке и $$…$$ для многострочного блока.
\proclaim — макрос,который выделит первое предложение до точки. А оставшуюся часть абзаца выдаст как описание теоремы.
\proclaim Theorem 1 (H.~G.~Wells). In the country of the blind, the one-eyed man is king.
Это мне всегда больше нравилось.
$$\pmatrix{
a & b & c & d \cr
b & a & c+d & c-d \cr
0 & 0 & a+b & a-b \cr
0 & 0 & ab & cd \cr
}.$$
создаст матрицу с круглыми скобками
\hfill — выравнивают значения в матрице
удаляет разделители круглые скобки и их можно задать явно с помощью команд: \left и \right
$$ \left |
\matrix{
a & b & c & d \cr
b & a & c+d & c-d \cr
0 & 0 & a+b & a-b \cr
0 & 0 & ab & cd \cr
}
\right | $$
типы скобок: (){}[]||
еще можно значения замещать многоточием: \cdots, \vdots, \ddots
$$\eqalign{
a+b &= c+d \cr
x &= w + y + z \cr
m + n + o + p &= q \cr
}$$
Можно нумеровать уравнения тоже через знак &
$$\eqalignno{
a+b &= c+d & (1) \cr
x &= w + y + z \cr
m + n + o + p &= q & * \cr
}$$
\settabs — команда создать tabbing
\settabs 4 \columns %установить 4 равных столбца
\+ British Columbia & Alberta & Saskatchewan & Manitoba \cr
\+ Ontario & Quebec & New Brunswick & Nova Scotia \cr
\+ & Prince Edward Island & Newfoundland \cr
+ — начало строки
\cr — завершение строки
\hfil, \hfill выравнивают текст в ячейках
\settabs \+ \hskip 1 in & \hskip 2 in & \hskip 1.5 in & \cr — это более жизненный пример таблицы с установленными значениями ширины столбцов
или так: \settabs \+ ---------- & ------------------ & ----------------------- & \cr
черточки не выводятся, так же как и любой текст
\hrule — начертит линию под строкой
+\strut — сделает отступ вокруг строки
$$\vbox{
\settabs \+ ----------------&-----&----\cr
\+Plums&\hfill \$1&.22\hfill \cr
\+Coffee&\hfill 1&.78\hfill \cr
\+Granola&\hfill 1&.98\hfill \cr
\+Mushrooms&\hfill &.63\hfill \cr
\+Kiwi fruit&\hfill& .39\hfill \cr
\+Orange juice&\hfill 1&.09\hfill \cr
\+Tuna&\hfill 1&.29\hfill \cr
\+Zucchini&\hfill 0&.64\hfill \cr
\+Grapes&\hfill 1&.69\hfill \cr
\+Smoked beef&\hfill &.75\hfill \cr
\+Broccoli&\hfill\underbar{\ \ 1}&\underbar{.09}\hfill \cr
\+Total&\hfill \$12&.55\hfill \cr
}$$
\halign{шаблон} \cr
\halign{\hskip 2 in $#$& \hfil \quad # \hfil & \qquad $#$ & \hfil \quad # \hfil \cr
вместо # будет подставлено значение из строки
\halign{\hskip 2 in $#$& \hfil \quad # \hfil & \qquad $#$ & \hfil \quad # \hfil \cr \alpha & alpha & \beta & beta \cr
\gamma & gamma & \delta & delta \cr
\epsilon & epsilon & \zeta & zeta \cr
}
\hrule — горизонтальная линия
\vrule — вертикальная линия
\offinterlineskip — позволяет зафиксировать раздвижение строк в таблице
\moveright 2 in
\vbox{\offinterlineskip
\halign{\strut \vrule \quad $#$\quad &\vrule \hfil \quad #\quad \hfil &\vrule \quad $#$\quad &\vrule \hfil \quad #\quad \hfil \vrule \cr
\noalign{\hrule}
\alpha & alpha & \beta & beta \cr
\noalign{\hrule} \gamma & gamma & \delta & delta \cr
\noalign{\hrule} \epsilon & epsilon & \zeta & zeta \cr
\noalign{\hrule}
}}
финальный вариант. \moveright сдвинет box на два In вправо
но для этого также исправно работают \centrline, а также \rightline и \leftline
\def\name{}
name — только буквы или одна не буква
\def\name#1#2{#1...#2}
\let \newname = \oldname
работать будут оба имени
! Undefined control sequence. %название ошибки
l.1 \line{ The left side \hfli %успешно прочитанная строка
the right side} % продолжение строки после ошибки
? %что делать?
варианты ответа:
| Ответ | буква | результат |
|---|---|---|
| help | h | причина указана на терминале |
| insert | i | показать следующую строку |
| exit | x | завершить tex |
| scroll | s | прокрутить ошибки |
| run | r | продолжить работу |
| quiet | q | подавляет вывод в терминал |
| carry on | продолжить лучше как можно |
\input filename
добавит маленькие файлы в большой
\hrule \vrule — имеют параметры width height depth
\vrule height 0 pt depth 0.4 pt width 3 in
\vbox и \hbox — основные кирпичи в tex.
Вкладывая их друг в друга можно получить любой результат.
Задать размер \hbox to 5cm{}
у \vbox есть брат \vtop — будет выравнивать по верхнему краю boxes
\vbox{ \hrule
\hbox{\vrule{} The text to be boxed \vrule}
\hrule }
А это будет текст в рамочке, а с ключевым слово \strut — оно будет с отступами
\moveright \moveleft — переместит вертикальный бокс
\raise \lower — переместит горизонтальный бокс
\hbox to 5 in{Getting Started\hrulefill 1} и еще есть \dotfill — полезно для оглавления
Дружелюбный функционал для полной графики в Latex. Картинки, иконки, графики и пр. Очень мощный пакет в котором можно нарисовать все.
\usepackage{tikz}
Окружение {tikzpicture} или команды \tikzpicture и \endtikzpicture
\documentclass{article} % say
\usepackage{tikz}
\usetikzlibrary{arrows.meta,decorations.pathmorphing,backgrounds,positioning,fit,petri}
\begin{document}
\begin{tikzpicture}
\draw (0,0) -- (1,1);
\end{tikzpicture}
\end{document}
Примеры использования поисковых запросов POSIX
Для описания инструкции по эксплуатации прибора необходимо описывать интерфейс внутренней программы с меню и другими изображениями на 7-ми строчном дисплее.
Дисплей имеет 22 знака в ширину и 7 строк.
Необходимо создать однострочную команду в Latex для удобного заполнения параметров дисплея и вывода графического изображения в любое место на странице документации.
Команда должна обеспечивать сохранение размеров и цветовой гаммы дисплея на всех страницах документации однообразными.
\definecolor{disp}{HTML}{000041} % цвет дисплея
\definecolor{textdisp}{HTML}{f0ffff} %цвет текста дисплея
\tikzset{%настройки стиля шрифта для вывода символов на терминал дисплея
terminal/.style = {text=textdisp,inner sep=0pt, anchor=west,font=\fontfamily{cmtt}\fontsize{10}{10}\selectfont}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%Аккумулятор
%%%%%%%%%%%%%
\tikzset{
accum/.pic={[font=\ttfamily]
\path (.5,.35) coordinate(acbl) ++(1,0) coordinate(acbr)
++(0,.6) coordinate(actr) ++(-1,0) coordinate(actl);
\draw[pic actions,thick] (acbl) -- (acbr) -- ($(acbr)!.2!(actr)$)-- ++(1pt,0) |- ($(acbr)!.8!(actr)$) -- (actr) -- (actl) -- cycle;
\fill[pic actions] (acbl) rectangle ($(actl)!#1!(actr)$);
}
}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%Антенна
%%%%%%%%%%%%%
\tikzset{
antena/.pic={
\path
(0,.35) coordinate(anbot) ++(0,.6) coordinate(antop)
+(-.3,0) coordinate(antl) +(.3,0) coordinate(antr);
\draw[pic actions,thick] (anbot) -- (antop)
($(anbot)!.5!(antop)$)--(antl)
($(anbot)!.5!(antop)$)--(antr);
\path[pic actions] (anbot) ++(.4,.3) node[terminal]{100\%};
}
}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%Уровень сигнала
%%%%%%%%%%%%%
\tikzset{
lsignal/.pic={
\coordinate (a) at (.35,.35);
\draw[pic actions,thick] (a) foreach \x in {1,...,#1} {+(.\x,0) -- +(.\x,.\x)};
}
}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%замок LOCK
%%%%%%%%%%%
\tikzset{
lockc/.pic={
\path (0,.15) coordinate (bl) +(.4,0) coordinate (br) +(.4,.3) coordinate (tr) +(0,.3) coordinate (tl);
\draw[pic actions,thick,fill] (bl) rectangle (tr);
\draw[thick,out=90,in=90,distance=.3em] (tl) to (tr);
}
}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%активная строка
%%%%%%%%%%%%%
\tikzset{
araw/.pic={%отображает строку подсвеченной как активную без текста
\path
(.4,.2) coordinate(arbl) ++(11.6,0) coordinate(arbr)
++(0,.9) coordinate(artr) ++(-11.6,0) coordinate(artl);
\fill[white!95,opacity=.7] (arbl) rectangle (artr);
},
arawp/.pic={%выводит текст без подсветки
\path
(0.4,.2) coordinate(arbl) ++(11.6,0) coordinate(arbr)
++(0,.9) coordinate(artr) ++(-11.6,0) coordinate(artl);
\node[terminal,text width=5.6em] at ($(arbl)!.5!(artl)$) {#1};%обычная строка
},
arawa/.pic={%выводит текст в активной строке
\path
(0.4,.2) coordinate(arbl) ++(11.6,0) coordinate(arbr)
++(0,.9) coordinate(artr) ++(-11.6,0) coordinate(artl);
\node[terminal,text width=5.6em,text=disp] at ($(arbl)!.5!(artl)$) {#1} [fill=white!95,opacity=.7] (arbl) rectangle (artr);%обычная строка
},
lbut/.pic={%выводит текст в левой функциональной кнопке в нижнем ряду
\path
(.4,.2) coordinate(arbl) ++(5.7,0) coordinate(arbr)
++(0,.9) coordinate(artr) ++(-5.7,0) coordinate(artl);
\node[terminal,text=disp,anchor=center] at ($(arbl)!.5!(artr)$) {#1} [fill=white!95,opacity=.7] (arbl) rectangle (artr) ;
},
rbut/.pic={%выводит текст в правой функциональной кнопке в нижнем ряду
\path
(6.3,.2) coordinate(arbl) ++(5.7,0) coordinate(arbr)
++(0,.9) coordinate(artr) ++(-5.7,0) coordinate(artl);
\node[terminal,text=disp,anchor=center] at ($(arbl)!.5!(artr)$) {#1} [fill=white!95,opacity=.7] (arbl) rectangle (artr) ;
},
rawc/.pic={%строка через весь дисплей с выделенной активностью и текстом по центру
\path
(.4,.2) coordinate(arbl) ++(11.6,0) coordinate(arbr)
++(0,.9) coordinate(artr) ++(-11.6,0) coordinate(artl);
\node[terminal,text=disp,anchor=center] at ($(arbl)!.5!(artr)$) {#1} [fill=white!95,opacity=.7] (arbl) rectangle (artr);
}
}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%Дисплей маленького экрана
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\tikzset{
display/.pic={%рамка для дисплея
\path[terminal] (0,.2) coordinate (dtl) ++(12.4,0) coordinate (dtr) ++(0,-7.2) coordinate (dbr) ++(-12.4,0) coordinate (dbl);
\draw[thick,gray!20,fill=disp,rounded corners] (dbl) rectangle (dtr);
}
}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%Строка состояния пульта
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\tikzset{
pultmain/.pic={% режим 1 с произвольным текстом, часами и аккумулятором заголовок дисплея пульт на вход отправим text
\path
(0.4,.2) coordinate(arbl) ++(11.6,0) coordinate(arbr)
++(0,.9) coordinate(artr) ++(-11.6,0) coordinate(artl);
\path ($(arbl)!.5!(artl)$) node[terminal] {#1} +(4,0) node[terminal] {08:20:46};
\pic[textdisp] at (10.4,0) {accum=.4};
\draw[textdisp,thick] (arbl.south west)--(arbr.south east);
},
pultfree/.pic={%заголовок дисплея пульт на вход отправим свободную строку
\path
(0.4,.2) coordinate(arbl) ++(11.6,0) coordinate(arbr)
++(0,.9) coordinate(artr) ++(-11.6,0) coordinate(artl);
\node[terminal,text width=10.5em] at ($(arbl)!.5!(artl)$) {#1};%обычная строка
\pic[textdisp] at (10.4,0) {accum=.4};%\fill[red](arbl.south west)circle (1pt);
\draw[textdisp,thick] (arbl.south west)--(arbr.south east);
},
priemfree/.pic={%заголовок дисплея приемника на вход отправим свободную строку
\path
(0.4,.2) coordinate(arbl) ++(11.6,0) coordinate(arbr)
++(0,.9) coordinate(artr) ++(-11.6,0) coordinate(artl);
\pic[textdisp]{accum=.5};\pic[textdisp] at (9.4,0) {antena};
\draw[textdisp,thick] (arbl.south west)--(arbr.south east);
},
rawg/.pic={\node[terminal,text width=5.6em] {#1};%обычная строка
},
rawa/.pic={\pic{arow} node[terminal,text width=5.6em,text=disp] {#1};%активная строка
}
}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%шаблон дисплея создаем команду \dispm с 8-ю входными параметрами
\def\dispm#1#2#3#4#5#6#7#8{
\begin{tikzpicture}[x=10pt,y=10pt,node distance=10pt]%установить масштаб отображения
\pic{display};%вывести фон дисплея
\pic at (0,-1) {#1};%строка состояния
\pic at (0,-2) {#2};%вторая строка
\pic at (0,-3) {#3};%третья строка
\pic at (0,-4) {#4};%четвертая строка
\pic at (0,-5) {#5};%пятая строка
\pic at (0,-6) {#6};%шестая строка
\path (0,-7) pic{lbut=#7} pic{rbut=#8};%седьмая строка с кнопками состояния
\draw[textdisp,thick] (6.2,-.9) -- (6.2,-5.9);%линия по центру экрана вертикальная
\end{tikzpicture}
}
% \dispm
% {}%1-я строка значения входного параметра (pultmain=text priemfree, pultfree=TEXT)
% {}%2-я строка (arawa=TEXT - активная строка, )
% {}%3-я строка (arawp=TEXT - пассивная строка,)
% {}%4-я строка (rawc=TEXT - активная строка с текстом по центру)
% {}%5-я строка
% {}%6-я строка
% {}{}%нижние кнопки в 7-й строке
%
\dispm
{pultmain=ARM}%1-я строка (pultmain=ARM, pultmain=DISARM, priemfree, pultfree=TEXT)
{arawa=TEXT}%2-я строка (arawa=TEXT - активная строка, )
{arawp=TEXT}%3-я строка (arawp=TEXT - пассивная строка,)
{}%4-я строка (rawc=TEXT - активная строка с текстом по центру)
{}%5-я строка
{rawc=TEXT}%6-я строка
{MENU}{SERVICE}%нижние кнопки в 7-й строке
\usepackage{pgffor} % LATEX
\input pgffor.tex % plain TEX
\usemodule[pgffor] % ConTEXt
Отдельный пакет для самостоятельного использования в документах Tex и Latex
По умолчанию сам загружает пакет \tikz
Он определяет две новые команды: \foreach и \breakforeach.
\foreach 〈variables〉 [〈options〉] in 〈list〉 〈commands〉
\def\mylist{1,2,3,0}
\foreach \x in \mylist {[\x]}
Выдаст: [1][2][3][0]
\begin{tikzpicture}
\foreach \x in {0,1,2,3}
\foreach \y in {0,1,2,3}
{
\draw (\x,\y) circle (0.2cm);
\fill (\x,\y) circle (0.1cm);
}
\end{tikzpicture}
\foreach \x in {a,b,9,8,...,1,2,2.125,...,2.5} {\x, }
выдаст:
a, b, 9, 8, 7, 6, 5, 4, 3, 2, 1, 2, 2.125, 2.25, 2.375, 2.5,
\foreach \x in {2^1,2^...,2^7} {$\x$, } yields 21, 22, 23, 24, 25, 26, 27,
\foreach \x in {0\pi,0.5\pi,...\pi,3\pi} {$\x$, } yields 0π, 0.5π, 1π, 1.5π, 2π, 2.5π, 3π,
\foreach \x in {A_1,..._1,H_1} {$\x$, } yields A1, B1, C1, D1, E1, F1, G1, H1,
\tikz \foreach \position in {(0,0), (1,1), (2,0), (3,1)}
\draw \position rectangle +(.25,.5);
\begin{tikzpicture}
\foreach \x/\xtext in {0,...,3,2.72 / e}
\draw (\x,0) node{$\xtext$};
\end{tikzpicture}
задан паттерн для получения переменных \x второе значение через / — \xtext
Отсутствие значений для второго параметра замещается первым значением.
/
\begin{tikzpicture} % Let's draw circles at interesting points:
\foreach \x / \y / \r in {0 / 0 / 2mm, 1 / 1 / 3mm, 2 / 0 / 1mm}
\draw (\x,\y) circle (\r);
% Same effect
\foreach \center/\r in {{(0,0)/2mm}, {(1,1)/3mm}, {(2,0)/1mm}} \draw[yshift=2.5cm] \center circle (\r);
\end{tikzpicture}
\begin{tikzpicture}[line cap=round,line width=3pt]
\filldraw [fill=yellow!80!black] (0,0) circle (2cm);
\foreach \angle / \label in
{0/3, 30/2, 60/1, 90/12, 120/11, 150/10, 180/9, 210/8, 240/7, 270/6, 300/5, 330/4}
{
\draw[line width=1pt] (\angle:1.8cm) -- (\angle:2cm);
\draw (\angle:1.4cm) node{\textsf{\label}};
}
\foreach \angle in {0,90,180,270}
\draw[line width=2pt] (\angle:1.6cm) -- (\angle:2cm);
\draw (0,0) -- (120:0.8cm); % hour
\draw (0,0) -- (90:1cm); % minute
\end{tikzpicture}%
Описанные ниже ключи можно использовать в аргументе 〈options〉 команды \foreach. Все они имеют путь /pgf/foreach/, однако путь устанавливается автоматически при анализе 〈options〉, поэтому его не нужно указывать явно.
/pgf/foreach/var=〈variable〉 — Этот ключ обеспечивает альтернативный способ указания переменных: \foreach [var=\x,var=\y] аналогичен \foreach \x/\y./pgf/foreach/evaluate=〈variable〉 as 〈macro〉 using 〈formula〉 — Этот ключ позволяет оценивать переменную с помощью математического механизма.
\foreach \x [evaluate=\x] in {2^0,2^...,2^8}{$\x$, } вернет 1.0, 2.0, 4.0, 8.0, 16.0, 32.0, 64.0, 128.0, 256.0,или \foreach \x [evaluate=\x as \xeval] in {2^0,2^...,2^8}{$\x=\xeval$, } значение будет помещено в \xeval
указывает формулу для вычисления
\tikz\foreach \x [evaluate=\x as \shade using \x*10] in {0,1,...,10} \node [fill=red!\shade!yellow, minimum size=0.65cm] at (\x,0) {\x};
/pgf/foreach/remember=〈variable〉 as 〈macro〉 (initially 〈value〉) — Этот ключ позволяет запомнить значение элемента, хранящееся в 〈variable〉, во время следующей итерации, сохраненное в 〈macro〉.\foreach \x [remember=\x as \lastx (initially A)] in {B,...,H}{$\overrightarrow{\lastx\x}$, }
/pgf/foreach/count=〈macro〉 from 〈value〉 — считает номер итерации\tikz[x=0.75cm,y=0.75cm]
\foreach \x [count=\xi] in {a,...,e}
\foreach \y [count=\yi] in {\x,...,e}
\node [draw, top color=white, bottom color=blue!50, minimum size=0.666cm]
at (\xi,-\yi) {$\mathstrut\x\y$};
/pgf/foreach/parse={〈boolean〉} — Если для этого ключа установлено значение true, верхняя граница цикла будет передана в \pgfmathparse./pgf/foreach/expand list={〈boolean〉} — Если для этого ключа установлено значение true, содержимое списка полностью раскрывается с помощью \edef перед дальнейшей обработкой.Если эта команда задана внутри команды \foreach, дальнейшее выполнение 〈команд〉 происходить не будет. Однако текущее выполнение 〈команд〉 продолжается в обычном режиме, поэтому, вероятно, лучше использовать эту команду только в конце команды \foreach.
В основном этот раздел описываю, так как его активно используют библиотеки TIKZ.
А в общем этот вопрос вполне удовлетворяет знание TEX и его внутренней кухни по созданию макросов и переменных.
\usepackage{pgfkeys}
pgfkeys от xkeyvalОрганизован по принципу файловой системы Unix, корень и как дерево ветвление всех элементов
Можно указать полный путь к ключу или сокращенное наименование и путь будет подставлен автоматически.
Основная команда \pgfkeys берет пару ключ и значение.
Для каждого
\pgfkeys{/my key=hallo,/your keys/main key=something\strange,
key name without path=something else}
Сначала установим код для ключа: стр.1 и затем выполним его с переданным параметром стр.2
\pgfkeys{/my key/.code=The value is '#1'.}
\pgfkeys{/my key=hi!}
В качестве параметров может быть несколько значений (ключевое слово /.code 2 args=)
\pgfkeys{/my key/.code 2 args=The values are '#1' and '#2'.}
\pgfkeys{/my key={a1}{a2}}
Может быть значение по умолчанию: \pgfkeys{/my key/.default=hello}
Можно указать обязательное значение /.value required или запрещенное значение /.value forbidden, т.е. не нужно вводить значение.
Ключ /.cd - изменит путь. Т.е. после этого ключа, все остальные будут выполнять команды с новым путем.
\pgfkeys{/tikz/.cd,line width=1cm,line cap=round}
т.е. все остальные команды будут начинаться с /tikz/
Ключи могут вызывать выполнение других ключей.
\pgfkeys{/a/.code=(a:#1)}
\pgfkeys{/b/.code=(b:#1)}
\pgfkeys{/my style/.style={/a=foo,/b=bar,/a=#1}}
\pgfkeys{/my style=wow}
получим (a:foo)(b:bar)(a:wow)
Еще пример с созданием стиля tikz
\pgfkeys{/tikz/.style=/tikz/.cd}
\pgfkeys{tikz,line width=1cm,draw=red}
Если ключ начинается с / — это ключ с полным путем, если без слеша, то это не полный путь.
Эта команда сохраняет token text в full key
Это не может быть частичным ключом.
\pgfkeyssetvalue{/my family/my key}{Hello, world!}%установить ключ
\pgfkeysvalueof{/my family/my key}%вывести ключ
\pgfkeyssetevalue{⟨full key⟩}{⟨token text⟩} — это тоже, но \edef версия
\def\helloworld{Hello, world!}
\pgfkeyslet{/my family/my key}{\helloworld}
\pgfkeysvalueof{/my family/my key}
позволяет устанавливать для ключа значение макроса, в нашем случае будет подставлено значение \helloworld
Недопустимо,чтобы ключ совпадал с \relax — relax это пустышка
Извлекает токены из ключа
Если ключ не установлен то токен будет равен \relax
Возвращает значение ключа и вставляет его в текст
\pgfkeyssetvalue{/my family/my key}{Hello, world!}
\pgfkeysifdefined{/my family/my key}{yes}{no}
проверяет, если ключ был определен, то выведет значение if, если не определен, то else
Ключи могут выполнять следующие действия:
Возможно указать:
или просто значение в {} если оно содержит запятые или спецсимволы
Эта команда имеет тот же эффект,что и \pgfkeys{⟨default path⟩/.cd,⟨key list⟩}
в этой команде путь не изменяется
вызывает с изменением пути
Наверно это удобно.
Так работают во всех nodes кавычки " которые заменяются текстом \label={}
Для этого нужно:
/handlers/first char syntax=〈true or false〉 в truethe character <символ> макрос, который будет выполняться\pgfkeys{
/handlers/first char syntax=true,
/handlers/first char syntax/the character "/.initial=\myquotemacro,
/handlers/first char syntax/the character </.initial=\mypointedmacro,
}
\def\myquotemacro#1{Quoted: #1. }
\def\mypointedmacro#1{Pointed: #1. }
\ttfamily \pgfkeys{"foo", <bar>}
Дальше все параметры в "" будут переданы в макрос myquotemacro, а в <> в макрос mypointedmacro
key=\pgfkeysnovalue〈key〉/.@defДля установки по умолчанию значения используем команду: \pgfkeys{/my key/.default=hello}
Во всем макросах в \pgf параметры должны заканчиваться значением \pgfeov
т.е. что сделает на самом деле пакет \pgf
\usepackage {shortvrb} \MakeShortVerb {\|}
\def\mystore#1+#2\pgfeov{\def\a{#1}\def\b{#2}}
\pgfkeyslet{/my key/.@cmd}{\mystore}
\pgfkeys{/my key=hello+world}
получим:
|\a| is `\a', |\b| is `\b'.
т.е.
\a is ‘hello’, \b is ‘world’.
\pgfkeysdef{〈key〉}{〈code〉} — Эта команда временно определяет TEX-макрос со списком аргументов #1\pgfeov, а затем позволяет 〈key〉/.@cmd быть равным этому макросу.\pgfkeysedef{〈key〉}{〈code〉} — аналогично, но работает, как edef\pgfkeysdefnargs{〈key〉}{〈argument count〉}{〈code〉} — Эта команда работает аналогично \pgfkeysdef, но позволяет вам указать произвольное «счетчик аргументов» от 0 до 9 (включительно).\usepackage {shortvrb} \MakeShortVerb {\|}
\pgfkeysdefnargs{/my key}{2}{\def\a{#1}\def\b{#2}}
\pgfkeys{/my key= {hello} {world}}
|\a| is `\a', |\b| is `\b'
\pgfkeysedefnargs{〈key〉}{〈argument count〉}{〈code〉} — аналогично, но edef\pgfkeysdefargs{〈key〉}{〈argument pattern〉}{〈code〉} — Эта команда работает аналогично \pgfkeysdefnargs, но позволяет вам предоставить произвольный «шаблон аргумента», а не просто несколько аргументов. \pgfkeysdefargs{/my key}{#1+#2}{\def\a{#1}\def\b{#2}}\pgfkeysedefargs{〈key〉}{〈argument pattern〉}{〈code〉} — это его edef версияЕсли у ключа не определен key/.@cmd, то он будет просто хранить значение которое может быть задано командой \pgfkeyssetvalue
Обработчики — это дополнительная возможность выполнять некие действия над ключами сверх того, что предоставляется стандартной библиотекой.
\pgfkeysdef{/handlers/.my code}{\pgfkeysdef{\pgfkeyscurrentpath}{#1}}
Путь ключа, хранится в макросе \pgfkeyscurrentpath
Имя ключа, хранится в макросе \pgfkeyscurrentname
обработчик должен начинаться с .
/handler config=all|only existing|full or existing — Изменяет исходную конфигурацию использования обработчиков ключей.
/handler config/only existing/add exception={〈key handler name〉} — Позволяет добавлять исключения к существующей функции /handler config=only.
Для некоторых ключей не определен ни сам ключ, ни его подраздел .@cmd, ни обработчик. В этом случае проверяется, существует ли ключ 〈текущий путь〉/.unknown/.@cmd.
Т.к. он существует, то будет выполнена какая-то странная вещь, как он ее поймет.
Теперь мы опишем, какие обработчики клавиш определены по умолчанию.
Key handler 〈key〉/.cd — Этот обработчик устанавливает путь по умолчанию 〈key〉. Обратите внимание, что путь по умолчанию сбрасывается в начале каждого вызова \pgfkeys и становится равным /.\pgfkeys{/tikz/.cd,...}
Key handler 〈key〉/.is family — Этот обработчик настраивает такие вещи, что при выполнении 〈key〉 текущий путь устанавливается на 〈key〉.\pgfkeys{/tikz/.is family}
\pgfkeys{tikz,line width=1cm}
Key handler 〈key〉/.default=〈value〉 — Устанавливает значение по умолчанию 〈key〉 в 〈value〉. Это означает, что всякий раз, когда при вызове \pgfkeys не указывается значение, вместо него будет использоваться это 〈значение〉. \pgfkeys{/width/.default=1cm}Key handler 〈key〉/.value required — Этот обработчик вызывает выдачу ключа /errors/value сообщения об ошибке всякий раз, когда 〈key〉 используется без значения. \pgfkeys{/width/.value required} Т.е. требует обязательно указать значение.Key handler 〈key〉/.value forbidden — не будет выдавать сообщение об ошибке, если указано будет значение ключаKey handler 〈key〉/.code=〈code〉 — Этот обработчик выполняет \pgfkeysdef с параметрами 〈key〉 и 〈code〉.Key handler 〈key〉/.ecode=〈code〉 — выполнит команду \pgfkeysedefKey handler 〈key〉/.code 2 args=〈code〉 — с двумя аргументамиKey handler 〈key〉/.ecode 2 args=〈code〉 — с двумя аргументами edefKey handler 〈key〉/.code n args={〈argument count〉}{〈code〉} — с n аргументамиKey handler 〈key〉/.ecode n args={〈argument count〉}{〈code〉} — с n аргументами edefKey handler 〈key〉/.code args={〈argument pattern〉}{〈code〉} — с произвольным паттерном аргументовKey handler 〈key〉/.ecode args={〈argument pattern〉}{〈code〉} — с произвольным паттерном аргументов edefKey handler 〈key〉/.add code={〈prefix code〉}{〈append code〉} — Этот обработчик добавляет код к существующему ключу. 〈код префикса〉 добавляется к коду, хранящемуся в 〈key〉/.@cmd, в начале, 〈код добавления〉 добавляется к этому коду в конце.\pgfkeys{/par indent/.code={\parindent=#1}}
\newdimen\myparindent
\pgfkeys{/par indent/.add code={}{\myparindent=#1}}
...
\pgfkeys{/par indent=1cm} % This will set both \p
Key handler 〈key〉/.prefix code=〈prefix code〉 — Этот обработчик является ярлыком для 〈key〉/.add code={〈prefix code〉}{}. То есть этот обработчик добавляет 〈префиксный код〉 в начало кода, хранящегося в 〈key〉/.@cmd.Key handler 〈key〉/.append code=〈append code〉 — Этот обработчик является ярлыком для 〈key〉/.add code={}{〈append code〉}.Key handler 〈key〉/.style=〈key list〉 — Этот обработчик настраивает ситуацию таким образом, что всякий раз, когда 〈ключ〉=〈значение〉 встречается в списке ключей, вместо этого обрабатывается 〈список ключей〉, в котором каждое вхождение #1 заменено на 〈значение〉. Как всегда, если 〈значение〉 не указано, используется значение по умолчанию, если оно определено, или специальное значение \pgfkeysnovalue.\pgfkeys{/par indent/.code={\parindent=#1}}
\pgfkeys{/no indent/.style={/par indent=0pt}}
\pgfkeys{/normal indent/.style={/par indent=2em}}
\pgfkeys{/no indent}
...
\pgfkeys{/normal indent}
Key handler 〈key〉/.estyle=〈key list〉 — определяет стиль через edefKey handler 〈key〉/.style 2 args=〈key list〉 — с двумя аргументамиKey handler 〈key〉/.estyle 2 args=〈key list〉 — с двумя аргументами edefKey handler 〈key〉/.style n args={〈argument count〉}〈key list〉 — n аргументовKey handler 〈key〉/.add style={〈prefix key list〉}{〈append key list〉} — добавить значение к стилюKey handler 〈key〉/.style args={〈argument pattern〉}{〈key list〉} — стиль с произвольным паттерномKey handler 〈key〉/.estyle args={〈argument pattern〉}{〈code〉} — стиль с произвольным паттерном edefKey handler 〈key〉/.prefix style=〈prefix key list〉 — prefix style добавитьKey handler 〈key〉/.append style=〈append key list〉 — добавить стиль в конецДля некоторых клавиш код, который должен по ним выполняться, достаточно «специализирован».
Key handler 〈key〉/.initial=〈value〉 — Этот обработчик устанавливает значение 〈key〉 в 〈value〉. Обратите внимание, что никакие подразделы не задействованы. После использования этого обработчика, согласно правилам, регулирующим ключи, вы можете впоследствии изменить значение 〈key〉, просто написав 〈key〉=〈value〉. Таким образом, этот обработчик используется для установки начального значения ключа.Key handler 〈key〉/.get=〈macro〉 — выведет содержимое ключа и поместит в \macroKey handler 〈key〉/.add={〈prefix value〉}{〈append value〉} — добавит к ключуKey handler 〈key〉/.prefix={〈prefix value〉} — добавит префиксKey handler 〈key〉/.append={〈append value〉} — добавит суффиксKey handler 〈key〉/.link=〈another key〉 — сделает ссылку на другой ключKey handler 〈key〉/.store in=〈macro〉 — это прямой аналог \def\macro{#1}\pgfkeys{/text/.store in=\mytext}
\def\a{world} \pgfkeys{/text=Hello \a!}
\def\a{Gruffalo}
\mytext
выведет:
Hello Gruffalo!
Key handler 〈key〉/.estore in=〈macro〉 — тоже, только edefKey handler 〈key〉/.is if=〈TEX-if name〉 — имитация if Tex\newif\iftheworldisflat
\pgfkeys{/flat world/.is if=theworldisflat}
\pgfkeys{/flat world=false}
\iftheworldisflat
Flat \else Round?
\fi
Key handler 〈key〉/.is choice — Этот обработчик настраивает ситуацию так, что запись 〈key〉=〈value〉 приведет к выполнению подраздела 〈key〉/〈value〉. Таким образом, каждый из возможных вариантов должен быть задан подразделом 〈key〉.\pgfkeys{/line cap/.is choice}
\pgfkeys{/line cap/round/.code={\pgfsetroundcap}}
\pgfkeys{/line cap/butt/.code={\pgfsetbuttcap}}
\pgfkeys{/line cap/rect/.code={\pgfsetrectcap}}
\pgfkeys{/line cap/rectangle/.style={/line cap=rect}}
...
\draw [/line cap=butt] ...
Key handler 〈key〉/.expand once=〈value〉 — Этот обработчик расширяет 〈value〉 один раз (точнее, он выполняет команду \expandafter для первого токена 〈value〉), а затем обрабатывает полученный 〈result〉, как если бы вы написали 〈key〉=〈result〉.Key handler 〈key〉/.expand twice=〈value〉 — дважды расширяет значениеKey handler 〈key〉/.expanded=〈value〉 — Этот обработчик полностью расширит 〈value〉 (с помощью \edef) перед обработкой 〈key〉=〈result〉.Key handler 〈key〉/.evaluated=〈value〉 — Этот обработчик оценит 〈value〉 как математическое выражение с помощью \pgfmathparse и присвоит 〈key〉=\pgfmathresult.Key handler 〈key〉/.list=〈comma-separated list of values〉 — Этот обработчик вызывает многократное использование ключа, а именно один раз для каждого элемента списка значений. Что-то вроде foreachKey handler 〈key〉/.forward to=〈another key〉 — Этот обработчик заставляет 〈key〉 «пересылать» свой аргумент 〈другому ключу〉. При использовании 〈key〉 сначала будет выполнен ее обычный код. Затем значение (дополнительно) передается «другому ключу».\pgfkeys{
/a/.code=(a:#1),
/b/.code=(b:#1),
/b/.forward to=/a,
/c/.forward to=/a
}
\pgfkeys{/b=1} \pgfkeys{/c=2}
выведет
(b:1)(a:1) (a:2)
Key handler 〈key〉/.search also={〈path list〉} — Стиль, который устанавливает обработчик /.unknown в 〈key〉. Этот обработчик /.unknown затем будет искать неизвестные ключи по каждому пути, указанному в {〈списке путей〉}.Key handler 〈key〉/.try=〈value〉 — Этот обработчик вызывает то же самое, как если бы вместо этого было написано 〈key〉=〈value〉. Однако если ни 〈key〉/.@cmd, ни сам ключ не определены, обработчики вызываться не будут. Вместо этого выполнение ключа просто останавливается. Таким образом, этот обработчик «пытается» использовать ключ, но никаких дальнейших действий не предпринимается, если ключ не определен.Key handler 〈key〉/.retry=〈value〉 — Этот обработчик работает так же, как /.try, только он ничего не будет делать, если \ifpgfkeyssuccess имеет значение false. Таким образом, этот обработчик попытается установить ключ только в том случае, если «последняя попытка не удалась».Key handler 〈key〉/.lastretry=〈value〉 — Этот обработчик работает как /.retry, только он будет вызывать обычные обработчики для неизвестных ключей, если \ifpgfkeyssuccess имеет значение false.Key handler 〈key〉/.show value — Этот обработчик выполняет команду \show для значения, хранящегося в 〈key〉. Это полезно в основном для отладки.Key handler 〈key〉/.show code — Этот обработчик выполняет команду \show для кода, хранящегося в 〈key〉/.@cmd. Это полезно в основном для отладки.В определенных ситуациях могут возникнуть ошибки, например, при использовании неопределенного ключа. В таких ситуациях выполняются ключи ошибок. Они должны хранить макрос, который получает два аргумента: первый — это ключ-нарушитель (возможно, только после раскрытия макроса), второй — значение, которое было передано в качестве параметра (также возможно, только после раскрытия макроса).
Обычно вызов \pgfkeys устанавливает все ключи, указанные в списке аргументов. Обычно именно этого ожидают пользователи. Однако реализации различных пакетов или pgf-библиотек могут нуждаться в большем контроле над процедурой установки ключей: библиотека A может захотеть установить свои параметры напрямую и передать все оставшиеся в библиотеку B.
Установить библиотеку фильтрации
\usepgfkeyslibrary{filtered} % LATEX and plain TEX
\usepgfkeyslibrary[filtered] % ConTEXt
Примеры использования поисковых запросов POSIX
Немного запутанно, но суть в том, что у устройства есть адреса на каждом выходе, и эти адреса изменяются, а картинок несколько.
Было принято решение не рисовать в редакторе картинки, а запрограммировать в LATEX и на вход просто подавать массив с адресами и номерами выходов.
\tikzset{vad/.style={node distance=0pt,inner sep=2pt,rotate=90,draw}}%настройка стиля для вертикальных адресов
\tikzset{had/.style={node distance=0pt,inner sep=2pt,rotate=0,draw}}%настройка стиля для горизонтальных адресов
\tikzset{
orr/.pic={%рисуем маленький красный кружок на белом фоне
\fill[white] (0,-0.3mm) ellipse (.6mm and 1mm);
\fill[red] (0,0) ellipse (.4mm and .6mm);},
piro/.pic={%рисуем скобку и внизу скобки помещаем красный кружок orr
\draw[thick,orange,rounded corners] (-.7ex,1cm) -- (-.7ex,.3cm) -- (0,0) pic{orr} -- (.7ex,.3cm) -- (.7ex,1cm);},
pics/ntt/.style={%рисуем черный кружок с переменной номер внутри кружка
code={\node [circle,fill=black,minimum size=1em,inner sep=0pt,text=white] {#1};}},
sp/.pic={\path (0,0)--(.2,0);}%это хитрый pic пробел. Чтобы не разъезжались строки.
}
\def\haddr#1#2{%строим горизонтальный адрес в формате 4:5
\coordinate(a0)at(0,.12);
\foreach \z [count=\x,evaluate=\x as \y using \x-1] in {#1}{
\node(a\x)[had,right=of a\y] {\z};
};
\node(s0)[had,draw=none,right=of a4] {:};
\foreach \z [count=\x,evaluate=\x as \y using \x-1] in {#2}{
\node(s\x)[had,right=of s\y] {\z};
};
}
\def\vaddr#1#2{%строим вертикальный адрес в формате 4:5
\coordinate(a0)at(0,0);
\foreach \z [count=\x,evaluate=\x as \y using \x-1] in {#1}{
\node(a\x)[vad,right=of a\y] {\z};
};
\node(s0)[vad,draw=none,right=of a4] {:};
\foreach \z [count=\x,evaluate=\x as \y using \x-1] in {#2}{
\node(s\x)[vad,right=of s\y] {\z};
};
}
%рисуем горизонтальную матрицу из пяти адресов
%в первой колонке черный кружок с номером \pic{ntt=1}
%во второй колонке пробел \pic{sp}, чтобы отделить
%в третьей колонке горизонтальный адрес \haddr...
\begin{tikzpicture}
\matrix[matrix of nodes,row sep={0ex}]{
\pic{ntt=1};&\pic{sp};&\haddr{0,0,0,1}{0,0,0,1,2}\\
\pic{ntt=2};& &\haddr{0,0,0,1}{0,0,0,1,3}\\
\pic{ntt=3};& &\haddr{0,0,0,1}{0,0,0,1,4}\\
\pic{ntt=4};& &\haddr{0,0,0,1}{0,0,0,1,5}\\
\pic{ntt=5};& &\haddr{0,0,0,1}{0,0,0,1,6}\\};
\end{tikzpicture}
%рисуем вертикальную матрицу из пяти адресов
%в первой строке черные кружки с номерами \pic{ntt=1}
%во второй строке скобки, \pic{piro}
%в третьей строке вертикальный адрес \vaddr...
\begin{tikzpicture}
\matrix[matrix of nodes,column sep={0ex}]{
\pic{ntt=1};&\pic{ntt=2};&\pic{ntt=3};&\pic{ntt=4};&\pic{ntt=5};\\
\pic{piro};&\pic{piro};&\pic{piro};&\pic{piro};&\pic{piro};\\
\vaddr{0,0,0,1}{0,0,0,1,2}&
\vaddr{0,0,0,1}{0,0,0,1,2}&
\vaddr{0,0,0,1}{0,0,0,1,2}&
\vaddr{0,0,0,1}{0,0,0,1,2}&
\vaddr{0,0,0,1}{0,0,0,1,2}\\};
\end{tikzpicture}
при объявлении node просто указать, что это будет matrix
\node [matrix,fill=red!20,draw=blue,very thick]
а дальше как в обычной таблице или array
\draw (0,0) circle (4mm); & \node[rotate=10] {Hello}; \\
\draw (0.2,0) circle (2mm); & \fill[red] (0,0) circle (3mm); \\
};
вот и всё.
определяет стиль matrix
это настраивает внешний node в котором объявлен matrix
специальная команда без node
аналог \path node[matrix]
расстояние между колонками
column sep={1cm,between origins} — расстояние будет мерить не по краям, а по центрам
расстояние между строк
Задавать можно целиком на matrix, так и на отдельную ячейку
\draw (0,0) circle (2mm); \\[1cm,between origins] — можно так
\node {8}; &[2mm] \node{1}; &[-1mm] \node {6}; \\ — а можно и так
&[between borders] \node (c) {6}; — а можно и так
every cell={⟨row⟩}{⟨column⟩} задает параметры каждой ячейки
это стиль ячейки cell/.append style=⟨options⟩
это тоже стиль для ячеек matrix node/.append style=⟨options⟩
\begin{tikzpicture}
\matrix [nodes={fill=blue!20,minimum size=5mm}]
{
\node {8}; & \node{1}; & \node {6}; \\
\node {3}; & \node{5}; & \node {7}; \\
\node {4}; & \node{9}; & \node {2}; \\
};
\end{tikzpicture}
column 2/.style={green!50!black}row 3/.style={green!50!black}\begin{tikzpicture}
[row 1/.style={red},
column 2/.style={green!50!black},
row 3 column 3/.style={blue}]
\matrix
{
\node {8}; & \node{1}; & \node {6}; \\
\node {3}; & \node{5}; & \node {7}; \\
\node {4}; & \node{9}; & \node {2}; \\
};
\end{tikzpicture}
\begin{tikzpicture}
[column 1/.style={anchor=base west},%выравнивает слева
column 2/.style={anchor=base east},%выравнивает справа
column 3/.style={anchor=base}]% выравнивает по центру
\matrix
{
\node {123}; & \node{456}; & \node {789}; \\
\node {12}; & \node{45}; & \node {78}; \\
\node {1}; & \node{4}; & \node {7}; \\
};
\end{tikzpicture}
\usetikzlibrary {matrix,fit}
\begin{tikzpicture}[
font=\sffamily,
head color/.style args={#1/#2}{
row 1 column #1/.append style={nodes={fill=#2}}},
% swap order of row and column styles
matrix/inner style order={
every cell,
row, even odd row,
column, even odd column,
cell
}
]
\matrix [
matrix of nodes, nodes in empty cells,
nodes={text width=2cm, align=center,
minimum height=1.5em, anchor=center},
% add striped row style
every even row/.style={nodes={fill=olive!50}},
% modify the feature column and header row
column 1/.style= {nodes={fill=olive, inner ysep=0}},
row 1/.style= {nodes={text depth=0.2ex, text=white}},
row 1 column 1/.style={nodes={fill=none, draw=none}},
head color/.list={2/orange,3/teal,4/cyan,5/magenta} % specify header colors
] (m)
{
& Basic & Standard & Professional & Enterprise \\
Feature A & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
Feature B & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
Feature C & & & & $\bullet$ \\
Feature D & & $\bullet$ & $\bullet$ & $\bullet$ \\
Feature E & & & $\bullet$ & $\bullet$ \\
};
% Add emphasis on selection by the use of "fit" library
\node[fit={(m-1-4.north west) (m-6-4.south east)},
ultra thick, inner sep=0pt, rounded corners=1mm,
draw=cyan, label={[cyan,align=center]270:Popular\\Choice!}]{};
\end{tikzpicture}
внутренние стили назначаются в определенной очередности.
Очередность задается параметром:
\tikzset{
matrix/inner style order={
every cell,
column,
even odd column,
row,
even odd row,
cell,
},
}
Для многих матриц нужно делать однообразные настройки
node{ какой-то текст и };
поэтому определим три макроса:
\begin{tikzpicture}
[matrix of nodes/.style={
execute at begin cell=\node\bgroup,
execute at end cell=\egroup;%
}]
\matrix [matrix of nodes]
{
8 & 1 & 6 \\
3 & 5 & 7 \\
4 & 9 & 2 \\
};
\end{tikzpicture}
или так
\begin{tikzpicture}
[matrix of nodes/.style={
execute at begin cell=\node\bgroup,
execute at end cell=\egroup;,%
execute at empty cell=\node{--};%
}]
\matrix [matrix of nodes]
{
8 & 1 & \\
3 & & 7 \\
& & 2 \\
};
\end{tikzpicture}
https://tikz.dev/library-matrix
matrix anchor=⟨anchor⟩
этот параметр применяется только к самой матрице, но не применяется к ячейкам
т.е. все north, south, east, west
\matrix [matrix anchor=west] at (0,0) поместит левую сторону матрицы в координату (0,0)
отличается от параметра [anchor=west] — который выравнивает в ячейках по левому краю
относится только к ячейке
если ячейке дали имя, то можно обращаться к ее якорям node.anchor
\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
\matrix[matrix anchor=inner node.south,anchor=base,row sep=3mm] at (1,1)
{
\node {a}; & \node {b}; & \node {c}; & \node {d}; \\
\node {a}; & \node(inner node) {b}; & \node {c}; & \node {d}; \\
\node {a}; & \node {b}; & \node {c}; & \node {d}; \\
};
\draw (inner node.south) circle (1pt);
\end{tikzpicture}
кратко по примеру выше:
inner node[matrix anchor=inner node.south, ... at (1,1), т.е. сказали, что точку юга этой ноды поместить в координату (1,1)anchor=base — колонки выравнивать по центруampersand replacement=⟨macro name or empty⟩
для некоторых процедур это нужно,чтобы не было конфликта с другими библиотеками. Если матрицу закручивать по контуру, то придется поменять разделитель на другое.
\matrix [ampersand replacement=\&]
без нее эта тема не закончена
\usetikzlibrary{matrix}
это матрица в которой каждая ячейка это node
\usetikzlibrary {matrix}
\begin{tikzpicture}
\matrix (magic) [matrix of nodes]
{
8 & 1 & 6 \\
3 & 5 & 7 \\
4 & 9 & 2 \\
};
\draw[thick,red,->] (magic-1-1) |- (magic-2-3);
\end{tikzpicture}
мы такую уже делали сами, но она объявлена в библиотеке, нужно просто сослаться в заголовке
указать колонку и строку в заголовке и назначить свой стиль
\begin{tikzpicture}[row 2 column 3/.style=red]
\matrix [matrix of nodes]
\usetikzlibrary {matrix}
\begin{tikzpicture}
\matrix [matrix of nodes]
{
8 & 1 & 6 \\
3 & 5 & |[red]| 7 \\
4 & 9 & 2 \\
};
\end{tikzpicture}
для этого нужно поместить между вертикальных линий все данные |[red] (seven)|, как здесь передаем цвет и имя ноды
у & есть необязательный аргумент [3mm] — это расстояние между колонками
8 &[1cm] 1 &[3mm] |[red]| 6 \\
3 & 5 & \node[red]{7}; \draw(0,0) circle(10pt);\\
все ячейки становятся заключены в $
обязывает отображать пустые ячейки
\usetikzlibrary {matrix}
\begin{tikzpicture}
\matrix [matrix of math nodes,nodes={circle,draw},nodes in empty cells]
{
a_8 & & a_6 \\
a_3 & & a_7 \\
a_4 & a_9 & \\
};
\end{tikzpicture}
обычно это \\
чтобы в ячейке переносить по строкам, нужно поместить текст в {}
\usetikzlibrary {matrix}
\begin{tikzpicture}
\matrix [matrix of nodes,nodes={text width=16mm,draw}]
{
row 1 & {upper line \\ lower line} \\
row 2 & hmm \\
};
\end{tikzpicture}
\usetikzlibrary {matrix}
\begin{tikzpicture}
\matrix [matrix of math nodes,%
left delimiter=\|,right delimiter=\rmoustache,%
above delimiter=(,below delimiter=\}]
{
a_8 & a_1 & a_6 \\
a_3 & a_5 & a_7 \\
a_4 & a_9 & a_2 \\
};
\end{tikzpicture}
\path … pic ⟨foreach statements⟩ [⟨options⟩] (⟨prefix⟩) at(⟨coordinate⟩) :⟨animation attribute⟩={⟨options⟩} {⟨pic type⟩} …;
\tikzset в преамбуле\tikzset{
seagull/.pic={
% Code for a "seagull". Do you see it?...
\draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0);
}
}
Вообще PIC это упрощенная запись вставки кода в path.
во втором случае напишем через pic type =:
\tikz {
\path (0,0) pic [pic type = seagull]
(1,0) pic {seagull};
}
pics/code={}:\tikz \pic [pics/code={\draw (-3mm,0) to[bend left] (0,0)
to[bend left] (3mm,0);}]
{}; % no pic type specified
но в последнем варианте, pic не будет, а будет чистый code, который и делает сам pic
позволяет в опцияхк команде pic передать дополнительные параметры.
\tikzset{
my pic/.pic = {
\path [pic actions] (0,0) circle[radius=3mm];
\draw (-3mm,-3mm) rectangle (3mm,3mm);
}
}
\tikz \pic {my pic}; \space
\tikz \pic [red] {my pic}; \space
\tikz \pic [draw] {my pic}; \space
\tikz \pic [draw=red] {my pic}; \space
\tikz \pic [draw, shading=ball] {my pic}; \space
\tikz \pic [fill=red!50] {my pic};
также как и node позволяет рисовать за основным рисунком или перед ним
можно указать индекс слоя
принимает параметры от foreach
\tikz \pic foreach \x in {1,2,3} at (\x,0) {seagull};
настраиваем стили для pic
\begin{tikzpicture}[every pic/.style={scale=2,transform shape}]
\pic foreach \x in {1,2,3} at (\x,0) {seagull};
\end{tikzpicture}
я не уверен,что буду этим пользоваться, но можно добавлять префиксы к именам точек pic
будет работать как label в nodes
или его аналог в библиотеке quotes
pic [draw, "$\alpha$"] {angle};
every pic quotes — для настройки кавычек
\tikzset{
pics/my circle/.style = {
background code = { \fill circle [radius=#1]; }
}
}
\tikz [fill=blue!30]
\draw (0,0) pic {my circle=2mm} -- (1,1) pic {my circle=5mm};
\path … node ⟨foreach statements⟩ [⟨options⟩] (⟨name⟩) at(⟨coordinate⟩) :⟨animation attribute⟩={⟨options⟩} {⟨node contents⟩} …;
это тоже, что и в фигурных скобках.
\tikz {
\path (0,0) node [red] {A}
(1,0) node [blue] {B}
(2,0) node [green, node contents=C]
(3,0) node [node contents=D] ;
}
Node размещается в последней координате path, а at указывает конкретно куда поместить node.
\node at (0,0) {сюда}
нарисует сзади текущего рисунка.
\tikz \fill [fill=blue!50, draw=blue, very thick] (0,0) node [behind path, fill=red!50] {first node}
тоже, что и выше, только нарисует спереди текущего рисунка
задает имя node, полезно для якорей и координат
можно задать alias и есть еще режим also, позволяет под этим же именем node разместить другой текст
\path … coordinate[⟨options⟩](⟨name⟩)at(⟨coordinate⟩) …;
специальный синтаксис для легковесных node
это будет просто точка и все якоря будут иметь одно и тоже значение.
\coordinate — простая запись
\path[shape=coordinate]
(0,0) coordinate(b1)
(1,0) coordinate(b2)
(1,1) coordinate(b3)
(0,1) coordinate(b4);
Опции для node отличаются от назначений path, поэтому для node нужно давать свои назначения в опциях.
Для рисования вокруг node используем библиотеку \usetikzlibrary {shapes.geometric}
https://tikz.dev/library-shapes
в ней много разных shapes, которые можно указывать в options
По умолчанию без библиотек в node можно применять 3 вида shapes:
в node можно вставлять несколько foreach
\tikz \node foreach \x in {1,...,4} foreach \y in {1,2,3}
[draw] at (\x,\y) {\x,\y};
устанавливает стиль для каждой ноды
\begin{tikzpicture}[every node/.style={draw}]
или
\begin{tikzpicture}
[every rectangle node/.style={draw},
every circle node/.style={draw,double}]
\draw (0,0) node[rectangle] {A} -- (1,1) node[circle] {B};
\end{tikzpicture}
для каждой прямоугольной node или для каждой круглой node
\begin{tikzpicture}
[execute at begin node={A},
execute at end node={D}]
\node[execute at begin node={B}] {C};
\end{tikzpicture}
На выходе даст ABCD
Используется в scope и добавляет префикс к имени node
\tikz {
\begin{scope}[name prefix = top-]
\node (A) at (0,1) {A};
\node (B) at (1,1) {B};
\draw (A) -- (B);
\end{scope}
\begin{scope}[name prefix = bottom-]
\node (A) at (0,0) {A};
\node (B) at (1,0) {B};
\draw (A) -- (B);
\end{scope}
\draw [red] (top-A) -- (bottom-B);
}
ее брат name suffix=⟨text⟩ добавит суффикс в конце имени
внутренний отступ от текста к рамке
margin по x
margin по y
эффект этой опции позволит сместить все якоря вовне
outer sep=auto
outer xsep=⟨dimension⟩
outer ysep=⟨dimension⟩
минимальная высота node
если текст не вместится,то node расширится
минимальная ширина node
для квадратных и круглых форм
пропорции сжатия
проверяет,чтобы внутрь фигуры вписывалась окружность
поворачивает контур фигуры, но не поворачивает текст
это node состоящая из нескольких частей
\usetikzlibrary {shapes.multipart}
\begin{tikzpicture}
\node [circle split,draw,double,fill=red!20]
{
% No \nodepart has been used, yet. So, the following is put in the
% ``text'' node part by default.
$q_1$
\nodepart{lower} % Ok, end ``text'' part, start ``output'' part
$00$
}; % output part ended.
\end{tikzpicture}
для ее использования нужно применить circle split и в \nodeparts указать аргументы {text,lower}.
для нее же можно настроить стиль:
every ⟨part name⟩ node part
\usetikzlibrary {shapes.multipart}
\tikz [every lower node part/.style={red}]
\node [circle split,draw] {$q_1$ \nodepart{lower} $00$};
задает цвет текста
\draw[node font=\itshape] — задает шрифт в node
или font=⟨font commands⟩ если задать внутри node
\begin{tikzpicture}
\node [font=\itshape] {italic};
\end{tikzpicture}
\tikz[align=center] \node[draw] {This is a\\demonstration.};задает ширину текстового поля в node
высоту текстового блока
глубина текста
south тоже есть
anchor= — по умолчанию это центр node, но можно задать любую координату и относительно ее будет идти привязка
\tikz \fill (0,0) circle (2pt) node[above=2pt] {above};
\usetikzlibrary{positioning}
дает все тоже самое,но можно еще вычислять расстояния
\node at (1,1) [above=2pt+3pt,draw]
of\usetikzlibrary {positioning}
\begin{tikzpicture}[every node/.style=draw]
\draw[help lines] (0,0) grid (2,2);
\node (somenode) at (1,1) {some node};
\node [above=5mm of somenode.north east] {\tiny 5mm of somenode.north east};
\node [above=1cm of somenode.north] {\tiny 1cm of somenode.north};
\end{tikzpicture}
of укажет относительно чего смещение
смещает node по сетке, а не относительно бордюра node
\usetikzlibrary {positioning}
\begin{tikzpicture}[every node/.style=draw]
\draw[help lines] (0,0) grid (2,3);
% Not gridded
\node (a1) at (0,0) {not gridded};
\node (b1) [above=1cm of a1] {fooy};
\node (c1) [above=1cm of b1] {a};
% gridded
\node (a2) at (2,0) {gridded};
\node (b2) [on grid,above=1cm of a2] {fooy};
\node (c2) [on grid,above=1cm of b2] {a};
\end{tikzpicture}
смещает без on grid относительно бордюра node
с on grid смещает четко по сетке grid
\begin{tikzpicture}[every node/.style=draw,node distance=5mm]
теперь все смещения будут на 5мм
Очень показательно как работает этот ключ
\usetikzlibrary {positioning}
\begin{tikzpicture}[every node/.style={draw,node distance=0mm}]
\draw[help lines] (0,0) grid (2,3);
% Not gridded
\node (a1) at (0,0) {not gridded};
\node (b1) [above=of a1] {fooy};
\node (c1) [above=of b1] {a};
% gridded
\node (a2) at (2,0) {gridded};
\node (b2) [on grid,above=of a2] {fooy};
\node (c2) [on grid,above=of b2] {a};
\end{tikzpicture}
node distance=0mm — показало смещение для on grid по центрам, а без grid от бордюра.
еще есть вариант [node distance=1 and 1]
К вышеперечисленной серии команд в библиотеке еще есть
о них отдельно
лучше позиционируют большие массивы node
т.е. подгонка координат
\usetikzlibrary {fit,shapes.geometric}
\begin{tikzpicture}[level distance=8mm]
\node (root) {root}
child { node (a) {a} }
child { node (b) {b}
child { node (d) {d} }
child { node (e) {e} } }
child { node (c) {c} };
\node[draw=red,inner sep=0pt,thick,ellipse,fit=(root) (b) (d) (e)] {};
\node[draw=blue,inner sep=0pt,thick,ellipse,fit=(b) (c) (e)] {};
\end{tikzpicture}
библиотека fit и опция fit позволяет охватить место,чтобы в него могли войти нужные данные
\tikz[scale=3] \node[transform shape] {X};
т.е. я сначала сказал, что нужно сделать scale=3, а потом команда transform shape выполнит это действие и я получу гигантскую X.
причем сказать можно в path или draw, а команда выполнится в node
модули и библиотеки для трансформаций
будет рисовать по криволинейным траекториям подробнее https://tikz.dev/tikz-shapes
указывает явно координату, где разместить node в path
\tikz \draw (0,0) -- (3,1)
node[pos=0]{0} node[pos=0.5]{1/2} node[pos=0.9]{9/10};
pos получает значение от 0 до 1 по длине пути
направление может быть left или right в зависимости от этого будет выбираться якорь в node для соединения
если установлена опция auto то будет делать наоборот, для left будет искать right якорь
' — апостроф отработает как swap
будет писать текст вдоль кривой
можно добавить [allow upside down] или [rotate=180]
node[midway,sloped,below] {$y$};
перевернет надпись вверх ногами
это такая надпись в надписи
\usetikzlibrary {positioning}
\tikz [circle] {
\node [draw] (s) [label=below:$s$] {ф};
\node [draw] (a) [right=of s] {} edge (s);
\node [draw] (b) [right=of a] {} edge (a);
\node [draw] (t) [right=of b, label=$t$] {} edge (b);
}
направление метки словами left, right, below, above или градусы и двоеточие:
label=[⟨options⟩]⟨angle⟩:⟨text⟩ или \node [draw] (s) [label=100:$s$] {ф};
\tikz
\node [circle, draw,
label=default,
label=60:$60^\circ$,
label=below:$-90^\circ$,
label=3:$3^\circ$,
label=2:$2^\circ$,
label={[below]180:$180^\circ$},
label={[centered]135:$135^\circ$}] {my circle};
установит дистанцию для label от меток
настроит стиль для label
булавка — похожа на label, но с булавкой)
расстояние до текста в булавке
стиль булавки
аналогично label position
настроит вид edge для pin
pin={[pin edge={blue,thick}]right:X},
Нужна библиотека \usetikzlibrary{quotes}
\usetikzlibrary {quotes}
\begin{tikzpicture}
\matrix [row sep=5mm] {
\node [draw, "label"] {A}; \\
\node [draw, "label" left] {B}; \\
\node [draw, "label" centered] {C}; \\
\node [draw, "label" color=red] {D}; \\
\node [draw, "label" {red,draw,thick}] {E}; \\
};
\end{tikzpicture}
текст в кавычках становится обычным label
\usetikzlibrary {quotes}
\tikz
\node ["90:$90^\circ$", "left:$180^\circ$", circle, draw] {circle};
задать стиль
Соединение Nodes
\begin{tikzpicture}
\path (0,0) node (x) {Hello World!}
(3,1) node[circle,draw](y) {$\int_1^2 x \mathrm d x$};
\draw[->,blue] (x) -- (y);
\draw[->,red] (x) -| node[near start,below] {label} (y);
\draw[->,orange] (x) .. controls +(up:1cm) and +(left:1cm) .. node[above,sloped] {label} (y);
\end{tikzpicture}
При соединении nodes стрелки будут проходить от границы node
это ребро, которое будет добавлено после того, как будет нарисован основной путь.
\path … edge[⟨options⟩] ⟨nodes⟩ (⟨coordinate⟩) …;
\begin{tikzpicture}
\node foreach \name/\angle in {a/0,b/90,c/180,d/270}
(\name) at (\angle:1) {$\name$};
\path[->] (b) edge (a)
edge (c)
edge [-,dotted] (d)
(c) edge (a)
edge (d)
(d) edge (a);
\end{tikzpicture}
edge — это просто ребра между координатами.
Внутри edge можно вставлять node
назначить стиль для всех edge
для edge в библиотеке quotes также работает текст в кавычках, как label
\usetikzlibrary {quotes}
\tikz \draw (0,0) edge ["left", ->] (2,0);
Стиль quotes
к тексту с кавычками добавить '
определяется параметром inner sep=
\usetikzlibrary {quotes}
\tikz [tight/.style={inner sep=1pt}, loose/.style={inner sep=.7em}]
\draw (0,0) edge ["left" tight,
"right"' loose,
"start" near start] (4,0);
Это означает,что можно ссылаться из одной картинки в другую картинку на странице.
этот параметр нужно назначить картинкам, которые будут друг на друга ссылаться
\tikzset{every picture/.append style={remember picture}}
этот стиль для всех картинок сразу.
эту опцию необходимо указать в свойствах path, которые будут ссылаться на другие изображения.
Да, я это видел и я это сделал. Все соединились стрелочками.
\tikz[remember picture] \node[circle,fill=red!50] (n1) {}; — это кружок в любом месте текста.
\tikz[remember picture] \node[fill=blue!50] (n2) {}; — это квадратик, в другом месте.
\begin{tikzpicture}[remember picture,overlay]
\draw[->,very thick] (n1) -- (n2);
\end{tikzpicture}
а это линия,которая соединит кружок с квадратиком
все так и произошло.
\begin{tikzpicture}[remember picture]
\node (c) [circle,draw] {Big circle};
\draw [overlay,->,very thick,red,opacity=.5]
(c) to[bend left] (n1) (n1) -| (n2);
\end{tikzpicture}
Это красная линия с еще более сложным маршрутом.
на каждой странице присутствует node — current page и у нее есть полный набор ancher: west,east,north,south,center…
для размещения в любом месте страницы нужно в свойствах указать:
\begin{tikzpicture}[remember picture,overlay]
\path … node also[⟨late options⟩](⟨name⟩) …; — добавляет опции к узлу позже.
Обязательно нужно указать имя node и не должно быть указано текста. Только опции.
\begin{tikzpicture}
\node [draw,circle] (a) {Hello};
\node also [label=above:world] (a);
\end{tikzpicture}
этот макрос подобен командам append after command и prefix after command
это еще один аналог node also
\begin{tikzpicture}
\node [draw,circle] (a) {Hello};
\path [late options={name=a, label=above:world}];
\end{tikzpicture}
\begin{tikzpicture}
\begin{scope}%делаю специальнуюзону видимости для CLIP
\fill[black!20](-6,0) circle (1.6);%немного фона вокруг кружка
\clip (-6,0) circle (1.5cm);%клипаю будущий рисунок
\node (p) at (-6,0) {\includegraphics[width=3.5cm]{lamp}%вставляю рисунок
\rule{15pt}{0pt}};%так я придумал делать отступ от рисунка невидимой rule
\end{scope}
\gridnum %это просто разметка координат в моем нехитром исполнении, покажу позже
\node[text width=12cm,anchor=north west] at (p.north east) {Для проведения теста, подайте рабочее напряжение на вход ...};%это собственно текстовый блок, который выровнялся по правому верхнему углу рисунка и левому верхнему углу текста
%anchor=north west] at (p.north east) - это магия
\end{tikzpicture}
Grid сделал, чтобы удобно было рисовать и не разу не пожалел.
Кидаешь рисунок в координату и дальше расставляешь свои фичи.
%%%%%%%%%%%%%%%%%%%%%%%%% GRID
\def\gridnum {
\draw[help lines] (-8,-8) grid +(16,16);
\node foreach \x in {-8,-7,...,8} at (\x,8.5) {\x};
\node foreach \y in {-8,-7,...,8} at (8.5,\y) {\y};
\node foreach \x in {-8,-7,...,8} at (\x,-8.5) {\x};
\node foreach \y in {-8,-7,...,8} at (-8.5,\y) {\y};
\draw[red] (0,-8.5) -- (0,8.5);
\draw[red] (-8.5,0) -- (8.5,0);
}
\tikzset{
num/.style={draw,shape=circle,fill=black,text=white,minimum size=2em,font=\bf,general shadow={fill=gray,shadow scale=1.1}},%определяет стиль кружка для отметки на рисунках
numtext/.style={draw,shape=circle,fill=black!85,text=white,minimum size=1em,font=\bf,general shadow={fill=gray,shadow scale=1.1}},%определяет стиль кружка для отметки в тексте
arrow num/.style={line width=.1em, gray,arrows = {-Stealth[line width=0.3pt, fill=gray, length=10pt,open,fill=gray,white,quick]}},%определяет стиль стрелки для отметки на рисунках
}
А это сами кружки
\def\numar#1#2#3{
\node [num] (l#1) at (#2) {#1};
\coordinate (t#1) at (#3);
\draw[line width=.15em, white] (l#1) -- ($(l#1)!.95!(t#1)$);
\draw[arrow num] (l#1) -- (t#1);
%рисует черный кружок с цифрой #1 кружок в координате #2, а стрелочку в координату #3
}
А это результат все вместе:
\begin{tikzpicture}
\begin{scope}%это клипнутый рисунок
\fill[black!20](-6,0) circle (1.6);
\clip (-6,0) circle (1.5cm);
\node (p) at (-6,0) {\includegraphics[width=3.5cm]{lamp}\rule{15pt}{0pt}};
\end{scope}
\gridnum % это мой грид
\numar{2}{0,-4}{-2.2,-1.8};%это кружок с 2 и со стрелкой
\numar{2}{0,-4}{2.2,-1.8};%из двойки вторая стрелка
\node at (-4,0){\num{1}};%это кружок без стрелки
\node at ( 4,0){\num{1}};
\end{tikzpicture}
Мощная примудрость, позволит на многое открыть глаза в TIKZ
\begin{tikzpicture}
\gridnum
\begin{scope}[scale=2] %сделал, чтобы видно лучше было
\draw[thick,red]
(0,0) coordinate (a) %назначаем координате имя (a)
-- coordinate (ab) %а это пока рисуем от (a) к (b) запоминаем середину и называем ее (ab)
(1,.5) coordinate (b) %назначаем координате имя (b)
.. coordinate (bc) controls +(up:1.5cm) and +(left:0cm) .. %а это пока рисуем от (b) к (c) запоминаем середину и называем ее (bc)
%но считает серидину сложно с учетом контрольных точек
(3,1) coordinate (c) %назначаем координате имя (c)
(0,1) -- (2,1) -- %просто рисуем замкнутый треугольник и
coordinate (x) (1,2) -- cycle;%x - будет точно серединой между двух вершин
\draw (a) node[below] {start part 1} %ничего интересного, просто подписать точки
(ab) node[below right] {straight segment}
(b) node[right] {end first segment}
(c) node[right] {end part 1}
(x) node[above right] {part 2 (closed)};
\fill[red](a) circle (1pt); %а это просто эти точки разукрасить
\fill[blue](b) circle (1pt);
\fill[green](ab) circle (1pt);
\fill[yellow](bc) circle (1pt);
\fill[magenta](c) circle (1pt);
\fill[orange](x) circle (1pt);
\end{scope}
\end{tikzpicture}
круглые и угловатые соединения линий
rounded corners=4pt — по умолчанию, или можно поменять
\tikz \draw (0,0) -- (1,1) [rounded corners] -- (2,0) -- (3,1) [sharp corners] -- (3,0) -- (2,1);
это группировка scope для назначения стиля
\tikz \draw (0,0) -- (1,1) {[rounded corners] -- (2,0) -- (3,1)} -- (3,0) -- (2,1);
задает имя пути, полезно при пересечениях
задает стиль всем значениям path
\begin{tikzpicture}
[fill=yellow!80!black, % only sets the color
every path/.style={draw}] % all paths are drawn
\fill (0,0) rectangle +(1,1); %все будут с конуром
\shade (2,0) rectangle +(1,1);%и градиент тоже
\end{tikzpicture}
по пути основного пути вставит любой другой путь))))
\tikz [c/.style={insert path={circle[radius=2pt]}}] \draw (0,0) -- (1,1) [c] -- (3,2) [c];
и его брат prefix after command=〈path〉
\tikz \draw node [append after command={(foo)--(1,1) (foo)--(2,1) (foo)--(3,1)},draw] (foo){foo};
Т.е. пока рисую draw, включаю node и обвожу ее [draw], а в параметрах command задаю лучики, сколько угодно.
cycle — замыкает контур
current subpath start — возвращается в исходную координату, но контур не замыкает
\useasboundingbox (0,2.5); % увеличивает отступ в картинке
тип линии которую нужно провести
-- — прямая
|- — вертикально, потом горизонтально или cycle
.. controls .. — контрольная точка 1 или 2
begin{tikzpicture}
\draw (1,0) circle [radius=1.5];
\fill (1,0) circle [x radius=1cm, y radius=5mm, rotate=30];
\end{tikzpicture}
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);
\draw (1,1) ellipse [x radius=1cm,y radius=.5cm];
\end{tikzpicture}
/tikz/start angle=〈degrees〉
/tikz/end angle=〈degrees〉
/tikz/delta angle=〈degrees〉
\tikz[rotate=30] \draw[step=1mm] (0,0) grid (2,2);
/tikz/step=〈number or dimension or coordinate〉
/tikz/xstep=〈dimension or number〉
/tikz/ystep=〈dimension or number〉
/tikz/help lines
\path ... parabola[〈options〉]bend〈bend coordinate〉〈coordinate or cycle〉 ...;
/tikz/bend=〈coordinate〉
/tikz/bend pos=〈fraction〉
/tikz/parabola height=〈dimension〉
/tikz/bend at start
/tikz/bend at end
\path ... sin〈coordinate or cycle〉 ...;
\path ... svg[〈options〉]{〈path data〉} ...;
\usetikzlibrary {svg.path}
\begin{tikzpicture}
\filldraw [fill=red!20] (0,1) svg[scale=2] {h 10 v 10 h -10} node [above left] {upper left} -- cycle;
\draw svg {M 0 0 L 20 20 h 10 a 10 10 0 0 0 -20 0};
\end{tikzpicture}
И кульминация!!!
\usetikzlibrary {svg.path}
\begin{tikzpicture}
\draw[fill=red] svg[rotate=180,scale=1pt] {m 0,0 c -7.1455,-3.0005 -14.1485,-6.184 -6.261,-17.3275 l 0.7006,-8.7994 -2.2838,-2.151 c 6.7935,-23.5259 19.2799,-46.8506 29.895,-65.918 11.1032,-15.0145 24.2647,-28.7189 28.7623,-47.9367 l 11.9841,-34.99407 c -0.1546,-13.35578 -2.0371,-27.40362 3.835,-38.34918 l 6.2318,-9.82699 c 1.5939,-28.91141 13.1608,-53.72504 12.7031,-82.211751 11.2272,-29.04903 17.5024,-22.60743 25.1668,-26.1256 4.524,-1.40654 8.693,-3.38055 10.0668,-9.827 l 4.554,2.1571 c -3.5888,-15.13669 -2.1459,-27.75767 1.9176,-39.06851 1.3477,-6.40097 7.8536,-8.21675 14.8602,-9.58722 8.592,-2.16346 14.2134,1.61359 20.3733,4.31421 3.564,5.54462 6.8227,11.17624 5.9921,17.97645 -0.088,2.44508 -1.4805,0.80239 -1.7797,2.90917 -0.6305,4.43879 2.7321,11.60579 -0.8615,12.55824 -4.4315,1.17434 -0.8057,12.46002 -5.2394,13.07901 -11.4427,1.59752 -8.2461,7.35191 -11.8607,9.9434 -2.2929,3.4139 -3.7804,7.09455 0.088,11.12472 7.8121,8.29041 7.5135,18.05557 8.6284,27.563671 5.5774,16.1437 10.1453,32.62388 26.8446,45.06055 8.8021,6.70563 14.713,14.56771 20.3734,22.53013 l 11.0253,11.26537 c 9.1625,0.81664 11.8325,3.66246 10.7858,7.6699 5.2654,7.69444 0.9194,8.78118 -3.835,9.58721 l -19.4145,0.23948 c -6.3528,-2.57118 -8.2777,-6.80263 -9.5872,-11.26507 -4.7804,-8.04729 -11.2793,-15.52136 -19.8938,-22.29065 -18.0192,-7.5638 -23.762,-19.73159 -32.1176,-30.91936 l -1.6779,37.15119 c 1.1413,7.46498 1.8943,15.70567 2.3969,24.44775 6.3573,7.86785 13.5455,15.45832 14.381,25.16679 l 14.6207,50.57336 c 5.1154,14.4625 1.2032,22.1542 -0.9588,31.1588 l -16.0588,44.3416 c -4.5409,19.7879 5.1463,25.3556 -1.6827,26.5005 1.2122,4.1548 5.7941,11.5294 10.791,15.6839 l 16.538,5.5128 c 5.8814,5.4882 4.5425,8.71988 0.2395,11.02528 -10.2823,0.03 -20.4991,0.7699 -31.3983,-5.99208 -24.5966,2.299 -20.5907,-1.8606 -27.3242,-3.5952 -6.3237,-9.1034 0.046,-19.8628 2.075,-24.194 l -6.8033,2.9522 c 2.2535,-29.9275 11.2296,-63.866 17.911,-84.9381 l 4.0747,-4.3145 c -2.5708,-2.0158 -5.4922,-2.5127 -6.2318,-12.4634 -4.9405,-15.5883 -14.1539,-28.3278 -22.7699,-41.4653 -16.0976,16.02 -27.5888,36.6464 -36.6716,59.6813 -3.0305,7.3616 -8.3362,10.1725 -13.1827,13.9017 -11.4324,16.4468 -20.5631,46.1767 -29.4813,66.3954 l -3.5952,-1.2016 c -2.918,8.9664 1.9352,10.8095 6.4716,12.9432 l 8.6284,4.7935 c 5.8839,5.6301 4.5728,8.9879 -1.6778,10.7858 -9.743,4.25658 -18.0911,2.2347 -26.6049,0.9588 -3.7097,-3.4521 -7.4534,-6.8618 -13.6619,-7.1907 z};
\end{tikzpicture}
строит график по координатам
\tikz \draw plot coordinates {(0,0) (1,1) (2,0) (3,1) (2,1) (10:2cm)};
(a) to (b) примерно тоже, что (a) – (b), но есть нюансы.
После to я могу передать дополнительные настройки для этого участка пути:
(a) to [out=135,in=45] (b) выйдет из точки (a) под углом 135, а войдет под 45.
или еще 3 замечательных макроса:
\tikztostart, \tikztotarget, и \tikztonodes — запоминают координаты без зацикливания пути: т.е. в режиме current subpath start
\begin{tikzpicture}[to path={
.. controls +(1,0) and +(1,0) .. (\tikztotarget) \tikztonodes}]
\node (a) at (0,0) {a};
\node (b) at (2,1) {b};
\node (c) at (1,2) {c};
\draw (a) to node {x} (b)
(a) to (c);
\end{tikzpicture}
Этот вариант я припас для вертикального написания шрифта
\begin{tikzpicture}
\draw (0,0) to node [sloped,above] {x} (3,2);
\draw (0,0) to[out=90,in=180] node [sloped,above] {x} (3,2);
\draw (0,0) to node[sloped,above] {0001000:000200} (0,5);
\end{tikzpicture}
EDGE умеет делать:
edge node={node [sloped,above] {x}} нодыedge label=x ставит меткиedge label=x, edge label'=y ставит зеркальные меткиНазначаем стили для всех to
\tikz[every to/.style={bend left}] \draw (0,0) to (3,2); назначает стиль для to
и ее брат execute at end to=⟨code⟩ выполняют код до и после начала рисования
Для него посвящу отдельную статью но в кратце:
\tikz \draw (0,0) foreach \x in {1,...,3} { -- (\x,1) -- (\x,0) };
Это цикл по списку.
Сначала не хотел разбираться, но потом стало так интересно, а выяснилось, что еще и полезно.
\path … let⟨assignment⟩ ,⟨assignment⟩,⟨assignment⟩… in …;
В let … in можем использовать переменные
\usetikzlibrary {calc}
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);
\draw let \p{foo} = (1,1), \p2 = (2,0) in
(0,0) -- (\p2) -- (\p{foo});
\end{tikzpicture}
оказалась полезная штука для смещения SCOPE и рисовать все в координатах с (0,0)
сначала хотел выбросить, но появилось время, почитал и тоже понравилось
\newdimen\mydim %назначаем переменную для измерения
\begin{tikzpicture}
\mydim=1cm% присваиваем первое значение
\draw (0pt,\mydim) \pgfextra{\mydim=2cm} -- (0pt,\mydim); изменяем значение и получаем новый результат
\end{tikzpicture}
я думаю использовать при настройке типовых рисунков для передачи им параметров
это такие ячейки памяти с сохранеными PATH, которые потом можно применять безограничений
\usetikzlibrary {intersections}
\begin{tikzpicture}
\path[save path=\pathA,name path=A] (0,1) to [bend left] (1,0);%запоминаю путь pathA
\path[save path=\pathB,name path=B]%запоминаю путь pathB
(0,0) .. controls (.33,.1) and (.66,.9) .. (1,1);
\fill[name intersections={of=A and B}] (intersection-1) circle (1pt);%нахожу пересечения пути (причем пути даже не наприсовал)
\draw[blue][use path=\pathA];%а теперь достаю путь и рисую
\draw[red] [use path=\pathB];
\end{tikzpicture}
Это наверно аксиомы с которыми работает path
\draw — аналогично \path[draw]. рисует
\fill — аналогично \path[fill]. заполняет цветом
\filldraw — \path[fill,draw]. рисует и заполняет
\pattern — \path[pattern]. заполняет маленькими path из библиотеки pattern
\shade — \path[shade]. градиент
\shadedraw — \path[shade,draw]. рисует и заполняет градиентом
\clip — \path[clip]. клипит
\useasboundingbox — \path[use as bounding box] связывает до и после
color= — покрасит в цветомline width= — толщина линииline cap= — round, rect, butt — завершение линииline join= — тип соединения линии round, bevel, mitermiter limit= — определяет остроту угла соединенияdash pattern — чередуются on 2pt off 3pt on 4pt off 4pt и получаем свой пунктирdash phase= — первоначальный сдвиг паттернаdash= — совмещает pattern и phase \draw [dash=on 20pt off 10pt phase 10pt]dash expand off
растягивает на сколько может dash, т.е. линия будет нужной длины и без разрывов\usetikzlibrary {decorations}
\begin{tikzpicture}[|-|, dash pattern=on 4pt off 2pt]
\draw [dash expand off] (0pt,30pt) -- (26pt,30pt);
\draw [dash expand off] (0pt,20pt) -- (24pt,20pt);
\draw [dash expand off] (0pt,10pt) -- (22pt,10pt);
\draw [dash expand off] (0pt, 0pt) -- (20pt, 0pt);
\begin{scope}[xshift=2cm]
\draw (0pt,30pt) -- (26pt,30pt);
\draw (0pt,20pt) -- (24pt,20pt);
\draw (0pt,10pt) -- (22pt,10pt);
\draw (0pt, 0pt) -- (20pt, 0pt);
\end{scope}
\end{tikzpicture}
solid — сплошная прямаяработает для всего и draw и fill и svg
double=<color> — нарисует двойную линию и закрасит цветомdouble distance=⟨dimension⟩ — расстояние между линиямиdouble distance between line centers=⟨dimension⟩ — расстояние между центрами линийdouble equal sign distance — удвоит расстояние знака\Huge $==>\implies$\tikz[baseline,double equal sign distance]
\draw[double,thick,-{Implies[]}](0,0.55ex) --++(3ex,0);
\usetikzlibrary {arrows.meta,bending} — это нам пригодится
\usetikzlibrary {arrows.meta,bending}
\tikz \draw[tips, -{Latex[open,length=10pt,bend]}] (0,0) to[bend left] (1,0);
\usetikzlibrary {patterns}
\begin{tikzpicture}
\draw[pattern=dots] (0,0) circle (1cm);
\draw[pattern=fivepointed stars] (0,0) rectangle (3,1);
\end{tikzpicture}
в библиотеке их много и лучше смотреть библиотеку https://tikz.dev/library-patterns#section-library-patterns
исключит из пересечения фигур
\begin{tikzpicture}
\filldraw[fill=yellow!80!black]
% Clockwise rectangle
(0,0) -- (0,1) -- (1,1) -- (1,0) -- cycle
% Counter-clockwise rectangle
(0.25,0.25) -- (0.75,0.25) -- (0.75,0.75) -- (0.25,0.75) -- cycle;
\draw[->] (0,1) -- (.4,1);
\draw[->] (0.75,0.75) -- (0.3,.75);
\draw[->] (0.5,0.5) -- +(0,1) node[above] {crossings: $-1+1 = 0$};
\begin{scope}[yshift=-3cm]
\filldraw[fill=yellow!80!black]
% Clockwise rectangle
(0,0) -- (0,1) -- (1,1) -- (1,0) -- cycle
% Clockwise rectangle
(0.25,0.25) -- (0.25,0.75) -- (0.75,0.75) -- (0.75,0.25) -- cycle;
\draw[->] (0,1) -- (.4,1);
\draw[->] (0.25,0.75) -- (0.4,.75);
\draw[->] (0.5,0.5) -- +(0,1) node[above] {crossings: $1+1 = 2$};
\end{scope}
\end{tikzpicture}
сразу не понял, но если внутри рисунок против шерсти,то вырезает пустоту. Смотрим на стрелочки внутреннего квадрата.
просто вырежет внутренний паттерн
Идея данной функции, добавить внутрь объекта другой объект, ограниченный первым.
причем родительский объект будет иметь имя box с метками по сторонам света.
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);
\filldraw [fill=blue!10,draw=blue,thick] (1.5,1) circle (1)% нарисую круг
[path picture={
\node at (path picture bounding box.center) {%вставлю в круг надпись в центр круга
This is a long text.
};}
];
\end{tikzpicture}
также path picture может быть \draw, \fill, \node, \pattern
Градиент
у него есть настройки
\tikz \shadedraw [shading=axis] (0,0) rectangle (1,1);
\tikz \shadedraw [shading=radial] (0,0) rectangle (1,1);
\tikz \shadedraw [shading=ball,ball color=red] (0,0) circle (.5cm);
\tikz \shadedraw [shading=ball,ball color=blue] (0,0) circle (.5cm);
\tikz \shadedraw [shading=ball,ball color=green] (0,0) circle (.5cm);
это красивые градиентные заливки объектов по 4-м углам
\usepgflibrary {shadings}
\tikz
\shade[upper left=red,upper right=green,
lower left=blue,lower right=yellow]
(0,0) rectangle (3,2);
\tikz \shade[shading=color wheel] (0,0) circle (1.5);
\tikz \shade[shading=color wheel] [even odd rule]
(0,0) circle (1.5)
(0,0) circle (1);
графически привязывает блоки слева и справа Наверно будет удобно для создания различных перекрестных указателей или еще чего-нибудь, где важно, чтобы блоки склеились в единое целое
У них есть подпараметры:
вырезает все на скорую руку
лучше использовать внутри рисунков с применением группировки scope
\begin{tikzpicture}
\draw (0,0) -- ( 0:1cm);
\draw (0,0) -- (10:1cm);
\draw (0,0) -- (20:1cm);
\draw (0,0) -- (30:1cm);
\begin{scope}[fill=red]
\fill[clip] (0.2,0.2) rectangle (0.5,0.5);
\draw (0,0) -- (40:1cm);
\draw (0,0) -- (50:1cm);
\draw (0,0) -- (60:1cm);
\end{scope}
\draw (0,0) -- (70:1cm);
\draw (0,0) -- (80:1cm);
\draw (0,0) -- (90:1cm);
\end{tikzpicture}
Я раньше использовал подобное для рисование стрелок с подложкой белого фона.
Оказалось, что все уже придумано до нас))
\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
\draw
[preaction={draw,line width=4mm,blue}]%нарисует по координатам draw прямоугольник с толщиной линии 4mm
[line width=2mm,red] (0,0) rectangle (2,2);%нарисует сверху по этим же координатам линию 2mm
\end{tikzpicture}
удобно для выделения контраста и рисования теней
\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
\draw
[preaction={fill=black,opacity=.5,
transform canvas={xshift=1mm,yshift=-1mm}}]
[fill=red] (0,0) rectangle (1,2)
(1,2) circle (5mm);
\end{tikzpicture}
preaction — может быть несколько штук в одном объекте
Это друг preaction, только делает после того как нарисовал основной рисунок
\usetikzlibrary {decorations.pathmorphing,shadows}
\begin{tikzpicture}
\node [circular drop shadow={shadow scale=1.05},minimum size=3.13cm,
decorate, decoration=zigzag,
fill=blue!20,draw,thick,circle] {Hello!};
\end{tikzpicture}
Целая библиотека различных декораций и линий для рисования объектов.
Для подключения TIKZ нужно в преамбуле добавить:
\usepackage{tikz} %подключить пакет
\usetikzlibrary {angles,calc,quotes} %подключить нужные библиотеки
Библиотеки по ходу буду тоже описывать, те, которые мне точно понравились и нужны. Но их очень много.
Чтобы вставить в текст объект TIKZ нужно использовать окружение
\begin{tikzpicture}
...
\end{tikzpicture}
или
\tikz ...
(X, Y) — разделитель запятая.
Измеряем либо в стандартных единицах TeX (cm, pt). По умолчанию PGF использует сантиметр: X -> вправо, Y -> вверх.
(30:1cm) — полярные координаты. Т.е. от текущей точки на 1см 30 градусов.
Для трехмерных объектов (1,1,1)
У каждого объекта есть свои якорные координаты,связанные со сторонами света:
например: first node.north
И их возможные комбинации: node.north west
Нужно перед указанием координат поставить ++ и указать относительное смещение ++(1cm,0pt) — вправо на 1см.
Но для этого нужно знать, где сейчас находится курсор.
Как выяснил, команда \node не изменяет текущую координату.
Если использовать один + перед координатами, то перемещение произойдет, но текущая координата не сменится.
(1,0) +(1,0) +(0,1) даст три точки (1,0), (2,0), (1,1).
PATH — водит пером по бумаге, но не оставляет следов, если его не попросить специально.
-- — прямая линия
-| — горизонтально + вертикально
|- — вертикально + горизонтально
cycle — вернуться в точку старта
PATH может:
Так же доступны комбинации с ними.
\path (0,0) rectangle (2ex,1ex); % ничего визуального не произойдет
\path[draw] (0,0) rectangle (2ex,1ex); % появится рамка
\path[fill=black] (0,0) rectangle (2ex,1ex); % появится черный прямоугольник
Для этих случаев есть сокращенные команды:
\path[draw]=\draw\path[fill]=\fill\path[fill,draw]=\filldraw\path[shade]=\shade\path[shade,draw]=\shadedraw\path[clip]=\clip\path[clip,draw]=\draw[clip]Текст добавляем с помощью команды \node прямо в синтаксис \path
\tikz \draw (1,1) node {text} -- (2,2);
У node могут быть:
(name) или [name=имя] [другие опции] {текст}
опции node:
и т.д. это то, что будет нарисовано вокруг текста.
Это такая умная \node с поднодиками.
\begin{tikzpicture}
\node {root}
child {node {left}}
child {node {right}
child {node {child}}
child {node {child}}
};
\end{tikzpicture}
Подключаем библиотеку со стрелочками и оформим стили.
FORK — это вилка, которой будем соединять вниз (down),также можно написать up, left, right и от этой стороны будет выходить стрелка.
\usetikzlibrary {arrows.meta,trees}
\begin{tikzpicture}
[edge from parent fork down, sibling distance=15mm, level distance=15mm,
every node/.style={fill=red!30,rounded corners},
edge from parent/.style={red,-{Circle[open]},thick,draw}]
\node {root}
child {node {left}}
child {node {right}
child {node {child}}
child {node {child}}
};
\end{tikzpicture}
И еще с шариками, а grow — покажет куда расти дереву (up,down,left,right или north,south,east,west). Anchor — это куда прицепляться parent и child.
sibling — ширина плечика на одном уровне, level — это расстояние между уровнями.
every node/.style — назначает стиль глобально для всех node без указания класса.
edge — это собственно само ребро или соединение
ball — это еще одна разновидность фигуры, шарик называется.
\begin{tikzpicture}
[parent anchor=east,child anchor=west,grow=east,
sibling distance=15mm, level distance=15mm,
every node/.style={ball color=red,circle,text=white},
edge from parent/.style={draw,dashed,thick,red}]
\node {root}
child {node {left}}
child {node {right}
child {node {child}}
child {node {child}}
};
\end{tikzpicture}
Нужна своя библиотека graphs
\usetikzlibrary {graphs}
\tikz \graph [grow down, branch left] {
root -> {
left,
2,3 ->{
5,6,7,8 ->{
11,12,13},
9},
right -> {
child,
child} }
};
Тема с графом тоже интересна.
grow — куда растем, указать сторону
branch — в какую сторону ветви раскидать
\usetikzlibrary {graphs.standard}
\tikz \graph [clockwise] { subgraph K_n [n=9] };
Уж очень он мне понравился. Библиотеку обязательно отдельно всю опишу.
Это внутреннее окружение для группировки настроек.
Это фактически зона видимости.
\begin{tikzpicture}
\begin{scope}[color=red]
\draw (0mm,10mm) -- (10mm,10mm);
\draw (0mm, 8mm) -- (10mm, 8mm);
\draw (0mm, 6mm) -- (10mm, 6mm);
\end{scope}
\begin{scope}[color=green]
\draw (0mm, 4mm) -- (10mm, 4mm);
\draw (0mm, 2mm) -- (10mm, 2mm);
\draw[color=blue] (0mm, 0mm) -- (10mm, 0mm);
\end{scope}
\end{tikzpicture}
/tikz/name=⟨scope name⟩ /tikz/every scope /tikz/execute at begin scope=⟨code⟩ /tikz/execute at end scope=⟨code⟩
И у нее есть даже библиотека \usetikzlibrary{scopes}
Когда библиотека загружена, то можно просто указать фигурные скобки, без begin/end
А еще становится доступной команда \scoped ⟨animations spec⟩[⟨options⟩]⟨path command⟩
\usetikzlibrary {scopes}
\begin{tikzpicture}
{ [ultra thick]
{ [red]
\draw (0mm,10mm) -- (10mm,10mm);
\draw (0mm,8mm) -- (10mm,8mm);
}
\draw (0mm,6mm) -- (10mm,6mm);
}
{ [green]
\draw (0mm,4mm) -- (10mm,4mm);
\draw (0mm,2mm) -- (10mm,2mm);
\draw[blue] (0mm,0mm) -- (10mm,0mm);
}
\end{tikzpicture}
\usetikzlibrary {backgrounds}
\begin{tikzpicture}
\node [fill=white] at (1,1) {Hello world};
\scoped [on background layer]
\draw (0,0) grid (3,2);
\end{tikzpicture}
\tikzset— установит в переменную любую команду для применения в окружении \begin{tikzpicture}
baseline— еще можно задать с помощью координаты, тоже поймет.
\tikz[baseline=0pt]\draw(0,0)circle(.5ex); — установит смещение от базовой линии. По умолчанию строго по центру.
А вот так перечеркнем слово
\usetikzlibrary {shapes.misc}
Hello
\tikz[baseline=(X.base)]
\node [cross out,draw] (X) {world.};
my style/.style={draw=red,fill=red!20}
Использование стилей
\begin{tikzpicture}[help lines/.style={blue!50,very thin}]
\draw (0,0) grid +(2,2);
\draw[help lines] (2,0) grid +(2,2);
\end{tikzpicture}
Чтобы добавить настройки к существующему стилю /.append style вместо style
\begin{tikzpicture}[outline/.style={draw=#1,thick,fill=#1!50}]
\node [outline=red] at (0,1) {red};
\node [outline=blue] at (0,0) {blue};
\end{tikzpicture}
или задать значение по умолчанию
\begin{tikzpicture}[outline/.style={draw=#1,thick,fill=#1!50},
outline/.default=black]
\node [outline] at (0,1) {default};
\node [outline=blue] at (0,0) {blue};
\end{tikzpicture}
Выполнит код до того как начал рисовать картину
Выполнит код после того как нарисовал картину
\usetikzlibrary {backgrounds}
\begin{tikzpicture}[execute at end picture=%
{
\begin{pgfonlayer}{background}
\path[fill=yellow,rounded corners]
(current bounding box.south west) rectangle
(current bounding box.north east);
\end{pgfonlayer}
}]
\node at (0,0) {X};
\node at (2,1) {Y};
\end{tikzpicture}
Нарисовал X и Y, а потом подрисовал фон желтого цвета.
В преамбуле напишем \tikzset{every picture/.style=semithick}
или если несколько значений, то \tikzset{every picture/.style={line width=1pt}}
Для работы со шрифтами,рекомендуется всегда загружать эту библиотеку.
Или поговорим о координатах.
([⟨options⟩]⟨coordinate specification⟩)
Три вида координат:
Явное указание координат и неявное указание.
/tikz/cs/x=⟨dimension⟩
/tikz/cs/y=⟨dimension⟩
Все тоже, только xyz
\begin{tikzpicture}[->]
\draw (0,0) -- (xyz cs:x=1);
\draw (0,0) -- (xyz cs:y=1);
\draw (0,0) -- (xyz cs:z=1);
\end{tikzpicture}
/tikz/cs/angle=⟨градусы⟩ — Угол координаты. Угол всегда должен быть указан в градусах.
/tikz/cs/radius=⟨размер) — Расстояние от текущей точки
/tikz/cs/x radius=⟨размер⟩ /tikz/cs/y radius=⟨размер⟩
\tikz \draw (0cm,0cm) -- (30:1cm) -- (60:1cm) -- (90:1cm)
-- (120:1cm) -- (150:1cm) -- (180:1cm);
up, down, left, right, north, south, west, east, north east, north west, south east, south west
\begin{tikzpicture}[x=1.5cm,y=1cm]%масштаб системы координат
\draw[help lines] (0cm,0cm) grid (3cm,2cm);
\draw (0,0) -- (xyz polar cs:angle=0,radius=1);
\draw (0,0) -- (xyz polar cs:angle=30,radius=1);
\draw (0,0) -- (xyz polar cs:angle=60,radius=1);
\draw (0,0) -- (xyz polar cs:angle=90,radius=1);
\draw (xyz polar cs:angle=0,radius=2)
-- (xyz polar cs:angle=30,radius=2)
-- (xyz polar cs:angle=60,radius=2)
-- (xyz polar cs:angle=90,radius=2);
\end{tikzpicture}
\begin{tikzpicture}[x={(-1cm,0cm)},y={(0cm,-1cm)}] %переворачиваю систему координат
\draw[help lines] (0cm,0cm) grid (3cm,2cm);%рисую сетку
\fill (canvas cs:x=1cm,y=0cm) node[right] {X} circle (2pt);%точка в абсолютных координатах без изменений (черная)
\fill (canvas cs:x=0cm,y=1cm) node[left] {Y} circle (2pt);%точка в абсолютных координатах без изменений (черная)
\fill [color=red] (1,0) node[left]{X'} circle (2pt);%точка в относительных координатах перевернутая (красная)
\fill [color=red] (0,1) node[right]{Y'} circle (2pt);%точка в относительных координатах перевернутая (красная)
\draw [color=red] (0,0) -- (30:1) -- (60:1) -- (90:1)
-- (120:1) -- (150:1) -- (180:1);%рисунок в относительных координатах красный
\end{tikzpicture}
barycentric — это координаты по сторонам света north, south, east, west и их комбинации
\begin{tikzpicture}
\coordinate (content) at (90:3cm);
\coordinate (structure) at (210:3cm);
\coordinate (form) at (-30:3cm);
\node [above] at (content) {content oriented};
\node [below left] at (structure) {structure oriented};
\node [below right] at (form) {form oriented};
\draw [thick,gray] (content.south) -- (structure.north east) -- (form.north west) -- cycle;
\small
\node at (barycentric cs:content=0.5,structure=0.1 ,form=1) {PostScript};
\node at (barycentric cs:content=1 ,structure=0 ,form=0.4) {DVI};
\node at (barycentric cs:content=0.5,structure=0.5 ,form=1) {PDF};
\node at (barycentric cs:content=0 ,structure=0.25,form=1) {CSS};
\node at (barycentric cs:content=0.5,structure=1 ,form=0) {XML};
\node at (barycentric cs:content=0.5,structure=1 ,form=0.4) {HTML};
\node at (barycentric cs:content=1 ,structure=0.2 ,form=0.8) {\TeX};
\node at (barycentric cs:content=1 ,structure=0.6 ,form=0.8) {\LaTeX};
\node at (barycentric cs:content=0.8,structure=0.8 ,form=1) {Word};
\node at (barycentric cs:content=1 ,structure=0.05,form=0.05) {ASCII};
\end{tikzpicture}
Для понимания процесса barycentric, каждая координата тянет к себе с определенной силой. Если я поставлю с одинаковой силой, то будет ровно посередине, относительно всех точек.
\node at (barycentric cs:content=1,structure=1 ,form=1) {PostScript}; как на рисунке ниже
/tikz/cs/name=⟨node name⟩
/tikz/anchor=⟨anchor⟩
\usetikzlibrary {arrows.meta}
\begin{tikzpicture}[node font=\ttfamily]
\node (shape) at (0,2) [draw] {class Shape};
\node (rect) at (-2,0) [draw] {class Rectangle};
\node (circle) at (2,0) [draw] {class Circle};
\node (ellipse) at (6,0) [draw] {class Ellipse};
\draw [color=red](node cs:name=circle,anchor=north) |- (0,1);
\draw [blue] (node cs:name=ellipse,anchor=north) |- (0,1);
\draw [arrows = -{Triangle[open, angle=60:3mm]}]
(node cs:name=rect,anchor=north)
|- (0,1) -| (node cs:name=shape,anchor=south);
\end{tikzpicture}
\usetikzlibrary {arrows.meta} — библиотека для красивых стрелочек
\begin{tikzpicture}[node font=\ttfamily] — назначаем шрифт
Присвоим имена каждой ноде
\node (shape) at (0,2) [draw] {class Shape};
\node (rect) at (-2,0) [draw] {class Rectangle};
\node (circle) at (2,0) [draw] {class Circle};
\node (ellipse) at (6,0) [draw] {class Ellipse};
Нарисуем первую линию красного цвета
\draw [color=red](node cs:name=circle,anchor=north) |- (0,1);
Нарисуем вторую линию синего цвета
\draw [blue] (node cs:name=ellipse,anchor=north) |- (0,1);
Нарисуем стрелку черногго цвета
\draw [arrows = -{Triangle[open, angle=60:3mm]}]
(node cs:name=rect,anchor=north)
|- (0,1) -| (node cs:name=shape,anchor=south);
А эта штука соединяет между собой две ноды по бордюру самым коротким путем: (node cs:name=a) -- (node cs:name=b), т.е. все, что в круглых скобках — это координаты.
\usetikzlibrary {shapes.geometric}
\begin{tikzpicture}
\path (0,0) node(a) [ellipse,rotate=10,draw] {An ellipse}
(3,-1) node(b) [circle,draw] {A circle};
\draw[thick] (node cs:name=a) -- (node cs:name=b);
\end{tikzpicture}
А это легкая замена rectangle, чтобы не пересекалось
\tikz \draw (0,0) node(x) [draw] {Text}
% rectangle (1,1)
(node cs:name=x) -- +(0,1) -- +(1,1) -- +(1,0) -- (node cs:name=x)
(node cs:name=x) -- +(1,1)
(node cs:name=x) -- +(1,.5)
(node cs:name=x) -- +(.5,1)
;
Для те, кто в танке, чтобы не забыть: +(координаты) — не изменяет точку отсчета и указывает относительную координату; ++(координаты) — изменяет точку отсчета и указывает относительные координаты; (координаты) — изменяет точку отсчета и указывает абсолютные координаты.
\begin{tikzpicture}
\draw[blue!20] (0,0) grid +(2,2);
\draw (0,0) node(x) [draw] {Text}
(node cs:name=x) -- ++(0,1) -- ++(1,1) -- +(1,0) -- (node cs:name=x);
\end{tikzpicture}
\usetikzlibrary {shapes.geometric}
\begin{tikzpicture}[fill=blue!20]
\draw[help lines] (-1,-2) grid (6,3);
\path (0,0) node(a) [ellipse,rotate=10,draw,fill] {An ellipse}
(3,-1) node(b) [circle,draw,fill] {A circle}
(2,2) node(c) [rectangle,rotate=20,draw,fill] {A rectangle}
(5,2) node(d) [rectangle,rotate=-30,draw,fill] {Another rectangle};
\draw[thick] (a.south) -- (b) -- (c) -- (d);
\draw[thick,red,->] (a) |- +(1,3) -| (c) |- (b);
\draw[thick,blue,<->] (b) .. controls +(right:2cm) and +(down:1cm) .. (d);
\end{tikzpicture}
Что здесь примечательного?
node и вначале подставляем координаты.\drawРаботает только с загруженной библиотекой CALC
Нарисует по касательной от точки (a):
\usetikzlibrary {calc}
\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
\coordinate (a) at (3,2);
\node [circle,draw] (c) at (1,1) [minimum size=40pt] {$c$};
\draw[red] (a) -- (tangent cs:node=c,point={(a)},solution=1) --
(c.center) -- (tangent cs:node=c,point={(a)},solution=2) -- cycle;
\end{tikzpicture}
Требует отдельного изучения, если вдруг понадобится
Или создать alias существующей системекоординат
\tikzaliascoordinatesystem{⟨new name⟩}{⟨old name⟩}
https://tikz.dev/tikz-coordinates#sec-13.2.5
Библиотека \usetikzlibrary{intersections}
/tikz/name path=⟨name⟩ — задать имя path для поиска пересечения
/tikz/name path global=⟨name⟩ — задает имя path глобально,будет доступно за пределами окружения SCOPE в рисунке
/tikz/name intersections={⟨options⟩} — поиск точек пересечения путей path
Если несколько точек пересечения им будут заданы координаты intersections-1 и intersections-2 и т.д. сколько получится.
\usetikzlibrary {intersections}
\begin{tikzpicture}[every node/.style={opacity=1, black, above left}]%стиль node подписи в лево вверх
\draw [help lines] grid (3,2);%нарисуем grid
\draw [name path=ellipse] (2,0.5) ellipse (0.75cm and 1cm);%нарисуем элипс и имя path=ellipse
\draw [name path=rectangle, rotate=10] (0.5,0.5) rectangle +(2,1);%нарисуем прямоугольник и имя path=rectangle
\fill [red, opacity=0.5, name intersections={of=ellipse and rectangle}]% найдем точки пересечения двух path
%name intersections --- это команда для поиска пересечений
%of= --- задает path для поиска пересечений
(intersection-1) circle (2pt) node {1}%нарисовать точку в пересечении 1
(intersection-2) circle (2pt) node {2};%нарисовать точку в пересечении 2
\end{tikzpicture}
name intersections={of=ellipse and rectangle} — задает имена path для поиска пересечений
выдаст имена точек пересечения, какие заданы в name
\fill [red, opacity=0.5, name intersections={of=ellipse and rectangle,name=insec}]
(insec-1) circle (2pt) node {1}
(insec-2) circle (2pt) node {2};
Создает список всех точек пересечения и сохраняет его в макросе tex по номерам 1,2,3 и т.д.
[name intersections={of=curve 1 and curve 2, name=i, total=\t}] — сохранит в макросе \t
присвоит каждой точке свое имя a и b
\fill [name intersections={of=curve 1 and curve 2, by={a,b}}]
(a) circle (2pt)
(b) circle (2pt);
Еще можно использовать нотацию ... подставит имена автоматически
[name intersections={
of=curve 1 and curve 2,
by={[label=center:a],[label=center:...],[label=center:i]}}]
Это мои любимые + и ++
Дают одинаковый вариант:
++ изменяет текущую координату и премещается относительно
+ не изменяет текущую координату и перемещается относительно
\begin{tikzpicture}
\draw (0,0) -- ++(1,0) -- ++(0,1) -- ++(-1,0) -- cycle;
\draw (2,0) -- ++(1,0) -- ++(0,1) -- ++(-1,0) -- cycle;
\draw (1.5,1.5) -- ++(1,0) -- ++(0,1) -- ++(-1,0) -- cycle;
\end{tikzpicture}
\begin{tikzpicture}
\draw (0,0) -- +(1,0) -- +(1,1) -- +(0,1) -- cycle;
\draw (2,0) -- +(1,0) -- +(1,1) -- +(0,1) -- cycle;
\draw (1.5,1.5) -- +(1,0) -- +(1,1) -- +(0,1) -- cycle;
\end{tikzpicture}
\tikz \draw (0,0) -- (1,1) -- ([turn]-45:1cm) -- ([turn]-30:1cm);
Поворачивает ось координат по касательной к последней точке.
\begin{tikzpicture} [delta angle=-180, radius=1cm]
\draw [help lines] (0,0) grid (10,5);
\draw (0,3) arc [start angle=-180] -- ([turn]60:1cm)
arc [start angle=-180] -- ([turn]60:1cm)
arc [start angle=180] -- ([turn]60:1cm);
\end{tikzpicture}
До меня дошло, когда нарисовал сетку координат
[delta angle=-180, radius=1cm] — параметры дуги: ее угол и радиус, минус говорит, что рисуем по часовой стрелке
[start angle=-180] — собственно стартовый угол дуги, относительно системы координат — здесь -180 и +180 роли не играет, но -90 и +90 развернут дугу в разные стороны.
– ([turn]60:1cm) — эта штука нарисует отрезок из последней точки но в системе координат именно последней точки. Т.е. 60 градусов она развернет относительно мысленного продолжения arc по касательной.
Укажет, что внутри фигурных скобок была относительная координата и после выхода из скобок, система координат будет как была до нее.
\begin{tikzpicture}
\draw (0,0) -- ++(1,0) -- ++(0,1) -- ++(-1,0);
\draw[red] (2,0) -- ++(1,0)
{ [current point is local] -- ++(0,1) } -- ++(-1,0);
\end{tikzpicture}
Вся мощь библиотеки CALC в расчете координат
($(a) + 1/3*(1cm,0)$) — вот так берем и изменяем координаты. Не забываем поставить эту конструкцию в $.
— синтаксис
\usetikzlibrary {calc}
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);
\fill [red] ($2*(1,1)$) circle (2pt);
\fill [green] (${1+1}*(1,.5)$) circle (2pt);
\fill [blue] ($cos(0)*sin(90)*(1,1)$) circle (2pt);
\fill [black] (${3*(4-3)}*(1,0.5)$) circle (2pt);
\end{tikzpicture}
Это возможные операции над координатами. Координаты всегда имеют структуру (x,y) и умножение будет происходить над x и y по отдельности.
(1,2)!.75!(3,4) — это значит, что координата будет на .75 между точками (1,2) и (3,4)
\usetikzlibrary {calc}
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);
\draw (1,0) -- (3,2);
\foreach \i in {0,0.2,0.5,0.9,1}
\node at ($(1,0)!\i!(3,2)$) {\i};
\end{tikzpicture}
\usetikzlibrary {calc}
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,3);
\coordinate (a) at (1,0);
\coordinate (b) at (3,2);
\draw[->] (a) -- (b);
\coordinate (c) at ($ (a)!1! 10:(b) $); % от точки (a) длина !1! --- такая же как (ab) и повернуть на 10 градусов.
\draw[->,red] (a) -- (c);
\fill ($ (a)!.5! 10:(b) $) circle (2pt); % а здесь точку нарисуем
\end{tikzpicture}
Змея для примера
\usetikzlibrary {calc}
\begin{tikzpicture}
\draw [help lines] (0,0) grid (4,4);
\foreach \i in {0,0.125,...,2}
\fill ($(2,2) !\i! \i*180:(3,2)$) circle (2pt);
\end{tikzpicture}
Модифаеры могут быть по нескольку штук дляг за другом
\usetikzlibrary {calc}
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);
\draw (0,0) -- (3,2);
\draw[red] ($(0,0)!.3!(3,2)$) -- (3,0);
\fill[red] ($(0,0)!.3!(3,2)!.7!(3,0)$) circle (2pt); %как здесь. Нашли точку на одной прямой и о нее ищем на другой.
\end{tikzpicture}
т.е. эта штука вычислит все в миллиметрах и расставит метки по прямой
\usetikzlibrary {calc}
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);
\draw (1,0) -- (3,2);
\foreach \i in {0cm,1cm,15mm}
\node at ($(1,0)!\i!(3,2)$) {\i};
\end{tikzpicture}
А эта будет ставить измерения
\usetikzlibrary {calc}
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);
\coordinate (a) at (1,0);
\coordinate (b) at (3,1);
\draw (a) -- (b);%нарисуем прямую ab
\coordinate (c) at ($ (a)!.25!(b) $);%найдем точку c
\coordinate (d) at ($ (c)!1cm!90:(b) $);%найдем точку d 90град от cb
\draw [<->] (c) -- (d) node [sloped,midway,above] {1cm};% начертим стрелочки и напишем 1 cm
\end{tikzpicture}
модификаторы проекции
Нарисуем треугольник и опустим перпендикуляры от вершин на противоположные стороны
между !()! укажем вершину в скобках
\usetikzlibrary {calc}
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);
\coordinate (a) at (0,1);
\coordinate (b) at (3,2);
\coordinate (c) at (2.5,0);
\draw (a) -- (b) -- (c) -- cycle;
\draw[red] (a) -- ($(b)!(a)!(c)$);%от a на сторону bc
\draw[orange] (b) -- ($(a)!(b)!(c)$);%от b на сторону ac
\draw[blue] (c) -- ($(a)!(c)!(b)$);%от c на сторону ab
\end{tikzpicture}
Основные команды это:
задают вертикальную и горизонтальные линии, но в основном используется синтаксис:
(⟨p⟩ |- ⟨q⟩) или (⟨q⟩ -| ⟨p⟩).
Для примера: (2,1 |- 3,4) и (3,4 -| 2,1) дадут точку (2,4)
\begin{tikzpicture}
\path (30:1cm) node(p1) {$p_1$} (75:1cm) node(p2) {$p_2$};
\draw (-0.2,0) -- (1.2,0) node(xline)[right] {$q_1$};
\draw (2,-0.2) -- (2,1.2) node(yline)[above] {$q_2$};
\draw[->] (p1) -- (p1 |- xline);
\draw[->] (p2) -- (p2 |- xline);
\draw[->] (p1) -- (p1 -| yline);
\draw[->] (p2) -- (p2 -| yline);
\end{tikzpicture}
или такой
\usetikzlibrary {calc}
\begin{tikzpicture}
\node (A) at (0,1) {A};
\node (B) at (1,1.5) {B};
\node (C) at (2,0) {C};
\node (D) at (2.5,-2) {D};
\draw (A) -- (B) node [midway] {x};
\draw (C) -- (D) node [midway] {x};
\node at ({$(A)!.5!(B)$} -| {$(C)!.5!(D)$}) {X};
\end{tikzpicture}
от одной средней точки возьмем координату X от другой Y и напишем метку X.
Возможности библиотеки TIKZ для рисования графиков в Latex. Обзор учебника из документации.
\usetikzlibrary {
positioning,% нативные позиции node
shapes.misc, % настройка внешнего вида фигур, углы и т.д.
graphs, % работает с диаграммами и графами
calc, % считает координаты
arrows.meta % рисует наконечники стрел
}
\usetikzlibrary {positioning}
\begin{tikzpicture}[
nonterminal/.style={
% The shape:
rectangle,
% The size:
minimum size=6mm,
% The border:
very thick,
draw=red!50!black!50, % 50% red and 50% black,
% and that mixed with 50% white
% The filling:
top color=white, % a shading that is white at the top...
bottom color=red!50!black!20, % and something else at the bottom
% Font
font=\itshape
}]
\node [nonterminal] {unsigned integer};
\end{tikzpicture}
В стиле определил:
Для рисования просто пишу NODE и все готово 
\usetikzlibrary {positioning}
\begin{tikzpicture}[node distance=5mm,
terminal/.style={
% The shape:
rectangle,minimum size=6mm,rounded corners=3mm,
% The rest
very thick,draw=black!50,
top color=white,bottom color=black!20,
font=\ttfamily}]
\node (dot) [terminal] {.};
\node (digit) [terminal,right=of dot] {digit};
\node (E) [terminal,right=of digit] {E};
\end{tikzpicture}
Как приятно писать что-то, когда ты понимаешь, что ты это понимаешь)))
В стиле определено:
node будет, то, которое задано.Односимвольный терминал станет кругом, а многосимвольный — прямоугольником с закругленными углами.
Только немного изменится настройка в описании стиля
[node distance=5mm,
terminal/.style={
% The shape:
rounded rectangle,
minimum size=6mm,
% The rest
very thick,draw=black!50,
top color=white,bottom color=black!20,
font=\ttfamily}]
убрали rounded corners а поставили rounded rectangle — собственно и все. Но разметка слегка отъехала. На рисунке можно увидеть небольшую разницу.
Просто добавляем в стиль высоту и глубину строки [text height=1.5ex,text depth=.25ex]
\usetikzlibrary {positioning,shapes.misc}
\begin{tikzpicture}[node distance=5mm and 5mm]
\node (ui1) [nonterminal] {unsigned integer};
\node (dot) [terminal,right=of ui1] {.};
\node (digit) [terminal,right=of dot] {digit};
\node (E) [terminal,right=of digit] {E};
\node (plus) [terminal,above right=of E] {+};
\node (minus) [terminal,below right=of E] {-};
\node (ui2) [nonterminal,below right=of plus] {unsigned integer};
\end{tikzpicture}
основные команды:
\tikzset {terminal/.style={
% The shape:
rectangle,minimum size=6mm,rounded corners=3mm,
% The rest
very thick,draw=black!50,
top color=white,bottom color=black!20,
font=\ttfamily}}
\tikzset {nonterminal/.style={
% The shape:
rectangle,
% The size:
minimum size=6mm,
% The border:
very thick,
draw=red!50!black!50, % 50% red and 50% black,
% and that mixed with 50% white
% The filling:
top color=white, % a shading that is white at the top...
bottom color=red!50!black!20, % and something else at the bottom
% Font
font=\itshape
}}
Теперь будет действовать глобально на всех.
\usetikzlibrary {calc,positioning,shapes.misc}
\begin{tikzpicture}[node distance=5mm and 5mm,
skip loop/.style={to path={-- ++(0,#1) -| (\tikztotarget)}}]
\node (dot) [terminal] {.};
\node (digit) [terminal,right=of dot] {digit};
\node (E) [terminal,right=of digit] {E};
\path (dot) edge[->] (digit) % simple edges
(digit) edge[->] (E)
($ (digit.east)!.5!(E.west) $)
edge[->,skip loop=-5mm] ($ (digit.west)!.5!(dot.east) $);
\end{tikzpicture}
($ (digit.east)!.5!(E.west) $)
edge[->,skip loop=-5mm] ($ (digit.west)!.5!(dot.east) $);
т.е. от середины между метками (digit.east)!.5!(E.west) до середины между метками (digit.west)!.5!(dot.east) рисуем кривулину типа skip loop
Пока все довольны.
Но разобрать по частям стиль skip loop очень хочется: skip loop/.style={to path={-- ++(0,#1) -| (\tikztotarget)}}
#1, а потом-| — рисует горизонтально, а потом вертикально к цели, это один из родственников -- — рисует прямую; |-— рисует вертикально и горизонтально и .. — рисует кривую(\tikztotarget) вообще таких макросов три (\tikztostart, \tikztotarget, and \tikztonodes;)\usetikzlibrary {shapes.misc}
\begin{tikzpicture}
\matrix[row sep=1mm,column sep=5mm] {
% First row:
& & & & \node [terminal] {+}; & \\
% Second row:
\node [nonterminal] {unsigned integer}; &
\node [terminal] {.}; &
\node [terminal] {digit}; &
\node [terminal] {E}; &
&
\node [nonterminal] {unsigned integer}; \\
% Third row:
& & & & \node [terminal] {-}; & \\
};
\end{tikzpicture}
Пока \matrix представляет собой что-то вроде таблицы, со своими дополнениями.
Дальше обычная tabular.
\usetikzlibrary {shapes.misc}
\begin{tikzpicture}[point/.style={circle,inner sep=0pt,minimum size=2pt,fill=red},
skip loop/.style={to path={-- ++(0,#1) -| (\tikztotarget)}}]
\matrix[row sep=1mm,column sep=2mm] {
% First row:
& & & & & & & & & & & \node (plus) [terminal] {+};\\
% Second row:
\node (p1) [point] {}; & \node (ui1) [nonterminal] {unsigned integer}; &
\node (p2) [point] {}; & \node (dot) [terminal] {.}; &
\node (p3) [point] {}; & \node (digit) [terminal] {digit}; &
\node (p4) [point] {}; & \node (p5) [point] {}; &
\node (p6) [point] {}; & \node (e) [terminal] {E}; &
\node (p7) [point] {}; & &
\node (p8) [point] {}; & \node (ui2) [nonterminal] {unsigned integer}; &
\node (p9) [point] {}; & \node (p10) [point] {};\\
% Third row:
& & & & & & & & & & & \node (minus)[terminal] {-};\\
};
\path (p4) edge [->,skip loop=-5mm] (p3)
(p2) edge [->,skip loop=5mm] (p6);
\end{tikzpicture}
[point/.style={circle,inner sep=0pt,minimum size=2pt,fill=red}] \node (p1) [point] {};edge — (p4) edge [->,skip loop=-5mm] (p3)Частично задача решена. Вторым этапом убираем видимость точек и результат готов.
Это еще одна мощная команда, которая должна со всем этим хозяйством управиться.
\begin{tikzpicture}[skip loop/.style={to path={-- ++(0,#1) -| (\tikztotarget)}},
point/.style={circle,inner sep=0pt,minimum size=2pt,fill=red},
hv path/.style={to path={-| (\tikztotarget)}},
vh path/.style={to path={|- (\tikztotarget)}}]
\matrix[row sep=1mm,column sep=2mm] {
% First row:
& & & & & & & & & & & \node (plus) [terminal] {+};\\
% Second row:
\node (p1) [point] {}; & \node (ui1) [nonterminal] {unsigned integer}; &
\node (p2) [point] {}; & \node (dot) [terminal] {.}; &
\node (p3) [point] {}; & \node (digit) [terminal] {digit}; &
\node (p4) [point] {}; & \node (p5) [point] {}; &
\node (p6) [point] {}; & \node (e) [terminal] {E}; &
\node (p7) [point] {}; & &
\node (p8) [point] {}; & \node (ui2) [nonterminal] {unsigned integer}; &
\node (p9) [point] {}; & \node (p10) [point] {};\\
% Third row:
& & & & & & & & & & & \node (minus)[terminal] {-};\\
};
\graph {
(p1) -> (ui1) -- (p2) -> (dot) -- (p3) -> (digit) -- (p4)
-- (p5) -- (p6) -> (e) -- (p7) -- (p8) -> (ui2) -- (p9) -> (p10);
(p4) ->[skip loop=-5mm] (p3);
(p2) ->[skip loop=5mm] (p5);
(p6) ->[skip loop=-11mm] (p9);
(p7) ->[vh path] (plus) -> [hv path] (p8);
(p7) ->[vh path] (minus) -> [hv path] (p8);
};
\end{tikzpicture}
Библиотека arrows.meta: и вариант работы p7 ->[vh path] { plus, minus } -> [hv path] p8; библиотеки graphs по раздвоению стрелок. Просто перечисляем узлы в фигурных скобках.
Итоговый вариант:
\begin{tikzpicture}[skip loop/.style={to path={-- ++(0,#1) -| (\tikztotarget)}},
point/.style={circle,inner sep=0pt,minimum size=2pt,fill=red},
>={Stealth[round]},thick,black!50,text=black,
every new ->/.style={shorten >=1pt},
graphs/every graph/.style={edges=rounded corners},
hv path/.style={to path={-| (\tikztotarget)}},
vh path/.style={to path={|- (\tikztotarget)}}]
\matrix[column sep=4mm] {
% First row:
& & & & & & & & & & & \node (plus) [terminal] {+};\\
% Second row:
\node (p1) [point] {}; & \node (ui1) [nonterminal] {unsigned integer}; &
\node (p2) [point] {}; & \node (dot) [terminal] {.}; &
\node (p3) [point] {}; & \node (digit) [terminal] {digit}; &
\node (p4) [point] {}; & \node (p5) [point] {}; &
\node (p6) [point] {}; & \node (e) [terminal] {E}; &
\node (p7) [point] {}; & &
\node (p8) [point] {}; & \node (ui2) [nonterminal] {unsigned integer}; &
\node (p9) [point] {}; & \node (p10) [point] {};\\
% Third row:
& & & & & & & & & & & \node (minus)[terminal] {-};\\
};
\graph [use existing nodes] {
p1 -> ui1 -- p2 -> dot -- p3 -> digit -- p4 -- p5 -- p6 -> e -- p7 -- p8 -> ui2 -- p9 -> p10;
p4 ->[skip loop=-5mm] p3;
p2 ->[skip loop=5mm] p5;
p6 ->[skip loop=-11mm] p9;
p7 ->[vh path] { plus, minus } -> [hv path] p8;
};
\end{tikzpicture}
\tikz \graph [grow right=2cm] { unsigned integer -> d -> digit -> E };
выдаст сразу: 
Добавим стилей:
\tikz \graph [grow right sep] {
unsigned integer[nonterminal] -> "."[terminal] -> digit[terminal] -> E[terminal]
};
Добавим + и -:
\usetikzlibrary {graphs,shapes.misc}
\tikz \graph [grow right sep] {
unsigned integer [nonterminal] ->
"." [terminal] ->
digit [terminal] ->
E [terminal] ->
{
"+" [terminal],
"" [coordinate],
"-" [terminal]
} ->
ui2/unsigned integer [nonterminal]
};
\usetikzlibrary {arrows.meta,graphs,shapes.misc}
\tikz [>={Stealth[round]}, black!50, text=black, thick,
every new ->/.style = {shorten >=1pt},
graphs/every graph/.style = {edges=rounded corners},
skip loop/.style = {to path={-- ++(0,#1) -| (\tikztotarget)}},
hv path/.style = {to path={-| (\tikztotarget)}},
vh path/.style = {to path={|- (\tikztotarget)}},
nonterminal/.style = {
rectangle, minimum size=6mm, very thick, draw=red!50!black!50, top color=white,
bottom color=red!50!black!20, font=\itshape, text height=1.5ex,text depth=.25ex},
terminal/.style = {
rounded rectangle, minimum size=6mm, very thick, draw=black!50, top color=white,
bottom color=black!20, font=\ttfamily, text height=1.5ex, text depth=.25ex},
shape = coordinate
]
\graph [grow right sep, branch down=7mm, simple] {
/ -> unsigned integer[nonterminal] -- p1 -> "." [terminal] -- p2 -> digit[terminal] --
p3 -- p4 -- p5 -> E[terminal] -- q1 ->[vh path]
{[nodes={yshift=7mm}]
"+"[terminal], q2, "-"[terminal]
} -> [hv path]
q3 -- /unsigned integer [nonterminal] -- p6 -> /;
p1 ->[skip loop=5mm] p4;
p3 ->[skip loop=-5mm] p2;
p5 ->[skip loop=-11mm] p6;
q1 -- q2 -- q3; % make these edges plain
};
Особенности кода:
{}/simpe — свойство graph — которое определяем, что между 2-мя узлами может быть только 1 edge.graphs/every graph/.style = {edges=rounded corners} — закругленные уголки у стрелок>={Stealth[round]}, black!50, text=black, thick, — стиль стрелок\documentclass{article} % say
% For LaTeX:
\usepackage{tikz}
\usetikzlibrary{calc,intersections,through,backgrounds}
\begin{tikzpicture}
\coordinate [label=left:\textcolor{blue}{$A$}] (A) at (0,0);
\coordinate [label=right:\textcolor{blue}{$B$}] (B) at (1.25,0.25);
\draw[blue] (A) -- (B);
\end{tikzpicture}
calc\begin{tikzpicture}
\coordinate [label=left:\textcolor{blue}{$A$}] (A) at ($ (0,0) + .1*(rand,rand) $);
\coordinate [label=right:\textcolor{red}{$B$}] (B) at ($ (1.25,0.25) + .1*(rand,rand) $);
\draw[blue] (A) -- (B);
\end{tikzpicture}
Все вычисления происходят между двух символов $.
Особенность оператора rand, что он каждый раз будет вычисляться одинаково. Т.е. не такой он уж и случайное число.
\usetikzlibrary {calc}
\begin{tikzpicture}
\coordinate [label=left:$A$] (A) at (0,0);
\coordinate [label=right:$B$] (B) at (1.25,0.25);
\draw (A) -- (B);
\draw (A) let
\p1 = ($ (B) - (A) $)
in
circle ({veclen(\x1,\y1)});
\end{tikzpicture}
\p1 = ($ (B) - (A) $) вычислит длину вектора и запишет в переменную 1p — это команда записать точку (коорд.x, коорд.y)veclen(\x1,\y1) — соответственно передать коордитаты x и y из переменной 1 и вычислить их длину для радиуса.n — похожа на p, но записывает число.т.е. let определил p1 и передал in в circle
\usetikzlibrary {calc}
\begin{tikzpicture}
\coordinate [label=left:$A$] (A) at (0,0);
\coordinate [label=right:$B$] (B) at (1.25,0.25);
\draw (A) -- (B);
\draw let \p1 = ($ (B) - (A) $),
\n2 = {veclen(\x1,\y1)}
in
(A) circle (\n2)
(B) circle (\n2);
\end{tikzpicture}
в этом примере, как раз вычисленный радиус, записали в переменную 2. Вместо цифры в этих переменных можно использовать длинные имена в скобках n{ragius} и также их использовать circle (\n{radius})
Создадим окружность через точку B относительно A, находящейся в центре координат. Т.е. точку A он всегда будет считать центром.
\usetikzlibrary {through}
\begin{tikzpicture}
\coordinate [label=left:$A$] (A) at (0,0);
\coordinate [label=right:$B$] (B) at (1.25,0.25);
\draw (A) -- (B);
\node [draw,circle through=(B),label=left:$D$] at (A) {};
\end{tikzpicture}
\usetikzlibrary {intersections,through}
\begin{tikzpicture}
\coordinate [label=left:$A$] (A) at (0,0);
\coordinate [label=right:$B$] (B) at (1.25,0.25);
\draw (A) -- (B);
\node (D) [name path=D,draw,circle through=(B),label=left:$D$] at (A) {}; %нода D и путь D это разные объекты, можно называть по разному
\node (E) [name path=E,draw,circle through=(A),label=right:$E$] at (B) {};
% Name the coordinates, but do not draw anything:
\path [name intersections={of=D and E}];
\coordinate [label=above:$C$] (C) at (intersection-1);
\draw [red] (A) -- (C);
\draw [red] (B) -- (C);
\end{tikzpicture}
\node (D) [name path=D,draw,circle through=(B),label=left:$D$] задаем имя \path где проходит окружность. \path [name intersections={of=D and E}]; — определяем пересечение двух путей D и E и у них образуются точки пересечения как (intersection-1) и (intersection-2).\coordinate [label=above:$C$] (C) at (intersection-1); — определим точку C с координатами пересечения.но есть еще у name intersections команда by, которая все это решит автоматически: \path [name intersections={of=D and E, by={[label=above:$C$]C, [label=below:$C'$]C'}}]; т.е. поставит точки и метки в них.
Потом просто проведем линию и дадим ей тоже имя \path — \draw [name path=C--C',red] (C) -- (C'); имя будет C--C'.
Новый intersection получит точку F
\path [name intersections={of=A--B and C--C',by=F}];
\begin{tikzpicture}
\coordinate [label=left:$A$] (A) at (0,0);
\coordinate [label=right:$B$] (B) at (1.25,0.25);
\draw [name path=A--B] (A) -- (B);
\node (D) [name path=D,draw,circle through=(B),label=left:$D$] at (A) {};
\node (E) [name path=E,draw,circle through=(A),label=right:$E$] at (B) {};
\path [name intersections={of=D and E, by={[label=above:$C$]C, [label=below:$C'$]C'}}];
\draw [name path=C--C',red] (C) -- (C');
\path [name intersections={of=A--B and C--C',by=F}];
\node [fill=red,inner sep=2pt,label=-45:$F$] at (F) {};
\end{tikzpicture}
это полная картина, где из нового inner sep=2pt — это толщина точки пересечения, а на самом деле просто размер node в виде точки
если бы я написал \node [fill=red,circle, inner sep=2pt,label=-45:$F$] at (F) {}; то получилось бы:
\begin{tikzpicture}[
thick,% толстые линии
help lines/.style={thin,draw=black!50}]%вспомогательные линии
\def\A{\textcolor{input}{$A$}} % макросы ABCDE со стилями меток
\def\B{\textcolor{input}{$B$}}
\def\C{\textcolor{output}{$C$}}
\def\D{$D$}
\def\E{$E$}
\colorlet{input}{blue!80!black} % input и output цвета, которые подставятся в макросы
\colorlet{output}{red!70!black}
\colorlet{triangle}{orange}
\draw [output] (A) -- (C) -- (B);
\foreach \point in {A,B,C}
\fill [black,opacity=.5] (\point) circle (2pt);
\begin{pgfonlayer}{background}
\fill[triangle!80] (A) -- (C) -- (B) -- cycle;
\end{pgfonlayer}
\usetikzlibrary {backgrounds,calc,intersections,through}
\begin{tikzpicture}[thick,help lines/.style={thin,draw=black!50}]
\def\A{\textcolor{input}{$A$}} \def\B{\textcolor{input}{$B$}}
\def\C{\textcolor{output}{$C$}} \def\D{$D$}
\def\E{$E$}
\colorlet{input}{blue!80!black} \colorlet{output}{red!70!black}
\colorlet{triangle}{orange}
\coordinate [label=left:\A] (A) at ($ (0,0) + .1*(rand,rand) $);
\coordinate [label=right:\B] (B) at ($ (1.25,0.25) + .1*(rand,rand) $);
\draw [input] (A) -- (B);
\node [name path=D,help lines,draw,label=left:\D] (D) at (A) [circle through=(B)] {};
\node [name path=E,help lines,draw,label=right:\E] (E) at (B) [circle through=(A)] {};
\path [name intersections={of=D and E,by={[label=above:\C]C}}];
\draw [output] (A) -- (C) -- (B);
\foreach \point in {A,B,C}
\fill [black,opacity=.5] (\point) circle (2pt);
\begin{pgfonlayer}{background}
\fill[triangle!80] (A) -- (C) -- (B) -- cycle;
\end{pgfonlayer}
\node [below right, text width=10cm,align=justify] at (4,3) {
\small\textbf{Proposition I}\par
\emph{To construct an \textcolor{triangle}{equilateral triangle}
on a given \textcolor{input}{finite straight line}.}
\par\vskip1em
Let \A\B\ be the given \textcolor{input}{finite straight line}. \dots
};
\end{tikzpicture}
\begin{tikzpicture}
\coordinate (NW) at (0,5); \coordinate (nw) at ($ (NW) + (1,-1) $);
\coordinate (NE) at (7,5); \coordinate (ne) at ($ (NE) + (-1,-1) $);
\coordinate (SE) at (7,0); \coordinate (se) at ($ (SE) + (-1,1) $);
\coordinate (SW) at (0,0); \coordinate (sw) at ($ (SW) + (1,1) $);
\draw[black!10] (NW) -- (NE) -- (SE) -- (SW) -- cycle;
\draw[black!30, thick, fill=black!25] ($ (NW) + (1,-1) $) -- (ne) -- (se) -- (sw) -- cycle;
\fill[black!25] (nw) -- (ne) -- (se) -- (sw) -- cycle;
\end{tikzpicture}
Немного неказист, но многообещающь.
Дальше он будет понемногу обрастать,пока не превратится в то,что я задумал.
Это будет ровно посередине между A и B.
\usetikzlibrary {calc}
\begin{tikzpicture}
\coordinate [label=left:$A$] (A) at (0,0);
\coordinate [label=right:$B$] (B) at (1.25,0.25);
\draw (A) -- (B);
\node [fill=red,inner sep=1pt,label=below:$X$] (X) at ($ (A)!.5!(B) $) {};
\end{tikzpicture}
Это для убедительности: 
Или за пределами точек и даже сложные вычисления:
\coordinate [label=above:$D$] (D) at ($ (A) ! .5 ! (B) ! {sin(60)*2} ! 90:(B) $) {};
И еще пример, чисто как памятка, потому-что очень сложные вычисления, мне точно не нужны.
\draw (D) -- ($ (D) ! 2.5 ! (A) $) coordinate [label=below:$E$] (E); — начертит прямую и установит новую точку E
NODE и настройки своих стилей.\documentclass{article} % say
\usepackage{tikz}
\usetikzlibrary{arrows.meta,decorations.pathmorphing,backgrounds,positioning,fit,petri}
\begin{document}
\begin{tikzpicture}
\draw (0,0) -- (1,1);
\end{tikzpicture}
\end{document}
NODE и настройки своих стилей.
node\begin{tikzpicture}
\path ( 0,2) node [shape=circle,draw] {}
( 0,1) node [shape=circle,draw] {}
( 0,0) node [shape=circle,draw] {}
( 1,1) node [shape=rectangle,draw] {}
(-1,1) node [shape=rectangle,draw] {};
\end{tikzpicture}
Но, выяснилось, что вариант выше не очень умен по своей сути. \path задает координату откуда начинается какое-то действие, в нашем случае размещаем node, а можно draw, но node с параметром draw обернет текст рамкой.
at т.е. поместить в…
\begin{tikzpicture}
\path node at ( 0,2) [shape=circle,draw] {}
node at ( 0,1) [shape=circle,draw] {}
node at ( 0,0) [shape=circle,draw] {}
node at ( 1,1) [shape=rectangle,draw] {}
node at (-1,1) [shape=rectangle,draw] {};
\end{tikzpicture}
Получаем тотже эффект, но говорят умнее.
Дальше больше:
\begin{tikzpicture}
\path node at ( 0,2) [circle,draw] {}
node at ( 0,1) [circle,draw] {}
node at ( 0,0) [circle,draw] {}
node at ( 1,1) [rectangle,draw] {}
node at (-1,1) [rectangle,draw] {};
\end{tikzpicture}
\begin{tikzpicture}[thick]
\path node at ( 0,2) [circle,draw=blue,fill=red] {}
node at ( 0,1) [circle,draw=blue,fill=yellow] {}
node at ( 0,0) [circle,draw=blue,fill=green] {}
node at ( 1,1) [rectangle,draw=black!50,fill=black!20] {}
node at (-1,1) [rectangle,draw=black!50,fill=black!20] {};
\end{tikzpicture}
Причем [draw=blue] — рисует такого цвета обводку, а fill — заполняет пространство
\begin{tikzpicture}
[place/.style={circle,draw=blue!50,fill=blue!20,thick},
transition/.style={rectangle,draw=black!50,fill=black!20,thick}]
\node at ( 0,2) [place] {};
\node at ( 0,1) [place] {};
\node at ( 0,0) [place] {};
\node at ( 1,1) [transition] {};
\node at (-1,1) [transition] {};
\end{tikzpicture}
просто один будет называться place а второй transition и теперь название этихстилей ставим в описании node.
Можно задать переменную inner sep=2mm в блоке — и это сделает отступ вокруг текста 2mm. Или:
[place/.style={circle,draw=blue!50,fill=blue!20,thick,
inner sep=0pt,minimum size=6mm},
т.е прямо в стиль и это даст эффект, что размер будет не меньше 4мм, пока в него влезает текст.
Очень пригодятся имена SHAPEs для того,чтобы иметь привязки и потом на них ссылаться.
\begin{tikzpicture}
\node (waiting 1) at ( 0,2) [place] {};
\node (critical 1) at ( 0,1) [place] {};
\node (semaphore) at ( 0,0) [place] {};
\node (leave critical) at ( 1,1) [transition] {};
\node (enter critical) at (-1,1) [transition] {};
\end{tikzpicture}
имена будут в круглых скобочках, причем порядок написания не имеет значения. Это все определения одного \path
Вместо указания координат, можно указывать влево, вправо, ниже, выше. Такого ума можно набраться в библиотеке: \usetikzlibrary {positioning}
\usetikzlibrary {positioning}
\begin{tikzpicture}
\node[place] (waiting) {};
\node[place] (critical) [below=of waiting] {}; % ниже waitinig
\node[place] (semaphore) [below=of critical] {}; % ниже critical
\node[transition] (leave critical) [right=of critical] {}; % справа от critical
\node[transition] (enter critical) [left=of critical] {}; % слева от critical
\end{tikzpicture}
Объекты размещаются по координатной сетке.
Все объекты TIKZ получают метки по сторонам света:
\node [red,above] at (semaphore.north) {$s\le 3$};
\end{tikzpicture}
напишет node красного цвета red над above северной меткой объекта semaphore.
но в библиотеке есть вариант с label, который сделает тоже самое.
\node[place] (semaphore) [below=of critical,
label=above:$s\le3$] {};
Памятка, как label работает:
\tikz
\node [circle,draw,label=60:$60^\circ$,label=below:$-90^\circ$] {my circle};
И немного подольем красочки: label={[red]below:$-90^\circ$} и будет метка красная, но чтобы небыло конфлика поставим все это дело в {}.
\draw [->] (enter critical.east) -- (critical.west);
\draw [->] (waiting.west) .. controls +(left:5mm) and +(up:5mm)
.. (enter critical.north);
т.е. \draw [в какую сторону стрелу] (координата откуда) -- (координата куда);
Это вставка вместо оператора рисования - -, которая позволяет поставить несколько контрольных точек относительно некоторого центра вращения и сказать куда они сдвигаются и насколько:
\draw[->](waiting.west) ..controls +(left:15mm) and +(up:15mm) .. (enter critical.north);
Можно не указывать стороны света в метках, от сделает это автоматически
\draw [->] (enter critical) -- (critical);
\draw [->] (waiting) .. controls +(left:5mm) and +(up:5mm)
.. (enter critical);
будет тоже самое.
Замечательный оператор to, который укажет под каким углом выйти и под каким углом войти стрелке.
Схема такая же, только вместо наших - - и .. controls .. появляется еще один оператор to [out=,in=]
in=220 — выглядит еще причудлевее.
\draw[->](waiting) to [out=0, in=180] (leave critical)
изгиб кривой.
\draw[->](leave critical) to [bend left=150] (semaphore)
но лучше загибать bend left=45, правда лучше.
край - ребро, как угодно, но эта штука действует как внутри \path так и самостоятельно. Т.е. можно задавать свои особые наконечники и цвета для edge.
\node[transition] (enter critical) [left=of critical] {}
edge [->] (critical)
edge [<-,bend left=45] (waiting)
edge [->,bend right=45] (semaphore);
буквально: там где нарисовал node от неё начинаю рисовать edges.
node точкой с запятой пишем edgenodeВот такой казус может получиться:
\begin{tikzpicture}
\node (c) at (0,0) {};
\node (n) at (0,1) {}
edge [bend right=45] (w);
\node (s) at (0,-1) {}
edge [bend right=45] (e);
\node (w) at (-1,0) {}
edge [bend right=45] (s);
\node (e) at (1,0) {}
edge [->,bend right=45] (n);
\end{tikzpicture}
Но если рисовать по задумке:
\begin{tikzpicture}
\node (c) at (0,0) {};
\node (n) at (0,1) {};
\node (w) at (-1,0) {}
edge [bend left=45] (n);
\node (s) at (0,-1) {}
edge [bend left=45] (w);
\node (e) at (1,0) {}
edge [bend left=45] (s)
edge [bend right=45] (n);
\end{tikzpicture}
то получим ->
[bend angle=45,
pre/.style={<-,shorten <=1pt,>={Stealth[round]},semithick},
post/.style={->,shorten >=1pt,>={Stealth[round]},semithick}]
вот такая штука позволит дальше в коде писать просто:
edge [pre] (critical) и edge [post,bend right] (waiting) и TIKZ все поймет.
\begin{tikzpicture}[auto,bend right]
\node (a) at (0:1) {$0^\circ$};
\node (b) at (120:1) {$120^\circ$};
\node (c) at (240:1) {$240^\circ$};
\draw (a) to node {1} node [swap] {1'} (b)
(b) to node {2} node [swap] {2'} (c)
(c) to node {3} node [swap] {3'} (a);
\end{tikzpicture}
at, т.е. поместить в … конкретную точкуto, т.е. от одной точки к другой, а на пути его рисования мы размещаем другие NODE и говорим с какой стороны их рисовать относительно линии.Собственно любую линию можно нарисовать, просто отдельно нужно изучить особенности этой библиотеки.
\usetikzlibrary {decorations.pathmorphing}
\begin{tikzpicture}
\draw [->,decorate,
decoration={snake,amplitude=.4mm,segment length=2mm,post length=1mm}]
(0,0) -- (3,0);
\end{tikzpicture}
получится вот такая кривулина: 
И продолжая тему кривулины или любой другой линии, если мне нужно разместить текст, то делаю в разрыве DRAW вставку NODE:
node [above,text width=3cm,align=center,midway]
{
replacement of the \textcolor{red}{capacity} by
\textcolor{red}{two places}
}
Нам поможет библиотека fit и background
fit — дает координаты всех узлов
background — размещает на разных слоях рисунки
Еще нам понадобятся знания об окружении SCOPE — это просто окружение чего-то, такие своеобразные скобки, в которых будут действовать правила, которые мы установим, а за пределами SCOPE все возвращается в исходные установки.
\begin{tikzpicture}[ultra thick]
\begin{scope}[red]
\draw (0mm,10mm) -- (10mm,10mm);
\draw (0mm,8mm) -- (10mm,8mm);
\end{scope}
\draw (0mm,6mm) -- (10mm,6mm);
\begin{scope}[green]
\draw (0mm,4mm) -- (10mm,4mm);
\draw (0mm,2mm) -- (10mm,2mm);
\draw[blue] (0mm,0mm) -- (10mm,0mm);
\end{scope}
\end{tikzpicture}
этот пример на линиях все показал
а про background мы просто добавим в конце такой код:
\begin{scope}[on background layer]
\node [fill=black!30,fit=(waiting) (critical) (semaphore)
(leave critical) (enter critical)] {};
\end{scope}
on background layer — на каком слое разместить, т.е. под рисунком\node — рисуем nodefill — заполняем ее цветомfit — перечисляем все внутренние node по которым определяем координаты\begin{tikzpicture}
[node distance=1.3cm,on grid,>={Stealth[round]},bend angle=45,auto,
every place/.style= {minimum size=6mm,thick,draw=blue!75,fill=blue!20},
every transition/.style={thick,draw=black!75,fill=black!20},
red place/.style= {place,draw=red!75,fill=red!20},
every label/.style= {red}]
т.е. там уже все определено, поэтому нарисуем все, что уже пытались с использованием библиотеки:
\usetikzlibrary {arrows.meta,petri,positioning}
\node [place,tokens=1] (w1) {};
\node [place] (c1) [below=of w1] {};
\node [place] (s) [below=of c1,label=above:$s\le 3$] {};
\node [place] (c2) [below=of s] {};
\node [place,tokens=1] (w2) [below=of c2] {};
\node [transition] (e1) [left=of c1] {}
edge [pre,bend left] (w1)
edge [post,bend right] (s)
edge [post] (c1);
\node [transition] (e2) [left=of c2] {}
edge [pre,bend right] (w2)
edge [post,bend left] (s)
edge [post] (c2);
\node [transition] (l1) [right=of c1] {}
edge [pre] (c1)
edge [pre,bend left] (s)
edge [post,bend right] node[swap] {2} (w1);
\node [transition] (l2) [right=of c2] {}
edge [pre] (c2)
edge [pre,bend right] (s)
edge [post,bend left] node {2} (w2);
а это ее более кудрявый друг:
\usetikzlibrary {arrows.meta,petri,positioning}
\begin{scope}[xshift=6cm]
\node [place,tokens=1] (w1') {};
\node [place] (c1') [below=of w1'] {};
\node [red place] (s1') [below=of c1',xshift=-5mm]
[label=left:$s$] {};
\node [red place,tokens=3] (s2') [below=of c1',xshift=5mm]
[label=right:$\bar s$] {};
\node [place] (c2') [below=of s1',xshift=5mm] {};
\node [place,tokens=1] (w2') [below=of c2'] {};
\node [transition] (e1') [left=of c1'] {}
edge [pre,bend left] (w1')
edge [post] (s1')
edge [pre] (s2')
edge [post] (c1');
\node [transition] (e2') [left=of c2'] {}
edge [pre,bend right] (w2')
edge [post] (s1')
edge [pre] (s2')
edge [post] (c2');
\node [transition] (l1') [right=of c1'] {}
edge [pre] (c1')
edge [pre] (s1')
edge [post] (s2')
edge [post,bend right] node[swap] {2} (w1');
\node [transition] (l2') [right=of c2'] {}
edge [pre] (c2')
edge [pre] (s1')
edge [post] (s2')
edge [post,bend left] node {2} (w2');
\end{scope}
и на финише фон:
\begin{scope}[on background layer]
\node (r1) [fill=black!10,rounded corners,fit=(w1)(w2)(e1)(e2)(l1)(l2)] {};
\node (r2) [fill=black!10,rounded corners,fit=(w1')(w2')(e1')(e2')(l1')(l2')] {};
\end{scope}
\draw [shorten >=1mm,->,thick,decorate,
decoration={snake,amplitude=.4mm,segment length=2mm,
pre=moveto,pre length=1mm,post length=2mm}]
(r1) -- (r2) node [above=1mm,midway,text width=3cm,align=center]
{replacement of the \textcolor{red}{capacity} by \textcolor{red}{two places}};
\end{tikzpicture}
получим такую красоту:
Дружелюбный функционал для полной графики в Latex. Картинки, иконки, графики и пр. Очень мощный пакет в котором можно нарисовать все.
\usepackage{tikz}
Окружение {tikzpicture} или команды \tikzpicture и \endtikzpicture
\documentclass{article} % say
\usepackage{tikz}
\begin{document}
We are working on
\begin{tikzpicture}
\draw (-1.5,0) -- (1.5,0);
\draw (0,-1.5) -- (0,1.5);
\end{tikzpicture}.
\end{document}
\begin{tikzpicture}
\filldraw [gray] (0,0) circle [radius=2pt]
(1,1) circle [radius=2pt]
(2,1) circle [radius=2pt]
(2,0) circle [radius=2pt];
\draw (0,0) .. controls (1,1) and (2,1) .. (2,0);
\end{tikzpicture}
filldraw [gray] — зальет фигуру серым цветом
.. controls — укажет контрольные точки для кривой Безье.
circle [radius=10pt] — нарисует окружность
\tikz \draw (0,0) ellipse [x radius=20pt, y radius=10pt];
\draw[rotate=30] — развернет рисунок на 30гр.
\draw (0,0) rectangle (0.5,0.5);
\draw (-0.5,-0.5) rectangle (-1,-1);
\tikz \draw[step=2pt] (0,0) grid (10pt,10pt);
нарисует сетку козявочку 
\begin{tikzpicture}
\draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
\draw (-1.5,0) -- (1.5,0);
\draw (0,-1.5) -- (0,1.5);
\draw (0,0) circle [radius=1cm];
\end{tikzpicture}
в draw — определим шаг, цвет и толщину линий
Глобально в переменной Ra grid
\tikzset{Ra grid/.style={help lines,color=blue!50}}
или локально в переменной Karl's grid
\begin{tikzpicture}
[Karl's grid/.style ={help lines,color=#1!50},
Karl's grid/.default=blue]
\draw[Karl's grid] (0,0) grid (1.5,2);
\draw[Karl's grid=red] (2,0) grid (3.5,2);
\end{tikzpicture}
\draw[ultra thin] (-1.5,1.1) -- (1.5,1.1);
\draw[very thin] (-1.5,1.6) -- (1.5,1.6);
\draw[thin] (-1.5,2.1) -- (1.5,2.1);
\draw[semithick] (-1.5,2.6) -- (1.5,2.6);
\draw[very thick] (-1.5,3.1) -- (1.5,3.1);
\draw[ultra thick] (-1.5,3.6) -- (1.5,3.6);
\begin{tikzpicture}[line width=5pt] — любая толщина
\draw[loosely dashed, ultra thick] (-1.5,-3.6) -- (1.5,-3.6);
\draw[densely dashed, ultra thick] (-1.5,-3.1) -- (1.5,-3.1);
\draw[loosely dotted, ultra thick] (-1.5,-2.6) -- (1.5,-2.6);
\draw[densely dotted, ultra thick] (-1.5,-2.1) -- (1.5,-2.1);
dash pattern — можно определить сложный паттерн
arc[start angle=10, end angle=80, radius=10pt]
Элипсоидная дуга
\tikz \draw (0,0)
arc [start angle=0, end angle=315,
x radius=1.75cm, y radius=1cm];
\begin{tikzpicture}[scale=3]
\draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
\draw (-1.5,0) -- (1.5,0);
\draw (0,-1.5) -- (0,1.5);
\draw (0,0) circle [radius=1cm];
\draw (3mm,0mm) arc [start angle=0, end angle=30, radius=3mm];
\end{tikzpicture}
после определения окружения, ставим [scale=3]
или обрезание рисунка
\clip (-0.1,-0.2) rectangle (1.1,0.75);
две точки на рисунке для обрезки прямоугольником, обрезать можно любой фигурой
\begin{tikzpicture}[scale=3]
\clip (-0.1,-0.2) rectangle (1.1,0.75);
\draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
\draw (-1.5,0) -- (1.5,0);
\draw (0,-1.5) -- (0,1.5);
\draw (0,0) circle [radius=1cm];
\draw (3mm,0mm) arc [start angle=0, end angle=30, radius=3mm];
\end{tikzpicture}
\path[draw, clip] или \path[clip] или \path[draw] — братья по смыслу и к ним же \draw[clip]
% чертит параболу в квадрате
\tikz \draw (0,0) rectangle (1,1) (0,0) parabola (1,1);
% чертит параболу и изгиб, по дороге поменяем размерность координат x и y
\tikz \draw[x=1pt,y=1pt] (0,0) parabola bend (4,16) (6,12);
A sine \tikz \draw[x=1ex,y=1ex] (0,0) sin (1.57,1); curve.
Нарисует прямо в тексте кривулину. A sine (-tikz- diagram) curve.
А вот эта штука покажет, что такое sin и cos на самом деле:
\tikz \draw[x=3.57ex,y=1ex] (0,0) sin (4,1) cos (6,-14) sin (8,12)
да,именно так — sin поднимаемся, cos — опускаемся
\fill[green!20!white] (0,0) -- (3mm,0mm)
arc [start angle=0, end angle=30, radius=3mm] -- (0,0);
% или сразу рисуем и красим
\filldraw[fill=green!20!white, draw=green!50!black] (0,0) -- (3mm,0mm)
arc [start angle=0, end angle=30, radius=3mm] -- cycle;
\begin{tikzpicture}[line width=5pt]
\draw (0,0) -- (1,0) -- (1,1) -- (0,0);
\draw (2,0) -- (3,0) -- (3,1) -- cycle;
\useasboundingbox (0,1.5); % make bounding box higher
\end{tikzpicture}
cycle — плавно замкнет контур, похожа на последнюю команду -- (0,0) но работает лучше
Команды shade и shadedraw
\begin{tikzpicture}[rounded corners,ultra thick]
\shade[top color=yellow,bottom color=black] (0,0) rectangle +(2,1);
\shade[left color=yellow,right color=black] (3,0) rectangle +(2,1);
\shadedraw[inner color=yellow,outer color=black,draw=yellow] (6,0) rectangle +(2,1);
\shade[ball color=green] (9,.5) circle (.5cm);
\end{tikzpicture}
(x,y) — с указанием размерности или по умолчанию в см.
(30:1cm) — полярные координаты 30 градусов и 1 см.
+(x,y) — переместиться относительно последней точки на x и y
++(x,y) — переместить указатель, но ничего не чертить, чертит только команда --.
\begin{tikzpicture}[scale=3]
\clip (-0.1,-0.2) rectangle (1.1,0.75);
\draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
\draw (-1.5,0) -- (1.5,0);
\draw (0,-1.5) -- (0,1.5);
\draw (0,0) circle [radius=1cm];
\filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm)
arc [start angle=0, end angle=30, radius=3mm] -- cycle;
\draw[red,very thick] (30:1cm) -- +(0,-0.5);
\draw[blue,very thick] (30:1cm) ++(0,-0.5) -- (0,0);
\end{tikzpicture}
\begin{tikzpicture}
\def\rectanglepath{-- ++(1cm,0cm) -- ++(0cm,1cm) -- ++(-1cm,0cm) -- cycle}
\draw (0,0) \rectanglepath;
\draw (1.5,0) \rectanglepath;
\end{tikzpicture}
нарисует два квадратика
или идентично:
\tikz \draw (0,0) rectangle +(1,1) (1.5,0) rectangle +(1,1);
1,{tan(30)}) — так тоже умеет. Любую функцию для расчета координат.
\path [name path=upward line] (1,0) -- (1,1);
\path [name path=sloped line] (0,0) -- (30:1.5cm);
% Рисуем невидимые пути. \path без атрибутов, просто перемещает указатель
% (добавить библиотеку `\usetikzlibrary{intersections}' после загрузки tikz)
\draw [name intersections={of=upward line and sloped line, by=x}] % нашли точку пересечения и назвали ее x
[very thick,orange] (1,0) -- (x); % нарисовали линию от (1,0) до точки пересечения
\draw[->] (-1.5,0) -- (1.5,0);
\draw[->] (0,-1.5) -- (0,1.5);
->, <-, <->, <<-, ->>
или использовать специальную библиотеку Documentation arrow
\usetikzlibrary {arrows.meta}
\begin{tikzpicture}[>=Stealth]
\begin{tikzpicture}[ultra thick]
\draw (0,0) -- (0,1);
\begin{scope}[thin]
\draw (1,0) -- (1,1);
\draw (2,0) -- (2,1);
\end{scope}
\draw (3,0) -- (3,1);
\end{tikzpicture}
Окружение {scope}
xshift=2pt — смещает все точки на 2pt по x
\begin{tikzpicture}[even odd rule,rounded corners=2pt,x=10pt,y=10pt]
\filldraw[fill=yellow!80!black] (0,0) rectangle (1,1)
[xshift=5pt,yshift=5pt] (0,0) rectangle (1,1)
[rotate=30] (-1,-1) rectangle (2,2);
\end{tikzpicture}
Самое интересное во всем этом процессе, что когда ты пишешь эти строки и видишь, как все это происходит по настоящему в твоем Latex документе — приходишь в восторг!
xshift и yshift смещают по осям, shift={(1,0)} смещает в точку shift={+(0,0)} или относительную точку.
rotate или rotate around вращают объект относительно точки
scale, xscale, yscale — масштабирует xscale=-1 схлопывает фигуру
xslant, yslant — наклоняет
cm — опция для произвольных преобразований по матрице
Можно использовать независимый пакет для \foreach или он автоматически подключен в Tikz
Синтаксис команды:
\foreach ⟨variable⟩ in {⟨list of values⟩} ⟨commands⟩
Пример:
\foreach \x in {1,2,3} {$x =\x$, }
x=1, x=2, x=3,
\begin{tikzpicture}[scale=3]
\clip (-0.1,-0.2) rectangle (1.1,1.51);
\draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
\filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm)
arc [start angle=0, end angle=30, radius=3mm] -- cycle;
\draw[->] (-1.5,0) -- (1.5,0);
\draw[->] (0,-1.5) -- (0,1.5);
\draw (0,0) circle [radius=1cm];
\foreach \x in {-1cm,-0.5cm,0.5cm,1cm}
\draw [red](\x,-1pt) -- (\x,1pt);
\foreach \y in {-1cm,-0.5cm,0.5cm,1cm}
\draw [blue](-1pt,\y) -- (1pt,\y);
\end{tikzpicture}
Поставил меточки на осях координат
\tikz \foreach \x in {1,...,10}
\draw (\x,0) circle (0.4cm);
еще вариант для диапазона значений: цикл в цикле
\begin{tikzpicture}
\foreach \x in {1,2,...,5,7,8,...,12}
\foreach \y in {1,...,5}
{
\draw (\x,\y) +(-.5,-.5) rectangle ++(.5,.5);
\draw (\x,\y) node{\x,\y};
}
\end{tikzpicture}
\begin{tikzpicture}
\draw (0,0) rectangle (2,2);
\draw (0.5,0.5) node [fill=yellow!80!black]
{Text at \texttt{node 1}}
-- (1.5,1.5) node {Text at \texttt{node 2}};
\end{tikzpicture}
любой текст или все что нам нужно можно вставить в Node и поместить в нужную точку координат рисунка
Фон можно закрасить [fill=white]
На всех рисунках есть якоря со сторонами света:
и их комбинации anchor=south west и т.д.
above rigth тоже, что south west
below=1pt — можно задавать смещение
\usetikzlibrary {intersections}
\begin{tikzpicture}[scale=3]
\clip (-2,-0.2) rectangle (2,0.8);
\draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
\filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm)
arc [start angle=0, end angle=30, radius=3mm] -- cycle;
\draw[->] (-1.5,0) -- (1.5,0) coordinate (x axis);
\draw[->] (0,-1.5) -- (0,1.5) coordinate (y axis);
\draw (0,0) circle [radius=1cm];
\draw[very thick,red]
(30:1cm) -- node[left=1pt,fill=white] {$\sin \alpha$} (30:1cm |- x axis);
\draw[very thick,blue]
(30:1cm |- x axis) -- node[below=2pt,fill=white] {$\cos \alpha$} (0,0);
\path [name path=upward line] (1,0) -- (1,1);
\path [name path=sloped line] (0,0) -- (30:1.5cm);
\draw [name intersections={of=upward line and sloped line, by=t}]
[very thick,orange] (1,0) -- node [right=1pt,fill=white]
{$\displaystyle \tan \alpha \color{black}=
\frac{{\color{red}\sin \alpha}}{\color{blue}\cos \alpha}$} (t);
\draw (0,0) -- (t);
\foreach \x/\xtext in {-1, -0.5/-\frac{1}{2}, 1}
\draw (\x cm,1pt) -- (\x cm,-1pt) node[anchor=north,fill=red!20] {$\xtext$};
\foreach \y/\ytext in {-1, -0.5/-\frac{1}{2}, 0.5/\frac{1}{2}, 1}
\draw (1pt,\y cm) -- (-1pt,\y cm) node[anchor=east,fill=red!20] {$\ytext$};
\end{tikzpicture}
\begin{tikzpicture}
\draw (0,0) .. controls (6,1) and (9,1) ..
node[near start,sloped,above] {near start}
node {midway}
node[very near end,sloped,below] {very near end} (12,0);
\end{tikzpicture}
\begin{tikzpicture}
[scale=3,line cap=round,
% Styles
axes/.style=,
important line/.style={very thick},
information text/.style={rounded corners,fill=red!10,inner sep=1ex}]
% Colors
\colorlet{anglecolor}{green!50!black}
\colorlet{sincolor}{red}
\colorlet{tancolor}{orange!80!black}
\colorlet{coscolor}{blue}
% The graphic
\draw[help lines,step=0.5cm] (-1.4,-1.4) grid (1.4,1.4);
\draw (0,0) circle [radius=1cm];
\begin{scope}[axes]
\draw[->] (-1.5,0) -- (1.5,0) node[right] {$x$} coordinate(x axis);
\draw[->] (0,-1.5) -- (0,1.5) node[above] {$y$} coordinate(y axis);
\foreach \x/\xtext in {-1, -.5/-\frac{1}{2}, 1}
\draw[xshift=\x cm] (0pt,1pt) -- (0pt,-1pt) node[below,fill=white] {$\xtext$};
\foreach \y/\ytext in {-1, -.5/-\frac{1}{2}, .5/\frac{1}{2}, 1}
\draw[yshift=\y cm] (1pt,0pt) -- (-1pt,0pt) node[left,fill=white] {$\ytext$};
\end{scope}
\filldraw[fill=green!20,draw=anglecolor] (0,0) -- (3mm,0pt)
arc [start angle=0, end angle=30, radius=3mm];
\draw (15:2mm) node[anglecolor] {$\alpha$};
\draw[important line,sincolor]
(30:1cm) -- node[left=1pt,fill=white] {$\sin \alpha$} (30:1cm |- x axis);
\draw[important line,coscolor]
(30:1cm |- x axis) -- node[below=2pt,fill=white] {$\cos \alpha$} (0,0);
\path [name path=upward line] (1,0) -- (1,1);
\path [name path=sloped line] (0,0) -- (30:1.5cm);
\draw [name intersections={of=upward line and sloped line, by=t}]
[very thick,orange] (1,0) -- node [right=1pt,fill=white]
{$\displaystyle \tan \alpha \color{black}=
\frac{{\color{red}\sin \alpha}}{\color{blue}\cos \alpha}$} (t);
\draw (0,0) -- (t);
\draw[xshift=1.85cm]
node[right,text width=6cm,information text]
{
The {\color{anglecolor} angle $\alpha$} is $30^\circ$ in the
example ($\pi/6$ in radians). The {\color{sincolor}sine of
$\alpha$}, which is the height of the red line, is
\[
{\color{sincolor} \sin \alpha} = 1/2.
\]
By the Theorem of Pythagoras ...
};
\end{tikzpicture}
Для node задали ширину текста text width=6cm
\usetikzlibrary {angles,quotes}
\begin{tikzpicture}[scale=3]
\coordinate (A) at (1,0);
\coordinate (B) at (0,0);
\coordinate (C) at (30:1cm);
\draw (A) -- (B) -- (C)
pic [draw=green!50!black, fill=green!20, angle radius=9mm,
"$\alpha$"] {angle = A--B--C};
\end{tikzpicture}
Команда pic создает макрос для последующего использования кода.
xcolor и colortbl - управление цветами в LaTeX\usepackage{xcolor} % Основной пакет для работы с цветами
\usepackage[table]{xcolor} % Альтернативный вариант с загрузкой colortbl
% или
\usepackage{colortbl} % Пакет для цветных таблиц
Пакет поддерживает несколько цветовых моделей:
| Модель | Компоненты | Диапазон значений |
|---|---|---|
rgb |
red, green, blue | [0, 1] для каждого |
cmyk |
cyan, magenta, yellow, black | [0, 1] для каждого |
gray |
оттенки серого | [0, 1] |
HTML |
RRGGBB | 000000 до FFFFFF |
RGB |
Red, Green, Blue | 0-255 для каждого |
red, green, blue, cyan, magenta, yellow, black, white, gray, darkgray, lightgray
brown, lime, olive, orange, pink, purple, teal, violet
\usepackage[dvipsnames]{xcolor} % 68 CMYK цветов
\usepackage[svgnames]{xcolor} % 151 RGB цвет
\usepackage[x11names]{xcolor} % 317 RGB цветов
\definecolor{myred}{rgb}{1,0,0} % Чистый красный
\definecolor{mygray}{gray}{0.5} % Серый 50%
\definecolor{myblue}{HTML}{1F77B4} % Синий в HEX
\colorlet{lightblue}{blue!20} % Светло-синий (20% от blue)
\colorlet{darkred}{red!80!black} % Темно-красный
\textcolor{red}{Красный текст} % Цвет текста
\colorbox{yellow}{Желтый фон} % Фон текста
\fcolorbox{blue}{white}{Рамка} % Рамка и фон
\begin{tabular}{|>{\columncolor{yellow!20}}c|c|}
\hline
\rowcolor{blue!10}
Заголовок 1 & Заголовок 2 \\
\hline
Ячейка 1 & \cellcolor{green!20}Ячейка 2 \\
\hline
\end{tabular}
\color{red!50!blue} % Фиолетовый (50% красного + 50% синего)
\color{green!40!white!60} % Светло-зеленый
\textcolor{red!50}{Полупрозрачный текст}
\fcolorbox{black}{yellow!30}{
\textcolor{blue!80!black}{
Важное сообщение!
}
}
\colorlet{startcolor}{red!20}
\colorlet{endcolor}{red!60}
\colorlet{middlecolor}{red!40}
\begin{tabular}{|p{3cm}|}
\arrayrulecolor{white}
\hline
\rowcolor{startcolor} Строка 1 \\
\rowcolor{middlecolor} Строка 2 \\
\rowcolor{endcolor} Строка 3 \\
\hline
\end{tabular}
\[
\textcolor{blue}{E} = \textcolor{red}{m}\textcolor{green}{c^2}
\]
\[
\colorbox{yellow!20}{
\color{blue}
\int_a^b f(x)dx
}
\]
\rowcolors из xcolor\rowcolors{1}{blue!10}{white} % Чередование цветов строк
\begin{tabular}{cc}
A & B \\
C & D \\
E & F \\
\end{tabular}
Этот пакет предоставляет полный контроль над цветами в вашем LaTeX документе, от простого окрашивания текста до сложного оформления таблиц и математических формул.
https://ctan.org/pkg/longtable
https://mirror.macomnet.net/pub/CTAN/macros/latex/required/tools/longtable.pdf
\usepackage{longtable} %собственно сам пакет для работы с таблицами
\usepackage{xcolor} %чтобы работать с цветами
\usepackage{colortbl} %чтобы работать с цветными таблицами
Полная приемственность от tabular и tabularx, поэтому можно только им и пользоваться.
Очень понадобятся первоначальные настройки для формата таблицы
\newcolumntype{C}[1]{>{\columncolor{white}\ttfamily\centering\arraybackslash}p{#1cm}}
\newcolumntype{R}[1]{>{\columncolor{white}\ttfamily\raggedleft\arraybackslash}p{#1cm}}
\newcolumntype{L}[1]{>{\columncolor{white}\ttfamily\raggedright\arraybackslash}p{#1cm}}
\newcolumntype{B}[1]{>{\columncolor{white}\ttfamily\bfseries\raggedright\arraybackslash}p{#1cm}}
\renewcommand{\tabcolsep}{0.05cm}
\renewcommand{\arraystretch}{1.7}
\newcolumntype похожа на \newcommand но только для настройки таблиц. Работает со всеми пакетами расширяющие стандартый пакет таблиц: xtab, xtabular, tabularx и longtable.
https://ctan.org/pkg/tabularx https://mirror.truenetwork.ru/CTAN/macros/latex/required/tools/tabularx.pdf
оттуда и возьмем описание команд:
\raggedright, \raggedleft, \centering — после этих команд изменяется поведение команды \\ и \\*, вот, чтобы этого не произошло и применяем команду \arraybackslash.
>{\raggedright\arraybackslash}X
определяет новые параметры колонки и назначает их переменной Y или какую напишем, но только из одной буквы. Мне алфавита хватало всегда.
\newcolumntype{Y}{>{\small\raggedright\arraybackslash}X}
после знака {> пишем любые команды для определения шрифта, цвета, выравнивания и т.д. Обычно это удобно связывать с шириной колонки и передавать значение через переменную в p{#1}.
Количество переменных может быть любое, главное в них самому не запутаться.
После определения новых типов колонок их можно использовать в заголовке описания таблицы наравне с lcrpm
Изменяет тип колонки X
\newcommand{\tabularxcolumn}[1]{p{#1}} — соответствует \parbox[t] — и определено по умолчанию
\renewcommand{\tabularxcolumn}[1]{>{\small}m{#1}} — соответствует \parbox[m] — контент выравнивается по центру и типа так я могу переопределить, но у меня ничего не получилось, зато мои настройки \newcolumn работают шикарно.
Умный Latex по умолчанию всегда пытается создать одинаковые колонки с размером \hsize, но мы можем переопределить пропорционально ширину каждой колонки. Первая будет половина от стандартной ширины, а вторая в 3 раза больше.
{>{\hsize=.5\hsize\linewidth=\hsize}X >{\hsize=1.5\hsize\linewidth=\hsize}X}
Дальше tabularx упрощает работы со сносками. Но я на этом пакете заканчиваю и перехожу к longtable.
yasnippet# -*- mode: snippet -*-
# name: longtable
# key: longtable
# --
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%LONGTABLE
\begin{center}
\rowcolors{2}{gray!10}{white} \\arrayrulecolor{gray!20} %раскрасим в два цвета строки
\begin{longtable}{c|c} %описание таблицы
%%%%%%%%%%%%%%% заголовок на первой странице
\caption[Название таблицы короткое]{Название таблицы длинное\label{tab:}}\\\
\rowcolor{blue!40} %раскрасим заголовок таблицы
\multicolumn{1}{c}{Наименование} % название первой колонки
& \multicolumn{1}{c}{Описание} % название второй колонки
% при большем количестве колонок последнюю строчку повторить столько же раз
% готовый раздел скопировать в раздел Заголовок на второй странице
\endfirsthead % конец заголовка
%%%%%%%%%%%%%%%%% конец заголовка на первой странице
%%%%%%%%%%%%%%% Заголовок на второй странице
\caption{продолжение таблицы на следующей странице}\\\
\rowcolor{blue!40}
\multicolumn{1}{c}{Наименование}
& \multicolumn{1}{c}{Описание}
\endhead %конец заголовка
%%%%%%%%%%%%%%%%% конец заголовка на второй странице
%%%%%%%%%%%%%%%%%%%%% BODY TABLE
Первый & Второй\\\\
Третий & Четвертый\\\\
%%%%%%%%%%%%%%%%%%%%%
\end{longtable}
\end{center}
\renewcommand{\tabcolsep}{0.05cm}
\renewcommand{\arraystretch}{1.7}
[!INFO] Собственно мне всего перечисленного хватало практически на 90% всех таблиц.
По умолчанию длина таблицы 20 строк, но можно изменить с помощью команты
\setcounter{LTchunksize}{10}
и будет 10!
\renewcommand\LTcaptype{⟨counter ⟩}
\endfirsthead\endhead.\endfoot также заканчивает описание последней строки таблицы на странице\endlastfoot описывает последнюю строку таблицы\caption{...} команда эквивалентна \multicolumn{n}{c}{\parbox{\LTcapwidth}{…}}
она просто объединяет все колонки и пишется как полноценная строка таблицы.
\caption[Опциональное имя, используется в списке таблиц]{Полноценное имя таблицы\label{long}}.
объединяет колонки \multicolumn{numcols}{cols}{text}
lcrmp\multirow для объединения строк. Но для нее нужно подключить пакет \usepackage{multirow}делаем строку для определения ширины столбцов и вместо \\ ставим \kill. Строка не будет отображаться в таблице, но ширину настроит.
LTleft и LTright
\setlength\LTleft\parindent
\setlength\LTright\fill
устанавливаем отступ для всей таблицы слева и справа, но один параметр нужно сотавлять тягучим \fill
\setlength\LTleft{0pt}
\setlength\LTright{0pt}
\begin{longtable}{@{\extracolsep{...}}...}
\extracolsep — делает резиновым столбец.
Параметры
| \LTleft | Glue to the left of the table. | (\fill) |
|---|---|---|
| \LTright | Glue to the right of the table. | (\fill) |
| \LTpre | Glue before the table. | (\bigskipamount) |
| \LTpost | Glue after the table. | (\bigskipamount) |
| \LTcapwidth | The width of a parbox containing the caption. | (4in) |
| \LTchunksize | The number of rows per chunk. | (20) |
Optional arguments to \begin{longtable}
| none | Position as specified by \LTleft and \LTright. |
|---|---|
| [c] | Centre the table. |
| [l] | Place the table flush left. |
| [r] | Place the table flush right. |
Commands to end table rows
| \ | Specifies the end of a row |
|---|---|
| \\[⟨dim⟩] | Ends row, then adds vertical space (as in the tabular environment). |
| \\* | The same as \ but disallows a page break after the row. |
| \tabularnewline | Alternative to \\ for use in the scope of \raggedright and similar commands that redefine \\. |
| \kill | Row is ‘killed’, but is used in calculating widths. |
| \endhead | Specifies rows to appear at the top of every page. |
| \endfirsthead | Specifies rows to appear at the top of the first page. |
| \endfoot | Specifies rows to appear at the bottom of every page. |
| \endlastfoot | Specifies rows to appear at the bottom of the last page. |
Longtable caption commands
| \caption{⟨caption⟩} | Caption ‘Table ?: ⟨caption⟩’, and a ‘⟨caption⟩’ entry in the list of tables. |
|---|---|
| \caption[⟨lot⟩]{⟨caption⟩} | Caption ‘Table ?: ⟨caption⟩’, and a ‘⟨lot⟩’ entry in the list of tables. |
| \caption[]{⟨caption⟩} | Caption ‘Table ?: ⟨caption⟩’, but no entry in the list of tables. |
| \caption*{⟨caption⟩} | Caption ‘⟨caption⟩’, but no entry in the list of tables. |
Commands available at the start of a row
| \pagebreak | Force a page break. |
|---|---|
| \pagebreak[⟨val ⟩] | A ‘hint’ between 0 and 4 of the desirability of a break. |
| \nopagebreak | Prohibit a page break. |
| \nopagebreak[⟨val ⟩] | A ‘hint’ between 0 and 4 of the undesirability of a break. |
| \newpage | Force a page break. |
Footnote commands available inside longtable
| \footnote | Footnotes, but may not be used in the table head & foot. |
|---|---|
| \footnotemark | Footnotemark, may be used in the table head & foot. |
| \footnotetext | Footnote text, use in the table body. |
Setlongtables
| \setlongtables | Obsolete command. Does nothing now. |
|---|
Объединяет строки в таблице
Подключить через команду
\usepackage{multirow}
\multirow[〈vpos 〉]{〈nrows 〉}[〈bigstruts 〉]{〈width 〉}[〈vmove 〉]{〈text 〉}
tcb выравнивает текст в общей ячейке по [t] [c] [b] (необязательный параметр) \multicolumn{2}{c}{\multirow{3}{*}{Multi-multi}} — с multirow использовать только в таком порядке, а не наоборот.
[!NOTE] В этом пакете еще есть утилиты для работы с большими скобками на объединенные строки.
История началась с французской компании, которая попросила меня написать несколько документаций на свои изделия.
Так как я сначала подумал,что отделаюсь легким испугом, то первую работу сделал в XARA. Замечательный редактор, но когда в моем документе перевалило за 50 страниц, я понял, что ошибся с выбором инструмента.
Потом было несколько документов по 4-8 страниц. Что не составило проблем сделать в XARA.
Но когда дело дошло до очередного 80-ти страничного документа, я решил просто сделать в Latex.
Эта компания использовала свои фирменные шрифты, поэтому шрифты скачал в интернет, подключил модуль \usepackage{fontspec} и вуаля!!!
\setmainfont{AllRoundGothic-Book}[
BoldFont = AllRoundGothic-Bold ,
ItalicFont = AllRoundGothic-BookOblique ]
\setsansfont{AllRoundGothic-XLig}
\setmonofont{Calibri}[
Extension = .ttf ,
BoldFont = Calibri_bold] % задаёт \sffamily, шрифт без засечек
Настроил цвета через пакет \usepackage{xcolor}
%%%%%%%%% COLOR %%%%%%%%%%%%%%%5
\definecolor{BleuProfond}{RGB}{7,29,73}%#071D49
\definecolor{BleuLBA}{RGB}{65,182,230}
\definecolor{GrisA}{RGB}{37,40,42}
\definecolor{GrisC}{RGB}{178,180,178}
Подключил нужные раскладки и настроил свои fontfamily
\newfontfamily\boldfont{AllRoundGothic-Bold}
\newfontfamily\demifont{AllRoundGothic-Demi}
\newfontfamily\demifontwhite{AllRoundGothic-Demi}[Color = white]
\newfontfamily\mediumfont{AllRoundGothic-Medium}
\newfontfamily\boldfontbleu{AllRoundGothic-Bold}[Color = BleuProfond]
\newfontfamily\boldfontlba{AllRoundGothic-Bold}[Color = BleuLBA]
\newfontfamily\boldfontwhite{AllRoundGothic-Bold}[Color = white]
\newfontfamily\lc[Scale=MatchLowercase]{AllRoundGothic-Demi}[Color = BleuProfond]
\newfontfamily\uc[Scale=MatchUppercase]{AllRoundGothic-Demi}
\newfontfamily\ac[Scale=MatchAveragecase]{AllRoundGothic-Demi}
\newfontfamily\numamco{Calibri}
Собственно все!
Дальше рутина по созданию стиля страницы. Очень приятный XELATEX с которым мы достаточно быстро справились с поставленной задачей (убрал только привычный мне %\usepackage{hyperref}), потому-что на него странно ругался компилятор. (вычислил эксперементально).
Но все мои познания подключения шрифтов начались тогда, когда заказчик попросил сделать оглавление кликабельное с возможностью переходить по ссылкам на страницы.
Оказывается не XELATEX не LUALATEX при всей своей красоте поддержки TrueType шрифтов напрямую, отказываются работать с \usepackage[xetex]{hyperref} даже в таком варианте.
Есть варианты создать свою структуру и прописать настройки к ней, но в этом варианте я ограничиваюсь настройкой в рабочей директории.
Подключать буду три шрифта:
- AllRoundGothic-Bold.ttf
- AllRoundGothic-Book.ttf
- AllRoundGothic-Demi.ttf
Нахожу в Latex (T1-WGL4.enc) на Manjaro он спрятался в /opt/texlive/2024/texmf-dist/fonts/enc/ttf2pk/base
Его тоже копирую в рабочуюдиректорию, чтобы ничего не потерялось. Для кирилических шрифтов копируем T2A.enc, он находится по соседству: /opt/texlive/2024/texmf-dist/fonts/enc/t2.
Теперь все готово для подключения.
Файлы с расширением tfm хранят необработанные шрифты, а файлы vpl виртуальные шрифты.
ttf2tfm AllRoundGothic-Demi.ttf -q -T T1-WGL4.enc -v ecAllRoundGothic-Demi.vpl recAllRoundGothic-Demi.tfm >> ttfonts.map
ttf2tfm AllRoundGothic-Bold.ttf -q -T T1-WGL4.enc -v ecAllRoundGothic-Bold.vpl recAllRoundGothic-Bold.tfm >> ttfonts.map
ttf2tfm AllRoundGothic-Book.ttf -q -T T1-WGL4.enc -v ecAllRoundGothic-Book.vpl recAllRoundGothic-Dook.tfm >> ttfonts.map
Можно посмотреть в ttfont.map, должно получиться что-то вроде:
recAllRoundGothic-Bold AllRoundGothic-Bold.ttf Encoding=T1-WGL4.enc
recAllRoundGothic-Book AllRoundGothic-Book.ttf Encoding=T1-WGL4.enc
recAllRoundGothic-Demi AllRoundGothic-Demi.ttf Encoding=T1-WGL4.enc
Чтобы создать наклонные версии обычного и жирного шрифта, команду следует расширить следующим образом:
ttf2tfm AllRoundGothic-Book.ttf -q -T T1-WGL4.enc -s .167 -v ecAllRoundGothic-Book.vpl recAllRoundGothic-Dook.tfm >> ttfonts.map
Но я так не делал, потому-что было не нужно.
vptovf ecAllRoundGothic-Demi.vpl ecAllRoundGothic-Demi.vf ecAllRoundGothic-Demi.tfm
vptovf ecAllRoundGothic-Bold.vpl ecAllRoundGothic-Bold.vf ecAllRoundGothic-Bold.tfm
vptovf ecAllRoundGothic-Book.vpl ecAllRoundGothic-Book.vf ecAllRoundGothic-Book.tfm
Но если бы я создавал какой-нибудь times, то нужно было создавать по всем законам толстые, наклонные и т.д.
vptovf ectimes.vpl ectimes.vf ectimes.tfm
vptovf ectimesi.vpl ectimesi.vf ectimesi.tfm
vptovf ectimesbd.vpl ectimesbd.vf ectimesbd.tfm
vptovf ectimesbi.vpl ectimesbi.vf ectimesbi.tfm
vptovf ectimeso.vpl ectimeso.vf ectimeso.tfm
vptovf ectimesbdo.vpl ectimesbdo.vf ectimesbdo.tfm
-rw-r--r-- 1 edge edge 555 ноя 12 16:31 ecAllRoundGothic-Bold.log
-rw-r--r-- 1 edge edge 1792 ноя 12 16:26 ecAllRoundGothic-Bold.tfm
-rw-r--r-- 1 edge edge 1784 ноя 12 16:26 ecAllRoundGothic-Bold.vf
-rw-r--r-- 1 edge edge 22500 ноя 12 16:19 ecAllRoundGothic-Bold.vpl
-rw-r--r-- 1 edge edge 1780 ноя 12 16:26 ecAllRoundGothic-Book.tfm
-rw-r--r-- 1 edge edge 1784 ноя 12 16:26 ecAllRoundGothic-Book.vf
-rw-r--r-- 1 edge edge 22365 ноя 12 16:20 ecAllRoundGothic-Book.vpl
-rw-r--r-- 1 edge edge 1788 ноя 12 16:25 ecAllRoundGothic-Demi.tfm
-rw-r--r-- 1 edge edge 1784 ноя 12 16:25 ecAllRoundGothic-Demi.vf
-rw-r--r-- 1 edge edge 22434 ноя 12 16:21 ecAllRoundGothic-Demi.vpl
del *.vpl они нам больше не нужны. Из них создали *.vf
Дальше размещаем по структурам каталогов Latex для постоянного использования или ничего не делаем, а все храним в рабочей папке. И все будет работать.
В latex вставляем такие простые вещи:
\font\myfont=ecAllRoundGothic-Bold
\font\mybigfont=ecAllRoundGothic-Bold at 36pt
\font\bookfont=ecAllRoundGothic-Book
\font\demifont=ecAllRoundGothic-Demi
\myfont Hello, I am being typeset in AllRoundGothic
\mybigfont Me too...
или назначаем по умолчанию, как описывал раньше.
Но, получаем:
Создаем файл .fd я этого не делал, но из образца записываю. Там подключали times.
\ProvidesFile{t1tnr.fd}[Put your description of font here]
\DeclareFontFamily{T1}{tnr}{}
\DeclareFontShape{T1}{tnr}{b}{n}{<->ectimesbd}{}
\DeclareFontShape{T1}{tnr}{b}{sl}{<-> ectimesbdo}{}
\DeclareFontShape{T1}{tnr}{b}{it}{<-> ectimesbi}{}
\DeclareFontShape{T1}{tnr}{m}{n}{<-> ectimes}{}
\DeclareFontShape{T1}{tnr}{m}{sl}{<-> ectimeso}{}
\DeclareFontShape{T1}{tnr}{m}{it}{<-> ectimesi}{}
\DeclareFontShape{T1}{tnr}{bx}{n}{<->ssub * tnr/b/n}{}
\DeclareFontShape{T1}{tnr}{bx}{sl}{<->ssub * tnr/b/sl}{}
\DeclareFontShape{T1}{tnr}{bx}{it}{<->ssub * tnr/b/it}{}
\endinput
Затем использование в документе будет выглядеть:
documentclass{article}
\begin{document}
\usefont{T1}{tnr}{m}{sl}
Hello, I am being typeset in Times New Roman Slanted
\end{document}
Или прописать прямо в преамбуле
\documentclass{article}
\renewcommand{\encodingdefault}{T1}
\renewcommand{\rmdefault}{tnr}
\begin{document}
Hello, I am being typeset in \textsl{Times New Roman Slanted}
\end{document}
Проверяем:
pdftex story
This is pdfTeX, Version 3.141592653-2.6-1.40.26 (TeX Live 2024) (preloaded format=pdftex)
restricted \write18 enabled.
entering extended mode
(/opt/texlive/2024/texmf-dist/tex/plain/knuth-lib/story.tex [1{/opt/texlive/202
4/texmf-var/fonts/map/pdftex/updmap/pdftex.map}])
*\bye
Создаем afm шрифты
ttf2afm -e T1-WGL4.enc -o rectimes.afm times.ttf
ttf2afm -e T1-WGL4.enc -o rectimesi.afm timesi.ttf
ttf2afm -e T1-WGL4.enc -o rectimesbd.afm timesbd.ttf
ttf2afm -e T1-WGL4.enc -o rectimesbi.afm timesbi.ttf
Создаем tfm и map
afm2tfm rectimes.afm -T T1-WGL4.enc rectimes.tfm >>winfonts.map
afm2tfm rectimesi.afm -T T1-WGL4.enc rectimesi.tfm >>winfonts.map
afm2tfm rectimesbd.afm -T T1-WGL4.enc rectimesbd.tfm >>winfonts.map
afm2tfm rectimesbi.afm -T T1-WGL4.enc rectimesbi.tfm >>winfonts.map
afm2tfm rectimes.afm -T T1-WGL4.enc -s .167 rectimeso.tfm >>winfonts.map
afm2tfm rectimesbd.afm -T T1-WGL4.enc -s .167 rectimesbdo.tfm >>winfonts.map
Редактируем map файл
rectimes TimesNewRomanPSMT " T1Encoding ReEncodeFont " <times.ttf T1-WGL4.enc
rectimesi TimesNewRomanPS-ItalicMT " T1Encoding ReEncodeFont " <timesi.ttf T1-WGL4.enc
rectimesbd TimesNewRomanPS-BoldMT " T1Encoding ReEncodeFont " <timesbd.ttf T1-WGL4.enc
rectimesbi TimesNewRomanPS-BoldItalicMT " T1Encoding ReEncodeFont " <timesbi.ttf T1-WGL4.enc
rectimeso TimesNewRomanPSMT " .167 SlantFont T1Encoding ReEncodeFont " <times.ttf T1-WGL4.enc
rectimesbdo TimesNewRomanPS-BoldMT " .167 SlantFont T1Encoding ReEncodeFont " <timesbd.ttf T1-WGL4.enc
Далее можно разложить по правильным директориям или оставить в рабочей дирректории.
Подключаем
\usepackage{DejaVuSans}
\renewcommand*\familydefault{\sfdefault}
и пользуемся без геммороя.
Для установки пакета в преамбуле документа пишем:
\usepackage[⟨options ⟩]{pdfpages}
https://mirror.macomnet.net/pub/CTAN/macros/latex/contrib/pdfpages/pdfpages.pdf
⟨option⟩
\includepdf[⟨key=val ⟩]{⟨filename⟩}
Вставляет файл где укажешь.
Key=val могут быть различными.
Если нужно вставить избранные страницы, используем ключ page
pages={3,5,6,8})
pages={4-9}
pages={3,{},8-11,15}
nup — укладывает логические страницы на лист (что-то вроде микространиц) nup=⟨xnup⟩x⟨ynup⟩
landscape=false — по умолчанию, но можно развернуть, если нужно
и еще куча всяких опций для какого-то боловства. Мне пока хватает этого.
Оформление стилей страниц, заголовков и оглавления. Продвинутый пакет. Оставляю его для настроек различных стилей документов.
Совместно с TITLESEC бомбическая штука по настройке стилей страниц. Обзор документации.
Для установки пакета в преамбуле документа пишем:
\usepackage[pagestyles]{titlesec}
https://mirror.truenetwork.ru/CTAN/macros/latex/contrib/titlesec/titleps.pdf
\newpagestyle{⟨name⟩}[⟨global-style⟩]{⟨commands⟩}
\renewpagestyle{⟨name⟩}[⟨global-style⟩]{⟨commands⟩}
Они их почему-то называют верхние и нижние команды.
\sethead[⟨even-left⟩][⟨even-center⟩][⟨even-right⟩] {⟨odd-left⟩}{⟨odd-center⟩}{⟨odd-right⟩}
\setfoot[⟨even-left⟩][⟨even-center⟩][⟨even-right⟩] {⟨odd-left⟩}{⟨odd-center⟩}{⟨odd-right⟩}
А теперь по-порядку.
Все
– \thechapter, \thesection, \thesubsection. . . --- печатают номера заголовков
– \chaptertitle, \sectiontitle, \subsectiontitle. . . --- печатают наименования заголовков
– (только для titlesec) \ifthechapter{⟨true⟩}{⟨false⟩}, \ifthesection{⟨true⟩}{⟨false⟩}, \ifthesubsection{⟨true⟩}{⟨false⟩}. . . --- проверяют где сейчас находится страница
– любые другие команды
относится ко всему, что есть на странице: - \thepage - другие не включенные в первую группу
\settitlemarks{⟨level-name⟩,⟨sublevel-name⟩,⟨subsublevel-name⟩...}
\settitlemarks*{⟨level-name⟩,⟨sublevel-name⟩,⟨subsublevel-name⟩...}
Устанавливает, какие команды ...title должны быть определены и когда выдаются метки; допускается любое количество уровней (1, 2, 3…). Например, \settitlemarks{chapter,section}
\headrule
\footrule
\setheadrule{⟨length⟩}
\setfootrule{⟨length⟩}
линии будут проведены под или над калантитулом
\makeheadrule
\makefootrule
\renewcommand{\makeheadrule}{\rule[-.3\baselineskip]{\linewidth}{⟨dim⟩}}
Этот пример из документации создаст две линнии в HEADER
\renewcommand{\makeheadrule}{%
\makebox[0pt][l]{\rule[.7\baselineskip]{\linewidth}{0.8pt}}%
\color[named]{Red}%
\rule[-.3\baselineskip]{\linewidth}{0.4pt}}
В документации целая дискуссия по поводу не нужности \markboth и что достаточно \markleft.
Пока не вдаюсь в подробности, но в пакете есть функция \setmarkboth{⟨code-to-use⟩}, чтобы переопределить markboth.
\widenhead[⟨even-left⟩][⟨even-right⟩]{⟨odd-left⟩}{⟨odd-right⟩}
\widenhead*{⟨even-right/odd-left⟩}{⟨even-left/odd-right⟩}
Этот параметр соответственно добавляет ширину header и footer-ов.
\widenhead*{0pt}{6pc}
тоже самое
\widenhead[6pc][0pt]{0pt}{6pc}
nopatches — это опция в преамбуле пакета для самостоятельной тонкой настройки с помощью \sectionmark.
Марксы можно получить 4 способами:
- top marks
- first marks
- botttom marks
- next top marks
Оформление стилей страниц, заголовков и оглавления. Продвинутый пакет. Оставляю его для настроек различных стилей документов.
Обзор документации.
Для установки пакета в преамбуле документа пишем:
\usepackage[explicit]{titlesec}
https://mirror.macomnet.net/pub/CTAN/macros/latex/contrib/titlesec/titlesec.pdf
команда explicit мне будет нужна, чтобы в настройках заголовков указывать {#1} для подстановки в нужное место.
В пакете есть так называемые простые настройки и продвинутые.
Для настройки формата заголовка используем три параметра:
rm sf tt md bf up it sl sc по умолчанию в заголовках стоит \bf.big medium small tinyraggedleft center raggedrightcompact — задает более компактный вид и уменьшает пробелыuppercase — выведет все буквы заглавными (говорят не всегда работает)\titlelabel{⟨label-format ⟩}
Эта команда изменяет формат метки заголовка
\titlelabel{\thetitle\quad}
т.е можно настроить буквенный вывод, изменить длину пробела, поставить точку и т.д.
\titleformat*{⟨command ⟩}{⟨format⟩}
Собственно сам формат заголовка.
command — это \section, \subsection и т.д.
format — соответственно, все, что было сказано выше. Размер шрифта, семейство шрифта и выравнивание.
\titleformat*{\section}{\Large\sf}
Собственно для простой настройки и все!!!
\titleformat{⟨command ⟩}[⟨shape⟩]{⟨format⟩}{⟨label ⟩}{⟨sep⟩}{⟨before-code⟩}[⟨after-code⟩]
это:
это:
\titleformat{\section}[display]
{\fontsize{120}{20}\boldfont}
{\vbox{\hfil\thesection}\hfil}{0em}
{\LARGE\uppercase{#1}}
\titlespacing{\section} {0pc}{20.5ex plus .1ex minus .2ex}{30.5ex minus .1ex}[0pc]
Вот так получится.
\titleformat{\subsection}[runin]
{\fontsize{44}{10}\boldfont}
{\thesection}{0.5em}
{\LARGE\uppercase{#1}}
\titlespacing{\section} {0pc}{20.5ex plus .1ex minus .2ex}{30.5ex minus .1ex}[0pc]
Использую пакет fontspec для большей красоты настроек. fontsize оттуда.
\titleformat{\subsection}[leftmargin]
{\boldfont}
{\thesection}{1.5em}
{\Large\uppercase{#1}}
\titlespacing{\subsection} {-15pc}{2.5ex plus .1ex minus .2ex}{3.5ex minus .1ex}[5pc]
...
\subsection{Subsection test two line}
И еще одна интересная заметка для заголовка: если я меняю первый параметр в \titlespacing на 3pc то получится:
titlespasing изменил третий параметр в отрицательную величину, и добился результата.
\titleformat{\subsection}[wrap]
{\Large\boldfont}
{\thesection}{1.5em}
{\uppercase{#1}}
\titlespacing{\subsection}{2pc}{4.5ex plus .1ex minus .2ex}{8.5ex plus .2ex minus .1ex}[2pc]
но нужно правильно настроить 3-й параметр в \titlespacing я для своего заголовка поставил 8.5ex, в общем подбираем экспериментально.
Но получилось:
\titlespacing{\subsection}{12pc}{8.5ex plus .1ex minus .2ex}{8.5ex plus .2ex minus .1ex}[6pc]
поменял настройки на 12pc и заголовок стал выглядеть приятнее,
для сравнения если я поставлю drop то будет перенос строк по другому режиму: см. ниже:
Все что угодно из латекса. Ставится перед заголовком и действует на метку и заголовок. Цвет, шрифт, размер и пр.
\titleformat{\section}[display]
{\color{red}\fontsize{120}{20}\boldfont}
{\vbox{\hfil\thesection}\hfil}{0em}
{\LARGE\uppercase{#1}}
метка раздела. Чтобы все работало корректно лучше ставить, если предусмотрено стилем. Т.к., когда будет применяться команда заголовка со *, то номер подавится автоматически.
\thesection
\thesubsection
\thesubsubsection
...
отступ от метки. Тоже нельзя оставлять пустым. 0pt но поставь.
самая звездная штука. В нее можно поставить вообще все и в качестве аргумента вляпать #1 как текст заголовка.
\titleformat{\section}
{\LARGE\boldfontwhite}
{}{.5em}
{\colorbox{BleuLBA}{\parbox{21cm}{\rule[-5pt]{0pt}{21pt}\hspace{1.5cm}\thesection\, \uppercase{#1}}}}
это я сделал для французов в синей рамочке белыми буквами. Но тут есть одна ошибка. Надеюсь с ней разобраться. Это номер заголовка.
тоже самое, что и before, только код ставит после заголовка. Любой!
изменяет название главы по умолчанию
\renewcommand{\chaptertitlename}{Новое название главы}
\titlespacing*{⟨command ⟩}{⟨left⟩}{⟨before-sep⟩}{⟨after-sep⟩}[⟨right-sep⟩]
Нужная команда для настроек пространства заголовка
Версия со звездочкой убирает отступ абзаца, следующего за заголовком, за исключением случаев удаления, переноса и запуска, где эта возможность не имеет смысла.
команда заголовка \section и т.д.
обязательный параметр, может быть положительный и отрицательный делает отступ заголовка влево и вправо.
Помогает при настройке с параметром drop и wrap.
буквально вертикаьный отступ перед заголовком
двигает текст после заголовка вертикально и горизонтально. Важен при настройке текста с обтеканием.
необязательный параметр для установки отступа справа для установок с hang, block и display. Помогает залезать в правое поле. Это \beforetitleunit и \aftertitleunit тонкие настройки клея в заголовках. Я не использую.
А теперь я добился того, ради чего затевал этот конспект. Я настроил заголовок без ошибок:
%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%5000
\titleformat{\section} [hang]
{\LARGE\boldfontwhite}
{\llap{\colorbox{BleuLBA}{\parbox{2cm}{\rule[-5pt]{0pt}{21pt}\filleft\thesection}}}}{0em}
{\colorbox{BleuLBA}{\parbox{21cm}{\rule[-5pt]{0pt}{21pt}\filright \uppercase{#1}}}}
\titlespacing{\section} {0pc}{2.5ex plus .1ex minus .2ex}{3.5ex minus .1ex}[0pc]
Результат смотрим ниже:
\filright \filcenter \filleft \fillast \filinner \filouter
в принципе благодаря им очень хорошо настроил и решил свою задачу выше.
Они заполняют пространство перед или после заголовкаа, в зависимости от названия.
\wordsep — пространство между слов в заголовке
indentafter noindentafter — обходит настройки отступов страницы
rigidchapters rubberchapters — регулирует пространство между титулом главы и текстом.
bottomtitles nobottomtitles nobottomtitles*
Устанавливаем минимальное пространство внизу страницы, чтобы заголовок не переносился на новую страницу.
\renewcommand{\bottomtitlespace}{⟨length ⟩}
aftersep largestsep
По умолчанию, когда есть два последовательных заголовка, между ними используется пространство ⟨after-sep⟩ от первого. Иногда это нежелательное поведение, особенно когда пространство ⟨before-sep⟩ намного больше, чем пространство ⟨after-sep⟩ (в противном случае предпочтительнее выглядит значение по умолчанию).
pageatnewline — этот странный параметр насильно разрывает заголовок на разные страницы, хотя по умолчанию команды \\ \\* подавлены.
\nostruts nostruts — подавляет умничество latex при изменении высоты пространства в заголовках.
Добавляет линии под заголовками и не только.
\titleline[⟨align⟩]{⟨horizontal material ⟩}
\titlerule[⟨height ⟩]
\titlerule*[⟨width ⟩]{⟨text ⟩}
Можно добавить прямо в текст и получить результат для одного заголовка:
\section{Title first}
\label{sec:title-first}
\titlerule[.8pt]%
\vspace{1pt}%
\titlerule
или можно эту же конструкцию добавить в настройки \titleformat.
calcwidth — изменяет формат переноса строк для режима wrap
\assignpagestyle{⟨command ⟩}{⟨pagestyle⟩}
...
\assignpagestyle{\chapter}{empty}
любой главе или странице можно назначить стиль по умолчанию.
\sectionbreak \subsectionbreak \subsubsectionbreak \paragraphbreak \subparagraphbreak \⟨section⟩break
\newcommand{\sectionbreak}{\clearpage}
или
\newcommand{\sectionbreak}{%
\addpenalty{-300}%
\vspace*{0pt}}
эта утилита настраивает автоматический разрыв страниц при достижения заданных параметров в разделах.
\chaptertolists — изменяет отступы перед заголовками
\newcommand{\chaptertolists}{}
а этот будет пустой
позволяет указывать в titleformat #1 как место для текста заголовка
\titleformat{\section}
{..}
{\thesection}{..}{#1.}
используется если \part была переопределена, помогает настроить TOC
Изменяет поведение \cleardoublepage, чтобы на пустых страницах использовался стиль пустой страницы.
Изменяет поведение необязательного аргумента в заголовках разделов, так что он устанавливает только заголовки в квадратных скобках, а не записи оглавления, которые будут основаны на полном заголовке.
Заменяет каждое вхождение символов \ или \* в заголовках на пробел в заголовках и записях оглавления.
⟨key⟩=⟨value⟩, ⟨key⟩=⟨value⟩, ⟨key⟩, ⟨key⟩,...
Первый аргумент как \titleformat, так и \titlespaceing имеет расширенный синтаксис, который позволяет устанавливать разные форматы в зависимости от контекста.
name= Допустимые значения: \chapter, \section и т. д.page= Допустимые значения: odd или even.numberless Бесполезный ключ. В этом нет необходимости, если вы не хотите установить разные нумерованные (без этого ключа) и ненумерованные (с безномерными) варианты.\titleformat{name=\section,page=even}[leftmargin]
{\filleft\scshape}{\thesection}{.5em}{}
\titleformat{name=\section,page=odd}[rightmargin]
{\filright\scshape}{\thesection}{.5em}{}
\titleclass{⟨name ⟩}{⟨class ⟩} \titleclass{⟨name⟩}{⟨class⟩}[⟨super-level-cmd ⟩]
Существует три класса:
page — это часть книги, на одной странице,top — это \chapter, который начинает страницу и помещает заголовок вверху,straight предназначен для заголовков в середине текста.В первом случае \titleclass{\part}{straight} заменяется просто класс.
Во втором случае, можно создать новые подуровни:
\titleclass{\subchapter}{straight}[\chapter] %новый класс
\newcounter{subchapter} %новый счетчик
\renewcommand{\thesubchapter}{\Alph{subchapter}} %буквенный счетчик
уровни секций изменяются автоматически
Глава 0 – уровень \section — 1 уровень и т.д.
Обнулит все настройки уровней и позволит создавать свои уровни с нуля.
\titleclass{⟨name ⟩}[⟨start-level-num ⟩]{⟨class ⟩}
добавляет высшего уровня заголовок (0) или (-1) и дальше создаем сои новые уровни.
В заголовки можно добавлять ссылки footnotes, но чтобы они не показывались в оглавлении нужно в преамбулу добавить:
\usepackage[stable]{footmisc}
Полезная вещь. Особенно когда колдуешь с отступами за пределы печатаемой области или работаешь с цветами.
\titleformat{\section}
{..}
{\makebox[2em]{\thesection}}{..}{..}
или
\titleformat{\section} [hang]
{\LARGE\boldfontwhite}
{\llap{\colorbox{BleuLBA}{\parbox{2cm}{\rule[-5pt]{0pt}{21pt}\filleft\thesection}}}}{0em}
{\colorbox{BleuLBA}{\parbox{21cm}{\rule[-5pt]{0pt}{21pt}\filright \uppercase{#1}}}}
\setcounter{secnumdepth}{0}
или
\newenvironment{exercises}
{\setcounter{secnumdepth}{0}}
{\setcounter{secnumdepth}{2}}
или
\newenvironment{exercises}
{\setcounter{secnumdepth}{0}%
\addtocontents{toc}{\protect\setcounter{tocdepth}{0}\ignorespaces}}
{\setcounter{secnumdepth}{2}%
\addtocontents{toc}{\protect\setcounter{tocdepth}{2}\ignorespaces}}
\newcommand{\secmark}{}
\newenvironment{advanced}
{\renewcommand{\secmark}{*}}
{}
\titleformat{\section} {..}
{\thesection\secmark\quad}{..}{..}
В документе пишим
\begin{advanced}
\section{...} ...
\end{advanced}
Этот раздел будет со звездочкой.
\documentclass[14pt,a4paper,twoside]{extbook}
\usepackage[utf8]{inputenc} %
\usepackage[T1]{fontenc}
\usepackage{lmodern} %
\usepackage[pagestyles]{titlesec}
\usepackage[x11names]{xcolor} %
\usepackage{theorem}
\newtheorem{worked example}{Worked Example}[chapter]
\newtheorem{solution}{SOLUTION}[chapter]
%\usepackage{anyfontsize}
\usepackage{amsfonts}
\usepackage{textcomp}
\usepackage{enumerate}
\setlength\headheight{21pt}
\newcommand{\hsp}{\hspace{20pt}}
\newcommand{\ntl}{\newline \newline}
\titleformat{\chapter}[hang]{\fontsize{50}{60}\bfseries\color[rgb]{0,0.5,0.75}}{\thechapter\hsp\fontsize{90}{60}\selectfont\textcolor{black}{|}\hsp}{0pt}{\thispagestyle{empty}\Huge\bfseries}
\titleformat{\section}{\large\bfseries}{}{0pt}{\textcolor[rgb]{0,0.5,0.75}{Topic \thesection} \ }[{\titlerule[0.8pt]}]
\usepackage{blindtext}
\newpagestyle{mine}{%
\setlength\fboxsep{10pt}
\sethead[\bfseries\llap{\colorbox{SteelBlue3}{\parbox{\dimexpr\marginparsep + \marginparwidth\relax}{\hspace{20pt}\color{white}\thepage\vphantom{|}}}}%
\colorbox{SlateGray2!40}{\parbox{\dimexpr\linewidth-2\fboxsep}{~\thechapter~|\hspace{0.75em}\chaptertitle}}][][]%
{}{}{\bfseries\colorbox{SlateGray2!40}{\parbox{\dimexpr\linewidth-2\fboxsep}{\thesection~|\hspace{0.75em}\sectiontitle}}%
\rlap{\colorbox{SteelBlue3}{\parbox{\dimexpr\marginparsep + \marginparwidth\relax}{\hspace{20pt}\color{white}\thepage\vphantom{|}}}}}
\setfoot{}{}{}
}
\pagestyle{mine}
\begin{document}
\chapter{{NUMBER}}%\textcolor{black}
\section{BIDMAS.}
\blindtext[10]
\end{document}
Выдает шикарную вещь:
Загрузка шрифтов в Latex. Package titlesec
fontenc - Управление кодировками шрифтов в LaTeXПакет fontenc является критически важным для правильного отображения текста в LaTeX-документах, особенно при работе с не-ASCII символами (кириллицей, диакритическими знаками и др.).
\usepackage[<кодировки>]{fontenc}
T1 - Расширенная латинская кодировка (поддержка акцентов, лигатур)OT1 - Базовая кодировка TeX (устаревшая)T2A - Основная кириллическая кодировкаT2B - Альтернативная кириллическая кодировкаT2C - Дополнительная кириллическая кодировка\usepackage[T1,T2A]{fontenc} % Латинские и кириллические символы
\usepackage[T1]{fontenc} % Только латинские символы
| Кодировка | Описание |
|---|---|
| OT1 | Базовая кодировка TeX |
| T1 | Расширенная латинская |
| T2A | Основная кириллица |
| T2B | Альтернативная кириллица |
| T2C | Дополнительная кириллица |
| LY1 | Улучшенная кодировка для LaTeX |
| … | Другие специализированные кодировки |
\fontencoding{<кодировка>} - Переключает текущую кодировку шрифта\selectfont - Применяет изменения кодировки{\fontencoding{T1}\selectfont Текст в T1 кодировке}
{\fontencoding{T2A}\selectfont Текст в T2A кодировке}
\usepackage[T1,T2A]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage[english,russian]{babel}
\begin{document}
Латинские символы: Café, naïve
Кириллические символы: Пример русского текста
\end{document}
{\fontencoding{T1}\selectfont
This text uses T1 encoding for proper hyphenation of words like "naïve".}
{\fontencoding{T2A}\selectfont
Этот текст использует кодировку T2A для корректного отображения кириллицы.}
\DeclareFontFamily{T2A}{cmr}{}
\DeclareFontShape{T2A}{cmr}{m}{n}{<-> ecrm1000}{}
Решение:
\usepackage[T2A]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage[russian]{babel}
Решение:
\usepackage[T1]{fontenc} % Для правильного разрыва слов типа "naïve"
Решение: Явное указание кодировок:
\usepackage[T1,T2A]{fontenc}
inputenc:\usepackage[T1,T2A]{fontenc}
\usepackage[utf8]{inputenc} % Рекомендуется всегда использовать utf8
babel:\usepackage[T1,T2A]{fontenc}
\usepackage[english,russian]{babel}
fontspec):\usepackage{fontspec} % Для XeLaTeX/LuaLaTeX
% fontenc не нужен при использовании fontspec
\DeclareFontEncoding{XYZ}{}{}
\DeclareErrorFont{XYZ}{cmr}{m}{n}{10}
\DeclareFontSubstitution{T2A}{cmr}{m}{n}
\usepackage[T2A]{fontenc}
\usepackage[T1]{fontenc}
\usepackage[T1,T2A]{fontenc}
fontenc используйте fontspecПакет fontenc обеспечивает критически важную функциональность для правильного отображения текста в различных языках. Правильная настройка кодировок шрифтов предотвращает множество проблем с отображением символов и переносом слов.
fontspecПакет fontspec предоставляет мощную систему выбора и настройки шрифтов для движков XeTeX и LuaTeX. Он заменяет традиционный подход с использованием fontenc и inputenc, предлагая прямую работу со шрифтами системы через Unicode.
\usepackage{fontspec} % В преамбуле документа
\setmainfont{<название шрифта>}[<опции>]
Пример:
\setmainfont{TeX Gyre Termes}[
Path = /usr/local/texlive/texmf-local/fonts/opentype/,
Extension = .otf,
UprightFont = *-regular,
BoldFont = *-bold,
ItalicFont = *-italic,
BoldItalicFont = *-bolditalic
]
\setmonofont{<название шрифта>}[<опции>]
\setsansfont{<название шрифта>}[<опции>]
\newfontfamily\<команда>{<название шрифта>}[<опции>]
Пример:
\newfontfamily\cyrillicfont{PT Serif}
\newfontfamily\cyrillicfontsf{PT Sans}
\newfontfamily\cyrillicfonttt{PT Mono}
| Опция | Описание |
|---|---|
Path |
Путь к файлам шрифтов |
Extension |
Расширение файлов |
UprightFont |
Обычное начертание |
BoldFont |
Полужирное начертание |
ItalicFont |
Курсивное начертание |
BoldItalicFont |
Полужирный курсив |
| Опция | Описание |
|---|---|
Ligatures |
Управление лигатурами |
Numbers |
Стиль цифр |
Scale |
Масштабирование |
Color |
Цвет шрифта |
WordSpace |
Межсловные пробелы |
| Опция | Описание |
|---|---|
Renderer |
Рендерер (Basic/Node) |
Script |
Скрипт (Cyrillic, Latin и др.) |
Language |
Язык |
FeatureFile |
Файл с OpenType-фичами |
\usepackage{polyglossia}
\setmainlanguage{russian}
\setotherlanguage{english}
\setmainfont{PT Serif}[
Ligatures=TeX,
Extension=.ttf,
UprightFont=*-Regular,
BoldFont=*-Bold,
ItalicFont=*-Italic,
BoldItalicFont=*-BoldItalic
]
\setsansfont{PT Sans}[
Ligatures=TeX,
Extension=.ttf,
UprightFont=*-Regular,
BoldFont=*-Bold,
ItalicFont=*-Italic,
BoldItalicFont=*-BoldItalic
]
\setmonofont{PT Mono}[
Scale=0.9,
Extension=.ttf,
UprightFont=*-Regular
]
\usepackage{polyglossia}
\setdefaultlanguage{russian}
\setotherlanguage{english}
\defaultfontfeatures{Ligatures=TeX}
\setmainfont{EB Garamond}[
Language=English,
Script=Latin
]
\newfontfamily\cyrillicfont{PT Serif}[
Language=Russian,
Script=Cyrillic
]
\setmainfont{Some Font}[
RawFeature={
+ss01; % Альтернативные глифы
+onum; % Старостильные цифры
+frac; % Дроби
+c2sc; % Капитель из прописных
}
]
+liga - стандартные лигатуры+dlig - декоративные лигатуры+tnum - табличные цифры+pnum - пропорциональные цифры+smcp - капитель из строчных+c2sc - капитель из прописных+frac - дроби+ss01-+ss20 - альтернативные наборы глифов\usepackage{unicode-math} % Должен загружаться после fontspec
\setmathfont{TeX Gyre Termes Math}
\setmathfont{XITS Math}[range={\mathcal,\mathbfcal}]
\setmathfont{STIX Two Math}[range={\mathscr}]
\newfontfamily\headfont{Helvetica Neue}[Scale=1.2]
\newcommand{\heading}[1]{{\headfont\Large #1}}
\newfontface\emojifont{Segoe UI Emoji}[Renderer=Harfbuzz]
\newcommand{\showemoji}[1]{{\emojifont #1}}
\newfontfamily\vertfont{SomeFont}[Vertical=RotatedGlyphs]
\setmainfont{Arial}[
Path=/Users/username/Library/Fonts/,
Extension=.ttf
]
\usepackage{fontspec}
% Не загружать fontenc или inputenc!
\usepackage{polyglossia}
\setmainlanguage{russian}
\setmainfont{Some Font}[Language=Russian]
Пакет fontspec предоставляет:
unicode-mathДля максимальной эффективности используйте fontspec в сочетании с:
polyglossia для языковой поддержкиunicode-math для математических шрифтовmicrotype для улучшенной типографикиНеудивительно, что разработчики часто используют поисковые системы, такие как OpenSearch, в качестве бэкенда для поисковых приложений — например, для Википедии или интернет-магазинов. Он обеспечивает отличную производительность и может масштабироваться в зависимости от потребностей приложения.
Ещё один популярный, но менее очевидный сценарий использования — анализ логов. В этом случае логи приложения загружаются в OpenSearch, а мощные функции поиска и визуализации помогают выявлять проблемы. Например, неисправный веб-сервер может выдавать ошибку 500 в 0,5% случаев, что сложно заметить без графика в реальном времени, отображающего все HTTP-статусы за последние четыре часа. С помощью OpenSearch Dashboards можно создавать такие визуализации на основе данных из OpenSearch.
OpenSearch — это не только поисковый движок. В его состав также входят:
OpenSearch поддерживает множество сценариев, например:
Термин распределённая означает, что OpenSearch можно запускать на нескольких компьютерах. Поиск и аналитика подразумевают, что после загрузки данных в OpenSearch их можно искать и анализировать. Независимо от типа данных, их можно хранить и исследовать с помощью OpenSearch.
Документ — это единица хранения информации (текстовой или структурированной). В OpenSearch документы хранятся в формате JSON.
Документ можно представить несколькими способами:
Например, в школьной базе данных документ может представлять студента и содержать следующие данные:
| ID | Имя | GPA | Год выпуска |
|---|---|---|---|
| 1 | John Doe | 3.89 | 2022 |
Вот как этот документ выглядит в формате JSON:
{
"name": "John Doe",
"gpa": 3.89,
"grad_year": 2022
}
Вы узнаете, как назначаются идентификаторы документов, в разделе Индексация документов.
Индекс — это коллекция документов.
Индекс можно рассматривать несколькими способами:
Например, в школьной базе данных индекс может содержать всех студентов школы:
| ID | Имя | GPA | Год выпуска |
|---|---|---|---|
| 1 | John Doe | 3.89 | 2022 |
| 2 | Jonathan Powers | 3.85 | 2025 |
| 3 | Jane Doe | 3.52 | 2024 |
| … | … | … | … |
OpenSearch разработан как распределённая поисковая система, что означает возможность работы на одном или нескольких узлах — серверах, хранящих данные и обрабатывающих поисковые запросы. Кластер OpenSearch — это совокупность таких узлов.
Вы можете запустить OpenSearch локально на ноутбуке (системные требования минимальны), но также можно масштабировать кластер до сотен мощных серверов в дата-центре.
В одноузловом кластере (например, развёрнутом на ноутбуке) одна машина выполняет все задачи:
Однако по мере роста кластера обязанности можно распределить:
В каждом кластере выбирается главный узел (cluster manager node), который координирует операции на уровне кластера (например, создание индекса). Узлы взаимодействуют между собой: если запрос направлен к одному узлу, он может запрашивать данные у других узлов, агрегировать их ответы и возвращать итоговый результат.
Подробнее о других типах узлов см. в разделе Формирование кластера.
OpenSearch разделяет индексы на шарды. Каждый шард хранит подмножество всех документов индекса, как показано на следующей диаграмме:
Шарды используются для равномерного распределения данных между узлами кластера. Например:
Рассмотрим кластер с двумя индексами:
Эти шарды распределены между двумя узлами, как показано на схеме:
Хотя каждый шард является частью индекса OpenSearch, технически он представляет собой полноценный индекс Lucene. Это важно учитывать, потому что:
Рекомендации по работе с шардами:
В OpenSearch шарды могут быть двух типов:
По умолчанию OpenSearch создаёт по одной реплике для каждого первичного шарда. Таким образом:
Функции реплик:
OpenSearch использует структуру данных под названием инвертированный индекс, которая:
Инвертированный индекс будет выглядеть так:
| Слово | Документы |
|---|---|
| красота | 1 |
| в | 1 |
| глазах | 1 |
| смотрящего | 1 |
| красавица | 2 |
| и | 2 |
| чудовище | 2 |
Дополнительно OpenSearch хранит:
При поиске OpenSearch:
Факторы оценки:
OpenSearch использует алгоритм BM25 для расчёта релевантности и сортировки результатов.
Узнайте, как быстро установить OpenSearch, в разделе Быстрый старт установки.
Для быстрого запуска OpenSearch и OpenSearch Dashboards используйте контейнеры Docker. Полное руководство по установке доступно в разделе Установка и обновление OpenSearch.
Предварительные требования:
Настройка системы
Перед запуском рекомендуется:
sudo swapoff -a
sudo vi /etc/sysctl.conf
vm.max_map_count=262144
sudo sysctl -p
Получение файла конфигурации
Загрузите образец docker-compose.yml:
curl -O https://raw.githubusercontent.com/opensearch-project/documentation-website/3.1/assets/examples/docker-compose.yml
wget https://raw.githubusercontent.com/opensearch-project/documentation-website/3.1/assets/examples/docker-compose.yml
Запуск кластера
Перейдите в директорию с файлом и выполните:
docker compose up -d
Проверьте статус контейнеров:
docker compose ps
Ожидаемый вывод:
NAME COMMAND SERVICE STATUS PORTS
opensearch-dashboards "./opensearch-dashbo…" opensearch-dashboards running 0.0.0.0:5601->5601/tcp
opensearch-node1 "./opensearch-docker…" opensearch-node1 running 0.0.0.0:9200->9200/tcp, 9300/tcp, 0.0.0.0:9600->9600/tcp, 9650/tcp
opensearch-node2 "./opensearch-docker…" opensearch-node2 running 9200/tcp, 9300/tcp, 9600/tcp, 9650/tcp
Проверка работы
Выполните тестовый запрос к API:
curl https://localhost:9200 -ku admin:ВАШ_ПАРОЛЬ
Успешный ответ:
{
"name": "opensearch-node1",
"cluster_name": "opensearch-cluster",
"version": {
"distribution": "opensearch",
"number": "2.6.0"
},
"tagline": "The OpenSearch Project: https://opensearch.org/"
}
Доступ к Dashboards
Откройте в браузере:
http://localhost:5601/
Логин: admin
Пароль: указан в OPENSEARCH_INITIAL_ADMIN_PASSWORD файла docker-compose.yml
Примечания:
-k) при использовании демо-сертификатовРассмотрите эти типичные проблемы и способы их решения, если контейнеры не запускаются или завершаются неожиданно.
Проблема:
Требуется использовать sudo для выполнения Docker команд.
Решение:
Добавьте пользователя в группу docker:
sudo usermod -aG docker $USER
Подробнее: Post-installation steps for Linux
Ситуация:
При использовании Docker Desktop.
Решение:
Используйте команду без дефиса:
docker compose
См. документацию Docker Compose
Ситуация:
При использовании Docker Engine.
Решение:
Установите Docker Compose отдельно и используйте команду с дефисом:
docker-compose
Симптомы:
В логах сервиса появляется сообщение:
opensearch-node1 | ERROR: [1] bootstrap checks failed
opensearch-node1 | [1]: max virtual memory areas vm.max_map_count [65530] is too low...
Решение:
Увеличьте значение vm.max_map_count (см. раздел “Важные системные настройки”):
sudo sysctl -w vm.max_map_count=262144
Помимо Docker, OpenSearch можно установить:
Полные руководства: Установка и обновление OpenSearch
После успешного развёртывания кластера рекомендуется изучить:
Ознакомьтесь с разделом Взаимодействие с OpenSearch, чтобы узнать как отправлять запросы в систему.
На этой странице рассматривается REST API. Список доступных клиентов для языков программирования вы найдёте в разделе Клиенты.
REST API предоставляет гибкий способ взаимодействия с кластерами OpenSearch. Через API вы можете:
Для отправки запросов можно использовать:
Формат запросов зависит от использования плагина безопасности.
Без плагина безопасности:
curl -X GET "http://localhost:9200/_cluster/health"
С плагином безопасности (требуются учётные данные):
curl -X GET "https://localhost:9200/_cluster/health" -ku admin:ВАШ_ПАРОЛЬ
По умолчанию:
adminOPENSEARCH_INITIAL_ADMIN_PASSWORD файла docker-compose.ymlФорматирование ответа:
Для удобочитаемого JSON добавьте параметр pretty:
curl -X GET "https://localhost:9200/_cluster/health?pretty"
Запросы с телом:
Укажите заголовок Content-Type и передайте данные через параметр -d:
curl -X GET "https://localhost:9200/students/_search?pretty" \
-H 'Content-Type: application/json' \
-d '{
"query": {
"match_all": {}
}
}'
Консоль Dev Tools в OpenSearch Dashboards использует упрощённый синтаксис:
https://localhost:5601/GET _cluster/health
В документации OpenSearch запросы чаще всего приводятся в формате Dev Tools.
Дополнительно:
Для добавления JSON-документа в индекс OpenSearch (индексации документа) отправьте HTTP-запрос со следующим форматом:
PUT https://<хост>:<порт>/<имя-индекса>/_doc/<идентификатор-документа>
Пример индексации документа о студенте:
PUT /students/_doc/1
{
"name": "Иван Иванов",
"gpa": 4.5,
"grad_year": 2023
}
После выполнения запроса:
students (если не существует)1)OpenSearch автоматически определяет типы полей на основе JSON-структуры документа.
Просмотр схемы полей:
GET /students/_mapping
Пример ответа:
{
"students": {
"mappings": {
"properties": {
"gpa": {"type": "float"},
"grad_year": {"type": "long"},
"name": {
"type": "text",
"fields": {
"keyword": {
"type": "keyword",
"ignore_above": 256
}
}
}
}
}
}
}
Особенности типов:
float, longtext): для полнотекстового поиска (с анализом)keyword): для точного поиска по терминамВажно: Для изменения типов (например, преобразования grad_year в дату) требуется пересоздание индекса с явным указанием маппинга.
Базовый запрос (возвращает все документы):
GET /students/_search
{
"query": {
"match_all": {}
}
}
Пример ответа:
{
"took": 12,
"hits": {
"total": {
"value": 1,
"relation": "eq"
},
"hits": [
{
"_index": "students",
"_id": "1",
"_score": 1,
"_source": {
"name": "Иван Иванов",
"gpa": 4.5,
"grad_year": 2023
}
}
]
}
}
Ключевые элементы ответа:
took: время выполнения (мс)hits.total: количество найденных документовhits.hits: массив результатов_score: релевантность документаДополнительные материалы:
В OpenSearch документы неизменяемы, но их можно обновить, полностью заменив содержимое или изменив отдельные поля.
Используйте Index Document API для полного обновления:
PUT /students/_doc/1
{
"name": "Иван Иванов",
"gpa": 4.7, // Обновлённое значение
"grad_year": 2023,
"address": "ул. Ленина, 123" // Новое поле
}
Используйте Update Document API для изменения отдельных полей:
POST /students/_update/1/
{
"doc": {
"gpa": 4.7,
"address": "ул. Ленина, 123"
}
}
DELETE /students/_doc/1
DELETE /students
Индексы настраиваются через:
Пример создания индекса с явными настройками:
PUT /students
{
"settings": {
"index.number_of_shards": 1
},
"mappings": {
"properties": {
"name": {"type": "text"},
"grad_year": {"type": "date"}
}
}
}
Проверка маппинга:
GET /students/_mapping
Важно:
Ознакомьтесь с разделом Загрузка данных в OpenSearch для изучения способов импорта данных.
Существует несколько способов импорта данных:
Добавление отдельных документов
См. раздел Индексация документов
Массовая загрузка документов
См. раздел Пакетная индексация
Использование Data Prepper
Серверного сборщика данных OpenSearch для обработки перед анализом
Другие инструменты
См. Инструменты OpenSearch
Для массовой загрузки используйте Bulk API:
POST _bulk
{ "create": { "_index": "students", "_id": "2" } }
{ "name": "Алексей Петров", "gpa": 4.2, "grad_year": 2025 }
{ "create": { "_index": "students", "_id": "3" } }
{ "name": "Мария Смирнова", "gpa": 4.8, "grad_year": 2024 }
OpenSearch предоставляет демонстрационный набор данных электронной коммерции.
Шаги для создания тестового индекса:
Скачайте файлы:
# Маппинг полей
curl -O https://raw.githubusercontent.com/.../ecommerce-field_mappings.json
# Данные для загрузки
curl -O https://raw.githubusercontent.com/.../ecommerce.ndjson
Примените схему полей:
curl -H "Content-Type: application/json" -X PUT "https://localhost:9200/ecommerce" \
-ku admin:ПАРОЛЬ --data-binary "@ecommerce-field_mappings.json"
Загрузите данные:
curl -H "Content-Type: application/x-ndjson" -X POST "https://localhost:9200/ecommerce/_bulk" \
-ku admin:ПАРОЛЬ --data-binary "@ecommerce.ndjson"
Пример поиска:
GET ecommerce/_search
{
"query": {
"match": {
"customer_first_name": "Светлана"
}
}
}
Инструкции по работе с визуализациями см. в руководстве по OpenSearch Dashboards.
Изучите раздел Поиск по данным для получения информации о возможностях поиска.
OpenSearch предлагает несколько методов поиска:
Перед началом загрузим тестовые данные о студентах:
POST _bulk
{ "create": { "_index": "students", "_id": "1" } }
{ "name": "Иван Петров", "gpa": 4.5, "grad_year": 2023}
{ "create": { "_index": "students", "_id": "2" } }
{ "name": "Алексей Смирнов", "gpa": 4.2, "grad_year": 2025 }
{ "create": { "_index": "students", "_id": "3" } }
{ "name": "Мария Иванова", "gpa": 4.8, "grad_year": 2024 }
Получение всех документов:
GET /students/_search
Эквивалентно:
GET /students/_search
{
"query": { "match_all": {} }
}
Структура ответа:
took - время выполнения (мс)timed_out - флаг превышения таймаута_shards - статистика по шардамhits - результаты поиска:
total - общее количество совпаденийmax_score - максимальная релевантностьhits - массив документов с оценкой релевантностиПример поиска по имени:
GET /students/_search?q=name:john
вернет ответ:
{
"took": 18,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 1,
"relation": "eq"
},
"max_score": 0.9808291,
"hits": [
{
"_index": "students",
"_id": "1",
"_score": 0.9808291,
"_source": {
"name": "John Doe",
"grade": 12,
"gpa": 3.89,
"grad_year": 2022,
"future_plans": "John plans to be a computer science major"
}
}
]
}
}
Поиск с анализом текста:
GET /students/_search
{
"query": {
"match": {
"name": "иван" # Найдёт "Иван Петров" и "Мария Иванова"
}
}
}
{
"took": 13,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 1,
"relation": "eq"
},
"max_score": 0.9808291,
"hits": [
{
"_index": "students",
"_id": "1",
"_score": 0.9808291,
"_source": {
"name": "Иван Петров",
"gpa": 3.89,
"grad_year": 2022
}
}
]
}
}
Точное совпадение (без анализа):
GET /students/_search
{
"query": {
"match": {
"name.keyword": "john doe" # Только полное совпадение
}
}
}
{
"took": 19,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 1,
"relation": "eq"
},
"max_score": 0.9808291,
"hits": [
{
"_index": "students",
"_id": "1",
"_score": 0.9808291,
"_source": {
"name": "John Doe",
"gpa": 3.89,
"grad_year": 2022
}
}
]
}
}
Точное значение:
GET students/_search
{
"query": {
"bool": {
"filter": [
{ "term": { "grad_year": 2023 }}
]
}
}
}
Диапазон значений:
GET students/_search
{
"query": {
"bool": {
"filter": [
{ "range": { "gpa": { "gt": 4.0 }}}
]
}
}
}
Комбинация условий:
GET students/_search
{
"query": {
"bool": {
"must": [
{ "match": { "name": "иван" } },
{ "range": { "gpa": { "gte": 4.0 } } },
{ "term": { "grad_year": 2023 }}
]
}
}
}
OpenSearch поддерживает современные методы поиска:
Наиболее простой способ начать работу с безопасностью OpenSearch - использовать демонстрационную конфигурацию. OpenSearch включает полезные скрипты, в том числе:
install_demo_configuration.sh (для Linux/macOS)install_demo_configuration.bat (для Windows)Расположение скрипта:
plugins/opensearch-security/tools/
Действия скрипта:
opensearch.yml базовой конфигурацией для запуска кластераВажно! Демонстрационные сертификаты и пароли по умолчанию не должны использоваться в production. Перед развертыванием в продакшене их необходимо заменить на собственные.
Перед запуском скрипта:
export OPENSEARCH_INITIAL_ADMIN_PASSWORD=<ваш_надежный_пароль>
Запуск скрипта:
./plugins/opensearch-security/tools/install_demo_configuration.sh
Проверка конфигурации:
curl -k -XGET -u admin:<пароль> https://<ip-opensearch>:9200
Ожидаемый ответ:
{
"name": "smoketestnode",
"cluster_name": "opensearch",
"version": {
"distribution": "opensearch",
"number": "2.13.0"
},
"tagline": "The OpenSearch Project: https://opensearch.org/"
}
Добавьте в opensearch_dashboards.yml следующую конфигурацию:
opensearch.hosts: [https://localhost:9200]
opensearch.ssl.verificationMode: none
opensearch.username: kibanaserver
opensearch.password: kibanaserver
opensearch.requestHeadersWhitelist: [authorization, securitytenant]
opensearch_security.multitenancy.enabled: true
opensearch_security.multitenancy.tenants.preferred: [Private, Global]
opensearch_security.readonly_mode.roles: [kibana_read_only]
opensearch_security.cookie.secure: false # Отключено для HTTP
Запуск Dashboards:
yarn start --no-base-path
После запуска в логах появятся строки:
[info][listening] Server running at http://localhost:5601
[info][server][OpenSearchDashboards][http] http server running at http://localhost:5601
Доступ через браузер: http://localhost:5601
Логин: admin
Пароль: значение из OPENSEARCH_INITIAL_ADMIN_PASSWORD
Способы:
internal_users.ymlПример добавления пользователя в internal_users.yml:
test-user:
hash: "$2y$12$CkxFoTAJKsZaWv/m8VoZ6ePG3DBeBTAvoo4xA2P21VCS9w2RYumsG"
backend_roles:
- "test-backend-role"
- "kibanauser"
description: "Тестовый пользователь"
Генерация хеша пароля:
./plugins/opensearch-security/tools/hash.sh
Введите пароль (например, secretpassword), скопируйте полученный хеш.
Формат roles.yml:
<имя_роли>:
cluster_permissions:
- <разрешение_кластера>
index_permissions:
- index_patterns:
- <шаблон_индекса>
allowed_actions:
- <разрешения_индекса>
Пример роли для доступа к индексу:
human_resources:
index_permissions:
- index_patterns:
- "humanresources"
allowed_actions:
- "READ"
Формат roles_mapping.yml:
<имя_роли>:
users:
- <имя_пользователя>
backend_roles:
- <имя_роли>
Пример привязки:
human_resources:
backend_roles:
- "test-backend-role"
kibana_user:
backend_roles:
- "kibanauser"
После изменения файлов необходимо загрузить конфигурацию в security index:
./plugins/opensearch-security/tools/securityadmin.sh \
-cd "config/opensearch-security" \
-icl \
-key "../kirk-key.pem" \
-cert "../kirk.pem" \
-cacert "../root-ca.pem" \
-nhnv
Примечания:
Документ
Базовая единица информации в OpenSearch, хранимая в формате JSON. Представляет собой структурированные данные в виде пар “ключ-значение”.
Индекс
Коллекция логически связанных документов. Аналог таблицы в реляционных БД.
JSON (JavaScript Object Notation)
Текстовый формат для хранения данных, использующий структуру ключ-значение. Основной формат представления данных в OpenSearch.
Маппинг
Схема индекса, определяющая:
Узел (Node)
Отдельный сервер, являющийся частью кластера OpenSearch.
Кластер
Совокупность узлов, работающих как единая система.
Управляющий узел (Cluster Manager)
Специальный узел, координирующий кластерные операции:
Шард (Shard)
Часть индекса, содержащая подмножество его данных. Индексы разделяются на шарды для:
Типы шардов:
Doc Values
Оптимизированная on-disk структура для:
Инвертированный индекс
Структура данных, отображающая термины на документы, которые их содержат. Основа полнотекстового поиска.
Lucene
Библиотека поиска, лежащая в основе OpenSearch. Отвечает за:
Сегмент (Segment)
Неизменяемая единица хранения данных внутри шарда. Особенности:
Ингestion
Процесс добавления данных в OpenSearch. Включает:
Индексация
Процесс организации данных для эффективного поиска:
Пакетная индексация
Массовая загрузка документов через Bulk API:
Текстовый анализ
Процесс преобразования неструктурированного текста в последовательность терминов для индексации.
Компоненты анализатора:
Character Filter
Обрабатывает сырой текст:
Tokenizer
Разбивает текст на токены (слова) с метаданными:
Token Filter
Модифицирует токены:
Типы анализаторов:
Analyzer
Полный конвейер обработки (character filter → tokenizer → token filter)
Normalizer
Только character filter (без токенизации)
Стемминг
Приведение слов к базовой форме (например: “running” → “run”)
Типы запросов:
Контексты выполнения:
Query Context
Оценивает релевантность (как хорошо документ соответствует запросу)
Filter Context
Проверяет точное соответствие (да/нет) без расчета релевантности
Типы поиска:
Полнотекстовый
С учетом морфологии и вариаций слов
По ключевым словам
Точное совпадение (без анализа)
Агрегации
Механизм анализа и суммирования данных:
Транзакционный лог (translog)
In-memory буфер
Refresh
Flush
Merge
Translog
Журнал операций для гарантии сохранности данных. Особенности:
Refresh
Периодическая операция (по умолчанию каждые 1с):
Flush
Операция записи на диск:
Merge
Фоновая оптимизация:
OpenSearch и OpenSearch Dashboards доступны на любом совместимом хосте, который поддерживает Docker (таких как Linux, MacOS или Windows). Кроме того, вы можете установить оба продукта на различных дистрибутивах Linux и на Windows.
Скачайте OpenSearch для вашей предпочтительной платформы, а затем выберите один из следующих руководств по установке.
| OpenSearch | OpenSearch Dashboards |
|---|---|
| Docker | Docker |
| Helm | Helm |
| Tarball | Tarball |
| RPM | RPM |
| Debian | Debian |
| Ansible playbook | |
| Windows | Windows |
После установки OpenSearch ознакомьтесь с его настройкой для вашего развертывания.
Для получения дополнительной информации об обновлении вашего кластера OpenSearch смотрите руководство по обновлению.
Для информации об инструментах обновления смотрите инструменты обновления, миграции и сравнения OpenSearch.
Для установки плагинов смотрите раздел Установка плагинов.
Избегайте использования сетевой файловой системы для хранения узлов в рабочем процессе в производственной среде. Использование сетевой файловой системы для хранения узлов может вызвать проблемы с производительностью в вашем кластере из-за таких факторов, как условия сети (например, задержка или ограниченная пропускная способность) или скорости чтения/записи. Вам следует использовать твердотельные накопители (SSD), установленные на хосте, для хранения узлов, где это возможно.
Распределение OpenSearch для Linux поставляется с совместимой версией JDK Adoptium Java в каталоге jdk. Чтобы узнать версию JDK, выполните команду ./jdk/bin/java -version. Например, архив OpenSearch 1.0.0 поставляется с Java 15.0.1+9 (не LTS), OpenSearch 1.3.0 поставляется с Java 11.0.14.1+1 (LTS), а OpenSearch 2.0.0 поставляется с Java 17.0.2+8 (LTS). OpenSearch тестируется со всеми совместимыми версиями Java.
| Версия OpenSearch | Совместимые версии Java | Встроенная версия Java |
|---|---|---|
| 1.0–1.2.x | 11, 15 | 15.0.1+9 |
| 1.3.x | 8, 11, 14 | 11.0.25+9 |
| 2.0.0–2.11.x | 11, 17 | 17.0.2+8 |
| 2.12.0+ | 11, 17, 21 | 21.0.5+11 |
Чтобы использовать другую установку Java, установите переменную окружения OPENSEARCH_JAVA_HOME или JAVA_HOME на расположение установки Java. Например:
export OPENSEARCH_JAVA_HOME=/path/to/opensearch-3.1.0/jdk
Следующие порты необходимо открыть для компонентов OpenSearch.
| Номер порта | Компонент OpenSearch |
|---|---|
| 443 | OpenSearch Dashboards в AWS OpenSearch Service с шифрованием в пути (TLS) |
| 5601 | OpenSearch Dashboards |
| 9200 | OpenSearch REST API |
| 9300 | Внутреннее взаимодействие узлов и транспорт, поиск по кластерам |
| 9600 | Анализатор производительности |
Для рабочих нагрузок в производственной среде убедитесь, что настройка Linux vm.max_map_count установлена как минимум на 262144. Даже если вы используете образ Docker, установите это значение на хост-машине. Чтобы проверить текущее значение, выполните следующую команду:
cat /proc/sys/vm/max_map_count
Чтобы увеличить значение, добавьте следующую строку в файл /etc/sysctl.conf:
vm.max_map_count=262144
Затем выполните команду sudo sysctl -p, чтобы перезагрузить настройки.
Для рабочих нагрузок Windows вы можете установить vm.max_map_count, выполнив следующие команды:
wsl -d docker-desktop
sysctl -w vm.max_map_count=262144
Файл docker-compose.yml также содержит несколько ключевых настроек:
bootstrap.memory_lock: true
Эта настройка отключает свопинг (вместе с memlock). Свопинг может значительно снизить производительность и стабильность, поэтому вы должны убедиться, что он отключен на производственных кластерах.
Включение настройки bootstrap.memory_lock заставит JVM зарезервировать всю необходимую память. Руководство по настройке сборки мусора Java SE Hotspot VM документирует резервирование 1 гигабайта (ГБ) нативной памяти для метаданных классов по умолчанию. В сочетании с кучей Java это может привести к ошибке из-за нехватки нативной памяти на ВМ с меньшим объемом памяти, чем эти требования. Чтобы предотвратить ошибки, ограничьте размер резервируемой памяти с помощью -XX:CompressedClassSpaceSize или -XX:MaxMetaspaceSize и установите размер кучи Java, чтобы убедиться, что у вас достаточно системной памяти.
OPENSEARCH_JAVA_OPTS: -Xms512m -Xmx512m
Эта настройка устанавливает размер кучи Java (рекомендуем использовать половину системной ОЗУ).
OpenSearch по умолчанию использует -Xms1g -Xmx1g для выделения памяти кучи, что имеет приоритет над конфигурациями, указанными с использованием процентной нотации (-XX:MinRAMPercentage, -XX:MaxRAMPercentage). Например, если вы установите OPENSEARCH_JAVA_OPTS=-XX:MinRAMPercentage=30 -XX:MaxRAMPercentage=70, предустановленные значения -Xms1g -Xmx1g переопределят эти настройки. При использовании OPENSEARCH_JAVA_OPTS для определения выделения памяти убедитесь, что вы используете нотацию -Xms и -Xmx.
nofile: 65536
Эта настройка устанавливает лимит в 65536 открытых файлов для пользователя OpenSearch.
port: 9600
Эта настройка позволяет вам получить доступ к Анализатору производительности на порту 9600.
Не объявляйте одни и те же параметры JVM в нескольких местах, так как это может привести к непредсказуемому поведению или сбою запуска службы OpenSearch. Если вы объявляете параметры JVM с помощью переменной окружения, такой как OPENSEARCH_JAVA_OPTS=-Xms3g -Xmx3g, то вам следует закомментировать любые ссылки на этот параметр JVM в config/jvm.options. Напротив, если вы определяете параметры JVM в config/jvm.options, то не следует определять эти параметры JVM с помощью переменных окружения.
OpenSearch имеет ряд системных свойств, перечисленных в следующей таблице, которые вы можете указать в файле config/jvm.options или в переменной OPENSEARCH_JAVA_OPTS, используя нотацию аргументов командной строки -D.
| Свойство | Описание |
|---|---|
opensearch.xcontent.string.length.max=<value> |
По умолчанию OpenSearch не накладывает ограничений на максимальную длину строковых полей JSON/YAML/CBOR/Smile. Чтобы защитить ваш кластер от потенциальных атак типа “отказ в обслуживании” (DDoS) или проблем с памятью, вы можете установить это свойство на разумный предел (максимум 2,147,483,647), например, -Dopensearch.xcontent.string.length.max=5000000. |
| `opensearch.xcontent.fast_double_writer=[true | false]` |
opensearch.xcontent.name.length.max=<value> |
По умолчанию OpenSearch не накладывает ограничений на максимальную длину имен полей JSON/YAML/CBOR/Smile. Чтобы защитить ваш кластер от потенциальных DDoS или проблем с памятью, вы можете установить это свойство на разумный предел (максимум 2,147,483,647), например, -Dopensearch.xcontent.name.length.max=50000. |
opensearch.xcontent.depth.max=<value> |
По умолчанию OpenSearch не накладывает ограничений на максимальную глубину вложенности для документов JSON/YAML/CBOR/Smile. Чтобы защитить ваш кластер от потенциальных DDoS или проблем с памятью, вы можете установить это свойство на разумный предел (максимум 2,147,483,647), например, -Dopensearch.xcontent.depth.max=1000. |
opensearch.xcontent.codepoint.max=<value> |
По умолчанию OpenSearch накладывает ограничение в 52428800 на максимальный размер YAML-документов (в кодовых точках). Чтобы защитить ваш кластер от потенциальных DDoS или проблем с памятью, вы можете изменить это свойство на разумный предел (максимум 2,147,483,647). Например, -Dopensearch.xcontent.codepoint.max=5000000. |
Docker значительно упрощает процесс настройки и управления вашими кластерами OpenSearch. Вы можете загружать официальные образы из Docker Hub или Amazon Elastic Container Registry (Amazon ECR) и быстро развернуть кластер, используя Docker Compose и любой из примеров файлов Docker Compose, включенных в этот гид. Опытные пользователи OpenSearch могут дополнительно настроить свое развертывание, создав собственный файл Docker Compose.
Контейнеры Docker являются портативными и будут работать на любом совместимом хосте, который поддерживает Docker (таких как Linux, MacOS или Windows). Портативность контейнера Docker предлагает гибкость по сравнению с другими методами установки, такими как RPM или ручная установка из Tarball, которые требуют дополнительной конфигурации после загрузки и распаковки.
Этот гид предполагает, что вы уверенно работаете с интерфейсом командной строки (CLI) Linux. Вы должны понимать, как вводить команды, перемещаться между директориями и редактировать текстовые файлы. Для получения помощи по Docker или Docker Compose обратитесь к официальной документации на их веб-сайтах.
Посетите страницу Get Docker для получения рекомендаций по установке и настройке Docker для вашей среды. Если вы устанавливаете Docker Engine с помощью CLI, то по умолчанию Docker не будет иметь никаких ограничений на доступные ресурсы хоста. В зависимости от вашей среды вы можете настроить ограничения ресурсов в Docker. См. раздел Runtime options with Memory, CPUs, and GPUs для получения информации.
Пользователи Docker Desktop должны установить использование памяти хоста на минимум 4 ГБ, открыв Docker Desktop и выбрав Settings → Resources.
Docker Compose — это утилита, которая позволяет пользователям запускать несколько контейнеров с одной командой. Вы передаете файл Docker Compose при его вызове. Docker Compose читает эти настройки и запускает запрашиваемые контейнеры. Docker Compose устанавливается автоматически с Docker Desktop, но пользователи, работающие в командной строке, должны установить Docker Compose вручную. Вы можете найти информацию о установке Docker Compose на официальной странице Docker Compose GitHub.
Если вам нужно установить Docker Compose вручную и ваш хост поддерживает Python, вы можете использовать pip для автоматической установки пакета Docker Compose.
Перед установкой OpenSearch с использованием Docker настройте следующие параметры. Это самые важные настройки, которые могут повлиять на производительность ваших сервисов, но для дополнительной информации смотрите раздел о важных системных настройках.
Для среды Linux выполните следующие команды:
Отключите производительность памяти с помощью свопинга для улучшения производительности:
sudo swapoff -a
Увеличьте количество доступных для OpenSearch карт памяти:
# Отредактируйте файл конфигурации sysctl
sudo vi /etc/sysctl.conf
# Добавьте строку для определения желаемого значения
# или измените значение, если ключ существует,
# а затем сохраните изменения.
vm.max_map_count=262144
# Перезагрузите параметры ядра с помощью sysctl
sudo sysctl -p
# Проверьте, что изменение было применено, проверив значение
cat /proc/sys/vm/max_map_count
Для рабочих нагрузок Windows, использующих WSL через Docker Desktop, выполните следующие команды в терминале, чтобы установить vm.max_map_count:
wsl -d docker-desktop
sysctl -w vm.max_map_count=262144
Официальные образы OpenSearch размещены на Docker Hub и Amazon ECR. Если вы хотите просмотреть образы, вы можете загружать их по отдельности, используя команду docker pull, как в следующих примерах.
docker pull opensearchproject/opensearch:3
docker pull opensearchproject/opensearch-dashboards:3
docker pull public.ecr.aws/opensearchproject/opensearch:3
docker pull public.ecr.aws/opensearchproject/opensearch-dashboards:3
Чтобы загрузить конкретную версию OpenSearch или OpenSearch Dashboards, отличную от последней доступной версии, измените тег образа, где он упоминается (либо в командной строке, либо в файле Docker Compose). Например, opensearchproject/opensearch:3.1.0 загрузит версию OpenSearch 3.1.0. Чтобы загрузить последнюю версию, используйте opensearchproject/opensearch:latest. Обратитесь к официальным репозиториям образов для доступных версий.
Перед тем как продолжить, вы должны убедиться, что Docker работает корректно, развернув OpenSearch в одном контейнере.
# Эта команда сопоставляет порты 9200 и 9600, устанавливает тип обнаружения на "single-node" и запрашивает самый новый образ OpenSearch
docker run -d -p 9200:9200 -p 9600:9600 -e "discovery.type=single-node" opensearchproject/opensearch:latest
Для OpenSearch версии 2.12 или выше установите новый пользовательский пароль администратора перед установкой, используя следующую команду:
docker run -d -p 9200:9200 -p 9600:9600 -e "discovery.type=single-node" -e "OPENSEARCH_INITIAL_ADMIN_PASSWORD=<custom-admin-password>" opensearchproject/opensearch:latest
admin.curl https://localhost:9200 -ku admin:<custom-admin-password>
Вы должны получить ответ, который выглядит следующим образом:
{
"name" : "a937e018cee5",
"cluster_name" : "docker-cluster",
"cluster_uuid" : "GLAjAG6bTeWErFUy_d-CLw",
"version" : {
"distribution" : "opensearch",
"number" : "<version>",
"build_type" : "<build-type>",
"build_hash" : "<build-hash>",
"build_date" : "<build-date>",
"build_snapshot" : false,
"lucene_version" : "<lucene-version>",
"minimum_wire_compatibility_version" : "7.10.0",
"minimum_index_compatibility_version" : "7.0.0"
},
"tagline" : "The OpenSearch Project: https://opensearch.org/"
}
a937e018cee5:$ docker container ls
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
a937e018cee5 opensearchproject/opensearch:latest "./opensearch-docker…" 19 minutes ago Up 19 minutes 0.0.0.0:9200->9200/tcp, 9300/tcp, 0.0.0.0:9600->9600/tcp, 9650/tcp wonderful_boyd
docker stop.docker stop <containerId>
Помните, что команда
docker container lsне отображает остановленные контейнеры. Если вы хотите просмотреть остановленные контейнеры, используйте командуdocker container ls -a. Вы можете удалить ненужные контейнеры вручную с помощью командыdocker container rm <containerId_1> <containerId_2> <containerId_3> [...](укажите все идентификаторы контейнеров, которые вы хотите остановить, разделенные пробелами), или, если вы хотите удалить все остановленные контейнеры, вы можете использовать более короткую командуdocker container prune.
Хотя технически возможно создать кластер OpenSearch, создавая контейнеры по одной команде за раз, гораздо проще определить вашу среду в YAML-файле и позволить Docker Compose управлять кластером. В следующем разделе содержатся примеры YAML-файлов, которые вы можете использовать для запуска предопределенного кластера с OpenSearch и OpenSearch Dashboards. Эти примеры полезны для тестирования и разработки, но не подходят для производственной среды. Если у вас нет опыта работы с Docker Compose, вам может быть полезно ознакомиться со спецификацией Docker Compose для получения рекомендаций по синтаксису и форматированию перед внесением изменений в структуры словарей в примерах.
Файл YAML, который определяет среду, называется файлом Docker Compose. По умолчанию команды docker-compose сначала проверяют вашу текущую директорию на наличие файла, который соответствует любому из следующих имен:
docker-compose.ymldocker-compose.yamlcompose.ymlcompose.yamlЕсли ни один из этих файлов не существует в вашей текущей директории, команда docker-compose завершится с ошибкой.
Вы можете указать пользовательское местоположение и имя файла при вызове docker-compose с помощью флага -f:
# Используйте относительный или абсолютный путь к файлу.
docker compose -f /path/to/your-file.yml up
Если вы впервые запускаете кластер OpenSearch с использованием Docker Compose, используйте следующий пример файла docker-compose.yml. Сохраните его в домашнем каталоге вашего хоста и назовите его docker-compose.yml. Этот файл создает кластер, который содержит три контейнера: два контейнера, работающих с сервисом OpenSearch, и один контейнер, работающий с OpenSearch Dashboards. Эти контейнеры общаются через мостовую сеть под названием opensearch-net и используют два тома, по одному для каждого узла OpenSearch. Поскольку этот файл явно не отключает демонстрационную конфигурацию безопасности, устанавливаются самоподписанные TLS-сертификаты, и создаются внутренние пользователи с именами и паролями по умолчанию.
Начиная с OpenSearch 2.12, для настройки демонстрационной конфигурации безопасности требуется пользовательский пароль администратора. Выполните одно из следующих действий:
Перед запуском docker-compose.yml установите новый пользовательский пароль администратора, используя следующую команду:
export OPENSEARCH_INITIAL_ADMIN_PASSWORD=<custom-admin-password>
Создайте файл .env в той же папке, что и ваш файл docker-compose.yml, с переменной OPENSEARCH_INITIAL_ADMIN_PASSWORD и значением надежного пароля.
OpenSearch по умолчанию обеспечивает высокую безопасность паролей, используя библиотеку оценки прочности паролей zxcvbn, разработанную компанией Dropbox.
Эта библиотека оценивает пароли на основе энтропии, а не жестких правил сложности, используя следующие рекомендации:
Сосредоточьтесь на энтропии, а не только на правилах: Вместо того чтобы просто добавлять цифры или специальные символы, придавайте приоритет общей непредсказуемости. Длинные пароли, состоящие из случайных слов или символов, обеспечивают более высокую энтропию, что делает их более безопасными, чем короткие пароли, соответствующие традиционным правилам сложности.
Избегайте общих шаблонов и слов из словаря: Библиотека zxcvbn обнаруживает распространенные шаблоны и слова из словаря, что помогает предотвратить использование легко угадываемых паролей.
Следуя этим рекомендациям, вы сможете создать более надежные пароли, которые обеспечат лучшую защиту ваших учетных записей и данных в OpenSearch.
services:
opensearch-node1: # This is also the hostname of the container within the Docker network (i.e. https://opensearch-node1/)
image: opensearchproject/opensearch:latest # Specifying the latest available image - modify if you want a specific version
container_name: opensearch-node1
environment:
- cluster.name=opensearch-cluster # Name the cluster
- node.name=opensearch-node1 # Name the node that will run in this container
- discovery.seed_hosts=opensearch-node1,opensearch-node2 # Nodes to look for when discovering the cluster
- cluster.initial_cluster_manager_nodes=opensearch-node1,opensearch-node2 # Nodes eligible to serve as cluster manager
- bootstrap.memory_lock=true # Disable JVM heap memory swapping
- "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" # Set min and max JVM heap sizes to at least 50% of system RAM
- OPENSEARCH_INITIAL_ADMIN_PASSWORD=${OPENSEARCH_INITIAL_ADMIN_PASSWORD} # Sets the demo admin user password when using demo configuration, required for OpenSearch 2.12 and later
ulimits:
memlock:
soft: -1 # Set memlock to unlimited (no soft or hard limit)
hard: -1
nofile:
soft: 65536 # Maximum number of open files for the opensearch user - set to at least 65536
hard: 65536
volumes:
- opensearch-data1:/usr/share/opensearch/data # Creates volume called opensearch-data1 and mounts it to the container
ports:
- 9200:9200 # REST API
- 9600:9600 # Performance Analyzer
networks:
- opensearch-net # All of the containers will join the same Docker bridge network
opensearch-node2:
image: opensearchproject/opensearch:latest # This should be the same image used for opensearch-node1 to avoid issues
container_name: opensearch-node2
environment:
- cluster.name=opensearch-cluster
- node.name=opensearch-node2
- discovery.seed_hosts=opensearch-node1,opensearch-node2
- cluster.initial_cluster_manager_nodes=opensearch-node1,opensearch-node2
- bootstrap.memory_lock=true
- "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m"
- OPENSEARCH_INITIAL_ADMIN_PASSWORD=${OPENSEARCH_INITIAL_ADMIN_PASSWORD}
ulimits:
memlock:
soft: -1
hard: -1
nofile:
soft: 65536
hard: 65536
volumes:
- opensearch-data2:/usr/share/opensearch/data
networks:
- opensearch-net
opensearch-dashboards:
image: opensearchproject/opensearch-dashboards:latest # Make sure the version of opensearch-dashboards matches the version of opensearch installed on other nodes
container_name: opensearch-dashboards
ports:
- 5601:5601 # Map host port 5601 to container port 5601
expose:
- "5601" # Expose port 5601 for web access to OpenSearch Dashboards
environment:
OPENSEARCH_HOSTS: '["https://opensearch-node1:9200","https://opensearch-node2:9200"]' # Define the OpenSearch nodes that OpenSearch Dashboards will query
networks:
- opensearch-net
volumes:
opensearch-data1:
opensearch-data2:
networks:
opensearch-net:
Если вы переопределяете настройки opensearch_dashboards.yml, используя переменные окружения в вашем файле Compose, используйте все заглавные буквы и заменяйте точки на подчеркивания. Например, для opensearch.hosts используйте OPENSEARCH_HOSTS.
Это поведение отличается от переопределения настроек opensearch.yml, где преобразование заключается только в изменении оператора присваивания. Например, discovery.type: single-node в opensearch.yml определяется как discovery.type=single-node в docker-compose.yml.
Создайте и запустите контейнеры в фоновом режиме из домашнего каталога вашего хоста (содержащего docker-compose.yml):
docker compose up -d
Проверьте, что сервисные контейнеры запустились корректно:
docker compose ps
Если контейнер не удалось запустить, вы можете просмотреть логи сервиса:
# Если вы не укажете имя сервиса, docker compose покажет логи всех узлов
docker compose logs <serviceName>
Проверьте доступ к OpenSearch Dashboards, подключившись к http://localhost:5601 из браузера. Для OpenSearch версии 2.12 и выше вы должны использовать ваш настроенный логин и пароль. Для более ранних версий логин и пароль по умолчанию — admin. Мы не рекомендуем использовать эту конфигурацию на хостах, доступных из публичного интернета, пока вы не настроите конфигурацию безопасности вашего развертывания.
Помните, что localhost не может быть доступен удаленно. Если вы развертываете эти контейнеры на удаленном хосте, вам нужно установить сетевое соединение и заменить localhost на IP-адрес или DNS-запись, соответствующую хосту.
Остановите работающие контейнеры в вашем кластере:
docker compose down
Команда
docker compose downостановит работающие контейнеры, но не удалит Docker-тома, которые существуют на хосте. Если вам не важны содержимое этих томов, используйте опцию-v, чтобы удалить все тома, например:docker compose down -v
В отличие от RPM-распределения OpenSearch, которое требует значительного объема конфигурации после установки, запуск кластеров OpenSearch с помощью Docker позволяет вам определить среду еще до создания контейнеров. Это возможно как при использовании Docker, так и при использовании Docker Compose.
Рассмотрим следующую команду:
docker run \
-p 9200:9200 -p 9600:9600 \
-e "discovery.type=single-node" \
-v /path/to/custom-opensearch.yml:/usr/share/opensearch/config/opensearch.yml \
opensearchproject/opensearch:latest
Разберем каждую часть команды:
discovery.type в single-node, чтобы проверки загрузки не завершились неудачей для этого развертывания с одним узлом.-v, чтобы передать локальный файл с именем custom-opensearch.yml в контейнер, заменяя файл opensearch.yml, включенный в образ.opensearchproject/opensearch:latest из Docker Hub.Если вы сравните эту команду с примером файла docker-compose.yml, вы можете заметить некоторые общие настройки, такие как сопоставление портов и ссылка на образ. Однако эта команда только развертывает один контейнер, работающий с OpenSearch, и не создает контейнер для OpenSearch Dashboards. Более того, если вы хотите использовать пользовательские TLS-сертификаты, пользователей или роли, или определить дополнительные тома и сети, то эта “однострочная” команда быстро становится непрактичной. Вот где полезность Docker Compose становится очевидной.
Когда вы строите свой кластер OpenSearch с помощью Docker Compose, вам может быть проще передавать пользовательские файлы конфигурации с вашего хоста в контейнер, вместо того чтобы перечислять каждую отдельную настройку в docker-compose.yml. Аналогично тому, как в примере команды docker run был смонтирован том с хоста в контейнер с помощью флага -v, файлы Compose могут указывать тома для монтирования как подопцию для соответствующей службы. Следующий сокращенный YAML-файл демонстрирует, как смонтировать файл или директорию в контейнер:
services:
opensearch-node1:
volumes:
- opensearch-data1:/usr/share/opensearch/data
- ./custom-opensearch.yml:/usr/share/opensearch/config/opensearch.yml
opensearch-node2:
volumes:
- opensearch-data2:/usr/share/opensearch/data
- ./custom-opensearch.yml:/usr/share/opensearch/config/opensearch.yml
opensearch-dashboards:
volumes:
- ./custom-opensearch_dashboards.yml:/usr/share/opensearch-dashboards/config/opensearch_dashboards.yml
Обратите внимание, что в этом примере каждый узел OpenSearch использует один и тот же файл конфигурации, что упрощает управление настройками. Для получения более подробной информации о использовании томов и синтаксисе обратитесь к официальной документации Docker по томам.
Если вы хотите создать свой собственный файл compose на основе примера, ознакомьтесь с следующим образцом файла docker-compose.yml. Этот образец создает два узла OpenSearch и один узел OpenSearch Dashboards с отключенным плагином безопасности. Вы можете использовать этот образец в качестве отправной точки, просматривая Настройка основных параметров безопасности.
services:
opensearch-node1:
image: opensearchproject/opensearch:latest
container_name: opensearch-node1
environment:
- cluster.name=opensearch-cluster # Название кластера
- node.name=opensearch-node1 # Название узла, который будет работать в этом контейнере
- discovery.seed_hosts=opensearch-node1,opensearch-node2 # Узлы, которые будут использоваться для обнаружения кластера
- cluster.initial_cluster_manager_nodes=opensearch-node1,opensearch-node2 # Узлы, которые могут служить менеджерами кластера
- bootstrap.memory_lock=true # Отключить свопинг памяти кучи JVM
- "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" # Установить минимальный и максимальный размеры кучи JVM не менее 50% от системной оперативной памяти
- "DISABLE_INSTALL_DEMO_CONFIG=true" # Предотвращает выполнение встроенного демо-скрипта, который устанавливает демо-сертификаты и конфигурации безопасности в OpenSearch
- "DISABLE_SECURITY_PLUGIN=true" # Отключает плагин безопасности
ulimits:
memlock:
soft: -1 # Установить memlock на неограниченное (без мягкого или жесткого ограничения)
hard: -1
nofile:
soft: 65536 # Максимальное количество открытых файлов для пользователя opensearch - установить не менее 65536
hard: 65536
volumes:
- opensearch-data1:/usr/share/opensearch/data # Создает том с именем opensearch-data1 и монтирует его в контейнер
ports:
- 9200:9200 # REST API
- 9600:9600 # Анализатор производительности
networks:
- opensearch-net # Все контейнеры будут присоединены к одной и той же сети Docker bridge
opensearch-node2:
image: opensearchproject/opensearch:latest
container_name: opensearch-node2
environment:
- cluster.name=opensearch-cluster # Название кластера
- node.name=opensearch-node2 # Название узла, который будет работать в этом контейнере
- discovery.seed_hosts=opensearch-node1,opensearch-node2 # Узлы, которые будут использоваться для обнаружения кластера
- cluster.initial_cluster_manager_nodes=opensearch-node1,opensearch-node2 # Узлы, которые могут служить менеджерами кластера
- bootstrap.memory_lock=true # Отключить свопинг памяти кучи JVM
- "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" # Установить минимальный и максимальный размеры кучи JVM не менее 50% от системной оперативной памяти
- "DISABLE_INSTALL_DEMO_CONFIG=true" # Предотвращает выполнение встроенного демо-скрипта, который устанавливает демо-сертификаты и конфигурации безопасности в OpenSearch
- "DISABLE_SECURITY_PLUGIN=true" # Отключает плагин безопасности
ulimits:
memlock:
soft: -1 # Установить memlock на неограниченное (без мягкого или жесткого ограничения)
hard: -1
nofile:
soft: 65536 # Максимальное количество открытых файлов для пользователя opensearch - установить не менее 65536
hard: 65536
volumes:
- opensearch-data2:/usr/share/opensearch/data # Создает том с именем opensearch-data2 и монтирует его в контейнер
networks:
- opensearch-net # Все контейнеры будут присоединены к одной и той же сети Docker bridge
opensearch-dashboards:
image: opensearchproject/opensearch-dashboards:latest
container_name: opensearch-dashboards
ports:
- 5601:5601 # Привязка порта хоста 5601 к порту контейнера 5601
expose:
- "5601" # Открыть порт 5601 для веб-доступа к OpenSearch Dashboards
environment:
- 'OPENSEARCH_HOSTS=["http://opensearch-node1:9200","http://opensearch-node2:9200"]' # Указать узлы OpenSearch для Dashboards
- "DISABLE_SECURITY_DASHBOARDS_PLUGIN=true" # Отключает плагин безопасности в OpenSearch Dashboards
networks:
- opensearch-net
volumes:
opensearch-data1: {} # Создает том opensearch-data1
opensearch-data2: {} # Создает том opensearch-data2
networks:
opensearch-net: {} # Создает сеть opensearch-net
Перед тем как сделать ваш кластер OpenSearch доступным для внешних хостов, рекомендуется ознакомиться с конфигурацией безопасности развертывания. Вы можете вспомнить из первого примера файла docker-compose.yml, что, если не отключить плагин безопасности, установив DISABLE_SECURITY_PLUGIN=true, встроенный скрипт применит стандартную демо-конфигурацию безопасности к узлам в кластере. Поскольку эта конфигурация используется для демонстрационных целей, стандартные имена пользователей и пароли известны. Поэтому мы рекомендуем создать собственные файлы конфигурации безопасности и использовать тома для передачи этих файлов в контейнеры. Для получения конкретных рекомендаций по настройке безопасности OpenSearch смотрите Конфигурация безопасности.
Чтобы использовать свои собственные сертификаты в конфигурации, добавьте все необходимые сертификаты в раздел томов файла compose:
volumes:
- ./root-ca.pem:/usr/share/opensearch/config/root-ca.pem
- ./admin.pem:/usr/share/opensearch/config/admin.pem
- ./admin-key.pem:/usr/share/opensearch/config/admin-key.pem
- ./node1.pem:/usr/share/opensearch/config/node1.pem
- ./node1-key.pem:/usr/share/opensearch/config/node1-key.pem
Когда вы добавляете сертификаты TLS к узлам OpenSearch с помощью томов Docker Compose, вы также должны включить пользовательский файл opensearch.yml, который определяет эти сертификаты. Например:
volumes:
- ./root-ca.pem:/usr/share/opensearch/config/root-ca.pem
- ./admin.pem:/usr/share/opensearch/config/admin.pem
- ./admin-key.pem:/usr/share/opensearch/config/admin-key.pem
- ./node1.pem:/usr/share/opensearch/config/node1.pem
- ./node1-key.pem:/usr/share/opensearch/config/node1-key.pem
- ./custom-opensearch.yml:/usr/share/opensearch/config/opensearch.yml
Помните, что сертификаты, которые вы указываете в файле compose, должны совпадать с сертификатами, определенными в вашем пользовательском файле opensearch.yml. Вам следует заменить корневые, администраторские и узловые сертификаты на свои собственные. Для получения дополнительной информации смотрите Настройка сертификатов TLS.
Пример конфигурации в вашем пользовательском файле opensearch.yml может выглядеть следующим образом, добавляя сертификаты TLS и отличительное имя (DN) сертификата администратора, определяя несколько разрешений и включая подробное аудиторское логирование:
plugins.security.ssl.transport.pemcert_filepath: node1.pem
plugins.security.ssl.transport.pemkey_filepath: node1-key.pem
plugins.security.ssl.transport.pemtrustedcas_filepath: root-ca.pem
plugins.security.ssl.transport.enforce_hostname_verification: false
plugins.security.ssl.http.enabled: true
plugins.security.ssl.http.pemcert_filepath: node1.pem
plugins.security.ssl.http.pemkey_filepath: node1-key.pem
plugins.security.ssl.http.pemtrustedcas_filepath: root-ca.pem
plugins.security.allow_default_init_securityindex: true
plugins.security.authcz.admin_dn:
- CN=A,OU=UNIT,O=ORG,L=TORONTO,ST=ONTARIO,C=CA
plugins.security.nodes_dn:
- 'CN=N,OU=UNIT,O=ORG,L=TORONTO,ST=ONTARIO,C=CA'
plugins.security.audit.type: internal_opensearch
plugins.security.enable_snapshot_restore_privilege: true
plugins.security.check_snapshot_restore_write_privileges: true
plugins.security.restapi.roles_enabled: ["all_access", "security_rest_api_access"]
cluster.routing.allocation.disk.threshold_enabled: false
opendistro_security.audit.config.disabled_rest_categories: NONE
opendistro_security.audit.config.disabled_transport_categories: NONE
Для получения полного списка настроек смотрите Безопасность.
Используйте тот же процесс для указания конфигурации Backend в файле /usr/share/opensearch/config/opensearch-security/config.yml, а также для создания новых внутренних пользователей, ролей, сопоставлений, групп действий и арендаторов в соответствующих YAML-файлах.
После замены сертификатов и создания собственных внутренних пользователей, ролей, сопоставлений, групп действий и арендаторов, используйте Docker Compose для запуска кластера:
docker compose up -d
Чтобы использовать образ OpenSearch с пользовательским плагином, вам сначала нужно создать Dockerfile. Ознакомьтесь с официальной документацией Docker для получения информации о создании Dockerfile.
FROM opensearchproject/opensearch:latest
RUN /usr/share/opensearch/bin/opensearch-plugin install --batch <pluginId>
Затем выполните следующие команды:
# Создание образа из Dockerfile
docker build --tag=opensearch-custom-plugin .
# Запуск контейнера из пользовательского образа
docker run -p 9200:9200 -p 9600:9600 -v /usr/share/opensearch/data opensearch-custom-plugin
В качестве альтернативы, вы можете удалить плагин из образа перед его развертыванием. Этот пример Dockerfile удаляет плагин безопасности:
FROM opensearchproject/opensearch:latest
RUN /usr/share/opensearch/bin/opensearch-plugin remove opensearch-security
Вы также можете использовать Dockerfile для передачи своих собственных сертификатов для использования с плагином безопасности:
FROM opensearchproject/opensearch:latest
COPY --chown=opensearch:opensearch opensearch.yml /usr/share/opensearch/config/
COPY --chown=opensearch:opensearch my-key-file.pem /usr/share/opensearch/config/
COPY --chown=opensearch:opensearch my-certificate-chain.pem /usr/share/opensearch/config/
COPY --chown=opensearch:opensearch my-root-cas.pem /usr/share/opensearch/config/
Установка OpenSearch с использованием менеджера пакетов Advanced Packaging Tool (APT) значительно упрощает процесс по сравнению с методом Tarball. Несколько технических аспектов, таких как путь установки, расположение конфигурационных файлов и создание службы, управляемой systemd, обрабатываются автоматически менеджером пакетов.
В общем, установка OpenSearch из дистрибутива Debian может быть разбита на несколько шагов:
Дистрибутив Debian предоставляет все необходимое для запуска OpenSearch внутри дистрибутивов Linux на базе Debian, таких как Ubuntu.
Этот гид предполагает, что вы уверенно работаете с интерфейсом командной строки (CLI) Linux. Вы должны понимать, как вводить команды, перемещаться между директориями и редактировать текстовые файлы. Некоторые примеры команд ссылаются на текстовый редактор vi, но вы можете использовать любой доступный текстовый редактор.
Скачайте Debian-пакет для желаемой версии непосредственно с страницы загрузок OpenSearch. Debian-пакет можно скачать как для архитектуры x64, так и для arm64.
Из командной строки установите пакет с помощью dpkg:
Для новых установок OpenSearch 2.12 и более поздних версий необходимо определить пользовательский пароль администратора для настройки демо-конфигурации безопасности. Используйте одну из следующих команд для определения пользовательского пароля администратора:
# x64
sudo env OPENSEARCH_INITIAL_ADMIN_PASSWORD=<custom-admin-password> dpkg -i opensearch-3.1.0-linux-x64.deb
# arm64
sudo env OPENSEARCH_INITIAL_ADMIN_PASSWORD=<custom-admin-password> dpkg -i opensearch-3.1.0-linux-arm64.deb
Используйте следующую команду для версий OpenSearch 2.11 и более ранних:
# x64
sudo dpkg -i opensearch-3.1.0-linux-x64.deb
# arm64
sudo dpkg -i opensearch-3.1.0-linux-arm64.deb
После успешной установки включите OpenSearch как службу:
sudo systemctl enable opensearch
Запустите службу OpenSearch:
sudo systemctl start opensearch
Проверьте, что OpenSearch запустился корректно:
sudo systemctl status opensearch
Debian-пакет не подписан. Если вы хотите проверить отпечаток, проект OpenSearch предоставляет файл .sig, а также пакет .deb для использования с GNU Privacy Guard (GPG).
Скачайте желаемый Debian-пакет:
curl -SLO https://artifacts.opensearch.org/releases/bundle/opensearch/3.1.0/opensearch-3.1.0-linux-x64.deb
Скачайте соответствующий файл подписи:
curl -SLO https://artifacts.opensearch.org/releases/bundle/opensearch/3.1.0/opensearch-3.1.0-linux-x64.deb.sig
Скачайте и импортируйте GPG-ключ:
curl -o- https://artifacts.opensearch.org/publickeys/opensearch-release.pgp | gpg --import -
Проверьте подпись:
gpg --verify opensearch-3.1.0-linux-x64.deb.sig opensearch-3.1.0-linux-x64.deb
APT, основной инструмент управления пакетами для операционных систем на базе Debian, позволяет загружать и устанавливать Debian-пакет из APT-репозитория.
sudo apt-get update && sudo apt-get -y install lsb-release ca-certificates curl gnupg2
curl -o- https://artifacts.opensearch.org/publickeys/opensearch-release.pgp | sudo gpg --dearmor --batch --yes -o /usr/share/keyrings/opensearch-release-keyring
echo "deb [signed-by=/usr/share/keyrings/opensearch-release-keyring] https://artifacts.opensearch.org/releases/bundle/opensearch/3.x/apt stable main" | sudo tee /etc/apt/sources.list.d/opensearch-3.x.list
sudo apt-get update
sudo apt list -a opensearch
# Для новых установок OpenSearch 2.12 и более поздних версий необходимо определить пользовательский пароль администратора для настройки демо-конфигурации безопасности.
# Используйте одну из следующих команд для определения пользовательского пароля:
sudo env OPENSEARCH_INITIAL_ADMIN_PASSWORD=<custom-admin-password> apt-get install opensearch
# Для версий OpenSearch 2.11 и более ранних используйте следующую команду:
sudo apt-get install opensearch
# Чтобы установить конкретную версию OpenSearch, укажите версию вручную, используя `opensearch=<version>`:
# Для новых установок OpenSearch 2.12 и более поздних версий:
sudo env OPENSEARCH_INITIAL_ADMIN_PASSWORD=<custom-admin-password> apt-get install opensearch=3.1.0
# Для версий OpenSearch 2.11 и более ранних:
sudo apt-get install opensearch=3.1.0
Fingerprint: c5b7 4989 65ef d1c2 924b a9d5 39d3 1987 9310 d3fc
sudo systemctl enable opensearch
Чтобы запустить OpenSearch, выполните следующую команду:
sudo systemctl start opensearch
После запуска проверьте, что OpenSearch запустился корректно, с помощью следующей команды:
sudo systemctl status opensearch
Перед тем как продолжить с любой конфигурацией, рекомендуется протестировать вашу установку OpenSearch. В противном случае может быть сложно определить, связаны ли будущие проблемы с установочными ошибками или с пользовательскими настройками, которые вы применили после установки.
Когда OpenSearch установлен с использованием Debian-пакета, некоторые демо-настройки безопасности автоматически применяются. Это включает в себя самоподписанные TLS-сертификаты и несколько пользователей и ролей. Если вы хотите настроить их самостоятельно, смотрите раздел Настройка OpenSearch в вашей среде.
Узел OpenSearch в своей стандартной конфигурации (с демо-сертификатами и пользователями с стандартными паролями) не подходит для производственной среды. Если вы планируете использовать узел в производственной среде, вам следует, как минимум, заменить демо TLS-сертификаты на ваши собственные и обновить список внутренних пользователей и паролей. Смотрите Конфигурация безопасности для получения дополнительной информации, чтобы убедиться, что ваши узлы настроены в соответствии с вашими требованиями безопасности.
Отправьте запросы на сервер, чтобы проверить, что OpenSearch работает. Обратите внимание на использование флага --insecure, который необходим, поскольку TLS-сертификаты самоподписаны.
curl -X GET https://localhost:9200 -u 'admin:<custom-admin-password>' --insecure
Вы должны получить ответ, который выглядит примерно так:
{
"name": "hostname",
"cluster_name": "opensearch",
"cluster_uuid": "QqgpHCbnSRKcPAizqjvoOw",
"version": {
"distribution": "opensearch",
"number": <version>,
"build_type": <build-type>,
"build_hash": <build-hash>,
"build_date": <build-date>,
"build_snapshot": false,
"lucene_version": <lucene-version>,
"minimum_wire_compatibility_version": "7.10.0",
"minimum_index_compatibility_version": "7.0.0"
},
"tagline": "The OpenSearch Project: https://opensearch.org/"
}
Запросите конечную точку плагинов:
curl -X GET https://localhost:9200/_cat/plugins?v -u 'admin:<custom-admin-password>' --insecure
Этот запрос вернет список установленных плагинов, что также подтвердит, что OpenSearch работает корректно.
| Name | Component | Version |
|---|---|---|
| hostname | opensearch-alerting | 3.1.0 |
| hostname | opensearch-anomaly-detection | 3.1.0 |
| hostname | opensearch-asynchronous-search | 3.1.0 |
| hostname | opensearch-cross-cluster-replication | 3.1.0 |
| hostname | opensearch-geospatial | 3.1.0 |
| hostname | opensearch-index-management | 3.1.0 |
| hostname | opensearch-job-scheduler | 3.1.0 |
| hostname | opensearch-knn | 3.1.0 |
| hostname | opensearch-ml | 3.1.0 |
| hostname | opensearch-neural-search | 3.1.0 |
| hostname | opensearch-notifications | 3.1.0 |
| hostname | opensearch-notifications-core | 3.1.0 |
| hostname | opensearch-observability | 3.1.0 |
| hostname | opensearch-performance-analyzer | 3.1.0 |
| hostname | opensearch-reports-scheduler | 3.1.0 |
| hostname | opensearch-security | 3.1.0 |
| hostname | opensearch-security-analytics | 3.1.0 |
| hostname | opensearch-sql | 3.1.0 |
Пользователи, не имеющие предварительного опыта работы с OpenSearch, могут захотеть получить список рекомендуемых настроек для начала работы с сервисом. По умолчанию OpenSearch не привязан к сетевому интерфейсу и не может быть доступен внешними хостами. Кроме того, настройки безопасности заполняются стандартными именами пользователей и паролями. Следующие рекомендации позволят пользователю привязать OpenSearch к сетевому интерфейсу, создать и подписать TLS-сертификаты, а также настроить базовую аутентификацию.
Следующие настройки позволят вам:
Если вы запускали демо-скрипт безопасности, вам нужно будет вручную перенастроить настройки, которые были изменены. Обратитесь к Конфигурации безопасности для получения рекомендаций перед продолжением.
Перед внесением каких-либо изменений в конфигурационные файлы всегда полезно сохранить резервную копию. Резервный файл можно использовать для устранения любых проблем, вызванных неправильной конфигурацией.
opensearch.ymlОткройте файл opensearch.yml:
sudo vi /etc/opensearch/opensearch.yml
Добавьте следующие строки в файл:
# Привязать OpenSearch к правильному сетевому интерфейсу. Используйте 0.0.0.0
# для включения всех доступных интерфейсов или укажите IP-адрес,
# назначенный конкретному интерфейсу.
network.host: 0.0.0.0
# Если вы еще не настроили кластер, установите
# discovery.type в single-node, иначе проверки загрузки
# не пройдут, когда вы попытаетесь запустить службу.
discovery.type: single-node
# Если вы ранее отключили плагин безопасности в opensearch.yml,
# обязательно включите его снова. В противном случае вы можете пропустить эту настройку.
plugins.security.disabled: false
Сохраните изменения и закройте файл
Укажите начальные и максимальные размеры кучи JVM
jvm.options:vi /etc/opensearch/jvm.options
Измените значения для начального и максимального размеров кучи. В качестве отправной точки вы должны установить эти значения на половину доступной системной памяти. Для выделенных хостов это значение можно увеличить в зависимости от ваших рабочих требований.
Например, если у хост-машины 8 ГБ памяти, вы можете установить начальные и максимальные размеры кучи на 4 ГБ:
-Xms4g
-Xmx4g
Сертификаты TLS обеспечивают дополнительную безопасность для вашего кластера, позволяя клиентам подтверждать личность хостов и шифровать трафик между клиентом и хостом. Для получения дополнительной информации обратитесь к разделам “Настройка сертификатов TLS” и “Генерация сертификатов”, которые включены в документацию по плагину безопасности. Для работы в среде разработки обычно достаточно самоподписанных сертификатов. Этот раздел проведет вас через основные шаги, необходимые для генерации собственных сертификатов TLS и их применения к вашему хосту OpenSearch.
cd /etc/opensearch
sudo rm -f *pem
Это то, что вы будете использовать для подписания других сертификатов.
# Создайте закрытый ключ для корневого сертификата
sudo openssl genrsa -out root-ca-key.pem 2048
# Используйте закрытый ключ для создания самоподписанного корневого сертификата. Обязательно
# замените аргументы, переданные в -subj, чтобы они отражали ваш конкретный хост.
sudo openssl req -new -x509 -sha256 -key root-ca-key.pem -subj "/C=CA/ST=ONTARIO/L=TORONTO/O=ORG/OU=UNIT/CN=ROOT" -out root-ca.pem -days 730
Этот сертификат используется для получения повышенных прав для выполнения административных задач, связанных с плагином безопасности.
# Создайте закрытый ключ для сертификата администратора
sudo openssl genrsa -out admin-key-temp.pem 2048
# Преобразуйте закрытый ключ в PKCS#8
sudo openssl pkcs8 -inform PEM -outform PEM -in admin-key-temp.pem -topk8 -nocrypt -v1 PBE-SHA1-3DES -out admin-key.pem
# Создайте запрос на подпись сертификата (CSR). Общим именем (CN) "A" можно пользоваться, так как этот сертификат
# используется для аутентификации повышенного доступа и не привязан к хосту.
sudo openssl req -new -key admin-key.pem -subj "/C=CA/ST=ONTARIO/L=TORONTO/O=ORG/OU=UNIT/CN=A" -out admin.csr
# Подпишите сертификат администратора с помощью корневого сертификата и закрытого ключа, которые вы создали ранее.
sudo openssl x509 -req -in admin.csr -CA root-ca.pem -CAkey root-ca-key.pem -CAcreateserial -sha256 -out admin.pem -days 730
sudo openssl genrsa -out node1-key-temp.pem 2048
# Преобразуйте закрытый ключ в PKCS#8
sudo openssl pkcs8 -inform PEM -outform PEM -in node1-key-temp.pem -topk8 -nocrypt -v1 PBE-SHA1-3DES -out node1-key.pem
# Создайте CSR и замените аргументы, переданные в -subj, чтобы они отражали ваш конкретный хост
# Обратите внимание, что CN должен соответствовать DNS A записи для хоста — не используйте имя хоста.
sudo openssl req -new -key node1-key.pem -subj "/C=CA/ST=ONTARIO/L=TORONTO/O=ORG/OU=UNIT/CN=node1.dns.a-record" -out node1.csr
# Создайте файл расширений, который определяет SAN DNS имя для хоста
# Этот файл должен соответствовать DNS A записи хоста.
sudo sh -c 'echo subjectAltName=DNS:node1.dns.a-record > node1.ext'
# Подпишите сертификат узла с помощью корневого сертификата и закрытого ключа, которые вы создали ранее
sudo openssl x509 -req -in node1.csr -CA root-ca.pem -CAkey root-ca-key.pem -CAcreateserial -sha256 -out node1.pem -days 730 -extfile node1.ext
sudo rm -f *temp.pem *csr *ext
sudo chown opensearch:opensearch admin-key.pem admin.pem node1-key.pem node1.pem root-ca-key.pem root-ca.pem root-ca.srl
opensearch.ymlКак описано в разделе “Генерация сертификатов”. Продвинутые пользователи также могут выбрать добавление настроек с помощью скрипта.
#! /bin/bash
# Before running this script, make sure to replace the CN in the
# node's distinguished name with a real DNS A record.
echo "plugins.security.ssl.transport.pemcert_filepath: /etc/opensearch/node1.pem" | sudo tee -a /etc/opensearch/opensearch.yml
echo "plugins.security.ssl.transport.pemkey_filepath: /etc/opensearch/node1-key.pem" | sudo tee -a /etc/opensearch/opensearch.yml
echo "plugins.security.ssl.transport.pemtrustedcas_filepath: /etc/opensearch/root-ca.pem" | sudo tee -a /etc/opensearch/opensearch.yml
echo "plugins.security.ssl.http.enabled: true" | sudo tee -a /etc/opensearch/opensearch.yml
echo "plugins.security.ssl.http.pemcert_filepath: /etc/opensearch/node1.pem" | sudo tee -a /etc/opensearch/opensearch.yml
echo "plugins.security.ssl.http.pemkey_filepath: /etc/opensearch/node1-key.pem" | sudo tee -a /etc/opensearch/opensearch.yml
echo "plugins.security.ssl.http.pemtrustedcas_filepath: /etc/opensearch/root-ca.pem" | sudo tee -a /etc/opensearch/opensearch.yml
echo "plugins.security.allow_default_init_securityindex: true" | sudo tee -a /etc/opensearch/opensearch.yml
echo "plugins.security.authcz.admin_dn:" | sudo tee -a /etc/opensearch/opensearch.yml
echo " - 'CN=A,OU=UNIT,O=ORG,L=TORONTO,ST=ONTARIO,C=CA'" | sudo tee -a /etc/opensearch/opensearch.yml
echo "plugins.security.nodes_dn:" | sudo tee -a /etc/opensearch/opensearch.yml
echo " - 'CN=node1.dns.a-record,OU=UNIT,O=ORG,L=TORONTO,ST=ONTARIO,C=CA'" | sudo tee -a /etc/opensearch/opensearch.yml
echo "plugins.security.audit.type: internal_opensearch" | sudo tee -a /etc/opensearch/opensearch.yml
echo "plugins.security.enable_snapshot_restore_privilege: true" | sudo tee -a /etc/opensearch/opensearch.yml
echo "plugins.security.check_snapshot_restore_write_privileges: true" | sudo tee -a /etc/opensearch/opensearch.yml
echo "plugins.security.restapi.roles_enabled: [\"all_access\", \"security_rest_api_access\"]" | sudo tee -a /etc/opensearch/opensearch.yml
# Скопируйте корневой сертификат в правильную директорию
sudo cp /etc/opensearch/root-ca.pem /etc/pki/ca-trust/source/anchors/
# Добавьте доверие
sudo update-ca-trust
Пользователи определяются и аутентифицируются OpenSearch различными способами. Один из методов, который не требует дополнительной инфраструктуры на стороне сервера, — это ручная настройка пользователей в файле internal_users.yml. В следующих шагах объясняется, как добавить нового внутреннего пользователя и как заменить пароль по умолчанию для администратора с помощью скрипта.
cd /usr/share/opensearch/plugins/opensearch-security/tools
hash.sh для генерации нового пароля# Пример вывода, если JDK не найден...
$ ./hash.sh
**************************************************************************
** Этот инструмент будет устаревшим в следующем крупном релизе OpenSearch **
** https://github.com/opensearch-project/security/issues/1755 **
**************************************************************************
which: no java in (/usr/local/bin:/usr/bin:/usr/local/sbin:/usr/sbin:/home/user/.local/bin:/home/user/bin)
WARNING: nor OPENSEARCH_JAVA_HOME nor JAVA_HOME is set, will use
./hash.sh: line 35: java: command not found
OPENSEARCH_JAVA_HOME=/usr/share/opensearch/jdk ./hash.sh
internal_users.ymlsudo vi /etc/opensearch/opensearch-security/internal_users.yml
internal_users.yml на вывод, предоставленный hash.sh на шаге 2Файл должен выглядеть примерно так:
---
# This is the internal user database
# The hash value is a bcrypt hash and can be generated with plugin/tools/hash.sh
_meta:
type: "internalusers"
config_version: 2
# Define your internal users here
admin:
hash: "$2y$1EXAMPLEQqwS8TUcoEXAMPLEeZ3lEHvkEXAMPLERqjyh1icEXAMPLE."
reserved: true
backend_roles:
- "admin"
description: "Admin user"
user1:
hash: "$2y$12$zoHpvTCRjjQr6h0PEaabueCaGam3/LDvT6rZZGDGMusD7oehQjw/O"
reserved: false
backend_roles: []
description: "New internal user"
# Other users
...
Теперь, когда сертификаты TLS установлены, а демонстрационные пользователи были удалены или им были назначены новые пароли, последний шаг — применить изменения конфигурации. Этот последний шаг конфигурации требует вызова securityadmin.sh, пока OpenSearch работает на хосте.
OpenSearch должен быть запущен, чтобы securityadmin.sh мог применить изменения. Если вы внесли изменения в opensearch.yml, перезапустите OpenSearch:
sudo systemctl restart opensearch
securityadmin.sh# Перейдите в правильную директорию
cd /usr/share/opensearch/plugins/opensearch-security/tools
Смотрите раздел “Применение изменений с помощью securityadmin.sh” для определения аргументов, которые вы должны передать.
# Вы можете опустить переменную окружения, если вы объявили ее в вашем $PATH.
OPENSEARCH_JAVA_HOME=/usr/share/opensearch/jdk ./securityadmin.sh -cd /etc/opensearch/opensearch-security/ -cacert /etc/opensearch/root-ca.pem -cert /etc/opensearch/admin.pem -key /etc/opensearch/admin-key.pem -icl -nhnv
-cd: указывает директорию конфигурации.-cacert: указывает путь к корневому сертификату.-cert: указывает путь к сертификату администратора.-key: указывает путь к закрытому ключу администратора.-icl: включает режим конфигурации.-nhnv: отключает проверку хоста и не выводит информацию о версии.OpenSearch теперь работает на вашем хосте с пользовательскими сертификатами TLS и безопасным пользователем для базовой аутентификации. Вы можете проверить внешнюю доступность, отправив API-запрос к вашему узлу OpenSearch с другого хоста.
Во время предыдущего теста вы направляли запросы на localhost. Теперь, когда сертификаты TLS были применены и новые сертификаты ссылаются на фактическую DNS-запись вашего хоста, запросы к localhost не пройдут проверку CN, и сертификат будет считаться недействительным. Вместо этого запросы должны быть отправлены на адрес, который вы указали при генерации сертификата.
Перед отправкой запросов вы должны добавить доверие к корневому сертификату на вашем клиенте. Если вы не добавите доверие, вам нужно будет использовать опцию
-k, чтобы cURL игнорировал проверку CN и корневого сертификата.
$ curl https://your.host.address:9200 -u admin:yournewpassword -k
{
"name":"hostname",
"cluster_name":"opensearch",
"cluster_uuid":"QqgpHCbnSRKcPAizqjvoOw",
"version":{
"distribution":"opensearch",
"number":<version>,
"build_type":<build-type>,
"build_hash":<build-hash>,
"build_date":<build-date>,
"build_snapshot":false,
"lucene_version":<lucene-version>,
"minimum_wire_compatibility_version":"7.10.0",
"minimum_index_compatibility_version":"7.0.0"
},
"tagline":"The OpenSearch Project: https://opensearch.org/"
}
Экземпляры OpenSearch, установленные с помощью dpkg или apt-get, можно легко обновить до более новой версии.
Скачайте Debian-пакет для желаемой версии обновления непосредственно со страницы загрузок OpenSearch Project.
Перейдите в директорию, содержащую дистрибутив, и выполните следующую команду:
sudo dpkg -i opensearch-3.1.0-linux-x64.deb
Чтобы обновить до последней версии OpenSearch с помощью apt-get, выполните:
sudo apt-get upgrade opensearch
Вы также можете обновить до конкретной версии OpenSearch:
sudo apt-get upgrade opensearch=<version>
Чтобы автоматически перезапустить OpenSearch после обновления пакета, включите opensearch.service через systemd:
sudo systemctl enable opensearch.service
OpenSearch Dashboards предоставляет полностью интегрированное решение для визуального изучения, обнаружения и запроса ваших данных наблюдаемости. Вы можете установить OpenSearch Dashboards с помощью одного из следующих вариантов:
OpenSearch Dashboards поддерживает следующие веб-браузеры:
Другие браузеры на основе Chromium также могут работать. Internet Explorer и Microsoft Edge Legacy не поддерживаются.
OpenSearch Dashboards требует бинарный файл среды выполнения Node.js для работы. Один из них включен в дистрибутивные пакеты, доступные на странице загрузок OpenSearch.
OpenSearch Dashboards версии 2.8.0 и новее могут использовать версии Node.js 14, 16 и 18. Дистрибутивные пакеты для OpenSearch Dashboards версии 2.10.0 и новее включают Node.js 18 и 14 (для обратной совместимости).
Чтобы использовать бинарный файл среды выполнения Node.js, отличный от включенных в дистрибутивные пакеты, выполните следующие шаги:
Скачайте и установите Node.js; совместимые версии: >=14.20.1 <19.
Установите путь установки в переменные окружения NODE_HOME или NODE_OSD_HOME.
На UNIX, если Node.js установлен в /usr/local/nodejs, а бинарный файл среды выполнения находится по пути /usr/local/nodejs/bin/node:
export NODE_HOME=/usr/local/nodejs
Если Node.js установлен с помощью NVM, а бинарный файл среды выполнения находится по пути /Users/user/.nvm/versions/node/v18.19.0/bin/node:
export NODE_HOME=/Users/user/.nvm/versions/node/v18.19.0
# или, если NODE_HOME используется для чего-то другого:
export NODE_OSD_HOME=/Users/user/.nvm/versions/node/v18.19.0
На Windows, если Node.js установлен в C:\Program Files\nodejs, а бинарный файл среды выполнения находится по пути C:\Program Files\nodejs\node.exe:
set "NODE_HOME=C:\Program Files\nodejs"
# или с использованием PowerShell:
$Env:NODE_HOME = 'C:\Program Files\nodejs'
Ознакомьтесь с документацией вашей операционной системы, чтобы внести постоянные изменения в переменные окружения.
Скрипт запуска OpenSearch Dashboards, bin/opensearch-dashboards, ищет бинарный файл среды выполнения Node.js, используя NODE_OSD_HOME, затем NODE_HOME, прежде чем использовать бинарные файлы, включенные в дистрибутивные пакеты. Если подходящий бинарный файл среды выполнения Node.js не найден, скрипт запуска попытается найти его в системном PATH, прежде чем завершить работу с ошибкой.
Чтобы узнать, как настроить TLS для OpenSearch Dashboards, смотрите раздел Настройка TLS.
Выполните команду для загрузки образа OpenSearch Dashboards:
docker pull opensearchproject/opensearch-dashboards:2
Создайте файл docker-compose.yml, соответствующий вашей среде. Пример файла, который включает OpenSearch Dashboards, доступен на странице установки OpenSearch Docker.
Так же, как и для opensearch.yml, вы можете передать пользовательский файл opensearch_dashboards.yml в контейнер в файле Docker Compose.
Запустите команду:
docker compose up
Подождите, пока контейнеры запустятся. Затем ознакомьтесь с документацией OpenSearch Dashboards.
Когда закончите, выполните команду:
docker compose down
Установка OpenSearch Dashboards с использованием менеджера пакетов Advanced Packaging Tool (APT) значительно упрощает процесс по сравнению с методом Tarball. Например, менеджер пакетов обрабатывает несколько технических аспектов, таких как путь установки, расположение конфигурационных файлов и создание службы, управляемой systemd.
Перед установкой OpenSearch Dashboards необходимо настроить кластер OpenSearch. Обратитесь к руководству по установке OpenSearch для Debian для получения инструкций.
Данное руководство предполагает, что вы уверенно работаете с интерфейсом командной строки (CLI) Linux. Вы должны понимать, как вводить команды, перемещаться между директориями и редактировать текстовые файлы. Некоторые примеры команд ссылаются на текстовый редактор vi, но вы можете использовать любой доступный текстовый редактор.
Скачайте пакет Debian для нужной версии непосредственно с страницы загрузок OpenSearch. Пакет Debian доступен для архитектур x64 и arm64.
Установите пакет с помощью dpkg из командной строки:
Для x64:
sudo dpkg -i opensearch-dashboards-3.1.0-linux-x64.deb
Для arm64:
sudo dpkg -i opensearch-dashboards-3.1.0-linux-arm64.deb
После завершения установки перезагрузите конфигурацию менеджера systemd:
sudo systemctl daemon-reload
Включите OpenSearch как службу:
sudo systemctl enable opensearch-dashboards
Запустите службу OpenSearch:
sudo systemctl start opensearch-dashboards
Проверьте, что OpenSearch запустился корректно:
sudo systemctl status opensearch-dashboards
Пакет Debian не подписан. Если вы хотите проверить подпись, проект OpenSearch предоставляет файл .sig, а также .deb пакет для использования с GNU Privacy Guard (GPG).
Скачайте нужный пакет Debian:
curl -SLO https://artifacts.opensearch.org/releases/bundle/opensearch-dashboards/3.1.0/opensearch-dashboards-3.1.0-linux-x64.deb
Скачайте соответствующий файл подписи:
curl -SLO https://artifacts.opensearch.org/releases/bundle/opensearch-dashboards/3.1.0/opensearch-dashboards-3.1.0-linux-x64.deb.sig
Скачайте и импортируйте GPG-ключ:
curl -o- https://artifacts.opensearch.org/publickeys/opensearch-release.pgp | gpg --import -
Проверьте подпись:
gpg --verify opensearch-dashboards-3.1.0-linux-x64.deb.sig opensearch-dashboards-3.1.0-linux-x64.deb
APT, основной инструмент управления пакетами для операционных систем на базе Debian, позволяет загружать и устанавливать пакет Debian из репозитория APT.
Установите необходимые пакеты:
sudo apt-get update && sudo apt-get -y install lsb-release ca-certificates curl gnupg2
Импортируйте публичный GPG-ключ. Этот ключ используется для проверки подписи репозитория APT:
curl -o- https://artifacts.opensearch.org/publickeys/opensearch-release.pgp | sudo gpg --dearmor --batch --yes -o /usr/share/keyrings/opensearch-release-keyring
Создайте репозиторий APT для OpenSearch:
echo "deb [signed-by=/usr/share/keyrings/opensearch-release-keyring] https://artifacts.opensearch.org/releases/bundle/opensearch-dashboards/3.x/apt stable main" | sudo tee /etc/apt/sources.list.d/opensearch-dashboards-3.x.list
Проверьте, что репозиторий был успешно создан:
sudo apt-get update
С добавленной информацией о репозитории, перечислите все доступные версии OpenSearch:
sudo apt list -a opensearch-dashboards
Выберите версию OpenSearch, которую хотите установить:
Если не указано иное, будет установлена последняя доступная версия OpenSearch:
sudo apt-get install opensearch-dashboards
Чтобы установить конкретную версию OpenSearch Dashboards, укажите номер версии после имени пакета:
# Укажите версию вручную с помощью opensearch=<version>
sudo apt-get install opensearch-dashboards=3.1.0
После завершения установки включите OpenSearch:
sudo systemctl enable opensearch-dashboards
Запустите OpenSearch:
sudo systemctl start opensearch-dashboards
Проверьте, что OpenSearch запустился корректно:
sudo systemctl status opensearch-dashboards
По умолчанию OpenSearch Dashboards, как и OpenSearch, связывается с localhost при первоначальной установке. В результате OpenSearch Dashboards недоступен с удаленного хоста, если конфигурация не обновлена.
Откройте файл opensearch_dashboards.yml:
sudo vi /etc/opensearch-dashboards/opensearch_dashboards.yml
Укажите сетевой интерфейс, к которому должен связываться OpenSearch Dashboards:
# Используйте 0.0.0.0, чтобы связаться с любым доступным интерфейсом.
server.host: 0.0.0.0
Сохраните изменения и выйдите из редактора.
Перезапустите OpenSearch Dashboards, чтобы применить изменения конфигурации:
sudo systemctl restart opensearch-dashboards
В веб-браузере перейдите к OpenSearch Dashboards. Порт по умолчанию — 5601.
Войдите с использованием имени пользователя admin и пароля admin. (Для OpenSearch 2.12 и новее пароль должен быть пользовательским паролем администратора.)
Посетите раздел “Начало работы с OpenSearch Dashboards”, чтобы узнать больше.
Экземпляры OpenSearch Dashboards, установленные с помощью dpkg или apt-get, можно легко обновить до новой версии.
Скачайте пакет Debian для желаемой версии обновления непосредственно со страницы загрузок проекта OpenSearch.
Перейдите в директорию, содержащую дистрибутив, и выполните следующую команду:
sudo dpkg -i opensearch-dashboards-3.1.0-linux-x64.deb
Чтобы обновить до последней версии OpenSearch Dashboards с помощью apt-get, выполните следующую команду:
sudo apt-get upgrade opensearch-dashboards
Вы также можете обновить до конкретной версии OpenSearch Dashboards, указав номер версии:
sudo apt-get upgrade opensearch-dashboards=<version>
Чтобы автоматически перезапустить OpenSearch Dashboards после обновления пакета, включите службу opensearch-dashboards.service через systemd:
sudo systemctl enable opensearch-dashboards.service
| Настройка | Описание |
|---|---|
server.ssl.enabled |
Включает SSL-соединение между сервером OpenSearch Dashboards и веб-браузером пользователя. Установите значение true для HTTPS или false для HTTP. |
server.ssl.supportedProtocols |
Указывает массив поддерживаемых протоколов TLS. Возможные значения: TLSv1, TLSv1.1, TLSv1.2, TLSv1.3. По умолчанию: ['TLSv1.1', 'TLSv1.2', 'TLSv1.3']. |
server.ssl.cipherSuites |
Указывает массив шифров TLS. Необязательная настройка. |
server.ssl.certificate |
Если server.ssl.enabled установлено в true, указывает полный путь к действительному сертификату сервера Privacy Enhanced Mail (PEM) для OpenSearch Dashboards. Вы можете сгенерировать свой сертификат или получить его у центра сертификации (CA). |
server.ssl.key |
Если server.ssl.enabled установлено в true, указывает полный путь к ключу для вашего серверного сертификата, например, /usr/share/opensearch-dashboards-1.0.0/config/my-client-cert-key.pem. Вы можете сгенерировать свой сертификат или получить его у CA. |
server.ssl.keyPassphrase |
Устанавливает пароль для ключа. Удалите эту настройку, если у ключа нет пароля. Необязательная настройка. |
server.ssl.keystore.path |
Использует файл JKS (Java KeyStore) или PKCS12/PFX (Public-Key Cryptography Standards) вместо сертификата и ключа PEM. |
server.ssl.keystore.password |
Устанавливает пароль для хранилища ключей. Обязательная настройка. |
server.ssl.clientAuthentication |
Указывает режим аутентификации клиента TLS. Может быть одним из следующих: none, optional или required. Если установлено в required, ваш веб-браузер должен отправить действительный клиентский сертификат, подписанный CA, настроенным в server.ssl.certificateAuthorities. По умолчанию: none. |
server.ssl.certificateAuthorities |
Указывает полный путь к одному или нескольким сертификатам CA в массиве, которые выдают сертификат, используемый для аутентификации клиента. Обязательная настройка, если server.ssl.clientAuthentication установлено в optional или required. |
server.ssl.truststore.path |
Использует файл JKS или PKCS12/PFX trust store вместо сертификатов CA PEM. |
server.ssl.truststore.password |
Устанавливает пароль для trust store. Обязательная настройка. |
opensearch.ssl.verificationMode |
Устанавливает связь между OpenSearch и OpenSearch Dashboards. Допустимые значения: full, certificate или none. Рекомендуется использовать full, если TLS включен, что включает проверку имени хоста. certificate проверяет сертификат, но не имя хоста. none не выполняет никаких проверок (подходит для HTTP). По умолчанию: full. |
opensearch.ssl.certificateAuthorities |
Если opensearch.ssl.verificationMode установлено в full или certificate, указывает полный путь к одному или нескольким сертификатам CA в массиве, которые составляют доверенную цепочку для кластера OpenSearch. Например, вам может потребоваться включить корневой CA и промежуточный CA, если вы использовали промежуточный CA для выдачи ваших сертификатов администратора, клиента и узла. |
opensearch.ssl.truststore.path |
Использует файл trust store JKS или PKCS12/PFX вместо сертификатов CA PEM. |
opensearch.ssl.truststore.password |
Устанавливает пароль для trust store. Обязательная настройка. |
opensearch.ssl.alwaysPresentCertificate |
Отправляет клиентский сертификат в кластер OpenSearch, если установлено значение true, что необходимо, когда mTLS включен в OpenSearch. По умолчанию: false. |
opensearch.ssl.certificate |
Если opensearch.ssl.alwaysPresentCertificate установлено в true, указывает полный путь к действительному клиентскому сертификату для кластера OpenSearch. Вы можете сгенерировать свой сертификат или получить его у CA. |
opensearch.ssl.key |
Если opensearch.ssl.alwaysPresentCertificate установлено в true, указывает полный путь к ключу для клиентского сертификата. Вы можете сгенерировать свой сертификат или получить его у CA. |
opensearch.ssl.keyPassphrase |
Устанавливает пароль для ключа. Удалите эту настройку, если у ключа нет пароля. Необязательная настройка. |
opensearch.ssl.keystore.path |
Использует файл хранилища ключей JKS или PKCS12/PFX вместо сертификата и ключа PEM. |
opensearch.ssl.keystore.password |
Устанавливает пароль для хранилища ключей. Обязательная настройка. |
opensearch_security.cookie.secure |
Если TLS включен для OpenSearch Dashboards, измените эту настройку на true. Для HTTP установите значение false. |
opensearch_dashboards.ymlСледующая конфигурация opensearch_dashboards.yml показывает, как OpenSearch и OpenSearch Dashboards могут работать на одной машине с демонстрационной конфигурацией:
server.host: '0.0.0.0'
server.ssl.enabled: true
server.ssl.certificate: /usr/share/opensearch-dashboards/config/client-cert.pem
server.ssl.key: /usr/share/opensearch-dashboards/config/client-cert-key.pem
opensearch.hosts: ["https://localhost:9200"]
opensearch.ssl.verificationMode: full
opensearch.ssl.certificateAuthorities: [ "/usr/share/opensearch-dashboards/config/root-ca.pem", "/usr/share/opensearch-dashboards/config/intermediate-ca.pem" ]
opensearch.username: "kibanaserver"
opensearch.password: "kibanaserver"
opensearch.requestHeadersAllowlist: [ authorization,securitytenant ]
opensearch_security.multitenancy.enabled: true
opensearch_security.multitenancy.tenants.preferred: ["Private", "Global"]
opensearch_security.readonly_mode.roles: ["kibana_read_only"]
opensearch_security.cookie.secure: true
Если вы используете опцию установки через Docker, вы можете передать пользовательский файл opensearch_dashboards.yml в контейнер. Чтобы узнать больше, посетите страницу установки Docker.
После включения этих настроек и запуска приложения вы можете подключиться к OpenSearch Dashboards по адресу https://localhost:5601. Возможно, вам потребуется подтвердить предупреждение браузера, если ваши сертификаты самоподписанные. Чтобы избежать такого предупреждения (или полной несовместимости с браузером), рекомендуется использовать сертификаты от доверенного центра сертификации (CA).
Динамические настройки индекса — это настройки, которые вы можете обновлять в любое время. Вы можете настраивать динамические параметры OpenSearch через API настроек кластера. Для получения подробной информации смотрите раздел Обновление настроек кластера с помощью API.
При возможности используйте API настроек кластера; файл opensearch.yml локален для каждого узла, в то время как API применяет настройки ко всем узлам в кластере.
Некоторые операции являются статическими и требуют изменения конфигурационного файла opensearch.yml и перезапуска кластера. В общем, эти настройки относятся к сетевым параметрам, формированию кластера и локальной файловой системе. Чтобы узнать больше, смотрите раздел Формирование кластера.
Вы можете указывать переменные окружения следующими способами:
Вы можете указать переменные окружения в качестве аргументов, используя -E при запуске OpenSearch:
./opensearch -Ecluster.name=opensearch-cluster -Enode.name=opensearch-node1 -Ehttp.host=0.0.0.0 -Ediscovery.type=single-node
Вы можете настроить переменные окружения непосредственно в среде оболочки перед запуском OpenSearch, как показано в следующем примере:
export OPENSEARCH_JAVA_OPTS="-Xms2g -Xmx2g"
export OPENSEARCH_PATH_CONF="/etc/opensearch"
./opensearch
При запуске OpenSearch как службы, управляемой systemd, вы можете указать переменные окружения в файле службы, как показано в следующем примере:
# /etc/systemd/system/opensearch.service.d/override.conf
[Service]
Environment="OPENSEARCH_JAVA_OPTS=-Xms2g -Xmx2g"
Environment="OPENSEARCH_PATH_CONF=/etc/opensearch"
После создания или изменения файла перезагрузите конфигурацию systemd и перезапустите службу с помощью следующих команд:
sudo systemctl daemon-reload
sudo systemctl restart opensearch
При запуске OpenSearch в Docker вы можете указать переменные окружения, используя опцию -e с командой docker run, как показано в следующей команде:
docker run -e "OPENSEARCH_JAVA_OPTS=-Xms2g -Xmx2g" -e "OPENSEARCH_PATH_CONF=/usr/share/opensearch/config" opensearchproject/opensearch:latest
Первый шаг в изменении настройки — это просмотр текущих настроек, отправив следующий запрос:
GET _cluster/settings?include_defaults=true
Для более краткого резюме нестандартных настроек отправьте следующий запрос:
GET _cluster/settings
В API настроек кластера существуют три категории настроек: постоянные, временные и стандартные. Постоянные настройки сохраняются после перезапуска кластера. После перезапуска OpenSearch очищает временные настройки.
Если вы указываете одну и ту же настройку в нескольких местах, OpenSearch использует следующий порядок приоритета:
opensearch.ymlЧтобы изменить настройку, используйте API настроек кластера и укажите новое значение как постоянное или временное. Этот пример показывает форму плоских настроек:
PUT _cluster/settings
{
"persistent" : {
"action.auto_create_index" : false
}
}
Вы также можете использовать расширенную форму, которая позволяет вам копировать и вставлять из ответа GET и изменять существующие значения:
PUT _cluster/settings
{
"persistent": {
"action": {
"auto_create_index": false
}
}
}
Вы можете найти файл opensearch.yml по следующему пути:
/usr/share/opensearch/config/opensearch.yml/etc/opensearch/opensearch.ymlВы можете отредактировать переменную OPENSEARCH_PATH_CONF=/etc/opensearch, чтобы изменить расположение каталога конфигурации. Эта переменная берется из /etc/default/opensearch (для Debian-пакета) и /etc/sysconfig/opensearch (для RPM-пакета).
Если вы установите свою пользовательскую переменную OPENSEARCH_PATH_CONF, имейте в виду, что другие стандартные переменные окружения не будут загружены.
В файле opensearch.yml вы не помечаете настройки как постоянные или временные, и настройки используют плоскую форму:
cluster.name: my-application
action.auto_create_index: true
compatibility.override_main_response_version: true
Демонстрационная конфигурация включает в себя ряд настроек для плагина безопасности, которые вы должны изменить перед использованием OpenSearch для производственной нагрузки. Чтобы узнать больше, смотрите раздел Безопасность.
Если вы работаете над клиентским приложением, которое взаимодействует с кластером OpenSearch на другом домене, вы можете настроить заголовки в opensearch.yml, чтобы разрешить разработку локального приложения на той же машине. Используйте механизм Cross Origin Resource Sharing (CORS), чтобы ваше приложение могло делать вызовы к API OpenSearch, работающему локально. Добавьте следующие строки в ваш файл custom-opensearch.yml (обратите внимание, что символ “-” должен быть первым символом в каждой строке):
- http.host: 0.0.0.0
- http.port: 9200
- http.cors.allow-origin: "http://localhost"
- http.cors.enabled: true
- http.cors.allow-headers: X-Requested-With,X-Auth-Token,Content-Type,Content-Length,Authorization
- http.cors.allow-credentials: true
Чтобы узнать больше о статических и динамических настройках, см. Настройка OpenSearch.
OpenSearch поддерживает следующие настройки снимков:
Для настроек снимков, связанных с безопасностью, см. Настройки безопасности.
Для получения информации о настройках файловой системы см. Общая файловая система.
Для получения информации о настройках репозитория Amazon S3 см. Amazon S3.
Для получения информации о настройках ограничения задач менеджера кластера см. Установка пределов ограничения.
OpenSearch поддерживает следующие настройки хранения с удаленной поддержкой на уровне кластера:
cluster.remote_store.translog.buffer_interval (Динамическое, единица времени): Значение по умолчанию для интервала буфера транзакционного лога, используемого при выполнении периодических обновлений транзакционного лога. Эта настройка эффективна только в том случае, если настройка индекса index.remote_store.translog.buffer_interval отсутствует.
remote_store.moving_average_window_size (Динамическое, целое число): Размер окна скользящего среднего, используемый для расчета значений скользящей статистики, доступных через API статистики удаленного хранилища. По умолчанию 20. Минимально допустимое значение - 5.
Для получения дополнительной информации о настройках хранения с удаленной поддержкой см. Хранение с удаленной поддержкой и Настройка хранения с удаленной поддержкой.
Для получения информации о настройках обратного давления сегментов см. Настройки обратного давления сегментов.
Обратное давление при поиске - это механизм, используемый для выявления ресурсоемких запросов на поиск и их отмены, когда узел испытывает нагрузку. Для получения дополнительной информации см. Настройки обратного давления при поиске.
Обратное давление при индексации шардов - это механизм умного отклонения на уровне шардов, который динамически отклоняет запросы на индексацию, когда ваш кластер испытывает нагрузку. Для получения дополнительной информации см. Настройки обратного давления при индексации шардов.
Для получения информации о настройках репликации сегментов см. Репликация сегментов.
Для получения информации о настройках обратного давления репликации сегментов см. Обратное давление репликации сегментов.
Для получения информации о настройках репликации между кластерами см. Настройки репликации.
Для получения обзора создания кластера OpenSearch и примеров настроек конфигурации см. раздел Создание кластера. Чтобы узнать больше о статических и динамических настройках, см. раздел Настройка OpenSearch.
OpenSearch поддерживает следующие системные настройки:
cluster.name (Статическая, строка): Имя кластера.
node.name (Статическая, строка): Описательное имя для узла.
node.roles (Статическая, список): Определяет одну или несколько ролей для узла OpenSearch. Допустимые значения: cluster_manager, data, ingest, search, ml, remote_cluster_client и coordinating_only.
path.data (Статическая, строка): Путь к директории, где хранятся ваши данные. Разделяйте несколько местоположений запятыми.
path.logs (Статическая, строка): Путь к файлам журналов.
bootstrap.memory_lock (Статическая, логическое): Блокирует память при запуске. Рекомендуется установить размер кучи примерно на половину доступной памяти в системе и убедиться, что владелец процесса имеет право использовать этот лимит. OpenSearch работает неэффективно, когда система использует свопинг памяти.
Чтобы узнать больше о статических и динамических настройках, см. раздел Настройка OpenSearch.
OpenSearch поддерживает следующие общие сетевые настройки:
network.host (Статическая, список): Привязывает узел OpenSearch к адресу. Используйте 0.0.0.0, чтобы включить все доступные сетевые интерфейсы, или укажите IP-адрес, назначенный конкретному интерфейсу. Настройка network.host является комбинацией network.bind_host и network.publish_host, если они имеют одинаковое значение. Альтернативой network.host является отдельная настройка network.bind_host и network.publish_host по мере необходимости. См. раздел Расширенные сетевые настройки.
http.port (Статическая, одно значение или диапазон): Привязывает узел OpenSearch к пользовательскому порту или диапазону портов для HTTP-связи. Вы можете указать адрес или диапазон адресов. По умолчанию — 9200-9300.
transport.port (Статическая, одно значение или диапазон): Привязывает узел OpenSearch к пользовательскому порту для связи между узлами. Вы можете указать адрес или диапазон адресов. По умолчанию — 9300-9400.
OpenSearch поддерживает следующие расширенные сетевые настройки:
network.bind_host (Статическая, список): Привязывает узел OpenSearch к адресу или адресам для входящих соединений. По умолчанию — значение из network.host.
network.publish_host (Статическая, список): Указывает адрес или адреса, которые узел OpenSearch публикует для других узлов в кластере, чтобы они могли подключиться к нему.
OpenSearch поддерживает следующие расширенные сетевые настройки для HTTP-связи:
http.host (Статическая, список): Устанавливает адрес узла OpenSearch для HTTP-связи. Настройка http.host является комбинацией http.bind_host и http.publish_host, если они имеют одинаковое значение. Альтернативой http.host является отдельная настройка http.bind_host и http.publish_host по мере необходимости.
http.bind_host (Статическая, список): Указывает адрес или адреса, к которым узел OpenSearch привязывается для прослушивания входящих HTTP-соединений.
http.publish_host (Статическая, список): Указывает адрес или адреса, которые узел OpenSearch публикует для других узлов для HTTP-связи.
http.compression (Статическая, логическое): Включает поддержку сжатия с использованием Accept-Encoding, когда это применимо. Когда включен HTTPS, по умолчанию — false, в противном случае — true. Отключение сжатия для HTTPS помогает снизить потенциальные риски безопасности, такие как атаки BREACH. Чтобы включить сжатие для HTTPS-трафика, явно установите http.compression в true.
http.max_header_size (Статическая, строка): Максимальный общий размер всех HTTP-заголовков, разрешенный в запросе. По умолчанию — 16KB.
OpenSearch поддерживает следующие расширенные сетевые настройки для транспортной связи:
transport.host (Статическая, список): Устанавливает адрес узла OpenSearch для транспортной связи. Настройка transport.host является комбинацией transport.bind_host и transport.publish_host, если они имеют одинаковое значение. Альтернативой transport.host является отдельная настройка transport.bind_host и transport.publish_host по мере необходимости.
transport.bind_host (Статическая, список): Указывает адрес или адреса, к которым узел OpenSearch привязывается для прослушивания входящих транспортных соединений.
transport.publish_host (Статическая, список): Указывает адрес или адреса, которые узел OpenSearch публикует для других узлов для транспортной связи.OpenSearch использует настройки HTTP для конфигурации связи с внешними клиентами через REST API и транспортные настройки для внутренней связи между узлами в OpenSearch.
По умолчанию OpenSearch использует транспорт, предоставляемый модулем transport-netty4, который использует движок Netty 4 как для внутренней TCP-связи между узлами в кластере, так и для внешней HTTP-связи с клиентами. Эта связь полностью асинхронна и неблокирующая. В следующей таблице перечислены другие доступные плагины транспорта, которые могут использоваться взаимозаменяемо.
| Плагин | Описание |
|---|---|
| transport-reactor-netty4 | HTTP-транспорт OpenSearch на основе Project Reactor и Netty 4 (экспериментальный) |
./bin/opensearch-plugin install transport-reactor-netty4
http.type: reactor-netty4
http.type: reactor-netty4-secure
Чтобы узнать больше о статических и динамических настройках, см. раздел Настройка OpenSearch.
Процесс обнаружения используется при формировании кластера. Он включает в себя обнаружение узлов и выбор узла-менеджера кластера. OpenSearch поддерживает следующие настройки обнаружения:
discovery.seed_hosts (Статическая, список): Список хостов, которые выполняют обнаружение при запуске узла. По умолчанию список хостов: ["127.0.0.1", "[::1]"].
discovery.seed_providers (Статическая, список): Указывает типы провайдеров начальных хостов, которые будут использоваться для получения адресов начальных узлов с целью запуска процесса обнаружения.
discovery.type (Статическая, строка): По умолчанию OpenSearch формирует кластер с несколькими узлами. Установите discovery.type в single-node, чтобы сформировать кластер с одним узлом.
cluster.initial_cluster_manager_nodes (Статическая, список): Список узлов, имеющих право быть узлами-менеджерами кластера, используемых для начальной загрузки кластера.
Локальный шлюз хранит состояние кластера и данные шардов, которые используются при перезапуске кластера. OpenSearch поддерживает следующие настройки локального шлюза:
gateway.recover_after_nodes (Статическая, целое число): После полного перезапуска кластера количество узлов, которые должны присоединиться к кластеру, прежде чем может начаться восстановление.
gateway.recover_after_data_nodes (Статическая, целое число): После полного перезапуска кластера количество узлов данных, которые должны присоединиться к кластеру, прежде чем может начаться восстановление.
gateway.expected_data_nodes (Статическая, целое число): Ожидаемое количество узлов данных, которые должны существовать в кластере. После того как ожидаемое количество узлов присоединится к кластеру, может начаться восстановление локальных шардов.
gateway.recover_after_time (Статическая, значение времени): Количество времени, которое нужно подождать перед началом восстановления, если количество узлов данных меньше ожидаемого количества узлов данных.
Для полного списка файлов конфигурации плагина безопасности см. раздел Изменение файлов YAML.
Следующие разделы описывают настройки, связанные с безопасностью, в файле opensearch.yml. Вы можете найти opensearch.yml в <OPENSEARCH_HOME>/config/opensearch.yml. Чтобы узнать больше о статических и динамических настройках, см. раздел Настройка OpenSearch.
Плагин безопасности поддерживает следующие общие настройки:
plugins.security.nodes_dn (Статическая): Указывает список отличительных имен (DN), обозначающих другие узлы в кластере. Эта настройка поддерживает подстановочные знаки и регулярные выражения. Список DN также считывается из индекса безопасности, помимо конфигурации YAML, когда plugins.security.nodes_dn_dynamic_config_enabled установлено в true. Если эта настройка не настроена правильно, кластер не сможет сформироваться, так как узлы не смогут доверять друг другу, что приведет к следующей ошибке: “Аутентификация транспортного клиента больше не поддерживается”.
plugins.security.nodes_dn_dynamic_config_enabled (Статическая): Актуально для сценариев использования кросс-кластера, где необходимо управлять разрешенными узлами DN без необходимости перезапускать узлы каждый раз, когда настраивается новый удаленный кросс-кластер. Установка nodes_dn_dynamic_config_enabled в true включает доступные для супер-администратора API для отличительных имен, которые предоставляют средства для динамического обновления или получения узлов DN. Эта настройка имеет эффект только если plugins.security.cert.intercluster_request_evaluator_class не установлено. По умолчанию — false.
plugins.security.authcz.admin_dn (Статическая): Определяет DN сертификатов, к которым должны быть назначены административные привилегии. Обязательно.
plugins.security.roles_mapping_resolution (Статическая): Определяет, как бэкенд-ролям сопоставляются роли безопасности. Поддерживаются следующие значения:
roles_mapping.yml.roles_mapping.yml не имеют эффекта.roles_mapping.yml.plugins.security.dls.mode (Статическая): Устанавливает режим оценки безопасности на уровне документа (DLS). По умолчанию — адаптивный. См. раздел Как установить режим оценки DLS.
plugins.security.compliance.salt (Статическая): Соль, используемая при генерации хеш-значения для маскирования полей. Должна содержать не менее 32 символов. Разрешены только ASCII-символы. Необязательно.
plugins.security.compliance.immutable_indices (Статическая): Документы в индексах, помеченных как неизменяемые, следуют парадигме “запись один раз, чтение много раз”. Документы, созданные в этих индексах, не могут быть изменены и, следовательно, являются неизменяемыми.
config.dynamic.http.anonymous_auth_enabled (Статическая): Включает анонимную аутентификацию. Это приведет к тому, что все HTTP-аутентификаторы не будут вызывать запросы на аутентификацию. По умолчанию — false.
http.detailed_errors.enabled (Статическая): Включает подробное сообщение об ошибке для REST-вызовов, выполненных против кластера OpenSearch. Если установлено в true, предоставляет root_cause вместе с кодом ошибки. По умолчанию — true.
Плагин безопасности поддерживает следующие настройки API управления REST:
plugins.security.restapi.roles_enabled (Статическая): Включает доступ к API управления REST на основе ролей для указанных ролей. Роли разделяются запятой. По умолчанию — пустой список (ни одна роль не имеет доступа к API управления REST). См. раздел Контроль доступа для API.
plugins.security.restapi.endpoints_disabled.plugins.security.restapi.endpoints_disabled.all_access.ACTIONGROUPS: ["PUT","POST","DELETE"]. По умолчанию все конечные точки и методы разрешены. Существующие конечные точки включают ACTIONGROUPS, CACHE, CONFIG, ROLES, ROLESMAPPING, INTERNALUSERS, SYSTEMINFO, PERMISSIONSINFO и LICENSE. См. раздел Контроль доступа для API.
plugins.security.restapi.password_validation_regex (Статическая): Указывает регулярное выражение для задания критериев для пароля при входе. Для получения дополнительной информации см. раздел Настройки пароля.
plugins.security.restapi.password_validation_error_message (Статическая): Указывает сообщение об ошибке, которое отображается, когда пароль не проходит проверку. Эта настройка используется вместе с plugins.security.restapi.password_validation_regex.
plugins.security.restapi.password_min_length (Статическая): Устанавливает минимальное количество символов для длины пароля при использовании оценщика силы пароля на основе баллов. По умолчанию — 8. Это также является минимальным значением. Для получения дополнительной информации см. раздел Настройки пароля.
plugins.security.restapi.password_score_based_validation_strength (Статическая): Устанавливает порог для определения, является ли пароль сильным или слабым. Допустимые значения: fair, good, strong и very_strong. Эта настройка используется вместе с plugins.security.restapi.password_min_length.
plugins.security.unsupported.restapi.allow_securityconfig_modification (Статическая): Включает использование методов PUT и PATCH для API конфигурации.
Плагин безопасности поддерживает следующие расширенные настройки:
plugins.security.authcz.impersonation_dn (Статическая): Включает подмену на уровне транспортного слоя. Это позволяет DN выдавать себя за других пользователей. См. раздел Подмена пользователей.
plugins.security.authcz.rest_impersonation_user (Статическая): Включает подмену на уровне REST. Это позволяет пользователям выдавать себя за других пользователей. См. раздел Подмена пользователей.
plugins.security.allow_default_init_securityindex (Статическая): При установке в true OpenSearch Security автоматически инициализирует индекс конфигурации с файлами из директории /config, если индекс не существует.
Это будет использовать известные стандартные пароли. Используйте только в частной сети/окружении.
plugins.security.allow_unsafe_democertificates (Статическая): При установке в true OpenSearch запускается с демонстрационными сертификатами. Эти сертификаты выданы только для демонстрационных целей.
Эти сертификаты хорошо известны и, следовательно, небезопасны для использования в производственной среде. Используйте только в частной сети/окружении.
plugins.security.system_indices.permission.enabled (Статическая): Включает функцию разрешений для системных индексов. При установке в true функция включена, и пользователи с разрешением на изменение ролей могут создавать роли, которые включают разрешения, предоставляющие доступ к системным индексам. При установке в false разрешение отключено, и только администраторы с административным сертификатом могут вносить изменения в системные индексы. По умолчанию разрешение установлено в false в новом кластере.
Настройки уровня эксперта должны настраиваться и развертываться только администратором, который полностью понимает данную функцию. Неправильное понимание функции может привести к рискам безопасности, неправильной работе плагина безопасности или потере данных.
Плагин безопасности поддерживает следующие настройки уровня эксперта:
plugins.security.config_index_name (Статическая): Имя индекса, в котором .opendistro_security хранит свою конфигурацию.
plugins.security.cert.oid (Статическая): Определяет идентификатор объекта (OID) сертификатов узлов сервера.
plugins.security.cert.intercluster_request_evaluator_class (Статическая): Указывает реализацию org.opensearch.security.transport.InterClusterRequestEvaluator, которая используется для оценки межкластерных запросов. Экземпляры org.opensearch.security.transport.InterClusterRequestEvaluator должны реализовывать конструктор с одним аргументом, принимающим объект org.opensearch.common.settings.Settings.
plugins.security.enable_snapshot_restore_privilege (Статическая): При установке в false эта настройка отключает восстановление снимков для обычных пользователей. В этом случае принимаются только запросы на восстановление снимков, подписанные административным TLS-сертификатом. При установке в true (по умолчанию) обычные пользователи могут восстанавливать снимки, если у них есть привилегии cluster:admin/snapshot/restore, indices:admin/create и indices:data/write/index.
Снимок можно восстановить только в том случае, если он не содержит глобального состояния и не восстанавливает индекс .opendistro_security.
plugins.security.check_snapshot_restore_write_privileges (Статическая): При установке в false дополнительные проверки индекса пропускаются. При установке по умолчанию в true попытки восстановить снимки оцениваются на наличие привилегий indices:admin/create и indices:data/write/index.
plugins.security.cache.ttl_minutes (Статическая): Определяет, как долго кэш аутентификации будет действителен. Кэш аутентификации помогает ускорить аутентификацию, временно храня объекты пользователей, возвращаемые из бэкенда, чтобы плагин безопасности не требовал повторных запросов к ним. Установите значение в минутах. По умолчанию — 60. Отключите кэширование, установив значение в 0.
plugins.security.disabled (Статическая): Отключает OpenSearch Security.
Отключение этого плагина может подвергнуть вашу конфигурацию (включая пароли) публичному доступу.
plugins.security.protected_indices.enabled (Статическая): Если установлено в true, включает защищенные индексы. Защищенные индексы более безопасны, чем обычные индексы. Эти индексы требуют роли для доступа, как и любой другой традиционный индекс, и требуют дополнительной роли для видимости. Эта настройка используется вместе с настройками plugins.security.protected_indices.roles и plugins.security.protected_indices.indices.
plugins.security.protected_indices.roles (Статическая): Указывает список ролей, к которым пользователь должен быть сопоставлен для доступа к защищенным индексам.
plugins.security.protected_indices.indices (Статическая): Указывает список индексов, которые следует пометить как защищенные. Эти индексы будут видны только пользователям, сопоставленным с ролями, указанными в plugins.security.protected_indices.roles. После выполнения этого требования пользователю все равно потребуется быть сопоставленным с традиционной ролью, используемой для предоставления разрешения на доступ к индексу.
plugins.security.system_indices.enabled (Статическая): Если установлено в true, включает системные индексы. Системные индексы аналогичны индексу безопасности, за исключением того, что их содержимое не зашифровано. Индексы, настроенные как системные индексы, могут быть доступны либо супер-администратором, либо пользователем с ролью, включающей разрешение на системный индекс. Для получения дополнительной информации о системных индексах см. раздел Системные индексы.
plugins.security.system_indices.indices (Статическая): Список индексов, которые будут использоваться как системные индексы. Эта настройка контролируется настройкой plugins.security.system_indices.enabled.
plugins.security.allow_default_init_securityindex (Статическая): При установке в true устанавливает плагин безопасности в его стандартные настройки безопасности, если попытка создать индекс безопасности завершается неудачей при запуске OpenSearch. Стандартные настройки безопасности хранятся в YAML-файлах, находящихся в директории opensearch-project/security/config. По умолчанию — false.
plugins.security.cert.intercluster_request_evaluator_class (Статическая): Класс, который будет использоваться для оценки межкластерной связи.
plugins.security.enable_snapshot_restore_privilege (Статическая): Включает предоставление привилегии восстановления снимков. Необязательно. По умолчанию — true.
plugins.security.check_snapshot_restore_write_privileges (Статическая): Обеспечивает оценку привилегий записи при создании снимков. По умолчанию — true.
Если вы измените любое из следующих свойств хеширования паролей, вам необходимо повторно хешировать все внутренние пароли для обеспечения совместимости и безопасности.
plugins.security.password.hashing.algorithm (Статическая): Указывает алгоритм хеширования паролей, который следует использовать. Поддерживаются следующие значения:
plugins.security.password.hashing.bcrypt.rounds (Статическая): Указывает количество раундов, используемых для хеширования паролей с помощью BCrypt. Допустимые значения находятся в диапазоне от 4 до 31, включая. По умолчанию — 12.
plugins.security.password.hashing.bcrypt.minor (Статическая): Указывает минорную версию алгоритма BCrypt, используемую для хеширования паролей. Поддерживаются следующие значения:
plugins.security.password.hashing.pbkdf2.function (Статическая): Указывает псевдослучайную функцию, применяемую к паролю. Поддерживаются следующие значения:
plugins.security.password.hashing.pbkdf2.iterations (Статическая): Указывает количество раз, которое псевдослучайная функция применяется к паролю. По умолчанию — 600,000.
plugins.security.password.hashing.pbkdf2.length (Статическая): Указывает желаемую длину окончательного производного ключа. По умолчанию — 256.
plugins.security.password.hashing.argon2.iterations (Статическая): Указывает количество проходов по памяти, которые выполняет алгоритм. Увеличение этого значения увеличивает время вычислений на ЦП и улучшает устойчивость к атакам грубой силы. По умолчанию — 3.
plugins.security.password.hashing.argon2.memory (Статическая): Указывает количество памяти (в кибибайтах), используемой во время хеширования. По умолчанию — 65536 (64 МиБ).
plugins.security.password.hashing.argon2.parallelism (Статическая): Указывает количество параллельных потоков, используемых для вычислений. По умолчанию — 1.
plugins.security.password.hashing.argon2.length (Статическая): Указывает длину (в байтах) результирующего хеш-выхода. По умолчанию — 32.
plugins.security.password.hashing.argon2.type (Статическая): Указывает, какой вариант Argon2 использовать. Поддерживаются следующие значения:
plugins.security.password.hashing.argon2.version (Статическая): Указывает, какую версию Argon2 использовать. Поддерживаются следующие значения:
Плагин безопасности поддерживает следующие настройки журнала аудита:
plugins.security.audit.enable_rest (Динамическая): Включает или отключает ведение журнала REST-запросов. По умолчанию установлено в true (включено).
plugins.security.audit.enable_transport (Динамическая): Включает или отключает ведение журнала запросов на уровне транспорта. По умолчанию установлено в false (выключено).
plugins.security.audit.resolve_bulk_requests (Динамическая): Включает или отключает ведение журнала пакетных запросов. При включении все подзапросы в пакетных запросах также записываются в журнал. По умолчанию установлено в false (выключено).
plugins.security.audit.config.disabled_categories (Динамическая): Отключает указанные категории событий.
plugins.security.audit.ignore_requests (Динамическая): Исключает указанные запросы из ведения журнала. Поддерживает подстановочные знаки и регулярные выражения, содержащие действия или пути REST-запросов.
plugins.security.audit.threadpool.size (Статическая): Определяет количество потоков в пуле потоков, используемом для ведения журнала событий. По умолчанию установлено в 10. Установка этого значения в 0 отключает пул потоков, что означает, что плагин ведет журнал событий синхронно.
plugins.security.audit.threadpool.max_queue_len (Статическая): Устанавливает максимальную длину очереди на поток. По умолчанию установлено в 100000.
plugins.security.audit.ignore_users (Динамическая): Массив пользователей. Запросы аудита от пользователей в списке не будут записываться в журнал.
plugins.security.audit.type (Статическая): Назначение событий журнала аудита. Допустимые значения: internal_opensearch, external_opensearch, debug и webhook.
plugins.security.audit.config.http_endpoints (Статическая): Список конечных точек для localhost.
plugins.security.audit.config.index (Статическая): Индекс журнала аудита. По умолчанию установлен auditlog6. Индекс может быть статическим или индексом, который включает дату, чтобы он вращался ежедневно, например, “‘auditlog6-‘YYYY.MM.dd”. В любом случае убедитесь, что индекс защищен должным образом.
plugins.security.audit.config.type (Статическая): Укажите тип журнала аудита как auditlog.
plugins.security.audit.config.username (Статическая): Имя пользователя для конфигурации журнала аудита.
plugins.security.audit.config.password (Статическая): Пароль для конфигурации журнала аудита.
plugins.security.audit.config.enable_ssl (Статическая): Включает или отключает SSL для ведения журнала аудита.
plugins.security.audit.config.verify_hostnames (Статическая): Включает или отключает проверку имени хоста для SSL/TLS сертификатов. По умолчанию установлено в true (включено).
plugins.security.audit.config.enable_ssl_client_auth (Статическая): Включает или отключает аутентификацию клиента SSL/TLS. По умолчанию установлено в false (выключено).
plugins.security.audit.config.cert_alias (Статическая): Псевдоним для сертификата, используемого для доступа к журналу аудита.
plugins.security.audit.config.pemkey_filepath (Статическая): Относительный путь к файлу ключа Privacy Enhanced Mail (PEM), используемого для ведения журнала аудита.
plugins.security.audit.config.pemkey_content (Статическая): Содержимое PEM-ключа, закодированное в base64, используемого для ведения журнала аудита. Это альтернатива …config.pemkey_filepath.
plugins.security.audit.config.pemkey_password (Статическая): Пароль для частного ключа в формате PEM, используемого клиентом.
plugins.security.audit.config.pemcert_filepath (Статическая): Относительный путь к файлу PEM-сертификата, используемого для ведения журнала аудита.
plugins.security.audit.config.pemcert_content (Статическая): Содержимое PEM-сертификата, закодированное в base64, используемого для ведения журнала аудита. Это альтернатива указанию пути к файлу с помощью …config.pemcert_filepath.
plugins.security.audit.config.pemtrustedcas_filepath (Статическая): Относительный путь к файлу доверенного корневого центра сертификации.
plugins.security.audit.config.pemtrustedcas_content (Статическая): Содержимое корневого центра сертификации, закодированное в base64. Это альтернатива …config.pemtrustedcas_filepath.
plugins.security.audit.config.webhook.url (Статическая): URL вебхука.
plugins.security.audit.config.webhook.format (Статическая): Формат, используемый для вебхука. Допустимые значения: URL_PARAMETER_GET, URL_PARAMETER_POST, TEXT, JSON и SLACK.
plugins.security.audit.config.webhook.ssl.verify (Статическая): Включает или отключает проверку любых SSL/TLS сертификатов, отправленных с любым запросом вебхука. По умолчанию установлено в true (включено).
plugins.security.audit.config.webhook.ssl.pemtrustedcas_filepath (Статическая): Относительный путь к файлу доверенного центра сертификации, против которого проверяются запросы вебхука.
plugins.security.audit.config.webhook.ssl.pemtrustedcas_content (Статическая): Содержимое центра сертификации, используемого для проверки запросов вебхука, закодированное в base64. Это альтернатива …config.pemtrustedcas_filepath.
plugins.security.audit.config.log4j.logger_name (Статическая): Пользовательское имя для логгера Log4j.
plugins.security.audit.config.log4j.level (Статическая): Устанавливает уровень журнала по умолчанию для логгера Log4j. Допустимые значения: OFF, FATAL, ERROR, WARN, INFO, DEBUG, TRACE и ALL. По умолчанию установлено в INFO.
opendistro_security.audit.config.disabled_rest_categories (Динамическая): Список категорий REST, которые будут игнорироваться логгером. Допустимые значения: AUTHENTICATED и GRANTED_PRIVILEGES.
opendistro_security.audit.config.disabled_transport_categories (Динамическая): Список категорий на транспортном уровне, которые будут игнорироваться логгером. Допустимые значения: AUTHENTICATED и GRANTED_PRIVILEGES.
Плагин безопасности поддерживает следующие настройки проверки имени хоста и DNS:
plugins.security.ssl.transport.enforce_hostname_verification (Статическая): Указывает, следует ли проверять имена хостов на транспортном уровне. Необязательно. По умолчанию установлено в true.
plugins.security.ssl.transport.resolve_hostname (Статическая): Указывает, следует ли разрешать имена хостов через DNS на транспортном уровне. Необязательно. По умолчанию установлено в true. Работает только если включена проверка имени хоста.
Для получения дополнительной информации см. раздел Проверка имени хоста и разрешение DNS.
Плагин безопасности поддерживает следующую настройку аутентификации клиента:
Для получения дополнительной информации см. раздел Аутентификация клиента.
Плагин безопасности поддерживает следующие настройки включенных шифров и протоколов. Каждая настройка должна быть выражена в массиве:
plugins.security.ssl.http.enabled_ciphers (Статическая): Включенные шифры TLS для REST-уровня. Поддерживается только формат Java.
plugins.security.ssl.http.enabled_protocols (Статическая): Включенные протоколы TLS для REST-уровня. Поддерживается только формат Java.
plugins.security.ssl.transport.enabled_ciphers (Статическая): Включенные шифры TLS для транспортного уровня. Поддерживается только формат Java.
plugins.security.ssl.transport.enabled_protocols (Статическая): Включенные протоколы TLS для транспортного уровня. Поддерживается только формат Java.
Для получения дополнительной информации см. раздел Включенные шифры и протоколы.
Плагин безопасности поддерживает следующие настройки хранилища ключей и доверенных сертификатов для транспортного уровня TLS:
plugins.security.ssl.transport.keystore_type (Статическая): Тип файла хранилища ключей. Необязательно. Допустимые значения: JKS или PKCS12/PFX. По умолчанию установлено в JKS.
plugins.security.ssl.transport.keystore_filepath (Статическая): Путь к файлу хранилища ключей, который должен находиться в каталоге конфигурации и указываться с использованием относительного пути. Обязательно.
plugins.security.ssl.transport.keystore_alias (Статическая): Имя псевдонима хранилища ключей. Необязательно. По умолчанию используется первый псевдоним.
plugins.security.ssl.transport.keystore_password (Статическая): Пароль для хранилища ключей. По умолчанию установлено в changeit.
plugins.security.ssl.transport.truststore_type (Статическая): Тип файла доверенного хранилища. Необязательно. Допустимые значения: JKS или PKCS12/PFX. По умолчанию установлено в JKS.
plugins.security.ssl.transport.truststore_filepath (Статическая): Путь к файлу доверенного хранилища, который должен находиться в каталоге конфигурации и указываться с использованием относительного пути. Обязательно.
plugins.security.ssl.transport.truststore_alias (Статическая): Имя псевдонима доверенного хранилища. Необязательно. По умолчанию используются все сертификаты.
plugins.security.ssl.transport.truststore_password (Статическая): Пароль для доверенного хранилища. По умолчанию установлено в changeit.
Для получения дополнительной информации о файлах хранилища ключей и доверенных сертификатов см. раздел TLS на транспортном уровне.
Плагин безопасности поддерживает следующие настройки хранилища ключей и доверенных сертификатов для уровня REST TLS:
plugins.security.ssl.http.enabled (Статическая): Указывает, следует ли включить TLS на уровне REST. Если включено, разрешен только HTTPS. Необязательно. По умолчанию установлено в false.
plugins.security.ssl.http.keystore_type (Статическая): Тип файла хранилища ключей. Необязательно. Допустимые значения: JKS или PKCS12/PFX. По умолчанию установлено в JKS.
plugins.security.ssl.http.keystore_filepath (Статическая): Путь к файлу хранилища ключей, который должен находиться в каталоге конфигурации и указываться с использованием относительного пути. Обязательно.
plugins.security.ssl.http.keystore_alias (Статическая): Имя псевдонима хранилища ключей. Необязательно. По умолчанию используется первый псевдоним.
plugins.security.ssl.http.keystore_password (Статическая): Пароль для хранилища ключей. По умолчанию установлено в changeit.
plugins.security.ssl.http.truststore_type (Статическая): Тип файла доверенного хранилища. Необязательно. Допустимые значения: JKS или PKCS12/PFX. По умолчанию установлено в JKS.
plugins.security.ssl.http.truststore_filepath (Статическая): Путь к файлу доверенного хранилища, который должен находиться в каталоге конфигурации и указываться с использованием относительного пути. Обязательно.
plugins.security.ssl.http.truststore_alias (Статическая): Имя псевдонима доверенного хранилища. Необязательно. По умолчанию используются все сертификаты.
plugins.security.ssl.http.truststore_password (Статическая): Пароль для доверенного хранилища. По умолчанию установлено в changeit.
Для получения дополнительной информации см. раздел TLS на уровне REST.
Плагин безопасности поддерживает следующие настройки TLS на транспортном уровне, связанные с X.509 PEM-сертификатами и ключами PKCS #8:
plugins.security.ssl.transport.pemkey_filepath (Статическая): Путь к файлу ключа сертификата (PKCS #8), который должен находиться в каталоге конфигурации и указываться с использованием относительного пути. Обязательно.
plugins.security.ssl.transport.pemkey_password (Статическая): Пароль для ключа. Укажите эту настройку, если у ключа есть пароль. Необязательно.
plugins.security.ssl.transport.pemcert_filepath (Статическая): Путь к цепочке сертификатов узла X.509 (формат PEM), который должен находиться в каталоге конфигурации и указываться с использованием относительного пути. Обязательно.
plugins.security.ssl.transport.pemtrustedcas_filepath (Статическая): Путь к корневым центрам сертификации (формат PEM), который должен находиться в каталоге конфигурации и указываться с использованием относительного пути. Обязательно.
Для получения дополнительной информации см. раздел TLS на транспортном уровне.
Плагин безопасности поддерживает следующие настройки TLS на уровне REST, связанные с X.509 PEM-сертификатами и ключами PKCS #8:
plugins.security.ssl.http.enabled (Статическая): Указывает, следует ли включить TLS на уровне REST. Если включено, разрешен только HTTPS. Необязательно. По умолчанию установлено в false.
plugins.security.ssl.http.pemkey_filepath (Статическая): Путь к файлу ключа сертификата (PKCS #8), который должен находиться в каталоге конфигурации и указываться с использованием относительного пути. Обязательно.
plugins.security.ssl.http.pemkey_password (Статическая): Пароль для ключа. Укажите эту настройку, если у ключа есть пароль. Необязательно.
plugins.security.ssl.http.pemcert_filepath (Статическая): Путь к цепочке сертификатов узла X.509 (формат PEM), который должен находиться в каталоге конфигурации и указываться с использованием относительного пути. Обязательно.
plugins.security.ssl.http.pemtrustedcas_filepath (Статическая): Путь к корневым центрам сертификации (формат PEM), который должен находиться в каталоге конфигурации и указываться с использованием относительного пути. Обязательно.
Для получения дополнительной информации см. раздел TLS на уровне REST.
Плагин безопасности поддерживает следующие настройки безопасности на транспортном уровне:
plugins.security.ssl.transport.enabled (Статическая): Указывает, следует ли включить TLS на уровне REST.
plugins.security.ssl.transport.client.pemkey_password (Статическая): Пароль для частного ключа в формате PEM, используемого клиентом на транспортном уровне.
plugins.security.ssl.transport.keystore_keypassword (Статическая): Пароль для ключа внутри хранилища ключей.
plugins.security.ssl.transport.server.keystore_keypassword (Статическая): Пароль для ключа внутри хранилища ключей сервера.
plugins.security.ssl.transport.server.keystore_alias (Статическая): Имя псевдонима для хранилища ключей сервера.
plugins.security.ssl.transport.client.keystore_alias (Статическая): Имя псевдонима для хранилища ключей клиента.
plugins.security.ssl.transport.server.truststore_alias (Статическая): Имя псевдонима для доверенного хранилища сервера.
plugins.security.ssl.transport.client.truststore_alias (Статическая): Имя псевдонима для доверенного хранилища клиента.
plugins.security.ssl.client.external_context_id (Статическая): Предоставляет клиенту на транспортном уровне идентификатор для использования внешнего SSL-контекста.
plugins.security.ssl.transport.principal_extractor_class (Статическая): Указывает класс, реализующий извлечение, чтобы использовать пользовательскую часть сертификата в качестве основного.
plugins.security.ssl.http.crl.file_path (Статическая): Путь к файлу списка отозванных сертификатов (CRL).
plugins.security.ssl.http.crl.validate (Статическая): Включает проверку списка отозванных сертификатов (CRL). По умолчанию установлено в false (выключено).
plugins.security.ssl.http.crl.prefer_crlfile_over_ocsp (Статическая): Указывает, следует ли предпочитать запись сертификата CRL перед записью протокола статуса сертификата в режиме онлайн (OCSP), если сертификат содержит обе записи. Необязательно. По умолчанию установлено в false.
plugins.security.ssl.http.crl.check_only_end_entities (Статическая): Если установлено в true, проверяются только конечные сертификаты. По умолчанию установлено в true.
plugins.security.ssl.http.crl.disable_ocsp (Статическая): Отключает OCSP. По умолчанию установлено в false (OCSP включен).
plugins.security.ssl.http.crl.disable_crldp (Статическая): Отключает конечные точки CRL в сертификатах. По умолчанию установлено в false (конечные точки CRL включены).
plugins.security.ssl.allow_client_initiated_renegotiation (Статическая): Включает или отключает повторнуюNegotiation, инициированную клиентом. По умолчанию установлено в false (повторнаяNegotiation, инициированная клиентом, не разрешена).
# Common configuration settings
plugins.security.nodes_dn:
- "CN=*.example.com, OU=SSL, O=Test, L=Test, C=DE"
- "CN=node.other.com, OU=SSL, O=Test, L=Test, C=DE"
- "CN=node.example.com, OU=SSL\\, Inc., L=Test, C=DE" # escape additional comma with `\\`
plugins.security.authcz.admin_dn:
- CN=kirk,OU=client,O=client,L=test, C=de
plugins.security.roles_mapping_resolution: MAPPING_ONLY
plugins.security.ssl.transport.pemcert_filepath: esnode.pem
plugins.security.ssl.transport.pemkey_filepath: esnode-key.pem
plugins.security.ssl.transport.pemtrustedcas_filepath: root-ca.pem
plugins.security.ssl.transport.enforce_hostname_verification: false
plugins.security.ssl.http.enabled: true
plugins.security.ssl.http.pemcert_filepath: esnode.pem
plugins.security.ssl.http.pemkey_filepath: esnode-key.pem
plugins.security.ssl.http.pemtrustedcas_filepath: root-ca.pem
plugins.security.allow_unsafe_democertificates: true
plugins.security.allow_default_init_securityindex: true
plugins.security.nodes_dn_dynamic_config_enabled: false
plugins.security.cert.intercluster_request_evaluator_class: # need example value for this.
plugins.security.audit.type: internal_opensearch
plugins.security.enable_snapshot_restore_privilege: true
plugins.security.check_snapshot_restore_write_privileges: true
plugins.security.cache.ttl_minutes: 60
plugins.security.restapi.roles_enabled: ["all_access", "security_rest_api_access"]
plugins.security.system_indices.enabled: true
plugins.security.system_indices.indices: [".opendistro-alerting-config", ".opendistro-alerting-alert*", ".opendistro-anomaly-results*", ".opendistro-anomaly-detector*", ".opendistro-anomaly-checkpoints", ".opendistro-anomaly-detection-state", ".opendistro-reports-*", ".opendistro-notifications-*", ".opendistro-notebooks", ".opendistro-asynchronous-search-response*"]
node.max_local_storage_nodes: 3
plugins.security.restapi.password_validation_regex: '(?=.*[A-Z])(?=.*[^a-zA-Z\d])(?=.*[0-9])(?=.*[a-z]).{8,}'
plugins.security.restapi.password_validation_error_message: "Password must be minimum 8 characters long and must contain at least one uppercase letter, one lowercase letter, one digit, and one special character."
plugins.security.allow_default_init_securityindex: true
plugins.security.cache.ttl_minutes: 60
#
# REST Management API configuration settings
plugins.security.restapi.roles_enabled: ["all_access","xyz_role"]
plugins.security.restapi.endpoints_disabled.all_access.ACTIONGROUPS: ["PUT","POST","DELETE"] # Alternative example: plugins.security.restapi.endpoints_disabled.xyz_role.LICENSE: ["DELETE"] #
# Audit log configuration settings
plugins.security.audit.enable_rest: true
plugins.security.audit.enable_transport: false
plugins.security.audit.resolve_bulk_requests: false
plugins.security.audit.config.disabled_categories: ["AUTHENTICATED","GRANTED_PRIVILEGES"]
plugins.security.audit.ignore_requests: ["indices:data/read/*","*_bulk"]
plugins.security.audit.threadpool.size: 10
plugins.security.audit.threadpool.max_queue_len: 100000
plugins.security.audit.ignore_users: ['kibanaserver','some*user','/also.*regex possible/']
plugins.security.audit.type: internal_opensearch
#
# external_opensearch settings
plugins.security.audit.config.http_endpoints: ['localhost:9200','localhost:9201','localhost:9202']
plugins.security.audit.config.index: "'auditlog6-'2023.06.15"
plugins.security.audit.config.type: auditlog
plugins.security.audit.config.username: auditloguser
plugins.security.audit.config.password: auditlogpassword
plugins.security.audit.config.enable_ssl: false
plugins.security.audit.config.verify_hostnames: false
plugins.security.audit.config.enable_ssl_client_auth: false
plugins.security.audit.config.cert_alias: mycert
plugins.security.audit.config.pemkey_filepath: key.pem
plugins.security.audit.config.pemkey_content: <...pem base 64 content>
plugins.security.audit.config.pemkey_password: secret
plugins.security.audit.config.pemcert_filepath: cert.pem
plugins.security.audit.config.pemcert_content: <...pem base 64 content>
plugins.security.audit.config.pemtrustedcas_filepath: ca.pem
plugins.security.audit.config.pemtrustedcas_content: <...pem base 64 content>
#
# Webhook settings
plugins.security.audit.config.webhook.url: "http://mywebhook/endpoint"
plugins.security.audit.config.webhook.format: JSON
plugins.security.audit.config.webhook.ssl.verify: false
plugins.security.audit.config.webhook.ssl.pemtrustedcas_filepath: ca.pem
plugins.security.audit.config.webhook.ssl.pemtrustedcas_content: <...pem base 64 content>
#
# log4j settings
plugins.security.audit.config.log4j.logger_name: auditlogger
plugins.security.audit.config.log4j.level: INFO
#
# Advanced configuration settings
plugins.security.authcz.impersonation_dn:
"CN=spock,OU=client,O=client,L=Test,C=DE":
- worf
"cn=webuser,ou=IT,ou=IT,dc=company,dc=com":
- user2
- user1
plugins.security.authcz.rest_impersonation_user:
"picard":
- worf
"john":
- steve
- martin
plugins.security.allow_default_init_securityindex: false
plugins.security.allow_unsafe_democertificates: false
plugins.security.cache.ttl_minutes: 60
plugins.security.restapi.password_validation_regex: '(?=.*[A-Z])(?=.*[^a-zA-Z\d])(?=.*[0-9])(?=.*[a-z]).{8,}'
plugins.security.restapi.password_validation_error_message: "A password must be at least 8 characters long and contain at least one uppercase letter, one lowercase letter, one digit, and one special character."
plugins.security.restapi.password_min_length: 8
plugins.security.restapi.password_score_based_validation_strength: very_strong
#
# Advanced SSL settings - use only if you understand SSL ins and outs
plugins.security.ssl.transport.client.pemkey_password: superSecurePassword1
plugins.security.ssl.transport.keystore_keypassword: superSecurePassword2
plugins.security.ssl.transport.server.keystore_keypassword: superSecurePassword3
plugins.security.ssl.http.keystore_keypassword: superSecurePassword4
plugins.security.ssl.http.clientauth_mode: REQUIRE
plugins.security.ssl.transport.enabled: true
plugins.security.ssl.transport.server.keystore_alias: my_alias
plugins.security.ssl.transport.client.keystore_alias: my_other_alias
plugins.security.ssl.transport.server.truststore_alias: trustore_alias_1
plugins.security.ssl.transport.client.truststore_alias: trustore_alias_2
plugins.security.ssl.client.external_context_id: my_context_id
plugins.security.ssl.transport.principal_extractor_class: org.opensearch.security.ssl.ExampleExtractor
plugins.security.ssl.http.crl.file_path: ssl/crl/revoked.crl
plugins.security.ssl.http.crl.validate: true
plugins.security.ssl.http.crl.prefer_crlfile_over_ocsp: true
plugins.security.ssl.http.crl.check_only_end_entitites: false
plugins.security.ssl.http.crl.disable_ocsp: true
plugins.security.ssl.http.crl.disable_crldp: true
plugins.security.ssl.allow_client_initiated_renegotiation: true
#
# Expert settings - use only if you understand their use completely: accidental values can potentially cause security risks or failures to OpenSearch Security.
plugins.security.config_index_name: .opendistro_security
plugins.security.cert.oid: '1.2.3.4.5.5'
plugins.security.cert.intercluster_request_evaluator_class: org.opensearch.security.transport.DefaultInterClusterRequestEvaluator
plugins.security.enable_snapshot_restore_privilege: true
plugins.security.check_snapshot_restore_write_privileges: true
plugins.security.cache.ttl_minutes: 60
plugins.security.disabled: false
plugins.security.protected_indices.enabled: true
plugins.security.protected_indices.roles: ['all_access']
plugins.security.protected_indices.indices: []
plugins.security.system_indices.enabled: true
plugins.security.system_indices.indices: ['.opendistro-alerting-config', '.opendistro-ism-*', '.opendistro-reports-*', '.opensearch-notifications-*', '.opensearch-notebooks', '.opensearch-observability', '.opendistro-asynchronous-search-response*', '.replication-metadata-store']
Родительский предохранитель указывает общее доступное количество памяти для всех дочерних предохранителей. Дочерние предохранители указывают общее доступное количество памяти для себя.
Для получения дополнительной информации о статических и динамических настройках см. раздел Конфигурация OpenSearch.
OpenSearch поддерживает следующие настройки родительского предохранителя:
indices.breaker.total.use_real_memory (Статическая, логическая): Если установлено в true, родительский предохранитель учитывает фактическое использование памяти. В противном случае родительский предохранитель учитывает количество памяти, зарезервированной дочерними предохранителями. По умолчанию установлено в true.
indices.breaker.total.limit (Динамическая, процент): Указывает начальный лимит памяти для родительского предохранителя. Если indices.breaker.total.use_real_memory установлено в true, по умолчанию составляет 95% кучи JVM. Если indices.breaker.total.use_real_memory установлено в false, по умолчанию составляет 70% кучи JVM.
Предохранитель данных полей ограничивает объем памяти кучи, необходимый для загрузки поля в кэш данных полей. OpenSearch поддерживает следующие настройки предохранителя данных полей:
indices.breaker.fielddata.limit (Динамическая, процент): Указывает лимит памяти для предохранителя данных полей. По умолчанию составляет 40% кучи JVM.
indices.breaker.fielddata.overhead (Динамическая, дробное число): Константа, на которую умножаются оценки данных полей для определения окончательной оценки. По умолчанию составляет 1.03.
Предохранитель запросов ограничивает объем памяти, необходимый для построения структур данных, необходимых для запроса (например, при вычислении агрегатов). OpenSearch поддерживает следующие настройки предохранителя запросов:
indices.breaker.request.limit (Динамическая, процент): Указывает лимит памяти для предохранителя запросов. По умолчанию составляет 60% кучи JVM.
indices.breaker.request.overhead (Динамическая, дробное число): Константа, на которую умножаются оценки запросов для определения окончательной оценки. По умолчанию составляет 1.
Предохранитель текущих запросов ограничивает использование памяти для всех текущих входящих запросов на транспортном и HTTP-уровне. Использование памяти для запроса основано на длине содержимого запроса и включает память, необходимую для необработанного запроса и структурированного объекта, представляющего запрос. OpenSearch поддерживает следующие настройки предохранителя текущих запросов:
network.breaker.inflight_requests.limit (Динамическая, процент): Указывает лимит памяти для предохранителя текущих запросов. По умолчанию составляет 100% кучи JVM (таким образом, лимит использования памяти для текущего запроса определяется лимитом памяти родительского предохранителя).
network.breaker.inflight_requests.overhead (Динамическая, дробное число): Константа, на которую умножаются оценки текущих запросов для определения окончательной оценки. По умолчанию составляет 2.
Предохранитель компиляции скриптов ограничивает количество компиляций встроенных скриптов в течение временного интервала. OpenSearch поддерживает следующую настройку предохранителя компиляции скриптов:
Предохранитель регулярных выражений включает или отключает регулярные выражения и ограничивает их сложность. OpenSearch поддерживает следующие настройки предохранителя регулярных выражений:
script.painless.regex.enabled (Статическая, строка): Включает регулярные выражения в скриптах Painless. Допустимые значения:
По умолчанию установлено в limited.
script.painless.regex.limit-factor (Статическая, целое число): Применяется только если script.painless.regex.enabled установлено в limited. Ограничивает количество символов, которые может содержать регулярное выражение в скрипте Painless. Лимит символов рассчитывается путем умножения количества символов во входных данных скрипта на script.painless.regex.limit-factor. По умолчанию составляет 6 (таким образом, если входные данные содержат 5 символов, максимальное количество символов в регулярном выражении составляет 5 · 6 = 30).
Чтобы узнать больше о статических и динамических настройках, смотрите раздел Настройка OpenSearch.
OpenSearch поддерживает следующие настройки маршрутизации на уровне кластера и распределения шардов:
Включает или отключает распределение для определенных типов шардов.
Допустимые значения:
По умолчанию установлено значение all.
Настраивает, сколько параллельных входящих восстановлений шардов разрешено на узле. По умолчанию установлено значение 2.
Настраивает, сколько параллельных исходящих восстановлений шардов разрешено на узле. По умолчанию установлено значение 2.
Используется для установки значений cluster.routing.allocation.node_concurrent_incoming_recoveries и cluster.routing.allocation.node_concurrent_outgoing_recoveries на одно и то же значение.
Устанавливает количество восстановлений для нераспределенных первичных шардов после перезапуска узла. По умолчанию установлено значение 4.
При установке в true предотвращает распределение нескольких копий шарда на разные узлы на одном хосте. По умолчанию установлено значение false.
Включает или отключает перераспределение для определенных типов шардов.
Допустимые значения:
По умолчанию установлено значение all.
Указывает, когда разрешено перераспределение шардов.
Допустимые значения:
По умолчанию установлено значение indices_all_active.
Позволяет контролировать, сколько параллельных перераспределений шардов разрешено в кластере. По умолчанию установлено значение 2.
Определяет весовой коэффициент для общего количества шардов, распределенных на узел. По умолчанию установлено значение 0.45.
Определяет весовой коэффициент для количества шардов на индекс, распределенных на узел. По умолчанию установлено значение 0.55.
Минимальное значение оптимизации операций, которые должны быть выполнены. По умолчанию установлено значение 1.0.
При установке в true OpenSearch пытается равномерно распределить первичные шары между узлами кластера. Включение этой настройки не всегда гарантирует равное количество первичных шардов на каждом узле, особенно в случае сбоя. Изменение этой настройки на false после установки в true не вызывает перераспределение первичных шардов. По умолчанию установлено значение false.
При установке в true OpenSearch пытается перераспределить первичные шары между узлами кластера. При включении кластер пытается поддерживать количество первичных шардов на каждом узле, с максимальным буфером, определенным настройкой cluster.routing.allocation.rebalance.primary.buffer. Изменение этой настройки на false после установки в true не вызывает перераспределение первичных шардов. По умолчанию установлено значение false.
Определяет максимальный допустимый буфер первичных шардов между узлами, когда включена настройка cluster.routing.allocation.rebalance.primary.enable. По умолчанию установлено значение 0.1.
При установке в false отключает решение о распределении по диску. Это также удалит любые существующие блокировки индекса index.blocks.read_only_allow_delete, когда отключено. По умолчанию установлено значение true.
Контролирует низкий водяной знак для использования дискового пространства. При установке в процентном соотношении OpenSearch не будет распределять шары на узлы с указанным процентом использования диска. Это также можно указать в виде дробного значения, например, 0.85. Наконец, это можно установить в байтовом значении, например, 400mb. Эта настройка не влияет на первичные шары новых индексов, но предотвратит распределение их реплик. По умолчанию установлено значение 85%.
Контролирует высокий водяной знак. OpenSearch попытается переместить шары с узла, использование диска на котором превышает установленный процент. Это также можно указать в виде дробного значения, например, 0.85. Наконец, это можно установить в байтовом значении, например, 400mb. Эта настройка влияет на распределение всех шардов. По умолчанию установлено значение 90%.
Контролирует водяной знак на уровне затопления. Это последний шаг для предотвращения исчерпания дискового пространства на узлах. OpenSearch применяет блокировку индекса только для чтения (index.blocks.read_only_allow_delete) ко всем индексам, на которых есть один или несколько шардов, распределенных на узле, и хотя бы один диск превышает уровень затопления. Блокировка индекса снимается, как только использование диска падает ниже высокого водяного знака. Это также можно указать в виде дробного значения, например, 0.85. Наконец, это можно установить в байтовом значении, например, 400mb. По умолчанию установлено значение 95%.
Устанавливает, как часто OpenSearch должен проверять использование диска для каждого узла в кластере. По умолчанию установлено значение 30s.
Распределяет шары на узел, атрибут которого содержит хотя бы одно из включенных значений, разделенных запятыми.
Распределяет шары только на узел, атрибут которого содержит все включенные значения, разделенные запятыми.
Не распределяет шары на узел, атрибут которого содержит любое из включенных значений, разделенных запятыми. Настройки распределения кластера поддерживают следующие встроенные атрибуты.
Допустимые значения:
Определяет порядок, в котором шары перемещаются с исходящих узлов на входящие.
Эта настройка поддерживает следующие стратегии:
Контролирует, как маршрутизируются поисковые запросы, когда для индекса существуют репликационные шары, например, когда index.number_of_search_replicas больше 0. Эта настройка применяется только в случае, если для индекса настроены поисковые реплики. При установке в true все поисковые запросы для таких индексов маршрутизируются только на репликационные шары. Если репликационные шары не назначены, запросы завершаются неудачей. При установке в false, если репликационные шары не назначены, запросы возвращаются к любому доступному шару. По умолчанию установлено значение true.
Ограничивает количество шардов, отправляемых на узлы данных в одной партии для получения метаданных любых нераспределенных шардов. По умолчанию установлено значение 2000.
Включает пакетное распределение нераспределенных шардов, которые уже существуют на диске, вместо распределения одного шара за раз. Это снижает нагрузку на память и транспорт, получая метаданные любых нераспределенных шардов в пакетном вызове. По умолчанию установлено значение false.
Максимальное общее количество первичных и репликационных шардов, которые могут быть распределены на один узел. По умолчанию установлено значение -1 (без ограничений). Помогает равномерно распределять шары по узлам, ограничивая общее количество шардов на узел. Используйте с осторожностью, так как шары могут оставаться нераспределенными, если узлы достигнут своих настроенных лимитов.
Максимальное количество первичных шардов, которые могут быть распределены на один узел. Эта настройка применима только для кластеров с удаленной поддержкой. По умолчанию установлено значение -1 (без ограничений). Помогает равномерно распределять первичные шары по узлам, ограничивая количество первичных шардов на узел. Используйте с осторожностью, так как первичные шары могут оставаться нераспределенными, если узлы достигнут своих настроенных лимитов.
OpenSearch поддерживает следующие настройки шардов, блокировок и задач на уровне кластера:
Ограничивает максимальное количество шардов, которые могут быть задействованы во время поиска. Запросы, превышающие этот лимит, будут отклонены.
Устанавливает весь кластер в режим только для чтения. По умолчанию установлено значение false.
Похоже на cluster.blocks.read_only, но позволяет удалять индексы.
Ограничивает общее количество первичных и репликационных шардов для кластера. Лимит рассчитывается следующим образом: cluster.max_shards_per_node умножается на количество не замороженных узлов данных. Шары для закрытых индексов не учитываются в этом лимите. По умолчанию установлено значение 1000.
Включает или отключает распределение для постоянных задач.
Допустимые значения:
По умолчанию установлено значение all.
Менеджер кластера автоматически проверяет, нужно ли назначать постоянные задачи, когда состояние кластера изменяется значительным образом. Существуют и другие факторы, такие как использование памяти, которые повлияют на то, будут ли постоянные задачи назначены на узлы, но не вызывают изменения состояния кластера. Эта настройка определяет, как часто выполняются проверки назначения в ответ на эти факторы. По умолчанию установлено значение 30 секунд, при этом минимальное значение составляет 10 секунд.
Для получения дополнительной информации смотрите раздел Медленные логи запросов поиска.
Устанавливает порог WARN для медленных логов на уровне запросов. По умолчанию установлено значение -1.
Устанавливает порог INFO для медленных логов на уровне запросов. По умолчанию установлено значение -1.
Устанавливает порог DEBUG для медленных логов на уровне запросов. По умолчанию установлено значение -1.
Устанавливает порог TRACE для медленных логов на уровне запросов. По умолчанию установлено значение -1.
Устанавливает минимальный уровень медленного лога для записи: WARN, INFO, DEBUG и TRACE. По умолчанию установлено значение TRACE.
Для получения информации о настройках индекса на уровне индекса смотрите раздел Настройки индекса на уровне кластера.
OpenSearch поддерживает следующие настройки координации на уровне кластера. Все настройки в этом списке являются динамическими:
Количество времени, в течение которого узел ждет ответа от избранного менеджера кластера во время проверки лидера, прежде чем считать проверку неудачной. Допустимые значения от 1ms до 60s, включая. По умолчанию установлено значение 10s. Изменение этой настройки на значение, отличное от значения по умолчанию, может привести к нестабильности кластера.
Количество времени, в течение которого избранный менеджер кластера ждет ответа во время проверки последователя, прежде чем считать проверку неудачной. Допустимые значения от 1ms до 60s, включая. По умолчанию установлено значение 10s. Изменение этой настройки на значение, отличное от значения по умолчанию, может привести к нестабильности кластера.
Количество времени, в течение которого избранный менеджер кластера ждет между отправкой проверок последователей другим узлам в кластере. Допустимые значения 100ms и выше. По умолчанию установлено значение 1000ms. Изменение этой настройки на значение, отличное от значения по умолчанию, может привести к нестабильности кластера.
Количество времени, в течение которого избранный менеджер кластера ждет получения подтверждений обновлений состояния кластера от отстающих узлов. По умолчанию установлено значение 90s. Если узел не успешно применяет обновление состояния кластера в течение этого времени, он считается неудавшимся и удаляется из кластера.
Количество времени, в течение которого менеджер кластера ждет, пока каждое обновление состояния кластера будет полностью опубликовано на всех узлах, если только discovery.type не установлен на single-node. По умолчанию установлено значение 30s.
OpenSearch поддерживает следующие настройки пределов ответов CAT API на уровне кластера, все из которых являются динамическими:
Устанавливает предел на количество индексов, возвращаемых API CAT Indices. Значение по умолчанию -1 (без ограничений). Если количество индексов в ответе превышает этот предел, API возвращает ошибку 429. Чтобы избежать этого, вы можете указать фильтр по шаблону индекса в вашем запросе (например, _cat/indices/<index-pattern>).
Устанавливает предел на количество шардов, возвращаемых API CAT Shards. Значение по умолчанию -1 (без ограничений). Если количество шардов в ответе превышает этот предел, API возвращает ошибку 429. Чтобы избежать этого, вы можете указать фильтр по шаблону индекса в вашем запросе (например, _cat/shards/<index-pattern>).
Устанавливает предел на количество индексов, возвращаемых API CAT Segments. Значение по умолчанию -1 (без ограничений). Если количество индексов в ответе превышает этот предел, API возвращает ошибку 429. Чтобы избежать этого, вы можете указать фильтр по шаблону индекса в вашем запросе (например, _cat/segments/<index-pattern>).
Чтобы узнать больше о статических и динамических настройках, смотрите Конфигурирование OpenSearch.
Существует два типа настроек кластера:
OpenSearch поддерживает следующие статические настройки индекса уровня кластера:
indices.cache.cleanup_interval (Единица времени): Запланирует периодическую фоновую задачу, которая очищает истекшие записи из кэша с указанным интервалом. По умолчанию 1m (1 минута). Для получения дополнительной информации смотрите Кэш запросов индекса.
indices.requests.cache.size (Строка): Размер кэша в процентах от размера кучи (например, чтобы использовать 1% кучи, укажите 1%). По умолчанию 1%. Для получения дополнительной информации смотрите Кэш запросов индекса.
OpenSearch поддерживает следующие динамические настройки индекса уровня кластера:
action.auto_create_index (Булевый): Автоматически создает индекс, если индекс еще не существует. Также применяет любые конфигурации шаблонов индексов. По умолчанию true.
indices.recovery.max_concurrent_file_chunks (Целое число): Количество частей файлов, отправляемых параллельно для каждой операции восстановления. По умолчанию 2.
indices.recovery.max_concurrent_operations (Целое число): Количество операций, отправляемых параллельно для каждого восстановления. По умолчанию 1.
indices.recovery.max_concurrent_remote_store_streams (Целое число): Количество потоков к удаленному репозиторию, которые могут быть открыты параллельно при восстановлении индекса из удаленного хранилища. По умолчанию 20.
indices.replication.max_bytes_per_sec (Строка): Ограничивает общий входящий и исходящий трафик репликации для каждого узла. Если значение не указано в конфигурации, используется настройка indices.recovery.max_bytes_per_sec, по умолчанию равная 40 МБ. Если вы установите значение трафика репликации меньше или равным 0 МБ, ограничение скорости будет отключено, что приведет к передаче данных репликации с максимальной возможной скоростью.
indices.fielddata.cache.size (Строка): Максимальный размер кэша данных полей. Может быть указан как абсолютное значение (например, 8 ГБ) или процент от кучи узла (например, 50%). Это значение статическое, поэтому его необходимо указать в файле opensearch.yml. Если вы не укажете эту настройку, максимальный размер будет неограниченным. Это значение должно быть меньше, чем indices.breaker.fielddata.limit. Для получения дополнительной информации смотрите Систему защиты от переполнения кэша данных полей.
indices.query.bool.max_clause_count (Целое число): Определяет максимальное произведение полей и терминов, которые могут быть запрошены одновременно. До версии OpenSearch 2.16 для применения этой статической настройки требовалась перезагрузка кластера. Теперь она динамическая, существующие пулы потоков поиска могут использовать старое статическое значение, что может привести к исключениям TooManyClauses. Новые пулы потоков используют обновленное значение. По умолчанию 1024.
cluster.remote_store.index.path.type (Строка): Стратегия пути для данных, хранящихся в удаленном хранилище. Эта настройка эффективна только для кластеров с включенным удаленным хранилищем. Эта настройка поддерживает следующие значения:
fixed: Хранит данные в структуре пути <repository_base_path>/<index_uuid>/<shard_id>/.hashed_prefix: Хранит данные в структуре пути hash(<shard-data-identifier>)/<repository_base_path>/<index_uuid>/<shard_id>/.hashed_infix: Хранит данные в структуре пути <repository_base_path>/hash(<shard-data-identifier>)/<index_uuid>/<shard_id>/. shard-data-identifier характеризуется index_uuid, shard_id, типом данных (translog, segments) и типом данных (data, metadata, lock_files). По умолчанию fixed.cluster.remote_store.index.path.hash_algorithm (Строка): Хеш-функция, используемая для получения хеш-значения, когда cluster.remote_store.index.path.type установлено на hashed_prefix или hashed_infix. Эта настройка эффективна только для кластеров с включенным удаленным хранилищем. Эта настройка поддерживает следующие значения:
fnv_1a_base64: Использует хеш-функцию FNV1a и генерирует безопасное для URL 20-битное хеш-значение в формате base64.fnv_1a_composite_1: Использует хеш-функцию FNV1a и генерирует пользовательское закодированное хеш-значение, которое хорошо масштабируется с большинством опций удаленного хранилища. Функция FNV1a генерирует 64-битное значение. Пользовательское кодирование использует 6 старших бит для создания безопасного для URL символа base64 и следующие 14 бит для создания двоичной строки. По умолчанию fnv_1a_composite_1.cluster.remote_store.translog.transfer_timeout (Единица времени): Управляет значением таймаута при загрузке файлов translog и контрольных точек во время синхронизации с удаленным хранилищем. Эта настройка применяется только для кластеров с включенным удаленным хранилищем. По умолчанию 30 секунд.
cluster.remote_store.index.segment_metadata.retention.max_count (Целое число): Управляет минимальным количеством файлов метаданных, которые необходимо сохранить в репозитории сегментов на удаленном хранилище. Значение ниже 1 отключает удаление устаревших файлов метаданных сегментов. По умолчанию 10.
cluster.remote_store.segment.transfer_timeout (Единица времени): Управляет максимальным временем ожидания обновления всех новых сегментов после обновления в удаленное хранилище. Если загрузка не завершится в течение указанного времени, будет выброшено исключение SegmentUploadFailedException. По умолчанию 30 минут. Минимальное ограничение составляет 10 минут.
cluster.remote_store.translog.path.prefix (Строка): Управляет фиксированным префиксом пути для данных translog на кластере с включенным удаленным хранилищем. Эта настройка применяется только в том случае, если настройка cluster.remote_store.index.path.type установлена на HASHED_PREFIX или HASHED_INFIX. По умолчанию пустая строка, “”.
cluster.remote_store.segments.path.prefix (Строка): Управляет фиксированным префиксом пути для данных сегментов на кластере с включенным удаленным хранилищем. Эта настройка применяется только в том случае, если настройка cluster.remote_store.index.path.type установлена на HASHED_PREFIX или HASHED_INFIX. По умолчанию пустая строка, “”.
cluster.snapshot.shard.path.prefix (Строка): Управляет фиксированным префиксом пути для блобов уровня сегмента снимка. Эта настройка применяется только в том случае, если настройка repository.shard_path_type установлена на HASHED_PREFIX или HASHED_INFIX. По умолчанию пустая строка, “”.
cluster.default_number_of_replicas (Целое число): Управляет значением по умолчанию для количества реплик индексов в кластере. Настройка уровня индекса index.number_of_replicas по умолчанию принимает это значение, если не настроена. По умолчанию 1.
cluster.thread_pool.<fixed-threadpool>.size (Целое число): Управляет размерами как фиксированных, так и изменяемых очередей пулов потоков. Переопределяет значения по умолчанию, указанные в opensearch.yml.
cluster.thread_pool.<scaling-threadpool>.max (Целое число): Устанавливает максимальный размер пула потоков с изменяемым размером. Переопределяет значение по умолчанию, указанное в opensearch.yml.
cluster.thread_pool.<scaling-threadpool>.core (Целое число): Указывает базовый размер пула потоков с изменяемым размером. Переопределяет значение по умолчанию, указанное в opensearch.yml.
Вы можете указать настройки индекса при создании индекса. Существует два типа настроек индекса:
Статические настройки индекса уровня индекса — это настройки, которые нельзя обновить, пока индекс открыт. Чтобы обновить статическую настройку, необходимо закрыть индекс, обновить настройку, а затем снова открыть индекс.
Динамические настройки индекса уровня индекса — это настройки, которые можно обновлять в любое время.
При создании индекса вы можете указать его статические или динамические настройки следующим образом:
PUT /testindex
{
"settings": {
"index.number_of_shards": 1,
"index.number_of_replicas": 2
}
}
OpenSearch поддерживает следующие статические настройки индекса уровня индекса:
index.number_of_shards (Целое число): Количество первичных шардов в индексе. По умолчанию 1.
index.number_of_routing_shards (Целое число): Количество шардов маршрутизации, используемых для разделения индекса.
index.shard.check_on_startup (Булевый): Указывает, следует ли проверять шардов индекса на наличие повреждений. Доступные опции:
false (не проверять на повреждения),checksum (проверять на физические повреждения),true (проверять как на физические, так и на логические повреждения).
По умолчанию false.index.codec (Строка): Определяет, как сжимаются и хранятся на диске сохраненные поля индекса. Эта настройка влияет на размер шардов индекса и производительность операций индексации.
Допустимые значения:
defaultbest_compressionzstd (OpenSearch 2.9 и позже)zstd_no_dict (OpenSearch 2.9 и позже)qat_lz4 (OpenSearch 2.14 и позже, на поддерживаемых системах)qat_deflate (OpenSearch 2.14 и позже, на поддерживаемых системах)Для zstd, zstd_no_dict, qat_lz4 и qat_deflate вы можете указать ур