🆕 feat(PageStack): add support for going back to specific page

docs/Masa.Blazor.Docs/Pages/PageStackPage3.razor

@@ -14,6 +14,11 @@
 
 <h3>Page 3 created at @(DateTimeOffset.UtcNow.ToString("HH:mm:ss zz"))</h3>
 
+<a class="text-decoration-underline"
+   @onclick="@(() => NavController.GoBackToPage("/blazor/examples/page-stack/page1"))">
+   Go back to page 1
+</a>
+
 <MSyntaxHighlight Code="@sourceCode"
                   Language="razor"
                   Style="font-size: 10px">

docs/Masa.Blazor.Docs/Pages/PageStackPage3.razor.cs

@@ -11,5 +11,7 @@ public partial class PageStackPage3
                 </MButton>
             </ActionContent>
         </PStackPageBarInit>
+
+        <a @onclick="@(() => NavController.GoBackToPage("/blazor/examples/page-stack/page1"))">Go back to page 1</a>
         """;
 }

docs/Masa.Blazor.Docs/wwwroot/pages/labs/page-stack/en-US.md

@@ -35,14 +35,15 @@ related:
 
 Used to control the navigation of the page stack.
 
-| Method name | Description                                                     |
-|-------------|-----------------------------------------------------------------|
-| `Push`      | Push a new page onto the stack.                                 |
-| `Pop`       | Pop the current page from the stack, equivalent to `GoBack(1)`. |
-| `GoBack`    | Return to the specified number of pages.                        |
-| `Replace`   | Replace the current page.                                       |
-| `Clear`     | Clear the current page stack.                                   |
-| `GoToTab`   | Clear the current stack and jump to the specified tab.          |
+| Method name    | Description                                                     |
+|----------------|-----------------------------------------------------------------|
+| `Push`         | Push a new page onto the stack.                                 |
+| `Pop`          | Pop the current page from the stack, equivalent to `GoBack(1)`. |
+| `GoBack`       | Return to the specified number of pages.                        |
+| `GoBackToPage` | Return to the specified page.                                   |
+| `Replace`      | Replace the current page.                                       |
+| `Clear`        | Clear the current page stack.                                   |
+| `GoBackToTab`  | Clear the current stack and jump to the specified tab.          |
 
 ```razor
 @inject PageStackNavController NavController

docs/Masa.Blazor.Docs/wwwroot/pages/labs/page-stack/zh-CN.md

@@ -39,9 +39,10 @@ related:
 | `Push`    | 将新页面推入堆栈。                  |
 | `Pop`     | 将当前页面弹出堆栈，同等于 `GoBack(1)`。 |
 | `GoBack`  | 返回到指定的前几个页面。               |
+| `GoBackToPage` | 返回到指定页面。                   |
 | `Replace` | 替换当前页面。                    |
 | `Clear`   | 清空当前页面堆栈。                  |
-| `GoToTab` | 清空当前堆栈并跳转到指定选项卡。           |
+| `GoBackToTab` | 清空当前堆栈并跳转到指定选项卡。           |
 
 ```razor
 @inject PageStackNavController NavController

src/Masa.Blazor/Presets/PageStack/NavController/PageStackGoBackToPageEventArgs.cs

@@ -0,0 +1,16 @@
+namespace Masa.Blazor.Presets.PageStack.NavController;
+
+public class PageStackGoBackToPageEventArgs : EventArgs
+{
+    public PageStackGoBackToPageEventArgs(string absolutePath, object? state = null)
+    {
+        ArgumentNullException.ThrowIfNull(absolutePath);
+
+        AbsolutePath = absolutePath;
+        State = state;
+    }
+
+    public string AbsolutePath { get; }
+
+    public object? State { get; }
+}

src/Masa.Blazor/Presets/PageStack/NavController/PageStackNavController.cs

@@ -34,6 +34,11 @@ public class PageStackNavController(IJSRuntime jsRuntime, NavigationManager navi
     /// </summary>
     public event EventHandler<PageStackPageClosedEventArgs>? PageClosed;
 
+    /// <summary>
+    /// Occurs when user invoked the <see cref="GoBackToPage(string)"/> method.
+    /// </summary>
+    internal event EventHandler<PageStackGoBackToPageEventArgs>? StackGoBackTo;
+
     /// <summary>
     /// Push a new page onto the page stack.
     /// </summary>
@@ -76,6 +81,16 @@ public void GoBack(int delta = 1, object? state = null)
         });
     }
 
+    /// <summary>
+    /// Go back to the specified page in the page stack.
+    /// If the page is not found, do nothing.
+    /// </summary>
+    /// <param name="absolutePath"></param>
+    public void GoBackToPage(string absolutePath)
+    {
+        ExecuteIfTimeElapsed(() => StackGoBackTo?.Invoke(this, new PageStackGoBackToPageEventArgs(absolutePath)));
+    }
+
     /// <summary>
     /// Replace the current page with the new page.
     /// </summary>
@@ -102,7 +117,17 @@ public void Clear()
     /// Clear current page stack and navigate to the new tab.
     /// </summary>
     /// <param name="relativeUri"></param>
+    [Obsolete("Use GoBackToTab instead.")]
     public void GoToTab(string relativeUri)
+    {
+        GoBackToTab(relativeUri);
+    }
+
+    /// <summary>
+    /// Clear current page stack and navigate to the new tab.
+    /// </summary>
+    /// <param name="relativeUri"></param>
+    public void GoBackToTab(string relativeUri)
     {
         ExecuteIfTimeElapsed(() => { StackClear?.Invoke(this, new PageStackClearEventArgs(relativeUri)); });
     }

src/Masa.Blazor/Presets/PageStack/PPageStack.razor.cs

@@ -66,10 +66,26 @@ protected override void OnInitialized()
         InternalPageStackNavManager.StackPop += InternalPageStackNavManagerOnStackPop;
         InternalPageStackNavManager.StackReplace += InternalStackStackNavManagerOnStackReplace;
         InternalPageStackNavManager.StackClear += InternalStackStackNavManagerOnStackClear;
+        InternalPageStackNavManager.StackGoBackTo += InternalPageStackNavManagerOnStackGoBackTo;
 
         _dotNetObjectReference = DotNetObjectReference.Create(this);
     }
 
+    private void InternalPageStackNavManagerOnStackGoBackTo(object? sender, PageStackGoBackToPageEventArgs e)
+    {
+        var delta = Pages.GetDelta(e.AbsolutePath);
+        if (delta == -1)
+        {
+            return;
+        }
+
+        _popstateByUserAction = true;
+
+        _ = Js.InvokeVoidAsync(JsInteropConstants.HistoryGo, -delta);
+
+        CloseTopPages(delta, null);
+    }
+
     protected override async Task OnAfterRenderAsync(bool firstRender)
     {
         await base.OnAfterRenderAsync(firstRender);
@@ -254,6 +270,7 @@ protected override async ValueTask DisposeAsyncCore()
             InternalPageStackNavManager.StackPop -= InternalPageStackNavManagerOnStackPop;
             InternalPageStackNavManager.StackReplace -= InternalStackStackNavManagerOnStackReplace;
             InternalPageStackNavManager.StackClear -= InternalStackStackNavManagerOnStackClear;
+            InternalPageStackNavManager.StackGoBackTo -= InternalPageStackNavManagerOnStackGoBackTo;
         }
     }
 

src/Masa.Blazor/Presets/PageStack/StackPages.cs

@@ -92,6 +92,17 @@ internal bool TryPeekByLastIndex(int index, [NotNullWhen(true)] out StackPageDat
         return true;
     }
 
+    /// <summary>
+    /// Get the number of pages between the current page and the specified page.
+    /// </summary>
+    /// <param name="absolutePath"></param>
+    /// <returns></returns>
+    internal int GetDelta(string absolutePath)
+    {
+        var lastIndex = _pages.FindLastIndex(x => x.AbsolutePath == absolutePath);
+        return lastIndex == -1 ? -1 : _pages.Count - 1 - lastIndex;
+    }
+
     internal void RemoveRange(int index, int count) => _pages.RemoveRange(index, count);
 
     internal StackPageData ElementAt(int index) => _pages.ElementAt(index);