完善注释和文档

2026-05-22 17:00:08 +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; }
--- a/Runtime/Coord/Grid/GridCoord.cs
+++ b/Runtime/Coord/Grid/GridCoord.cs
@@ -43,7 +43,6 @@ namespace XCharts.Runtime
        /// When this value is set, the left, right, top, and bottom properties will be invalid.
        /// ||网格所属的网格布局组件的索引。默认为-1，表示不属于任何网格布局组件。当设置了该值时，left、right、top、bottom属性将失效。
        /// </summary>
-        /// <value></value>
        public int layoutIndex
        {
            get { return m_LayoutIndex; }
--- a/Runtime/Serie/Serie.cs
+++ b/Runtime/Serie/Serie.cs
@@ -798,7 +798,6 @@ namespace XCharts.Runtime
        /// <summary>
        /// 忽略数据时折线是断开还是连接。默认false为连接。
        /// </summary>
-        /// <value></value>
        public bool ignoreLineBreak
        {
            get { return m_IgnoreLineBreak; }
--- a/Runtime/Serie/SerieData.cs
+++ b/Runtime/Serie/SerieData.cs
@@ -106,7 +106,6 @@ namespace XCharts.Runtime
        /// <summary>
        /// 数据项图例名称。当数据项名称不为空时，图例名称即为系列名称；反之则为索引index。
        /// </summary>
-        /// <value></value>
        public string legendName { get { return string.IsNullOrEmpty(name) ? ChartCached.IntToStr(index) : name; } }

        /// <summary>
--- a/Runtime/Theme/Theme.cs
+++ b/Runtime/Theme/Theme.cs
@@ -277,7 +277,6 @@ namespace XCharts.Runtime
        /// default theme.
        /// ||默认主题。
        /// </summary>
-        /// <value></value>
        public static void ResetToDefaultTheme(Theme theme)
        {
            theme.themeType = ThemeType.Default;
@@ -303,7 +302,6 @@ namespace XCharts.Runtime
        /// dark theme.
        /// ||暗主题。
        /// </summary>
-        /// <value></value>
        public static void ResetToDarkTheme(Theme theme)
        {
            theme.themeType = ThemeType.Dark;
--- a/Runtime/Theme/ThemeStyle.cs
+++ b/Runtime/Theme/ThemeStyle.cs
@@ -109,7 +109,6 @@ namespace XCharts.Runtime
        /// you can use 'sync color to custom' to synchronize the theme color to the custom color. It can also be set manually.
        /// ||是否自定义主题颜色。当设置为true时，可以用‘sync color to custom’同步主题的颜色到自定义颜色。也可以手动设置。
        /// </summary>
-        /// <value></value>
        public bool enableCustomTheme
        {
            get { return m_EnableCustomTheme; }
--- a/Runtime/Theme/VisualMapTheme.cs
+++ b/Runtime/Theme/VisualMapTheme.cs
@@ -42,7 +42,6 @@ namespace XCharts.Runtime
        /// <summary>
        /// 可视化组件的调节三角形边长。
        /// </summary>
-        /// <value></value>
        public float triangeLen
        {
            get { return m_TriangeLen; }
--- a/Runtime/Utilities/DateTimeUtil.cs
+++ b/Runtime/Utilities/DateTimeUtil.cs
@@ -19,24 +19,24 @@ namespace XCharts.Runtime
        private static string s_YearDateFormatter = "yyyy";
        //private static string s_MonthDateFormatter = "MM";
        //private static string s_DayDateFormatter = "dd";
-        private static string s_HourDateFormatter = "HH:mm";
-        private static string s_MinuteDateFormatter = "HH:mm";
+        //private static string s_HourDateFormatter = "HH:mm";
+        //private static string s_MinuteDateFormatter = "mm:ss";
        private static string s_SecondDateFormatter = "HH:mm:ss";
-        //private static string s_DateFormatter = "yyyy-MM-dd HH:mm:ss";
+        //private static string s_FullDateFormatter = "yyyy-MM-dd HH:mm:ss";

        public static int GetTimestamp()
        {
-            return (int) (DateTime.Now - k_DateTime1970).TotalSeconds;
+            return (int)(DateTime.Now - k_DateTime1970).TotalSeconds;
        }

        public static int GetTimestamp(DateTime time)
        {
-            return (int) (time - k_DateTime1970).TotalSeconds;
+            return (int)(time - k_DateTime1970).TotalSeconds;
        }

        public static DateTime GetDateTime(int timestamp)
        {
-            long span = ((long) timestamp) * 10000000;
+            long span = ((long)timestamp) * 10000000;
            return k_DateTime1970.Add(new TimeSpan(span));
        }

@@ -61,11 +61,11 @@ namespace XCharts.Runtime
            }
            else if (range >= DateTimeUtil.ONE_HOUR * DateTimeUtil.MIN_TIME_SPLIT_NUMBER)
            {
-                dateString = dateTime.ToString(s_HourDateFormatter);
+                dateString = dateTime.ToString(s_SecondDateFormatter);
            }
            else if (range >= DateTimeUtil.ONE_MINUTE * DateTimeUtil.MIN_TIME_SPLIT_NUMBER)
            {
-                dateString = dateTime.ToString(s_MinuteDateFormatter);
+                dateString = dateTime.ToString(s_SecondDateFormatter);
            }
            else
            {