InteractionTracker 类

定义

命名空间:

Microsoft.UI.Composition.Interactions

处理可用作 ExpressionAnimations 中目标的输入逻辑，通常用于根据输入驱动视觉对象的运动。

public ref class InteractionTracker sealed : CompositionObject

/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.Foundation.WindowsAppSDKContract, 65536)]
class InteractionTracker final : CompositionObject

[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.Foundation.WindowsAppSDKContract), 65536)]
public sealed class InteractionTracker : CompositionObject

Public NotInheritable Class InteractionTracker
Inherits CompositionObject

继承

Object Platform::Object IInspectable CompositionObject InteractionTracker

属性

ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

示例

void SetupSimpleInteractionTracker(Visual viewportVisual, Visual contentVisual)
{
  //
  // Create the InteractionTracker and set its min/max position and scale.  These could 
  // also be bound to expressions.  Note: The scrollable area can be changed from either 
  // the min or the max position to facilitate content updates/virtualization.
  //

  _tracker = InteractionTracker.Create(_compositor);

  _tracker.MaxPosition = new Vector3(
    contentVisual.Size.X - viewportVisual.Size.X,
    contentVisual.Size.Y - viewportVisual.Size.Y,
    0.0f);

  _tracker.MinScale = 0.5f;
  _tracker.MaxScale = 4.0f;


  //
  // Configure the interaction source.  Enable input with inertia on all axes.
  //

  var interactionSource = VisualInteractionSource.Create(viewportVisual);

  interactionSource.PositionXSourceMode = InteractionSourceMode.EnabledWithInertia;
  interactionSource.PositionYSourceMode = InteractionSourceMode.EnabledWithInertia;
  interactionSource.ScaleSourceMode = InteractionSourceMode.EnabledWithInertia;

  _tracker.InteractionSources.Add(interactionSource);


  //
  // Bind the InteractionTracker outputs to the contentVisual.
  //

  var positionExpression = _compositor.CreateExpressionAnimation("-tracker.Position");
  positionExpression.SetReferenceParameter("tracker", _tracker);

  contentVisual.StartAnimation("Offset", positionExpression);


  var scaleExpression = _compositor.CreateExpressionAnimation("Vector3(tracker.Scale, tracker.Scale, 1.0)");

  scaleExpression.SetReferenceParameter("tracker", _tracker);

  contentVisual.StartAnimation("Scale", scaleExpression);
}

注解

InteractionTracker 是一种状态机，可以通过活动输入或显式调用来更新或对其属性进行动画处理。 InteractionTracker 类旨在启用输入以驱动 CompositionAnimation，以实现自定义交互体验。 若要构建交互式体验，必须将一个或多个 VisualInteractionSource与 InteractionTracker 相关联。

常见方案

IneractionTracker 旨在用于：

• 添加自定义轻扫行为，例如轻扫 ListView 项目或其他视觉对象以删除/消除
• 与平移绑定的转换，例如轻扫以在“已关闭”和“打开”状态之间切换
• 效果的输入驱动动画，例如平移会导致屏幕模糊
• 自定义控件，例如创建具有不同平移速度或以编程方式控制的 ScrollViewer 的自定义实现

InteractionTracker 状态和转换

InteractionTracker 是具有四种状态的状态机：

• 空闲：没有活动输入或驱动 InteractionTracker 的动画
• 交互：活动用户输入驱动 InteractionTracker
• 惯性：活动输入或编程速度产生的活动动画正在驱动 InteractionTracker
• CustomAnimation：InteractionTracker 的一个属性正在直接进行动画处理 下图显示了这四种状态以及哪些状态转换有效。

状态转换可能是由于用户操作 (（例如启动或停止操作) ）或显式调用 InteractionTracker 上的方法而导致的。 每当进行其中一个显式调用时，都会发出 requestID 以跟踪请求是否被忽略或导致状态更改。

需要注意的一个重要事项是，InteractionTracker 在与使用它的应用程序不同的进程中运行。 因此，InteractionTracker 和关联类上的所有方法调用都是异步的，通过 IInteractionTrackerOwner 接口发出的回调也是异步的。

