本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

進度追蹤

S3 Transfer Manager 提供內建的進度追蹤功能。

追蹤所有操作

您可以在S3TransferManager執行個體true上track_progress將 設定為 ，以啟用所有操作 （檔案和目錄） 的追蹤。

<?php

use Aws\S3\S3Transfer\S3TransferManager;

require __DIR__ . '/../vendor/autoload.php';


$transferManager = new S3TransferManager(
    null,
    [
        'track_progress' => true,
    ]
);

透過此設定，開發套件會使用內建的 SingleProgressTracker<add link> 進行檔案操作，並使用 MultiProgressTracker<add link> 進行目錄操作。

追蹤單一檔案操作

下列範例顯示名為 之檔案SingleProgressTracker上傳進度的內建 範例主控台輸出MyFile.txt：

追蹤單一目錄操作

如果您未在 Transfer Manager 上啟用進度追蹤，您可以透過兩種方式將其啟用以進行目錄操作。

下列範例顯示 內建的範例主控台輸出，MultiProgressTracker用於目錄的上傳進度：

每個檔案的進度會與最後一行的摘要進度一起列出。

自訂進度追蹤

您可以實作自己的檔案操作進度追蹤。建立擴展AbstractTransferListener界面的類別，並將它傳遞給請求上的 方法。

下列實作會以文字格式顯示單一檔案操作的進度資訊：

<?php

use Aws\S3\S3Transfer\Models\UploadRequest;
use Aws\S3\S3Transfer\Progress\AbstractTransferListener;
use Aws\S3\S3Transfer\S3TransferManager;

require __DIR__ . '/../vendor/autoload.php';

class MyProgressTracker extends AbstractTransferListener 
{
    public function transferInitiated(array $context): void
    {
        $key = $context['request_args']['Key'] ?? 'unknown';
        echo "Starting transfer of {$key}...\n";
    }

    public function bytesTransferred(array $context): bool
    {
        $snapshot = $context['progress_snapshot'];
        $percent = round($snapshot->ratioTransferred() * 100, 2);
        $transferred = round($snapshot->getTransferredBytes() / 1024 / 1024, 2);
        $total = round($snapshot->getTotalBytes() / 1024 / 1024, 2);

        echo "Progress: {$percent}% ({$transferred}MB of {$total}MB)\n";
    }

    public function transferComplete(array $context): void
    {
        $key = $context['request_args']['Key'] ?? 'unknown';
        echo "Transfer complete for {$key}!\n";
    }

    public function transferFail(array $context): void
    {
        $key = $context['request_args']['Key'] ?? 'unknown';
        $reason = $context['reason']->getMessage();
        echo "Transfer failed for {$key}: {$reason}\n";
    }
}

$transferManager = new S3TransferManager(
    null, []
);

// Use your custom tracker.
$uploadPromise = $transferManager->upload(
    new UploadRequest(
        '/path/to/file.txt', // Or an instance of StreamInterface.
        [
            'Bucket' => 'amzn-s3-demo-bucket',
            'Key'    => 'file.txt',
        ],
        [],
        [],
        new MyProgressTracker()
    )
);

下列範例顯示傳送至 主控台的範例輸出，以進行檔案上傳：

Starting transfer of file.txt...
Progress: 42% (16.8MB of 40MB)

自訂內建進度追蹤器

您可以透過幾種方式自訂進度追蹤：

下列範例示範如何自訂進度追蹤。請參閱類別圖表，以查看 SDK 中進度追蹤元件之間的關係。

自訂 ConsoleProgressBar

自訂預設長條格式

下列範例會自訂預設進度列格式，即 ColoredTransferProgressBarFormat<新增連結>。此格式會根據傳輸狀態顯示不同顏色的進度。

範例會變更：

<?php

use Aws\S3\S3Client;
use Aws\S3\S3Transfer\Models\UploadRequest;
use Aws\S3\S3Transfer\Progress\ConsoleProgressBar;
use Aws\S3\S3Transfer\Progress\SingleProgressTracker;
use Aws\S3\S3Transfer\S3TransferManager;

require __DIR__ . '/../vendor/autoload.php';

$progressBar = new ConsoleProgressBar(
    progressBarChar: '=',
    progressBarWidth: 100,
// Default `ColoredTransferProgressBarFormat` is used.
);
$progressTracker = new SingleProgressTracker(
    progressBar: $progressBar,
);
$s3Client = new S3Client([
    'region' => 'us-east-2',
]);
$s3TransferManager = new S3TransferManager($s3Client);
$source = "/path/file.txt";

