在 Windows 應用程式 SDK 應用程式中建立使用者活動

使用者活動代表使用者在應用程式中執行的任務。 你可以建立活動，讓使用者能從中斷的地方繼續。 活動會出現在本地活動歷史紀錄中，並可透過 Windows 功能顯示，幫助使用者回到先前的任務。

Note

Timeline 雲端同步功能於 2021 年 7 月被淘汰。 您的應用程式所建立的使用者活動會儲存在本地，不再透過 Microsoft Graph Timeline 在裝置間同步。 裝置的本地活動紀錄仍然正常。

先決條件

  • 你的應用程式必須是打包（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"));

Note

AdaptiveCardBuilder（Windows.UI.Shell）可讓你將完整的 Adaptive Card 轉譯為活動的視覺呈現，但該介面屬於 Windows Timeline 的一部分，而 Microsoft 已將其停用。 不要在新程式碼中使用 AdaptiveCardBuilder ——改用 VisualElements 上述的屬性。

處理活動的啟動

當使用者選擇要繼續的活動時，應用程式會以協議 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，讓活動能將應用程式重新啟動至正確狀態。
  • 一次建立一個會話 — 先處理前一個會話再建立新會話。

如需詳細指引，請參閱 使用者活動最佳實務。

相關內容

  • Last updated on