完善注释和文档

2026-05-22 00:20:18 +00:00 · 2023-11-16 08:20:26 +08:00
parent 9816c34701
commit f94f678661
17 changed files with 68 additions and 59 deletions
--- a/Runtime/Component/Animation/AnimationStyle.cs
+++ b/Runtime/Component/Animation/AnimationStyle.cs
@@ -121,7 +121,6 @@ namespace XCharts.Runtime
        /// Data hiding animation configuration.
        /// ||数据隐藏动画配置。
        /// </summary>
-        /// <value></value>
        public AnimationHiding hiding { get { return m_Hiding; } }
        /// <summary>
        /// Interaction animation configuration.
--- a/Runtime/Component/Child/ItemStyle.cs
+++ b/Runtime/Component/Child/ItemStyle.cs
@@ -214,7 +214,6 @@ namespace XCharts.Runtime
        /// 使用Axx的形式：A是格式说明符的单字符，支持C货币、D十进制、E指数、F定点数、G常规、N数字、P百分比、R往返、X十六进制的。xx是精度说明，从0-99。
        /// 参考：https://docs.microsoft.com/zh-cn/dotnet/standard/base-types/standard-numeric-format-strings
        /// </summary>
-        /// <value></value>
        public string numericFormatter
        {
            get { return m_NumericFormatter; }
--- a/Runtime/Component/Child/Location.cs
+++ b/Runtime/Component/Child/Location.cs
@@ -92,7 +92,6 @@ namespace XCharts.Runtime
        /// the anchor of text.
        /// ||Location对应的Anchor锚点
        /// </summary>
-        /// <value></value>
        public TextAnchor runtimeTextAlignment { get { return m_TextAlignment; } }

 #if dUI_TextMeshPro
--- a/Runtime/Component/Label/LabelStyle.cs
+++ b/Runtime/Component/Label/LabelStyle.cs
@@ -182,14 +182,17 @@ namespace XCharts.Runtime
            set { if (PropertyUtil.SetClass(ref m_Formatter, value)) SetComponentDirty(); }
        }
        /// <summary>
-        /// Standard numeric format string. Used to format numeric values and display them as strings.
-        /// Use the Axx format: A is a single-character format specifier that supports C currency, D decimal, E exponent, F fixed-point number, G regular, N number, P percentage, R round trip, and X hexadecimal. xx is precision specification, from 0-99.
-        /// reference: https://docs.microsoft.com/zh-cn/dotnet/standard/base-types/standard-numeric-format-strings
-        /// ||标准数字格式字符串。用于将数值格式化显示为字符串。
-        /// 使用Axx的形式：A是格式说明符的单字符，支持C货币、D十进制、E指数、F定点数、G常规、N数字、P百分比、R往返、X十六进制的。xx是精度说明，从0-99。
-        /// 参考：https://docs.microsoft.com/zh-cn/dotnet/standard/base-types/standard-numeric-format-strings
+        /// Standard number and date format string. Used to format a Double value or a DateTime date as a string. numericFormatter is used as an argument to either `Double.ToString ()` or `DateTime.ToString()`. <br />
+        /// The number format uses the Axx format: A is a single-character format specifier that supports C currency, D decimal, E exponent, F fixed-point number, G regular, N digit, P percentage, R round trip, and X hexadecimal. xx is precision specification, from 0-99. E.g. F1, E2<br />
+        /// Date format Common date formats are: yyyy year, MM month, dd day, HH hour, mm minute, ss second, fff millisecond. For example: yyyy-MM-dd HH:mm:ss<br />
+        /// number format reference: https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-numeric-format-strings<br/>
+        /// date format reference: https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-numeric-format-strings<br/>
+        /// ||标准数字和日期格式字符串。用于将Double数值或DateTime日期格式化显示为字符串。numericFormatter用来作为Double.ToString()或DateTime.ToString()的参数。<br/>
+        /// 数字格式使用Axx的形式：A是格式说明符的单字符，支持C货币、D十进制、E指数、F定点数、G常规、N数字、P百分比、R往返、X十六进制的。xx是精度说明，从0-99。如：F1, E2<br/>
+        /// 日期格式常见的格式：yyyy年，MM月，dd日，HH时，mm分，ss秒，fff毫秒。如：yyyy-MM-dd HH:mm:ss<br/>
+        /// 数值格式化参考：https://docs.microsoft.com/zh-cn/dotnet/standard/base-types/standard-numeric-format-strings <br/>
+        /// 日期格式化参考：https://learn.microsoft.com/zh-cn/dotnet/standard/base-types/standard-date-and-time-format-strings
        /// </summary>
