Індикатор прогресса

Дата обновления перевода 2023-08-21

Індикатор прогресса

Индикаторы прогресса полезны для того, чтобы пользователи знали, что команда не остановилась. В отличие от индикаторов выполнения, эти индикаторы используются, когда продолжительность выполнения команды является неопределенной (например, долговременные команды, задачи с неопределенной продолжительностью и т.д.).

Они работают путём инстанцирования класса ProgressIndicator` и отслеживают прогресс при выполнении команды:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
use Symfony\Component\Console\Helper\ProgressIndicator;

// создаёт новий индикатор прогресса
$progressIndicator = new ProgressIndicator($output);

// запускает и отображает индикатор прогресса з пользовательским сообщением
$progressIndicator->start('Processing...');

$i = 0;
while ($i++ < 50) {
    // ... сделать какую-то работу

    // продвигает индикатор прогресса
    $progressIndicator->advance();
}

// гарантирует, что индикатор прогресса отобразит финальное сообщение
$progressIndicator->finish('Finished');

Настройка индикатора прогресса

Встроенные форматы

По умолчанию, информация, отображённая на индикаторе прогресса, зависит от текущего уровня детализации экземпляра OutputInterface:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# OutputInterface::VERBOSITY_NORMAL (CLI без флажка детализации)
 \ Processing...
 | Processing...
 / Processing...
 - Processing...

# OutputInterface::VERBOSITY_VERBOSE (-v)
 \ Processing... (1 sec)
 | Processing... (1 sec)
 / Processing... (1 sec)
 - Processing... (1 sec)

# OutputInterface::VERBOSITY_VERY_VERBOSE (-vv) and OutputInterface::VERBOSITY_DEBUG (-vvv)
 \ Processing... (1 sec, 6.0 MiB)
 | Processing... (1 sec, 6.0 MiB)
 / Processing... (1 sec, 6.0 MiB)
 - Processing... (1 sec, 6.0 MiB)

Tip

Визовите команду с немым флажком (-q), чтобы не отображать индикатор прогресса.

Вместо того, чтоб полагаться на режим детализации текущей команды, вы также можете принудительно установить формат через второй аргумент конструктора ProgressIndicator:

1
$progressIndicator = new ProgressIndicator($output, 'verbose');

Встроенные форматы:

  • normal
  • verbose
  • very_verbose

Если ваш терминал не поддерживает ANSI, используйте варианты no_ansi:

  • normal_no_ansi
  • verbose_no_ansi
  • very_verbose_no_ansi

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

Вместо использования встроенных значений индикатора, вы также можете установить собственные:

1
$progressIndicator = new ProgressIndicator($output, 'verbose', 100, ['⠏', '⠛', '⠹', '⢸', '⣰', '⣤', '⣆', '⡇']);

Теперь индикатор прогресса будет выглядеть так:

1
2
3
4
⠏ Processing...
⠛ Processing...
⠹ Processing...
⢸ Processing...

Настройте заполнители

Индикатор прогресса использует заполнители (имя, окружённое символом %) для определения формата вывода. Вот список встроенных заполнителей:

  • indicator: Текущий индикатор;
  • elapsed: Время, которое прошло с момента запуска индикатора прогресса;
  • memory: Текущее использование памяти;
  • message: используется для отображения произвольных сообщений в индикаторе прогресса.

Например, вот как вы можете настроить заполнитель message:

1
2
3
4
5
6
7
ProgressIndicator::setPlaceholderFormatterDefinition(
    'message',
    static function (ProgressIndicator $progressIndicator): string {
        // Вернуть любую произвольную строку
        return 'My custom message';
    }
);

Note

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