$result = $s3TransferManager->upload(
    new UploadRequest(
        source: $source,
        uploadRequestArgs: [
            'Bucket' => 'amzn-s3-demo-bucket',
            'Key'    => 'key',
        ],
        progressTracker: $progressTracker,
    )
)->wait();
print_r($result);

下圖顯示自訂內建的主控台輸出ConsoleProgressBar，其寬度為 100，字元為 "="：

使用純進度列格式自訂

下列範例使用內建PlainProgressBarFormat的 <新增連結> 搭配自訂字元和寬度來自訂預設進度列。僅以黑色PlainProgressBarFormat顯示。顏色不會根據傳輸狀態而變更。

範例會變更：

<?php

use Aws\S3\S3Client;
use Aws\S3\S3Transfer\Models\UploadRequest;
use Aws\S3\S3Transfer\Progress\ConsoleProgressBar;
use Aws\S3\S3Transfer\Progress\PlainProgressBarFormat;
use Aws\S3\S3Transfer\Progress\SingleProgressTracker;
use Aws\S3\S3Transfer\S3TransferManager;

require __DIR__ . '/../vendor/autoload.php';

$progressBar = new ConsoleProgressBar(
    progressBarChar: '*',
    progressBarWidth: 25,
    progressBarFormat: new PlainProgressBarFormat(),
);
$progressTracker = new SingleProgressTracker(
    progressBar: $progressBar,
);
$s3Client = new S3Client([
    'region' => 'us-east-2',
]);
$s3TransferManager = new S3TransferManager($s3Client);
$source = "/path/file.txt";

$result = $s3TransferManager->upload(
    new UploadRequest(
        source: $source,
        uploadRequestArgs: [
            'Bucket' => 'amzn-s3-demo-bucket',
            'Key'    => 'key',
        ],
        progressTracker: $progressTracker,
    )
)->wait();
print_r($result);

下圖顯示ConsoleProgressBar使用寬度為 25 且字元為 "*" 的純進度列格式自訂內建的主控台輸出：

透過建立新的長條格式來自訂

下列範例使用新的長條格式 （延伸 ProgressBarFormat<add link>) 來自訂預設進度列，而不是自訂內建格式。

<?php

use Aws\S3\S3Client;
use Aws\S3\S3Transfer\Models\UploadRequest;
use Aws\S3\S3Transfer\Progress\ConsoleProgressBar;
use Aws\S3\S3Transfer\Progress\ProgressBarFormat;
use Aws\S3\S3Transfer\Progress\SingleProgressTracker;
use Aws\S3\S3Transfer\S3TransferManager;

require __DIR__ . '/../vendor/autoload.php';

// Implement a custom bar format.
class PercentBarFormat extends ProgressBarFormat
{
    public const FORMAT_TEMPLATE = "|object_name| - |percent|% [|transferred| |unit|ytes]";
    public const FORMAT_PARAMETERS = [
        'object_name',       // `uploadRequestArgs` Key parameter.
        'percent',           //  Percent transferred.
        // 'progress_bar',      Optional, if used, default is a `ConsoleProgressBar`.
        // 'to_be_transferred', Optional.
        'transferred',       //  Default is bytes transferred.
        'unit',              //  Default is 'B'.
    ];

    public function getFormatTemplate(): string
    {
        return self::FORMAT_TEMPLATE;
    }

    public function getFormatParameters(): array
    {
        return self::FORMAT_PARAMETERS;
    }

    protected function getFormatDefaultParameterValues(): array
    {
        return [];
    }
}

// Create an instance of the custom implemention
$progressBarFormat = new PercentBarFormat();
$progressBar = new ConsoleProgressBar(
    progressBarFormat: $progressBarFormat,
);
$progressTracker = new SingleProgressTracker(
    progressBar: $progressBar,
);
$s3Client = new S3Client([
    'region' => 'us-east-2',
]);
$s3TransferManager = new S3TransferManager($s3Client);
$source = "/path/file";

$result = $s3TransferManager->upload(
    new UploadRequest(
        source: $source,
        uploadRequestArgs: [
            'Bucket' => 'amzn-s3-demo-bucket',
            'Key'    => 'key',
        ],
        progressTracker: $progressTracker,
    )
)->wait();
print_r($result);

下圖顯示ConsoleProgressBar使用自訂進度列格式自訂內建的主控台輸出：

自訂長條格式接受數個參數：

您可以結合分隔 （管道字元） 參數名稱來自訂輸出。此範例使用下列範本。PercentBarFormat 類別的 getFormatTemplate方法會傳回此範本：

"|object_name| - |percent|% [|transferred| |unit|ytes]"