Duration 結構

定義

/// [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) 。 此行為很少需要做為最終結果，但可讓您在測試期間查看執行中的動畫，然後再建立最終的時間範圍。

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++ 中可用的對等屬性和方法。

欄位

適用於

另請參閱

• Storyboard
• Duration
• 腳本動畫