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。
• 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 的时间定义。 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，并自行进行转换 ，了解 hours：minutes：seconds 转换为 C++ Windows.Foundation.TimeSpan 数据值的方式，该值以毫秒为单位。

自动和永远

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

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

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

重要

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

投影和持续时间的成员

如果使用 C#，则 Duration 具有可用的非数据成员，并且其数据成员公开为读写属性，而不是字段。 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
• 情节提要动画