在 Windows 应用 SDK 应用中创建用户活动

用户活动表示用户在应用中执行的任务。 你可以创建活动，让用户能够从上次中断的地方继续。 活动显示在本地活动历史记录中，可以通过Windows功能显示，这些功能可帮助用户返回到以前的任务。

先决条件

• 你的应用必须打包（MSIX）或具有包标识。
• 不需要特殊功能声明 — UserActivity API 适用于所有打包的应用。

创建用户活动

使用 UserActivityChannel 和 UserActivity 类：

using Windows.ApplicationModel.UserActivities;

private UserActivitySession? _currentSession;

private async Task CreateActivityAsync()
{
    var channel = UserActivityChannel.GetDefault();
    var activity = await channel.GetOrCreateUserActivityAsync("document-123");

    activity.ActivationUri = new Uri("myapp://open?doc=123");
    activity.VisualElements.DisplayText = "Quarterly Report";
    activity.VisualElements.Description = "Working on Q4 financial summary";

    await activity.SaveAsync();
    _currentSession = activity.CreateSession();
}

活动会话表示用户当前已参与此任务。 当用户切换到其他任务时，将其处置。

设置丰富的视觉细节

使用 UserActivityVisualElements 上的属性向用户描述活动：

UserActivity activity = new UserActivity("quarterly-report");

activity.VisualElements.DisplayText = "Quarterly Report";
activity.VisualElements.Description = "Last edited: Section 3 - Revenue Analysis";
activity.VisualElements.Attribution = new UserActivityAttribution(
    new Uri("ms-appx:///Assets/AppIcon.png"));

处理来自 Activity 的激活

当用户选择要恢复的活动时，你的应用会使用协议 URI 激活。 在激活逻辑中处理它：

var activatedArgs = AppInstance.GetCurrent().GetActivatedEventArgs();

if (activatedArgs.Kind == ExtendedActivationKind.Protocol)
{
    var protocolArgs = activatedArgs.Data as Windows.ApplicationModel.Activation.IProtocolActivatedEventArgs;
    if (protocolArgs?.Uri.Scheme == "myapp")
    {
        // Parse the query string manually; System.Web.HttpUtility isn't
        // available to apps that target .NET (as opposed to .NET Framework).
        string? docId = protocolArgs.Uri.Query
            .TrimStart('?')
            .Split('&', StringSplitOptions.RemoveEmptyEntries)
            .Select(pair => pair.Split('=', 2))
            .FirstOrDefault(pair => pair[0] == "doc")
            ?.ElementAtOrDefault(1);
        // Navigate to the document
    }
}

结束会话

当用户停止处理活动时，释放会话：

UserActivitySession? _currentSession = null;

_currentSession?.Dispose();
_currentSession = null;

最佳做法

• 使用有意义的活动 ID — ID 应唯一标识任务（例如，文档路径或项目名称）。
• 更新活动 — 用户进行进度时调用 SaveAsync() 以保持说明最新状态。
• 设置激活 URI — 始终提供 URI，以便活动可以将应用重新启动到正确的状态。
• 一次创建一个会话——在创建新会话之前，先释放之前的会话。

有关详细指南，请参阅 用户活动最佳做法。

相关内容

• 用户活动最佳做法
• UserActivity 类
• UserActivityChannel 类
• 自适应卡片 (自适应卡片)