Duration 結構

參考

定義

命名空間:: Windows.UI.Xaml

重要

部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

編輯

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

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
struct Duration

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 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

Windows 需求

裝置系列	Windows 10 (已於 10.0.10240.0 引進)
API contract	Windows.Foundation.UniversalApiContract (已於 v1.0 引進)

備註

持續時間值會用於下列屬性：

Timeline.Duration (可以在分鏡腳本或動畫)
VisualTransition.GeneratedDuration
RepeatBehavior.Duration
MediaElement.NaturalDuration (此用法不屬於腳本動畫案例的一部分;所有其他專案都是)

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

XAML 使用方式

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

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

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

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

自動：常值字串 Automatic 。

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

永久：常值字串 Forever 。

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

XAML 語法的注意事項

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

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

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

程式碼使用方式

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

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

自動和永久

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

XAML 或程式碼中套用的 Automatic 值會導致 Storyboard 上的行為與動畫不同。

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

重要

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

Duration 的投影和成員

如果您使用 Microsoft .NET 語言 (C# 或 Microsoft Visual Basic) ，或 Visual C++ 元件延伸模組 (C++/CX) ，則 Duration 有可用的非資料成員，且其資料成員會公開為讀寫屬性，而非欄位。 Duration 會公開數個運算子，包括比較運算子。請參閱 .NET API 瀏覽器中的持續時間。

針對 Microsoft .NET，Duration 會公開 TimeSpan.Parse 的 TimeSpan 屬性、 Implicit 和 UnaryPlus 運算子，以及 Add 和 Subtract 方法。 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	型別做為列舉的成員。

適用於