下面描述了触发每个状态更改的原因：

开始状态	结束状态	可能的触发器
闲置	正在交互	仅当执行与 InteractionTracker 关联的 VisualInteractionSource 的用户操作时，才会发生此状态转换。
闲置	惯性	仅当 InteractionTracker 处于空闲状态并且调用 TryUpdatePositionWithVelocity 或 TryUpdateScaleWithVelocity 时，才会发生此状态转换。
闲置	CustomAnimation	当 InteractionTracker 处于空闲状态并调用 TryUpdatePositionWithAnimation 或 TryUpdateScaleWithAnimation 时，会发生此状态转换。
正在交互	惯性	仅当已发送到 InteractionTracker 的用户操作完成时，才会发生此状态转换。 当活动输入结束时，InteractionTracker 将进入惯性状态，手指的释放速度和 InertiaDecayRate 等信息将决定惯性状态期间的行为。
惯性	闲置	当用于更新位置和/或缩放的函数 () 不再导致更改时，会发生此状态转换。 换句话说，位置和刻度速度都到了零。 如果调用来显式更新位置或缩放而不使用动画或速度，则也会发生此状态转换。 这些调用将结束惯性，并使用更新的属性值转换为 Idle。
惯性	惯性	当 TryUpdatePositionWithVelocity 或 TryUpdateScaleWithVelocity 在已处于惯性状态时，会发生此状态转换。 重新输入 Inertia 将导致重新计算所有 InertiaStateEntered 属性。
惯性	CustomAnimation	当在 Inertia sate 中调用 TryUpdatePositionWithAnimation 或 TryUpdateScaleWithAnimation 时，会发生此状态转换。
惯性	正在交互	当用户从命中测试到 VisualInteractionSource 的活动输入在 Inertia 完成之前进入时，会发生此状态转换。
CustomAnimation	闲置	当在 InteractionTracker 的位置和缩放属性上设置的所有动画完成时，将发生此状态转换。
CustomAnimation	CustomAnimation	当调用 TryUpdatePositionWithAnimation 或 TryUpdateScaleWithAnimation 而已处于 CustomAnimation 状态时，会发生此状态转换。
CustomAnimation	惯性	当在 CustomAnimation 状态下调用 TryUpdatePositionWithVelocity 或 TryUpdateScaleWithVelocity 时，会发生此状态转换。
CustomAnimation	正在交互	当用户操作命中测试与 InteractionTracker 关联的 VisualInteractionSource 时，会发生此状态转换。

InteractionTracker 进行的任何状态转换都将生成一个回调，指示新状态，其中包含与该状态相关的信息以及导致状态更改的请求的 requestID。 用户的活动操作将导致 requestID 为 0。 任何 Try* 调用都会发出 requestID，该 ID 可用于跟踪哪个 Try* 调用导致状态更改。 应用程序生存期内的第一个 requestID 将为 1，每次后续调用都会递增 requestID，这意味着每个请求 ID 都是唯一的。

InteractionTracker 位置和比例

InteractionTracker 的两个最常用的属性是位置和缩放。 每当其中一个或两个属性发生更改时，都会发送 ValuesChanged 回调，其中包含有关当前值的信息。 由于 InteractionTracker 的异步性质，通过 InteractionTracker 回调接收的值是更新针对 InteractionTracker 及其属性的当前状态和值的应用程序逻辑的最佳方式。

InteractionTracker 的一个重要区别在于其位置和比例与任何特定视觉对象的坐标空间无关。 创建 InteractionTracker 时，其位置会将矢量的 x、y 和 z 子通道设置为 0，小数位数将设置为 1。 只有活动输入或 Try* 调用会导致这些值发生更改。 每个属性的最小值和最大值将决定值可以波动的范围。 一个例外是“overpan”或“overzoom”的概念，其中活动操作可能会导致值在交互状态期间略高于最小值或最大值。 但是，当操作完成时，值将始终在设置范围内静止。 CustomAnimation 将始终固定在为位置和比例设置的范围内。

InteractionTracker 坐标空间概念与屏幕坐标的概念保持一致，即向上/向左运动会增加位置值，而向下/向右运动会降低位置值。 因此，在将位置属性附加到视觉对象的 Offset 时，通常会将其求反。

