Merge pull request #3585 from VisActor/style/add-comments

Style/add comments

packages/vchart/src/component/axis/cartesian/interface/spec.ts

@@ -24,7 +24,13 @@ export type ICartesianVertical = {
    * @since 1.8.10
    */
   innerOffset?: {
+    /**
+     * 顶部留白
+     */
     top?: ILayoutNumber;
+    /**
+     * 底部留白
+     */
     bottom?: ILayoutNumber;
   };
 };
@@ -35,7 +41,13 @@ export type ICartesianHorizontal = {
    * @since 1.8.10
    */
   innerOffset?: {
+    /**
+     * 左侧留白
+     */
     left?: ILayoutNumber;
+    /**
+     * 右侧留白
+     */
     right?: ILayoutNumber;
   };
 };

packages/vchart/src/component/axis/interface/spec.ts

@@ -364,10 +364,9 @@ export interface ITitle extends IAxisItem<ITextMarkSpec> {
    * */
   type?: 'text' | 'rich';
   /**
-   * 轴标题内容格式化函数
-   * @param text 原始标签文本值
-   * @param datum 图形数据
-   * @returns 格式化后的文本
+   * 轴标题内容，支持多种格式
+   * - 字符串或者数值
+   * - 字符串或者数值数组
    */
   text?: ITextMarkSpec['text'] | ReturnType<IRichTextFormatMethod<[]>>;
   /**

packages/vchart/src/component/crosshair/interface/spec.ts

@@ -103,7 +103,13 @@ export type ICrosshairLineStyle = Pick<
 export type ICrosshairRectStyle = ICrosshairLineStyle & Pick<IRectMarkSpec, 'fill' | 'fillOpacity' | 'cornerRadius'>;
 
 export interface ICrosshairLineSpec {
+  /**
+   * 是否显示
+   */
   visible?: boolean;
+  /**
+   * 辅助图形的类型
+   */
   type?: 'line';
   /**
    * 线宽
@@ -112,6 +118,9 @@ export interface ICrosshairLineSpec {
   width?: number;
   /** 极坐标系下是否平滑 */
   smooth?: boolean;
+  /**
+   * 辅助图形的样式配置
+   */
   style?: ICrosshairLineStyle;
 }
 

packages/vchart/src/component/data-zoom/data-zoom/interface.ts

@@ -19,33 +19,95 @@ export interface IDataZoomStyle {
    * @default 'auto' 鼠标hover在选中区域时才显示startText和endText
    */
   showDetail?: 'auto' | boolean;
-
+  /**
+   * 中间手柄样式
+   */
   middleHandler?: {
+    /**
+     * 中间手柄是否可见
+     */
     visible?: boolean;
+    /**
+     * 中间手柄的中点图标
+     */
     icon?: ISymbolMarkSpec;
+    /**
+     * 中间手柄的背景矩形
+     */
     background?: {
+      /**
+       * 中间手柄背景矩形的尺寸（当缩略轴为横向时，该尺寸代表高度；同理，当缩略轴为纵向时，该尺寸代表宽度）。
+       */
       size?: number;
     } & IRectMarkSpec;
   };
+  /**
+   * 缩略轴的背景矩形
+   */
   background?: {
+    /**
+     * 缩略轴背景矩形的尺寸（当缩略轴为横向时，该尺寸代表高度；同理，当缩略轴为纵向时，该尺寸代表宽度）
+     */
     size?: number;
   } & IRectMarkSpec;
+  /**
+   * 缩略轴的起点手柄
+   */
   startHandler?: ISymbolMarkSpec;
+  /**
+   * 缩略轴的终点手柄
+   */
   endHandler?: ISymbolMarkSpec;
+  /**
+   * 起点文字样式配置
+   */
   startText?: {
+    /**
+     * 起点文字外边距配置
+     */
     padding?: number;
   } & ITextMarkSpec;
+  /**
+   * 终点文字样式配置
+   */
   endText?: {
+    /**
+     * 终点文字外边距配置
+     */
     padding?: number;
   } & ITextMarkSpec;
+  /**
+   * 缩略轴的拖拽轨迹图元
+   */
   dragMask?: IRectMarkSpec;
+  /**
+   * 缩略轴的选中部分对应的矩形样式配置
+   */
   selectedBackground?: IRectMarkSpec;
+  /**
+   * 缩略轴的预览图表
+   */
   backgroundChart?: {
+    /**
+     * 缩略轴的预览图表，line 样式配置
+     */
     line?: ILineMarkSpec;
+    /**
+     * 缩略轴的预览图表，area 样式配置
+     */
     area?: IAreaMarkSpec;
   };
+  /**
+   * 缩略轴的选中部分预览图表样式配置
+   */
   selectedBackgroundChart?: {
+    /**
+     * 缩略轴的选中部分，line 样式配置
+     */
     line?: ILineMarkSpec;
+    /**
+     * 缩略轴的选中部分，area 样式配置
+     */
     area?: IAreaMarkSpec;
   };
 }
