布局模块的文档重构

tdesign-blazor · Aug 8, 2023 · f65326f · f65326f
1 parent 2f8ef3f
commit f65326f
Show file tree

Hide file tree

Showing 10 changed files with 59 additions and 35 deletions.
diff --git a/doc/TDesign.Docs.Shared/Pages/Components/Layout/DividerPage.razor b/doc/TDesign.Docs.Shared/Pages/Components/Layout/DividerPage.razor
@@ -1,8 +1,6 @@
 @page "/components/divider"
-<LayoutContent AnchorItems="@(new[]{"水平分割线","垂直分割线","带文字的分割线","文字对齐方式","虚线","API"})">
-<PageHeader Title="Divider 分割线">  
-    分割线是一个呈线状的轻量化组件，起到分割、组织、细化的作用，用于有逻辑的组织元素内容和页面结构。
-</PageHeader>
+<PageLayout Title="Divider 分割线" Description="分割线是一个呈线状的轻量化组件，起到分割、组织、细化的作用，用于有逻辑的组织元素内容和页面结构。"
+    Anchors="@(new[]{"水平分割线","垂直分割线","带文字的分割线","文字对齐方式","虚线"})" ComponentType="typeof(TDivider)">
 
 <Example Title="水平分割线">
     <Description>水平分割线常用来对不同元素内容进行分割。</Description>
@@ -95,6 +93,5 @@
 ```
 ")
     </CodeContent>
-    </Example><div id="API"></div>
-<ComponentAPI Component="typeof(TDivider)"></ComponentAPI>
-</LayoutContent>
+    </Example>
+</PageLayout>
diff --git a/doc/TDesign.Docs.Shared/Pages/Components/Layout/GridPage.razor b/doc/TDesign.Docs.Shared/Pages/Components/Layout/GridPage.razor
@@ -1,8 +1,7 @@
 @page "/components/grid"
-<LayoutContent AnchorItems="@(new[]{"基本使用","区块间隔","左右偏移","排序","次序","水平对齐","垂直对齐","API"})">
-<PageHeader Title="Grid 栅格">
-    栅格是以规则的网格阵列来指导和规范网页中的版面布局以及信息分布，提高界面内布局的一致性，节约成本。
-</PageHeader>
+<PageLayout Title="Grid 栅格" Description="栅格是以规则的网格阵列来指导和规范网页中的版面布局以及信息分布，提高界面内布局的一致性，节约成本。"
+    Anchors="@(new[]{"基本使用","区块间隔","左右偏移","排序","次序","水平对齐","垂直对齐"})">
+    <ChildContent>
 
 <Example Title="基本使用">
     <Description>
@@ -423,7 +422,11 @@
 ```
 ")
     </CodeContent>
-    </Example><div id="API"></div>
-<ComponentAPI Component="typeof(TRow)"></ComponentAPI>
-<ComponentAPI Component="typeof(TColumn)"></ComponentAPI>
-</LayoutContent>
+        </Example>
+
+    </ChildContent>
+    <ApiContent>
+        <ApiDocument ComponentType="typeof(TRow)"/>
+        <ApiDocument ComponentType="typeof(TColumn)"/>
+    </ApiContent>
+</PageLayout>
diff --git a/doc/TDesign.Docs.Shared/Pages/Components/Layout/LayoutPage.razor b/doc/TDesign.Docs.Shared/Pages/Components/Layout/LayoutPage.razor
@@ -1,6 +1,6 @@
 @page "/components/layout"
-<LayoutContent AnchorItems="@(new[]{"基本用法","API"})">
-<PageHeader Title="Layout 布局">用于组织网页的框架结构。</PageHeader>
+<PageLayout Title="Layout 布局" Description="用于组织网页的框架结构。" ComponentType="typeof(TLayout)"
+    Anchors="@(new[]{"基本用法"})">
 
 <Example Title="基本用法">
     <Description>
@@ -59,6 +59,4 @@
 ")
     </CodeContent>
 </Example>
-    <div id="API"></div>
-<ComponentAPI Component="typeof(TLayout)"></ComponentAPI>
-</LayoutContent>
+</PageLayout>
diff --git a/doc/TDesign.Docs.Shared/Pages/Components/Layout/SpacePage.razor b/doc/TDesign.Docs.Shared/Pages/Components/Layout/SpacePage.razor
@@ -1,8 +1,7 @@
 @page "/components/space"
-<LayoutContent AnchorItems="@(new[]{"基本用法","垂直间距","间距大小","自动换行","API"})">
-<PageHeader Title="Space 间距">
-    控制组件之间的间距。
-</PageHeader>
+<PageLayout Title="Space 间距" Description="控制组件之间的间距。"
+Anchors="@(new[]{"基本用法","垂直间距","间距大小","自动换行"})">
+<ChildContent>
 
 <Example Title="基本用法">
     <Description>默认为横向排列，控制相邻组件水平间距</Description>