默认情况下，最小和最大位置通道均为 0，最小和最大刻度值为 1。 如果任一属性的所需行为是允许其在这些起始值之外更改，则需要更新最小值/最大值。

InteractionTracker 和 ExpressionAnimations

InteractionTracker 公开了可在 ExpressionAnimation的上下文中使用的各种属性，以推动 对 CompositionObject 的可动画属性的更新。 由于 InteractionTracker 的异步性质，不建议直接查询这些属性。 相反，应使用回调中传递的属性来驱动应用程序逻辑，并引用 ExpressionAnimation 中的值来更新可进行动画处理的属性。

如上所述，InteractionTracker 的两个最常用的属性是 Position 和 Scale 属性。 这些属性将更新以响应用户输入和 Try* 调用。 在 ExpressionAnimations 中使用这些属性将导致 CompositionObjects 的可动画处理属性在响应中更新。 例如，InteractionTracker.position 属性可以绑定到视觉对象的偏移量。 使用这些属性来填充跟踪进度的 CompositionPropertySet 也很常见，这反过来又可以驱动一系列协调动画。

将输入定向到 InteractionTracker

配置后，InteractionTracker 仍然需要最后一个步骤才能实际接收触摸输入并做出响应。 请参阅 VisualInteractionSource 上的文档。TryRedirectForManipulation 了解有关配置传入输入以流入 InteractionTracker 的详细信息。

属性

Comment	要与 CompositionObject 关联的字符串。 (继承自 CompositionObject)
Compositor	用于创建此 CompositionObject 的 Compositor。 (继承自 CompositionObject)
DispatcherQueue	获取 CompositionObject 的 DispatcherQueue。 (继承自 CompositionObject)
ImplicitAnimations	附加到此 对象的隐式动画的集合。 (继承自 CompositionObject)
InteractionSources	生成交互的 对象的集合。
IsInertiaFromImpulse	获取一个值，该值指示惯性是否是脉冲的结果。
IsPositionRoundingSuggested	指示当前是否建议位置舍入的布尔值。
MaxPosition	InteractionTracker 允许的最大位置。
MaxScale	InteractionTracker 的最大缩放比例。
MinPosition	InteractionTracker 允许的最小位置。
MinScale	InteractionTracker 的最小比例。
NaturalRestingPosition	InteractionTracker 的自然静息位置。 NaturalRestingPosition 属性是 InteractionTracker 将在不考虑边界或惯性修饰符的情况下停止的计算位置。 此属性通常适用于滚动体验中的虚拟化等操作，其中必须知道 InteractionTracker 停止的位置。 使用 NaturalRestingPosition 属性有两个main用例：在 InertiaStateEntered 事件参数中检索其当前值，或者在创建惯性修饰符等内容时在 ExpressionAnimation 中引用此属性。
NaturalRestingScale	InteractionTracker 的自然静态刻度。 NaturalRestingScale 属性是 InteractionTracker 将在不考虑边界或惯性修饰符的情况下停止的计算比例位置。 此属性通常适用于滚动体验中的虚拟化等操作，其中必须知道 InteractionTracker 停止的位置。 使用 NaturalRestingScale 属性有两个main用例：在 InertiaStateEntered 事件参数中检索其当前值，或者在创建惯性修饰符等内容时在 ExpressionAnimation 中引用此属性。
Owner	与 InteractionTracker 关联的 IInteractionTrackerOwner。
Position	由 InteractionTracker 计算的输出位置。 当前位置是相对值。 在 Idle 和 CustomAnimation 状态期间，它将始终介于 MinPosition 和 MaxPosition 属性中指定的值之间。 InteractionTracker 的位置属性可以在交互和惯性状态期间超出此范围，以便在边界处显示反弹或阻力。 InteractionTracker 的位置属性是一个 Vector3，表示 X、Y 和 Z 轴中的位置。 此时，X 和 Y 通道是唯一将由 InteractionTracker 更新的组件。 如果未设置 MinPosition 和 MaxPosition，此 Vector3 的通道不会在 0 (默认值) 波动。
PositionInertiaDecayRate	位置的惯性衰减率。 范围为 0 到 1。 PositionInertiaDecayRate 属性定义 InteractionTracker 进入惯性且位置发生变化时减慢停止的速度。 越接近 1， InteractionTracker 的速度越快，停止的速度就越慢，反之亦然。 定义为 Vector3，每个分量相应地表示 x、y、z 的惯性衰减率。
PositionVelocityInPixelsPerSecond	当前应用于位置的速度。 PositionVelocityInPixelsPerSecond 属性表示在 Inertia 中的 InteractionTracker 当前位置速度。 此属性有两个main用例：在交互发生后立即检索 InteractionTracker 的位置速度，或在 ExpressionAnimation 中引用 InteractionTracker 的最新速度。
Properties	与 CompositionObject 关联的属性的集合。 (继承自 CompositionObject)
Scale	由 InteractionTracker 计算的输出比例。 当前小数位数是一个相对值，取决于 MinScale 和 MaxScale 属性中指定的值。 InteractionTracker 的 scale 属性是一个浮点数，表示 InteractionTracker 坐标空间中的刻度。 此值将从 1 开始，并将根据活动输入或直接调用来增加或减少以更新或创建属性动画。 当 InteractionTracker 处于 Idle 或 CustomAnimation 状态时，scale 属性不会从 1 更改，除非更新 MinScale 和 MaxScale 属性（默认值均为 1）。 InteractionTracker 在交互和惯性状态期间，的比例可能会略超出此范围，以便在边界处显示反弹或阻力。
ScaleInertiaDecayRate	惯性衰减率，用于缩放。 范围为 0 到 1。 ScaleInertiaDecayRate 属性定义 当 InteractionTracker 进入惯性且缩放发生更改时减慢到停止的速度。 越接近 1， InteractionTracker 的速度越快，停止的速度就越慢，反之亦然。 与定义为 Vector3 的 PositionInertiaDecayRate 不同，ScaleInertiaDecayRate 定义为单个浮点数。
ScaleVelocityInPercentPerSecond	缩放的更改率。 ScaleVelocityInPercentPerSecond 属性表示在惯性模式下 的 InteractionTracker 的当前缩放速度。 在交互发生后立即获取 InteractionTracker 的位置速度，或在 ExpressionAnimation 中引用 InteractionTracker 的最新速度。

