Блок команды

Блок команды показывает то, что человек скопирует и вставит в терминал: команду установки, строку подключения, ключ. Кнопка «Копировать» рядом забирает текст целиком, без риска недовыделить.

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

Человек должен выполнить команду у себя: установить пакет, отправить релиз, подключить зеркало.
Нужно отдать строку, которую набирать руками долго и ошибочно: токен, адрес, ключ.

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

В дереве холста блок собирается словами: команда позицией, пояснение и надпись кнопки — цепочкой (см. Язык узлов).

Узлом холста — словами

Выполните в каталоге проекта:

приложение отправить отчёт-1.0.0

HTML = Кит.БлокКоманды("приложение отправить отчёт-1.0.0")
	.Пояснение("Выполните в каталоге проекта:").Рендер();

Команда с копированием#

Строка — самая короткая модель: кит сам поймёт её как Команда. Текст печатается моноширинным шрифтом на заливке surface-container-highest, кнопка копирования стоит справа.

Команда с копированием

приложение установить отчёт

HTML = Набор.БлокКоманды().Отрисовать("приложение установить отчёт");

Кнопку оживляет скрипт страницы по атрибуту data-copy: в нём лежит тот же текст, что и в блоке. Без скрипта блок остаётся читаемым, и команду можно выделить мышью.

С пояснением#

Пояснение — строка над блоком: где и когда выполнять. Она приглушена и не копируется вместе с командой.

С пояснением — где выполнять

Выполните в каталоге проекта:

приложение отправить отчёт-1.0.0

HTML = Набор.БлокКоманды().Отрисовать(Новый Структура("Команда, Пояснение",
	"приложение отправить отчёт-1.0.0", "Выполните в каталоге проекта:"));

Без копирования#

БезКопирования убирает кнопку. Это нужно, когда блок — пример формата, а не готовая команда, или когда рядом уже есть способ забрать значение.

Без кнопки копирования

приложение установить отчёт

HTML = Набор.БлокКоманды().Отрисовать(Новый Структура("Команда, БезКопирования",
	"приложение установить отчёт", Истина));

Надпись кнопки меняется полем Подпись, если «Копировать» не подходит по смыслу.

Своя надпись кнопки

https://хаб.пример/зеркало/отчёт.git

HTML = Набор.БлокКоманды().Отрисовать(Новый Структура("Команда, Подпись",
	"https://хаб.пример/зеркало/отчёт.git", "Копировать адрес"));

Длинная команда#

Строка без пробелов — адрес, путь, ключ — переносится у края блока, а кнопка копирования держит свою ширину и никогда не уезжает за край. На телефоне кнопка встаёт под код, когда рядом с ним не помещается; короткая команда остаётся с кнопкой в одну строку.

Длинный адрес на узком экране

Установка из своего хаба:

приложение установить localhost:3412/team/reference-contractors

HTML = Кит.БлокКоманды("приложение установить localhost:3412/team/reference-contractors")
	.Пояснение("Установка из своего хаба:").Рендер();

Несколько строк#

Перевод строки в команде сохраняется: блок держит многострочный сниппет, а кнопка остаётся у первой строки.

Сниппет из двух строк

export APP_STORAGE_ROOT=/var/lib/приложение
приложение запустить

HTML = Набор.БлокКоманды().Отрисовать(
	"export APP_STORAGE_ROOT=/var/lib/приложение" + Символы.ПС
	+ "приложение запустить");

Гайдлайны#

приложение установить отчёт

ДелайтеКоманда без приглашения оболочки — вставил и выполнил

Код

HTML = Набор.БлокКоманды().Отрисовать("приложение установить отчёт");

$ приложение установить отчёт

Не делайтеЗнак «$» в команде: вставленная, она упадёт

Код

HTML = Набор.БлокКоманды().Отрисовать("$ приложение установить отчёт");

1. Установите пакет:

приложение установить отчёт

2. Запустите:

приложение запустить отчёт

ДелайтеШаги — отдельными блоками, каждый со своим пояснением

Код

HTML = Набор.БлокКоманды().Отрисовать(Новый Структура("Команда, Пояснение",
	"приложение установить отчёт", "1. Установите пакет:"))
	+ Набор.БлокКоманды().Отрисовать(Новый Структура("Команда, Пояснение",
	"приложение запустить отчёт", "2. Запустите:"));

приложение установить отчёт && приложение запустить отчёт

Не делайтеНесколько шагов одним блоком через «&&»: сбой в середине не виден

Код

HTML = Набор.БлокКоманды().Отрисовать(
	"приложение установить отчёт && приложение запустить отчёт");

Выполните в каталоге проекта:

приложение отправить отчёт-1.0.0

ДелайтеПояснение говорит, где выполнять

Код

HTML = Набор.БлокКоманды().Отрисовать(Новый Структура("Команда, Пояснение",
	"приложение отправить отчёт-1.0.0", "Выполните в каталоге проекта:"));

Команда отправки отчёта:

приложение отправить отчёт-1.0.0

Не делайтеПояснение пересказывает команду

Код

HTML = Набор.БлокКоманды().Отрисовать(Новый Структура("Команда, Пояснение",
	"приложение отправить отчёт-1.0.0", "Команда отправки отчёта:"));

Доступность#

Команда печатается в <code> и экранируется: в блок можно отдать любой текст.
Кнопка копирования — настоящая <button type="button"> с видимой надписью: её читает скринридер, её нажимают с клавиатуры, и форму она не отправляет.
Пустую команду кит не печатает, а кидает исключение: рамка с кнопкой, копирующей пустоту, никому не нужна.

Узлом холста#

Блок команды узлом дерева

приложение установить отчёт

HTML = Кит.БлокКоманды("приложение установить отчёт").Рендер();

Модель#

Поля модели — из комментария в исходнике компонента. Структура с этими полями — прежний вид модели: в дереве холста те же поля пишут слова Кит.БлокКоманды.

Кит.БлокКоманды()src/Классы/холст/Кит.os

Блок копируемой команды. Слова: Подпись (кнопки копирования), Пояснение, БезКопирования.

Параметры:
 Модель - Строка, Структура - текст команды; Структура — прежний вид модели.

Возвращаемое значение:
 ЭлементЭкрана

БлокКоманды.Отрисовать()src/Классы/компоненты/БлокКоманды.os

Отрисовывает блок копируемой команды.

Параметры:
 Модель - Строка, Структура - текст команды либо структура: Команда (обязательна),
          Подпись (надпись кнопки, "Копировать"), Пояснение (строка над блоком),
          БезКопирования (не рисовать кнопку).

Возвращаемое значение:
 Строка - фрагмент <div class="cmd">. Кидается исключением, если Команда пуста.