-        /// <value></value>
        public string numericFormatter
        {
            get { return m_NumericFormatter; }
@@ -235,7 +238,6 @@ namespace XCharts.Runtime
        /// the width of label. If set as default value 0, it means than the label width auto set as the text width.
        /// ||标签的宽度。一般不用指定，不指定时则自动是文字的宽度。
        /// </summary>
-        /// <value></value>
        public float width
        {
            get { return m_Width; }
@@ -245,7 +247,6 @@ namespace XCharts.Runtime
        /// the height of label. If set as default value 0, it means than the label height auto set as the text height.
        /// ||标签的高度。一般不用指定，不指定时则自动是文字的高度。
        /// </summary>
-        /// <value></value>
        public float height
        {
            get { return m_Height; }
@@ -452,7 +453,14 @@ namespace XCharts.Runtime
            }
            else
            {
-                dateString = dateTime.ToString(numericFormatter);
+                try
+                {
+                    dateString = dateTime.ToString(numericFormatter);
+                }
+                catch
+                {
+                    XLog.Warning("not support datetime formatter:" + numericFormatter);
+                }
            }
            if (!string.IsNullOrEmpty(m_Formatter))
            {
--- a/Runtime/Component/Radar/RadarCoord.cs
+++ b/Runtime/Component/Radar/RadarCoord.cs
@@ -133,7 +133,6 @@ namespace XCharts.Runtime
        /// Radar render type, in which 'Polygon' and 'Circle' are supported.
        /// ||雷达图绘制类型，支持 'Polygon' 和 'Circle'。
        /// </summary>
-        /// <value></value>
        public Shape shape
        {
            get { return m_Shape; }
--- a/Runtime/Component/Settings/Settings.cs
+++ b/Runtime/Component/Settings/Settings.cs
@@ -90,7 +90,6 @@ namespace XCharts.Runtime
        /// ||When the area with gradient is filled, the larger the value, the worse the transition effect.
        /// ||曲线平滑度。值越小曲线越平滑，但顶点数也会随之增加。当开启有渐变的区域填充时，数值越大渐变过渡效果越差。
        /// </summary>
-        /// <value></value>
        public float lineSmoothness
        {
            get { return m_LineSmoothness; }
@@ -102,7 +101,6 @@ namespace XCharts.Runtime
        /// the higher the number of vertices. When the area with gradient is filled, the larger the value, the worse the transition effect.
        /// ||线段的分割距离。普通折线图的线是由很多线段组成，段数由该数值决定。值越小段数越多，但顶点数也会随之增加。当开启有渐变的区域填充时，数值越大渐变过渡效果越差。
        /// </summary>
-        /// <value></value>
        public float lineSegmentDistance
        {
            get { return m_LineSegmentDistance; }
--- a/Runtime/Component/Tooltip/Tooltip.cs
+++ b/Runtime/Component/Tooltip/Tooltip.cs
@@ -181,9 +181,24 @@ namespace XCharts.Runtime
            set { if (PropertyUtil.SetStruct(ref m_Position, value)) SetAllDirty(); }
        }
        /// <summary>
-        /// The string template formatter for the tooltip title content. Support for wrapping lines with \n.
-        /// The placeholder {I} can be set separately to indicate that the title is ignored and not displayed.
-        /// Template see itemFormatter.
+        /// String template formatter for tooltip title content. \n line wrapping is supported. The placeholder {i} can be set separately to indicate that title is ignored and not displayed.
+        /// Template variables are {.}, {a}, {b}, {c}, {d}, {e}, {f}, and {g}. <br />
+        /// {.} is the dot of the corresponding color of serie currently indicated or index 0. <br />
+        /// {a} is the series name name of serie currently indicated or index 0. <br />
+        /// {b} is the name of the serie data item serieData currently indicated or index 0, or the category value (such as the X-axis of a line chart). <br />
+        /// {c} is the value of the serie y-dimension (dimesion is 1) currently indicated or index is 0. <br />
+        /// {d} is the serie y-dimensional (dimesion 1) percentage value of the currently indicated or index 0, note without the % sign. <br />
+        /// {e} is the name of the serie data item serieData currently indicated or whose index is 0. <br />
+        /// {h} is the hexadecimal color value of serieData for the serie data item currently indicated or index 0. <br />
+        /// {f} is the sum of data. <br />
+        /// {g} indicates the total number of data. <br />
+        /// {.1} represents a dot of the corresponding color with serie specified as index 1. <br />
+        /// The 1 in {a1}, {b1}, {c1} represents serie where index is specified as 1. <br />
+        /// {c1:2} represents the third data of the current indicator data item in serie with index 1 (one data item has multiple data, index 2 represents the third data). <br />
+        /// {c1:2-2} represents the third data of serie third data item with index 1 (that is, the number of data items must be specified when specifying the number of data items). <br />
+        /// {d1:2:f2} indicates that a format string with a single value is f2 (numericFormatter is used if no value is specified). <br />
+        /// {d:0.##} indicates that the format string with a value specified alone is 0.## # (for percentages, preserving a 2-digit significant number while avoiding the "100.00%" situation with f2). <br />
+        /// example: "{a}, {c}", "{a1}, {c1: f1}", "{a1}, {c1:0: f1}", "{a1}, {c1:1-1: f1}"
        /// ||提示框标题内容的字符串模版格式器。支持用 \n 换行。可以单独设置占位符{i}表示忽略不显示title。
        /// 模板变量有{.}、{a}、{b}、{c}、{d}、{e}、{f}、{g}。<br/>
        /// {.}为当前所指示或index为0的serie的对应颜色的圆点。<br/>
@@ -203,7 +218,6 @@ namespace XCharts.Runtime
        /// {d:0.##} 表示单独指定了数值的格式化字符串为 0.## （用于百分比，保留2位有效数同时又能避免使用 f2 而出现的类似于"100.00%"的情况 ）。<br/>
        /// 示例："{a}:{c}"、"{a1}:{c1:f1}"、"{a1}:{c1:0:f1}"、"{a1}:{c1:1-1:f1}"
        /// </summary>
-        /// </summary>
        public string titleFormatter { get { return m_TitleFormatter; } set { m_TitleFormatter = value; } }
        /// <summary>
        /// a string template formatter for a single Serie or data item content. Support for wrapping lines with \n.
@@ -237,11 +251,28 @@ namespace XCharts.Runtime
        /// {c0}表示当前数据项维度为0的数据。<br/>
        /// {c1}表示当前数据项维度为1的数据。<br/>
        /// {d3}表示维度3的数据的百分比。它的分母是默认维度（一般是1维度）数据。<br/>
-        /// |表示多个列的分隔。<br>
+        /// |表示多个列的分隔。<br/>
        /// 示例："{i}", "{.}|{a}|{c}", "{.}|{b}|{c2:f2}"
        /// </summary>
        public string itemFormatter { get { return m_ItemFormatter; } set { m_ItemFormatter = value; } }
        /// <summary>
+        /// Standard number and date format string. Used to format a Double value or a DateTime date as a string. numericFormatter is used as an argument to either `Double.ToString ()` or `DateTime.ToString()`. <br />
+        /// The number format uses the Axx format: A is a single-character format specifier that supports C currency, D decimal, E exponent, F fixed-point number, G regular, N digit, P percentage, R round trip, and X hexadecimal. xx is precision specification, from 0-99. E.g. F1, E2<br />
+        /// Date format Common date formats are: yyyy year, MM month, dd day, HH hour, mm minute, ss second, fff millisecond. For example: yyyy-MM-dd HH:mm:ss<br />
+        /// number format reference: https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-numeric-format-strings<br/>
+        /// date format reference: https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-numeric-format-strings<br/>
+        /// ||标准数字和日期格式字符串。用于将Double数值或DateTime日期格式化显示为字符串。numericFormatter用来作为Double.ToString()或DateTime.ToString()的参数。<br/>
+        /// 数字格式使用Axx的形式：A是格式说明符的单字符，支持C货币、D十进制、E指数、F定点数、G常规、N数字、P百分比、R往返、X十六进制的。xx是精度说明，从0-99。如：F1, E2<br/>
+        /// 日期格式常见的格式：yyyy年，MM月，dd日，HH时，mm分，ss秒，fff毫秒。如：yyyy-MM-dd HH:mm:ss<br/>
+        /// 数值格式化参考：https://docs.microsoft.com/zh-cn/dotnet/standard/base-types/standard-numeric-format-strings <br/>
+        /// 日期格式化参考：https://learn.microsoft.com/zh-cn/dotnet/standard/base-types/standard-date-and-time-format-strings
+        /// </summary>
+        public string numericFormatter
+        {
+            get { return m_NumericFormatter; }
+            set { if (PropertyUtil.SetClass(ref m_NumericFormatter, value)) SetComponentDirty(); }
+        }
+        /// <summary>
        /// the marker of serie.
        /// ||serie的符号标志。
        /// </summary>
@@ -267,21 +298,6 @@ namespace XCharts.Runtime
        /// </summary>
        public float minHeight { get { return m_MinHeight; } set { m_MinHeight = value; } }
        /// <summary>
-        /// Standard numeric format string. Used to format numeric values to display as strings.
-        /// Using 'Axx' form: 'A' is the single character of the format specifier, supporting 'C' currency, 
-        /// 'D' decimal, 'E' exponent, 'F' number of vertices, 'G' regular, 'N' digits, 'P' percentage, 
-        /// 'R' round tripping, 'X' hex etc. 'XX' is the precision specification, from '0' - '99'.
-        /// ||标准数字格式字符串。用于将数值格式化显示为字符串。
-        /// 使用Axx的形式：A是格式说明符的单字符，支持C货币、D十进制、E指数、F定点数、G常规、N数字、P百分比、R往返、X十六进制的。xx是精度说明，从0-99。
-        /// 参考：https://docs.microsoft.com/zh-cn/dotnet/standard/base-types/standard-numeric-format-strings
-        /// </summary>
-        /// <value></value>
-        public string numericFormatter
-        {
-            get { return m_NumericFormatter; }
-            set { if (PropertyUtil.SetClass(ref m_NumericFormatter, value)) SetComponentDirty(); }
-        }
-        /// <summary>
        /// the text padding of left and right. defaut:5.
        /// ||左右边距。
        /// </summary>
--- a/Runtime/Component/VisualMap/VisualMap.cs
+++ b/Runtime/Component/VisualMap/VisualMap.cs
@@ -193,7 +193,6 @@ namespace XCharts.Runtime
        /// ||
        /// 对于连续型数据，自动平均切分成几段，默认为0时自动匹配inRange颜色列表大小。
        /// </summary>
-        /// <value></value>
        public int splitNumber
        {
            get { return m_SplitNumber; }
@@ -277,7 +276,6 @@ namespace XCharts.Runtime
        /// 打开 hoverLink 功能时，鼠标悬浮到 visualMap 组件上时，鼠标位置对应的数值 在 图表中对应的图形元素，会高亮。
        /// 反之，鼠标悬浮到图表中的图形元素上时，在 visualMap 组件的相应位置会有三角提示其所对应的数值。
        /// </summary>
-        /// <value></value>
        public bool hoverLink
        {
            get { return m_HoverLink; }