@@ -182,7 +181,10 @@
 ```
 ")
     </CodeContent>
-    </Example><div id="API"></div>
-<ComponentAPI Component="typeof(TSpace)"></ComponentAPI>
-<ComponentAPI Component="typeof(TSpaceItem)"></ComponentAPI>
-</LayoutContent>
+        </Example>
+    </ChildContent>
+    <ApiContent>
+        <ApiDocument ComponentType="typeof(TSpace)"/>
+        <ApiDocument ComponentType="typeof(TSpaceItem)"/>
+    </ApiContent>
+</PageLayout>
diff --git a/src/TDesign/Components/Grid/TColumn.cs b/src/TDesign/Components/Grid/TColumn.cs
@@ -7,7 +7,7 @@ namespace TDesign;
 /// </summary>
 [ChildComponent(typeof(TRow))]
 [CssClass("t-col")]
-public class TColumn : TDesignComponentBase, IHasChildContent
+public class TColumn : TDesignAdditionParameterComponentBase, IHasChildContent
 {
     /// <summary>
     /// 获取或设置父组件 <see cref="TRow"/> 的级联参数的值。
@@ -16,26 +16,32 @@ public class TColumn : TDesignComponentBase, IHasChildContent
     /// <summary>
     /// 获取或设置栅格的宽度。
     /// </summary>
+    [ParameterApiDoc("栅格的宽度", Value ="Is1")]
     [Parameter][CssClass("t-col-")] public ColumnSpan Span { get; set; } = ColumnSpan.Is1;
     /// <summary>
     /// 获取或设置栅格的偏移量。
     /// </summary>
+    [ParameterApiDoc("栅格的偏移量")]
     [Parameter][CssClass("t-col-offset-")] public ColumnSpan? Offset { get; set; }
     /// <summary>
     /// 获取或设置向左边拉动的单元格宽度。
     /// </summary>
+    [ParameterApiDoc("向左边拉动的单元格宽度")]
     [Parameter][CssClass("t-col-pull-")] public ColumnSpan? Pull { get; set; }
     /// <summary>
     /// 获取或设置向右边推动的单元格宽度。
     /// </summary>
+    [ParameterApiDoc("向右边推动的单元格宽度")]
     [Parameter][CssClass("t-col-push-")] public ColumnSpan? Push { get; set; }
     /// <summary>
     /// 获取或设置单元格的排序。
     /// </summary>
+    [ParameterApiDoc("单元格的排序")]
     [Parameter][CssClass("t-col-order-")] public ColumnSpan? Order { get; set; }
     /// <summary>
     /// <inheritdoc/>
     /// </summary>
+    [ParameterApiDoc("任意的内容")]
     [Parameter] public RenderFragment? ChildContent { get; set; }
 
 

diff --git a/src/TDesign/Components/Grid/TRow.cs b/src/TDesign/Components/Grid/TRow.cs
@@ -5,23 +5,27 @@
 /// </summary>
 [CssClass("t-row")]
 [ParentComponent]
-public class TRow : TDesignComponentBase, IHasChildContent
+public class TRow : TDesignAdditionParameterComponentBase, IHasChildContent
 {
     /// <summary>
     /// 间隔，单位 px。
     /// </summary>
+    [ParameterApiDoc("行间隔，单位 px")]
     [Parameter] public int? Gutter { get; set; }
     /// <summary>
     /// 水平对齐方式。
     /// </summary>
+    [ParameterApiDoc("水平对齐方式", Value = "Start")]
     [Parameter][CssClass("t-row--")] public JustifyContent HorizontalAlignment { get; set; } = JustifyContent.Start;
     /// <summary>
     /// 垂直对齐方式。
     /// </summary>
+    [ParameterApiDoc("垂直对齐方式", Value = "Top")]
     [Parameter][CssClass("t-row--")] public VerticalAlignment VerticalAlignment { get; set; } = VerticalAlignment.Top;
     /// <summary>
     /// <inheritdoc/>
     /// </summary>
+    [ParameterApiDoc($"装载 {nameof(TColumn)} 组件的内容")]
     [Parameter] public RenderFragment? ChildContent { get; set; }
 
     protected override void BuildStyle(IStyleBuilder builder)

diff --git a/src/TDesign/Components/Space/TSpace.cs b/src/TDesign/Components/Space/TSpace.cs
@@ -5,23 +5,27 @@
 /// </summary>
 [ParentComponent]
 [CssClass("t-space")]
-public class TSpace : TDesignComponentBase, IHasChildContent
+public class TSpace : TDesignAdditionParameterComponentBase, IHasChildContent
 {
     /// <summary>
     /// <inheritdoc/>
     /// </summary>
+    [ParameterApiDoc($"装载 {nameof(TSpaceItem)} 组件的内容")]
     [Parameter] public RenderFragment? ChildContent { get; set; }
     /// <summary>
     /// 是否为竖向排列。
     /// </summary>
+    [ParameterApiDoc($"是否为竖向排列")]
     [Parameter][BooleanCssClass("t-space-vertical", "t-space-horizontal")] public bool Vertical { get; set; }
     /// <summary>
     /// <see cref="TSpaceItem"/> 之间的间距。
     /// </summary>
+    [ParameterApiDoc($"每一个 {nameof(TSpaceItem)} 的间距", Value ="16px")]
     [Parameter] public string? Gap { get; set; } = "16px";
     /// <summary>
     /// 水平排列时是否可以被自动换行。
     /// </summary>
+    [ParameterApiDoc($"水平排列时是否可以被自动换行")]
     [Parameter] public bool BreakLine { get; set; }
 
     protected override void BuildStyle(IStyleBuilder builder)

diff --git a/src/TDesign/Components/Space/TSpaceItem.cs b/src/TDesign/Components/Space/TSpaceItem.cs
@@ -5,10 +5,11 @@
 /// </summary>
 [ChildComponent(typeof(TSpace))]
 [CssClass("t-space-item")]
-public class TSpaceItem : TDesignComponentBase, IHasChildContent
+public class TSpaceItem : TDesignAdditionParameterComponentBase, IHasChildContent
 {
     /// <summary>
     /// <inheritdoc/>
     /// </summary>
+    [ParameterApiDoc("间距内的任意内容")]
     [Parameter] public RenderFragment? ChildContent { get; set; }
 }
diff --git a/src/TDesign/Components/TDivider.cs b/src/TDesign/Components/TDivider.cs
@@ -7,26 +7,30 @@ namespace TDesign;
 /// 分割线。
 /// </summary>
 [CssClass("t-divider")]
-public class TDivider : TDesignComponentBase, IHasChildContent
+public class TDivider : TDesignAdditionParameterComponentBase, IHasChildContent
 {
     /// <summary>
     /// 分割线的文本。
     /// </summary>
+    [ParameterApiDoc("分割线的任意内容")]
     [Parameter] public RenderFragment? ChildContent { get; set; }
 
     /// <summary>
-    /// 垂直分割线。
+    /// 是否垂直分割线。
     /// </summary>
+    [ParameterApiDoc("是否为垂直分割线")]
     [Parameter][CssClass("t-divider--vertical")] public bool Vertical { get; set; }
 
     /// <summary>
     /// 是否为虚线。
     /// </summary>
+    [ParameterApiDoc("是否为虚线")]
     [Parameter][CssClass("t-divider--dashed")] public bool Dashed { get; set; }
 
     /// <summary>
     /// 文字对齐方式。
     /// </summary>
+    [ParameterApiDoc("文字对齐方式", Value = "Center")]
     [Parameter][CssClass("t-divider--with-text-")] public HorizontalAlignment Alignment { get; set; } = HorizontalAlignment.Center;
 
     protected override void AddContent(RenderTreeBuilder builder, int sequence)

diff --git a/src/TDesign/Components/TLayout.cs b/src/TDesign/Components/TLayout.cs
@@ -8,27 +8,32 @@ namespace TDesign;
 [CssClass("t-layout")]
 [HtmlTag("section")]
 [ParentComponent]
-public class TLayout : TDesignComponentBase, IHasChildContent
+public class TLayout : TDesignAdditionParameterComponentBase, IHasChildContent
 {
     /// <summary>
     /// 布局的顶部内容。
     /// </summary>
+    [ParameterApiDoc("布局的顶部内容")]
     [Parameter] public RenderFragment? HeaderContent { get; set; }
     /// <summary>
     /// 布局的右侧内容。
     /// </summary>
+    [ParameterApiDoc("布局的右侧内容")]
     [Parameter] public RenderFragment? LeftSideContent { get; set; }
     /// <summary>
     /// 布局的左侧部分。
     /// </summary>
+    [ParameterApiDoc("布局的左侧部分")]
     [Parameter] public RenderFragment? RightSideContent { get; set; }
     /// <summary>
     /// 布局的底部部分。
     /// </summary>
+    [ParameterApiDoc("布局的底部部分")]
     [Parameter] public RenderFragment? FooterContent { get; set; }
     /// <summary>
     /// 布局的主体部分。
     /// </summary>
+    [ParameterApiDoc("布局的主体部分")]
     [Parameter] public RenderFragment? ChildContent { get; set; }
 
     protected override void AddContent(RenderTreeBuilder builder, int sequence)