Duration 结构

定义

命名空间:

Windows.UI.Xaml

表示 时间线 处于活动状态的持续时间，或者更一般地表示也支持两个特殊值 “自动 ”和 “永远”的持续时间。

/// [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 的整数值，用于指定天数。
• 小时：一个介于 0 和 23 之间的整数值，用于指定小时数。 如果将 Duration 指定为 XAML 属性，则需要一个小时组件，即使它是 0。
• 分钟：一个介于 0 和 59 之间的整数值，用于指定分钟数。 如果将 Duration 指定为 XAML 属性，则需要分钟组件，即使它是 0。
• seconds：一个介于 0 和 59 之间的整数值，用于指定秒数。 如果仅设置秒分量，请将 hours：minutes 组件设置为 0：0。
• fractionalSeconds：可选。 一个十进制值，由小数点后的 1 到 7 个位置组成，指定秒的小数。

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

• 自动：文本字符串 Automatic。

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

• 永久：文本字符串 Forever。

使用类似于整数的字符串指定 Duration，而不在 hours：minutes：秒 字符串格式（如 ：或 ） 中使用任何文本字符，将导致该天数的持续时间！ 这很少是预期的结果。 通常指定动画持续时间（以秒为单位）。 因此，Duration 字符串必须包含 小时 和 分钟之前的 0 个值，文本 ： 字符作为 小时 和 分钟之间的分隔符， 以及分钟 和 秒之间的分隔符。 例如，若要指定持续时间为 5 秒，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 结构也使用的时间定义。 如果使用 C# 或 Microsoft Visual Basic 编程，则 TimeSpan 结构由 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，并自行进行转换 ，了解 hours：minutes：seconds 转换为 C++ Windows.Foundation.TimeSpan 数据值的方式，该值以毫秒为单位。

自动和永远

Automatic 和 Forever 是持续时间属性值具有特殊含义的值。 对于 Microsoft .NET，这些属性由静态属性 Automatic 和 Forever 表示。

XAML 或代码中应用的 “自动” 值会导致 情节提要 上的行为与动画不同。

• 对于 Storyboard， “自动 ”值将有效时间跨度设置为等于其运行时间最长的子动画的结束时间，这样任何子动画都不会发生剪辑。
• 对于动画， “自动 ”值会导致动画以 1 秒 (0：0：1) 的时间跨度运行的行为。 此行为很少用作最终结果，但它使你可以在测试期间查看正在运行的动画，然后再确定最终时间跨度。

重要

将 Forever 用于动画是已弃用的用法，很少使用。 这会导致动画永远不会从其起始值前进，无论为 “从/到”、关键帧等提供了什么值。 如果希望动画连续重复，请使用 RepeatBehavior="Forever"而不是 Duration="Forever"。

投影和持续时间的成员

如果使用 Microsoft .NET 语言 (C# 或 Microsoft Visual Basic) ，或 Visual C++ 组件扩展 (C++/CX) ，则 Duration 具有可用的非数据成员，并且其数据成员公开为读写属性，而不是字段。 持续时间公开多个运算符，包括比较运算符。 请参阅 .NET API 浏览器中的 持续时间 。

对于 Microsoft .NET，Duration 公开其 TimeSpan 属性的 TimeSpan.Parse、隐式和 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)
TimeSpan) (持续时间	FromTimeSpan (TimeSpan)
自动	自动
永远	永远
HasTimeSpan	GetHasTimeSpan (持续时间)
添加 (持续时间)	添加 (持续时间、持续时间)
比较 (持续时间、持续时间)	比较 (持续时间、持续时间)
等于	等于 (Duration、Duration)
减去 (持续时间)	减去 (持续时间、持续时间)

字段

TimeSpan	TimeSpan 值组件。
Type	作为枚举成员的类型。

另请参阅

• Storyboard
• Duration
• 情节提要动画