Duration 結構

定義

命名空間:

Microsoft.UI.Xaml

表示 時間軸 作用中的時間持續時間，或更通常代表同時支援兩個特殊值 Automatic 和 Forever 的時間持續時間。

/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 65536)]
struct Duration

[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 65536)]
public struct Duration

Public Structure Duration

<object property="[days.]hours:minutes:seconds[.fractionalSeconds]"/>
-or-
<object property="Automatic" .../>
-or-
<object property="Forever" .../>

繼承

ValueType

Duration

屬性

ContractVersionAttribute

備註

Duration這些屬性會使用值：

• Timeline.Duration (可以在 分鏡腳本 或動畫)
• VisualTransition.GeneratedDuration
• RepeatBehavior.Duration
• Windows.UI.Xaml.Controls.MediaElement.NaturalDuration (此使用方式不屬於分鏡腳本動畫案例;所有其他專案都是)

如需如何在時間軸中使用 Duration 的詳細資訊，包括程式碼範例，請參閱分鏡腳本動畫或Timeline.Duration。

XAML 使用方式

使用Windows 執行階段中值最常見的方式 Duration 是使用 XAML 屬性來設定此值。 當您在 XAML 中設定值時，您會提供字串，並使用 hours：minutes：seconds 字串格式及其變體剖析字串，如這裡所述。

<object property="[days.]hours:minutes:seconds[.fractionalSeconds]"/>

• days：大於或等於 0 的整數值，指定天數。
• 小時：介於 0 到 23 之間的整數值，指定小時數。 如果您將 Duration 指定為 XAML 屬性，則即使為 0，也需要小時元件。
• 分鐘：介於 0 到 59 之間的整數值，指定分鐘數。 如果您將 Duration 指定為 XAML 屬性，則即使為 0，也需要分鐘元件。
• 秒：介於 0 到 59 之間的整數值，指定秒數。 如果您只設定秒元件，請將小時：分鐘元件設定為 0：0。
• fractionalSeconds：選擇性。 包含 1 到 7 個位置的十進位值，超過小數點，指定小數秒。

<object property="Automatic" .../>

• 自動：常值字串 Automatic 。

<object property="Forever" .../>

• 永久：常值字串 Forever 。

使用類似整數的字串來指定 Duration，而不需在 小時：分鐘：秒 字串格式中使用的任何常值字元，例如 ： 或 。 將會產生該天數的持續時間！ 這很少會是預期的結果。 您通常會以秒為單位指定動畫持續時間。 因此，Duration 字串必須包含前 0 個小時 和 分鐘的值，其中常值 ： 字元做為 小時 和 分鐘之間的分隔符號，以及 分鐘 和 秒之間的分隔符號。 例如，若要指定五秒的持續時間，XAML 屬性值的正確字串是 「0：0：5」 (「0：0：05」 相當於) 。

XAML 語法注意事項

在 XAML 屬性使用方式所示的文法中，[ ] (方括弧) 表示選擇性值，[ ] 不是常值。 ： (冒號) 和。 (句號) 字元都是常值，並且分隔一般時間範圍的h：m：s字串形式，或選擇性的天數和fractionalSeconds值。

如果您想要 Duration.Automatic 和 Duration.Forever所記載的 Duration，請使用常值 「Automatic」 和 「Forever」 做為 XAML 屬性值。

Duration 不支持對象專案語法，而且您無法將 Duration 宣告為 ResourceDictionary中的可共用專案。

程式碼使用方式

如果您在程式碼中使用 Duration ，則會 Duration 使用 結構也會使用 TimeSpan 的時間定義。 TimeSpan如果您是使用 C# 或 Microsoft Visual Basic 進行程式設計，則結構是由System.TimeSpan表示，如果您是使用 C++ 進行程式設計，則為Windows.Foundation.TimeSpan。

• C# 或 Microsoft Visual Basic System.TimeSpan有使用hours：minutes：seconds字串格式的Parse方法。 如果您需要在程式碼中建立 Duration 值，您可以呼叫Duration建構函式，並使用hours：minutes：seconds字串呼叫TimeSpan.Parse來提供 System.TimeSpan 引數。 請一律使用 「en-us」 文化特性來剖析此字串，因為這是 XAML 解譯字串格式的方式，您不應該使用特定文化特性的輸入來產生動畫時間。
• C++ Windows.Foundation.TimeSpan 不支援以 小時：分鐘：秒 字串格式建立它的方法。 您必須使用 DurationHelper.FromTimeSpan，並自行進行 時數：分鐘：秒 轉換成 C++ Windows.Foundation.TimeSpan 資料值的方式，這是以毫秒為單位的值。

自動和永久

Automatic 和 Forever 是保留 Duration 屬性值特殊意義的值。 對於 Microsoft .NET，這些屬性是由靜態屬性 Automatic 和 Forever來表示。

在 Automatic XAML 或程式碼中套用的值會導致 分鏡腳本 上的不同行為，而不是動畫。

• 針對 Storyboard，此值 Automatic 會將有效時間範圍設定為等於其長時間執行之子動畫的結束時間，如此一來，任何子動畫就不會進行裁剪。
• 對於動畫，值會產生行為， Automatic 讓動畫執行的時間範圍為 1 秒， (0：0：1) 。 此行為很少需要做為最終結果，但可讓您在測試期間查看執行中的動畫，然後再建立最終的時間範圍。

重要

針對動畫使用 Forever 是已被取代的使用方式，而且很少使用。 這會產生永遠不會從其起始值前進的動畫，不論從到到 提供/ 哪些值、主要畫面格等等。 如果您想要讓動畫持續重複，請使用 RepeatBehavior="Forever" ，而不是 Duration="Forever" 。

Duration 的投影和成員

如果您使用 C#，則 Duration 具有可用的非資料成員，而且其資料成員會公開為讀寫屬性，而不是欄位。 Duration 會公開數個運算子，包括比較運算子。 請參閱 .NET API 瀏覽器中的 持續時間 。

針對 Microsoft .NET，Duration 會針對 TimeSpan 屬性、Implicit和UnaryPlus運算子，以及Add和Subtract方法公開TimeSpan.Parse。 這些無法從 Visual C++ 元件延伸模組中的結構取得， (C++/CX) ，但您可以針對其中一些使用對等 的 DurationHelper 方法。

如果您是使用C++/WinRT 或Windows 執行階段 C++ 樣板庫進行程式設計， (WRL) ，則只有資料成員欄位會以 的成員 Duration 的形式存在，而且您無法使用 .NET 投影的公用程式方法或屬性。 C++ 程式碼可以存取 DurationHelper 類別上存在的類似公用程式方法。 例如，您可以呼叫 DurationHelper.Compare 來比較兩個 C++ Duration 值。 如需詳細資訊，請參閱 DurationHelper。

下表顯示 .NET 和 C++ 中可用的對等屬性和方法。

.NET (持續時間)	C++ (DurationHelper)
Duration (TimeSpan)	FromTimeSpan (TimeSpan)
自動	自動
不限次數	不限次數
HasTimeSpan	GetHasTimeSpan (Duration)
新增 (持續時間)	新增 (持續時間、持續時間)
比較 (持續時間、持續時間)	比較 (持續時間、持續時間)
等於	等於 (期間、持續時間)
減去 (持續時間)	減去 (持續時間、持續時間)

欄位

TimeSpan	TimeSpan值元件。
Type	型別做為列舉的成員。

另請參閱

• Storyboard
• Duration
• 腳本動畫