方法

AdjustPositionXIfGreaterThanThreshold(Single, Single)	如果 x 坐标大于指定的阈值，则调整其位置。
AdjustPositionYIfGreaterThanThreshold(Single, Single)	如果位置 y 坐标大于指定的阈值，则调整该坐标。
Close()	关闭 CompositionObject 并释放系统资源。 (继承自 CompositionObject)
ConfigureCenterPointXInertiaModifiers(IIterable<CompositionConditionalValue>)	采用 CompositionConditionalValue 的有序列表。 在帧中，当跟踪器处于惯性状态时，第一个 CompositionConditionalValue 具有其 “ 。“条件”的计算结果为 true，将跟踪器使用的缩放 CenterPointX 值替换为其 “。Value”。 如果没有计算结果为 true，则不替换该框架的 CenterPointX。
ConfigureCenterPointYInertiaModifiers(IIterable<CompositionConditionalValue>)	采用 CompositionConditionalValue 的有序列表。 在帧中，当跟踪器处于惯性状态时，第一个 CompositionConditionalValue 具有其 “ 。条件“的计算结果为 true，将跟踪器使用的缩放 CenterPointY 值替换为其 ”。Value”。 如果没有的计算结果为 true，则不替换该框架的 CenterPointY。
ConfigurePositionXInertiaModifiers(IIterable<InteractionTrackerInertiaModifier>)	将 InteractionTrackerInertiaModifier 对象的集合应用于 InteractionTracker 的 x 惯性。 ConfigurePositionXInertiaModifiers 方法将 InteractionTrackerInertiaModifier的单个或集合应用于 InteractionTracker 的 x 组件。 系统将按照添加到 InteractionTracker 的顺序评估每个 X 修饰符的条件属性。 因此， InteractionTrackerInertiaModifier 在集合中的顺序将与系统计算的顺序相同。
ConfigurePositionYInertiaModifiers(IIterable<InteractionTrackerInertiaModifier>)	将 InteractionTrackerInertiaModifier 对象的集合应用于 InteractionTracker 的 y 惯性。 ConfigurePositionYInertiaModifiers 方法将 InteractionTrackerInertiaModifiers 的单个或集合应用于 InteractionTracker 的 y 组件。 系统将按照添加到 InteractionTracker 的顺序评估每个 Y 修饰符的条件属性。 因此， InteractionTrackerInertiaModifier 在集合中的顺序将与系统计算的顺序相同。
ConfigureScaleInertiaModifiers(IIterable<InteractionTrackerInertiaModifier>)	将 InteractionTrackerInertiaModifier 对象的集合应用于 InteractionTracker 的规模。 ConfigureScaleInertiaModifiers 方法将 InteractionTrackerInertiaModifier的单个或集合应用于 InteractionTracker 的缩放组件。 系统将按照添加到 InteractionTracker 的顺序评估 Scale 修饰符的每个条件属性。 因此， InteractionTrackerInertiaModifier 在集合中的顺序将与系统计算的顺序相同。
ConfigureVector2PositionInertiaModifiers(IIterable<InteractionTrackerVector2InertiaModifier>)	将 InteractionTrackerInertiaModifier 对象的集合应用于 InteractionTracker 的位置。
Create(Compositor)	创建 InteractionTracker 的实例。 此 Create 方法将实例化 InteractionTracker。 创建 InteractionTracker 设置属性、附加 VisualInteractionSource 并在 ExpressionAnimation 中引用位置或缩放后，活动输入可以驱动 ExpressionAnimation。
CreateWithOwner(Compositor, IInteractionTrackerOwner)	使用指定的所有者创建 InteractionTracker 的实例。 此 Create 方法将与所有者实例化 InteractionTracker ，以便注册回调。 创建 InteractionTracker 设置属性、附加 VisualInteractionSource 并在 ExpressionAnimation 中引用位置或缩放后，活动输入可以驱动 ExpressionAnimation。 仅当应用程序需要接收有关 InteractionTracker 的状态和值的回调时，才需要创建具有所有者的 InteractionTracker。
Dispose()	执行与释放或重置非托管资源关联的应用程序定义的任务。 (继承自 CompositionObject)
GetBindingMode(InteractionTracker, InteractionTracker)	检索两个交互跟踪器之间的绑定轴模式。
PopulatePropertyInfo(String, AnimationPropertyInfo)	定义可进行动画处理的属性。 (继承自 CompositionObject)
SetBindingMode(InteractionTracker, InteractionTracker, InteractionBindingAxisModes)	设置两个交互跟踪器之间的绑定轴模式。
StartAnimation(String, CompositionAnimation)	将动画与 对象的指定属性连接，并启动动画。 (继承自 CompositionObject)
StartAnimation(String, CompositionAnimation, AnimationController)	将动画与 对象的指定属性连接，并启动动画。 (继承自 CompositionObject)
StartAnimationGroup(ICompositionAnimationBase)	启动动画组。 使用 CompositionObject 上的 StartAnimationGroup 方法可以启动 CompositionAnimationGroup。 组中的所有动画都将在 对象上同时启动。 (继承自 CompositionObject)
StopAnimation(String)	断开动画与指定属性的连接，并停止动画。 (继承自 CompositionObject)
StopAnimationGroup(ICompositionAnimationBase)	停止动画组。 (继承自 CompositionObject)
TryGetAnimationController(String)	返回指定属性上运行的动画的 AnimationController。 (继承自 CompositionObject)
TryUpdatePosition(Vector3)	尝试更新 InteractionTracker 的位置。 TryUpdatePosition 方法将 InteractionTracker 的位置更新为指定为参数的 Vector3 位置。 TryUpdatePosition 用于以声明方式定义 InteractionTracker 在任意时间点的位置， (在开始时、从某些进入状态的事件等) 。 可以从 Idle、CustomAnimation 或 Inertia 状态调用 TryUpdatePosition - 这样做会将 InteractionTracker 的位置移动到定义的位置并进入空闲状态。
TryUpdatePosition(Vector3, InteractionTrackerClampingOption)	尝试使用指定的固定选项更新 InteractionTracker 的位置。
TryUpdatePosition(Vector3, InteractionTrackerClampingOption, InteractionTrackerPositionUpdateOption)	尝试使用指定的固定选项更新 InteractionTracker 的位置。
TryUpdatePositionBy(Vector3)	尝试按指定量调整 InteractionTracker 的位置。 TryUpdatePositionBy 方法通过指定为参数的 Vector3 增量更新 InteractionTracker 的当前位置。 与 TryUpdatePosition 类似，TryUpdatePositionBy 用于按定义的增量以声明方式移动 InteractionTracker ，而无需动画或惯性。 可以从 Idle、CustomAnimation 或 Inertia 状态调用 TryUpdatePositionBy - 这样做将按定义的增量移动 InteractionTracker 的位置并进入空闲状态。
TryUpdatePositionBy(Vector3, InteractionTrackerClampingOption)	尝试使用指定的固定选项按指定量调整 InteractionTracker 的位置。
TryUpdatePositionWithAdditionalVelocity(Vector3)	尝试通过添加速度来更新 InteractionTracker 的位置。 TryUpdatePositionWithAdditionalVelocity 方法将表示其他速度的输入 Vector3 添加到 InteractionTracker 的当前速度。 因此，由于 InteractionTracker 的速度现在已更改， 因此 InteractionTracker 的目标静态位置现在会更改。 TryUpdatePositionWithAdditionalVelocity 可以从空闲、惯性或 CustomAnimation 状态调用 ， 这样做将添加或更新 InteractionTracker 的速度并进入惯性状态。
TryUpdatePositionWithAnimation(CompositionAnimation)	尝试通过应用动画来更新 InteractionTracker 的位置。 TryUpdatePositionWithAnimation 方法根据 CompositionAnimation 输入作为参数更新 InteractionTracker 的位置。 此方法用于需要由特定动画而不是传统的惯性体验定义的 InteractionTracker 运动的情况。 可以从空闲或惯性状态调用 TryUpdatePositionWithAnimation - 这样做， InteractionTracker 的位置将由定义的动画驱动，并进入 CustomAnimation 状态。
TryUpdateScale(Single, Vector3)	尝试将刻度更新为指定的值。 TryUpdateScale 方法将 InteractionTracker 的缩放位置更新为指定为参数的缩放位置和中心点。 TryUpdateScale 用于在任意时间点以声明方式定义 InteractionTracker 的规模， (在开始时、从某些进入状态的事件等) 。 可以从 Idle、CustomAnimation 或 Inertia 状态调用 TryUpdateScale ， 这样做会将 InteractionTracker 的缩放位置移动到定义的位置并进入空闲状态。
TryUpdateScaleWithAdditionalVelocity(Single, Vector3)	尝试通过添加指定的速度来更新刻度。 TryUpdateScaleWithAdditionalVelocity 方法将表示其他速度的输入标量添加到 InteractionTracker 的当前速度，并将中心点移动到输入的 Vector3。 因此，由于 InteractionTracker 的速度现已更改，因此 InteractionTracker 的目标静态缩放位置现在会更改。 可以从 Idle、Inertia 或 CustomAnimation 状态调用 TryUpdateScaleWithAdditionalVelocity - 这样做将添加或更新 InteractionTracker 的速度并进入惯性状态。
TryUpdateScaleWithAnimation(CompositionAnimation, Vector3)	尝试使用指定的动画更新刻度。 TryUpdateScaleWithAnimation 方法根据作为参数输入的 CompositionAnimation 更新 InteractionTracker 的缩放位置。 此方法用于需要由特定动画而不是传统的惯性体验定义的 InteractionTracker 运动的情况。 可以从空闲或惯性状态调用 TryUpdateScaleWithAnimation - 这样做， InteractionTracker 的位置将由定义的动画驱动并进入 CustomAnimation 状态。

另请参阅

• VisualInteractionSource
• ExpressionAnimation