🆕 feat: Add ScrollToTarget component (#1730)

* 🆕 feat: Add ScrollToTarget component * done
masastack · Jan 26, 2024 · 1477f43 · 1477f43
1 parent f298bd5
commit 1477f43
Show file tree

Hide file tree

Showing 38 changed files with 695 additions and 235 deletions.
diff --git a/docs/Masa.Blazor.Docs/Examples/components/application/DefaultAppMarkup.razor b/docs/Masa.Blazor.Docs/Examples/components/application/DefaultAppMarkup.razor
@@ -1,6 +1,6 @@
 @attribute [JSCustomElement]
 
-<Markup Class="mb-4" Code="@Code" Language="@Language" FileName="@FileName" LineHighlights="@LineHighlights"></Markup>
+<Markup Class="pb-4" Code="@Code" Language="@Language" FileName="@FileName" LineHighlights="@LineHighlights"></Markup>
 
 @code {
     [Parameter]

diff --git a/docs/Masa.Blazor.Docs/Examples/labs/scroll-to-target/ChipGroup.razor b/docs/Masa.Blazor.Docs/Examples/labs/scroll-to-target/ChipGroup.razor
@@ -0,0 +1,45 @@
+<MScrollToTarget ScrollContainerSelector="#scroll-to-target-chip-group-scroll"
+                 RootSelector="#scroll-to-target-chip-group"
+                 RootMarginTop="-50%"
+                 RootMarginBottom="-50%">
+    <MChipGroup Value="@context.ActiveTarget"
+                ActiveClass="primary--text">
+        @foreach (var item in _items)
+        {
+            <MScrollToTargetTrigger Target="@item" Context="triggerContext">
+                <MChip Outlined
+                       Value="@item"
+                       OnClick="@triggerContext.ScrollToTarget">
+                    @item
+                </MChip>
+            </MScrollToTargetTrigger>
+        }
+    </MChipGroup>
+    <div id="scroll-to-target-chip-group"
+         style="position: relative; height: 300px;"
+         class="d-flex flex-column overflow-hidden surface">
+        <div id="scroll-to-target-chip-group-scroll"
+             class="px-4"
+             style="flex: 1;overflow-y: scroll;">
+            @foreach (var item in _items)
+            {
+                <div id="@item"
+                     Class="d-flex justify-center align-center"
+                     style="border: 1px dashed; height: 100%; width: 100%">
+                    Content for @item
+                </div>
+            }
+        </div>
+    </div>
+</MScrollToTarget>
+
+@code {
+
+    private List<string> _items =
+    [
+        "chip-1",
+        "chip-2",
+        "chip-3"
+    ];
+
+}
diff --git a/docs/Masa.Blazor.Docs/Examples/labs/scroll-to-target/Tabs.razor b/docs/Masa.Blazor.Docs/Examples/labs/scroll-to-target/Tabs.razor
@@ -0,0 +1,46 @@
+<div id="scroll-to-target-tabs"
+     style="position: relative; height: 300px;"
+     class="d-flex overflow-hidden surface">
+    <MScrollToTarget ScrollContainerSelector="#scroll-to-target-tabs-scroll"
+                     RootSelector="#scroll-to-target-tabs"
+                     RootMarginTop="-50%"
+                     RootMarginBottom="-50%"
+                     DisableIntersectAfterTriggering>
+        <MTabs Value="@context.ActiveTarget"
+               Vertical
+               Style="width: auto; flex: none;">
+            @foreach (var item in _items)
+            {
+                <MScrollToTargetTrigger Target="@item" Context="triggerContext">
+                    <MTab Value="@item"
+                          OnClick="@triggerContext.ScrollToTarget">
+                        @item
+                    </MTab>
+                </MScrollToTargetTrigger>
+            }
+        </MTabs>
+        <div id="scroll-to-target-tabs-scroll"
+             class="px-4"
+             style="flex: 1;overflow-y: scroll;">
+            @foreach (var item in _items)
+            {
+                <div id="@item"
+                     Class="d-flex justify-center align-center"
+                     style="border: 1px dashed; height: 100%; width: 100%">
+                        Content for @item
+                </div>
+            }
+        </div>
+    </MScrollToTarget>
+</div>
+
+@code {
+
+    private List<string> _items =
+    [
+        "menu-1",
+        "menu-2",
+        "menu-3"
+    ];
+
+}
diff --git a/docs/Masa.Blazor.Docs/Pages/Components.razor b/docs/Masa.Blazor.Docs/Pages/Components.razor
@@ -4,8 +4,8 @@
 <MContainer Class="pa-4 pa-sm-6 pa-md-8"
             Fluid
             Tag="section">
-    <MResponsive MaxWidth="960"
-                 Class="mx-auto overflow-visible">
+    <div style="max-width: 960px"
+         class="mx-auto overflow-visible">
         @if (_frontMatterMeta is not null)
         {
             <FrontMatter Meta="_frontMatterMeta" AdditionalTags="@Tags"></FrontMatter>
@@ -23,18 +23,14 @@
             </MTabs>
         }
 
-        @if (IsApiTab && _apiData.Count == 0)
-        {
-            <MSkeletonLoader Type="table"></MSkeletonLoader>
-        }
-        else if (!IsApiTab && _md == null)
-        {
-            <MSkeletonLoader Type="article,card"></MSkeletonLoader>
-        }
-        else
-        {
-            <MTabsItems Value="IsApiTab.ToString()" Style="background-color: unset;">
-                <MTabItem Value="@("False")" Transition="" Eager>
+        <MTabsItems Value="IsApiTab.ToString()" Style="background-color: unset; overflow: unset;">
+            <MTabItem Value="@("False")" Transition="" Eager>
+                @if (_md == null)
+                {
+                    <MSkeletonLoader Type="article,card"></MSkeletonLoader>
+                }
+                else
+                {
                     <DocumentMarkdownIt Source="@_md"
                                         OnTocParsed="@OnTocParsed"
                                         OnFrontMatterParsed="@OnFrontMatterParsed" />
@@ -43,16 +39,23 @@
                     {
                         <BackMatter Related="@_frontMatterMeta.Related"></BackMatter>
                     }
-                </MTabItem>
-                <MTabItem Value="@("True")" Transition="">
+                }
+            </MTabItem>
+            <MTabItem Value="@("True")" Transition="">
+                @if (_apiData.Count == 0)
+                {
+                    <MSkeletonLoader Type="table"></MSkeletonLoader>
+                }
+                else
+                {
                     <Apis @bind-Value="@CurrentApi"
                           Data="@_apiData"
                           GithubUri="@ApiGithubUri">
                     </Apis>
-                </MTabItem>
-            </MTabsItems>
-        }
+                }
+            </MTabItem>
+        </MTabsItems>
 
         <Contribute GithubUri="@(IsApiTab ? ApiGithubUri : ComponentGithubUri)" />
-    </MResponsive>
+    </div>
 </MContainer>
diff --git a/docs/Masa.Blazor.Docs/wwwroot/data/apis/scroll-to-target/MScrollToTarget-en-US.json b/docs/Masa.Blazor.Docs/wwwroot/data/apis/scroll-to-target/MScrollToTarget-en-US.json
@@ -0,0 +1,18 @@
+{
+  "props": {
+    "activeClass": "A css class to be added to the observed target when it is intersecting",
+    "autoRootMargin": "A boolean which specifies whether the rootMargin should be calculated automatically",
+    "Offset": "Scroll offset",
+    "RootMarginBottom": "The bottom margin of the root's bounding box",
+    "RootMarginLeft": "The left margin of the root's bounding box",
+    "RootMarginRight": "The right margin of the root's bounding box",
+    "RootMarginTop": "The top margin of the root's bounding box",
+    "RootSelector": "A string which specifies a set of offsets to add to the root's bounding_box when calculating intersections",
+    "ScrollContainerSelector": "A string which specifies a selector for the scroll container of the observed targets",
+    "Threshold": "specifying a ratio of intersection area to total bounding box area for the observed target.",
+    "DisableIntersectAfterTriggering": "Whether to disable intersection activation briefly when scrolling after clicking to trigger"
+  },
+  "methods": {
+    "scrollToTarget": "Scroll to the target element, input argument is the target element `id`"
+  }
+}
diff --git a/docs/Masa.Blazor.Docs/wwwroot/data/apis/scroll-to-target/MScrollToTarget-zh-CN.json b/docs/Masa.Blazor.Docs/wwwroot/data/apis/scroll-to-target/MScrollToTarget-zh-CN.json
@@ -0,0 +1,18 @@
+{
+  "props": {
+    "activeClass": "目标元素与视区相交时需要添加的类名，可以通过 context 获取",
+    "autoRootMargin": "是否自动计算 rootMargin",
+    "Offset": "滚动偏移量",
+    "RootMarginBottom": "根元素的底部边界",
+    "RootMarginLeft": "根元素的左边界",
+    "RootMarginRight": "根元素的右边界",
+    "RootMarginTop": "根元素的顶部边界",
+    "RootSelector": "根元素的选择器",
+    "ScrollContainerSelector": "滚动容器的选择器",
+    "Threshold": "交叉比例阈值",
+    "DisableIntersectAfterTriggering": "是否在点击触发后滚动时短暂禁用交叉激活"
+  },
+  "methods": {
+    "scrollToTarget": "滚动到目标元素，入参为目标元素的`id`"
+  }
+}
diff --git a/docs/Masa.Blazor.Docs/wwwroot/data/apis/scroll-to-target/MScrollToTargetTrigger-en-US.json b/docs/Masa.Blazor.Docs/wwwroot/data/apis/scroll-to-target/MScrollToTargetTrigger-en-US.json
@@ -0,0 +1,5 @@
+{
+  "props": {
+    "target": "The `id` of the target element, also used to register the intersection observer"
+  }
+}
diff --git a/docs/Masa.Blazor.Docs/wwwroot/data/apis/scroll-to-target/MScrollToTargetTrigger-zh-CN.json b/docs/Masa.Blazor.Docs/wwwroot/data/apis/scroll-to-target/MScrollToTargetTrigger-zh-CN.json
@@ -0,0 +1,5 @@
+{
+  "props": {
+    "target": "目标元素的`id`，也用于注册交叉观察器"
+  }
+}
diff --git a/docs/Masa.Blazor.Docs/wwwroot/data/nav.json b/docs/Masa.Blazor.Docs/wwwroot/data/nav.json
@@ -296,6 +296,11 @@
         "state": "new",
         "releasedOn": "v1.1.1"
       },
+      {
+        "title": "scroll-to-target",
+        "state": "new",
+        "releasedOn": "v1.3.4"
+      },
       {
         "title": "splitters",
         "state": "new",

diff --git a/docs/Masa.Blazor.Docs/wwwroot/data/page-to-api.json b/docs/Masa.Blazor.Docs/wwwroot/data/page-to-api.json
@@ -148,6 +148,10 @@
   "date-pickers-month": [
     "MDatePicker"
   ],
+  "scroll-to-target": [
+    "MScrollToTarget",
+    "MScrollToTargetTrigger"
+  ],
   "steppers": [
     "MStepper",
     "MStepperContent",
@@ -187,6 +191,7 @@
     "MXgMusicPlayer",
     "MXgplayerControls",
     "MXgplayerPlay",
-    "MXgplayerTime"
+    "MXgplayerTime",
+    "MXgplayerStart"
   ]
 }
diff --git a/docs/Masa.Blazor.Docs/wwwroot/pages/labs/scroll-to-target/en-US.md b/docs/Masa.Blazor.Docs/wwwroot/pages/labs/scroll-to-target/en-US.md
@@ -0,0 +1,24 @@
+---
+title: Scroll to target
+desc: "Provides a set of components that support automatic scrolling to the specified element and highlighting of the active item."
+related:
+  - /docs/components/tabs
+  - /docs/components/chip-groups
+---
+
+**MScrollToTarget** component is used to set the configuration of the intersection observer API so that the active item is set when scrolling to the target element.
+
+**MScrollToTargetTrigger** component provides the ability to trigger scrolling to the target element, and provides the `Target` of the tracked element, that is, the `id` of the target element.
+
+## Examples
+
+### Misc
+
+#### Tabs
+
+<masa-example file="Examples.labs.scroll_to_target.Tabs"></masa-example>
+
+#### Chip group
+
+<masa-example file="Examples.labs.scroll_to_target.ChipGroup"></masa-example>
+
diff --git a/docs/Masa.Blazor.Docs/wwwroot/pages/labs/scroll-to-target/zh-CN.md b/docs/Masa.Blazor.Docs/wwwroot/pages/labs/scroll-to-target/zh-CN.md
@@ -0,0 +1,23 @@
+---
+title: Scroll to target（滚动到目标）
+desc: "提供一组组件，支持自动滚动到指定元素和高亮激活项。"
+related:
+  - /docs/components/tabs
+  - /docs/components/chip-groups
+---
+
+**MScrollToTarget** 组件用于设置交叉点观察者API的配置，以便在滚动到目标元素时设置激活项。
+
+**MScrollToTargetTrigger** 组件提供触发滚动到目标元素的功能，并提供跟踪的元素的`Target`，即目标元素的 `id`。
+
+## 示例
+
+### 其他
+
+#### 选项卡
+
+<masa-example file="Examples.labs.scroll_to_target.Tabs"></masa-example>
+
+#### 纸片组
+
+<masa-example file="Examples.labs.scroll_to_target.ChipGroup"></masa-example>
diff --git a/docs/Masa.Docs.Core/Components/AppCodeGroup.razor b/docs/Masa.Docs.Core/Components/AppCodeGroup.razor
@@ -1,7 +1,7 @@
 @using System.Text.Json.Serialization
 @attribute [JSCustomElement]
 
-<div class="mb-4">
+<div class="pb-4">
     @if (Model is not null)
     {
         <MLazy MinHeight="48">

diff --git a/docs/Masa.Docs.Core/Components/DocumentMarkdownIt.razor b/docs/Masa.Docs.Core/Components/DocumentMarkdownIt.razor
@@ -15,6 +15,9 @@
 
 @code {
 
+    [CascadingParameter]
+    private MScrollToTarget? ScrollToTargetComp { get; set; }
+
     [CascadingParameter(Name = "IsDark")]
     private bool IsDark { get; set; }
 

diff --git a/docs/Masa.Docs.Shared/Pages/Document.razor b/docs/Masa.Docs.Shared/Pages/Document.razor
@@ -4,11 +4,11 @@
 <MContainer Class="pa-4 pa-sm-6 pa-md-8"
             Fluid
             Tag="section">
-    <MResponsive MaxWidth="960"
-                 Class="mx-auto overflow-visible">
+    <div class="mx-auto overflow-visible"
+         style="max-width: 960px">
         <DocumentMarkdownIt Source="@_md"
                             OnTocParsed="@OnTocParsed" />
-        
+
         <Contribute GithubUri="@GithubUri"></Contribute>
-    </MResponsive>
+    </div>
 </MContainer>