@@ -72,8 +134,17 @@ export interface IDataZoomSpec extends IDataZoomStyle, IDataFilterComponentSpec
    * 起始点文字标签format格式配置
    */
   startText?: {
+    /**
+     * 起点文字外边距配置
+     */
     padding?: number;
+    /**
+     * 起点文字文本样式配置
+     */
     style?: IMarkSpec<ITextMarkSpec>;
+    /**
+     * 起点文字格式化配置，使用回调函数的形式配置。
+     */
     formatMethod?: (text: string | number) => string | string[];
     /**
      * 格式化模板
@@ -83,9 +154,24 @@ export interface IDataZoomSpec extends IDataZoomStyle, IDataFilterComponentSpec
     formatter?: string | string[];
   };
   endText?: {
+    /**
+     * 终点文字外边距配置
+     */
     padding?: number;
+    /**
+     * 终点文字文本样式配置
+     */
     style?: IMarkSpec<ITextMarkSpec>;
+    /**
+     *
+     * 终点文字格式化配置, 使用回调函数的形式配置
+     */
     formatMethod?: (text: string | number) => string | string[];
+    /**
+     * 格式化模板
+     * @description 可以通过类似 `{value:.2f}%` 的形式对指定数据字段进行格式化
+     * @since 1.10.0
+     */
     formatter?: string | string[];
   };
   /**

packages/vchart/src/component/label/interface.ts

@@ -22,6 +22,9 @@ export interface ILabelFormatMethodContext {
   series?: ISeries;
 }
 
+/**
+ * 系列图元标签配置，一般用于展示数据项
+ */
 export interface ILabelSpec extends IComponentSpec, ILabelAnimationSpec {
   /** 默认不显示标签 */
   visible?: boolean;
@@ -98,9 +101,21 @@ export type ILabelAnimationSpec = Pick<
 export type IMultiLabelSpec<T extends Omit<ILabelSpec, 'position'>> = T | T[];
 
 type LabelStateStyle<T> = {
+  /**
+   * 标签hover状态样式配置
+   */
   hover?: T;
+  /**
+   * 标签hover_reverse状态样式配置
+   */
   hover_reverse?: T;
+  /**
+   * 标签选中状态样式配置
+   */
   selected?: T;
+  /**
+   * 标签未选中状态样式配置
+   */
   selected_reverse?: T;
 };
 

packages/vchart/src/component/marker/interface.ts

@@ -65,9 +65,12 @@ export type IDataPointSpec = {
    */
   [key: string]: IDataPos | IDataPosCallback;
   /**
-   * 具体某个数据元素关联的series（仅在标注目标：数据元素下有效）
+   * 具体某个数据元素关联的series序号（仅在标注目标：数据元素下有效）
    */
   refRelativeSeriesIndex?: number;
+  /**
+   * 具体某个数据元素关联的series 的id（仅在标注目标：数据元素下有效）
+   */
   refRelativeSeriesId?: StringOrNumber;
   /**
    * 指定使用 xField 上的那个维度索引，因为 xField 字段有可能会包含多个维度，比如分组场景
@@ -268,9 +271,12 @@ export interface IMarkerCrossSeriesSpec {
 
 export type IMarkerSpec = IComponentSpec & {
   /**
-   * 标注数据关联的series
+   * 标注数据关联的series序号
    */
   relativeSeriesIndex?: number;
+  /**
+   * 标注数据关联系列对应的id
+   */
   relativeSeriesId?: number | string;
   /**
    * marker组件是否可见

packages/vchart/src/component/marker/mark-area/interface/spec.ts

@@ -17,6 +17,9 @@ export type IMarkArea = IComponent;
 
 export type IRegressType = 'regression';
 
+/**
+ * 面积标注、区块标注、辅助区块相关配置
+ */
 export type IMarkAreaSpec = IMarkerSpec &
   /**
    * 标注目标：笛卡尔坐标系坐标空间

packages/vchart/src/component/marker/mark-line/interface/spec.ts

@@ -20,6 +20,9 @@ import type { BaseMarkerAnimation, MarkCommonLineAnimationType } from '@visactor
 
 export type IMarkLine = IComponent;
 
+/**
+ * 辅助线配置，一般用于展示图表的趋势线、平均线等
+ */
 export type IMarkLineSpec =
   | (IMarkerSpec &
       /**
@@ -250,8 +253,13 @@ export type IStepMarkLineSpec = IMarkerSpec & {
    * string 类型为百分比，相对于 region 区域宽度/高度的百分比，如 '30%'
    */
   expandDistance?: number | string;
-
+  /**
+   * 标注线的标签样式
+   */
   label?: IMarkerLabelSpec;
+  /**
+   * 标注线的线配置
+   */
   line?: {
     /**
      * 是否对 points 进行多段处理，默认为 false，即直接将所有的点连接成线。

packages/vchart/src/component/marker/mark-line/interface/theme.ts

@@ -3,16 +3,26 @@ import type { IArcMarkSpec, ILineMarkSpec } from '../../../../typings';
 import type { IMarkerLabelSpec, IMarkerState, IMarkerSymbol } from '../../interface';
 
 export interface IMarkLineTheme {
+  /**
+   * 标注线的线样式
+   */
   line?: Partial<IMarkerState<ILineMarkSpec | IArcMarkSpec>>;
-
+  /**
+   * 标注线的标签样式
+   */
   label?: {
     /**
      * label整体 - 相对line的位置
      */
     position?: keyof typeof IMarkLineLabelPosition | IMarkCommonArcLabelPosition;
   } & IMarkerLabelSpec;
 
+  /**
+   * 线标注起点symbol样式
+   */
   startSymbol?: IMarkerSymbol;
-
+  /**
+   * 线标注终点symbol样式
+   */
   endSymbol?: IMarkerSymbol;
 }

packages/vchart/src/component/marker/mark-point/interface/spec.ts

@@ -14,7 +14,9 @@ import type { IMarkPointTheme } from './theme';
 import type { BaseMarkerAnimation, MarkPointAnimationType } from '@visactor/vrender-components';
 
 export type IMarkPoint = IComponent;
-
+/**
+ * 辅助点、点标注相关配置
+ */
 export type IMarkPointSpec = IMarkerSpec &
   // 标注目标: 笛卡尔坐标系
   (| IMarkPointXYSpec