style: add comments

VisActor · Dec 18, 2024 · 005b5da · 005b5da
1 parent 0df703c
commit 005b5da
Show file tree

Hide file tree

Showing 8 changed files with 153 additions and 8 deletions.
diff --git a/packages/vchart/src/component/axis/cartesian/interface/spec.ts b/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;
   };
 };

diff --git a/packages/vchart/src/component/axis/interface/spec.ts b/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<[]>>;
   /**

diff --git a/packages/vchart/src/component/data-zoom/data-zoom/interface.ts b/packages/vchart/src/component/data-zoom/data-zoom/interface.ts
@@ -20,33 +20,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;
   };
 }
@@ -73,8 +135,17 @@ export interface IDataZoomSpec extends IDataZoomStyle, IDataFilterComponentSpec
    * 起始点文字标签format格式配置
    */
   startText?: {
+    /**
+     * 起点文字外边距配置
+     */
     padding?: number;
+    /**
+     * 起点文字文本样式配置
+     */
     style?: IMarkSpec<ITextMarkSpec>;
+    /**
+     * 起点文字格式化配置，使用回调函数的形式配置。
+     */
     formatMethod?: (text: string | number) => string | string[];
     /**
      * 格式化模板
@@ -84,9 +155,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[];
   };
   /**

diff --git a/packages/vchart/src/component/label/interface.ts b/packages/vchart/src/component/label/interface.ts
@@ -87,9 +87,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;
 };
 

diff --git a/packages/vchart/src/component/marker/mark-line/interface/spec.ts b/packages/vchart/src/component/marker/mark-line/interface/spec.ts
@@ -253,8 +253,13 @@ export type IStepMarkLineSpec = IMarkerSpec & {
    * string 类型为百分比，相对于 region 区域宽度/高度的百分比，如 '30%'
    */
   expandDistance?: number | string;
-
+  /**
+   * 标注线的标签样式
+   */
   label?: IMarkerLabelSpec;
+  /**
+   * 标注线的线配置
+   */
   line?: {
     /**
      * 是否对 points 进行多段处理，默认为 false，即直接将所有的点连接成线。

diff --git a/packages/vchart/src/component/marker/mark-line/interface/theme.ts b/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;
 }
diff --git a/packages/vchart/src/series/mosaic/interface.ts b/packages/vchart/src/series/mosaic/interface.ts
@@ -8,6 +8,9 @@ export interface IMosaicSeriesSpec extends Omit<IBarSeriesSpec, 'type' | 'label'
   type: 'mosaic';
   [SeriesMarkNameEnum.label]?: IMultiLabelSpec<
     Omit<ILabelSpec, 'position'> & {
+      /**
+       * 是否根据分组字段过滤标签
+       */
       filterByGroup?: {
         field: string;
         type?: 'min' | 'max';

diff --git a/packages/vchart/src/typings/visual.ts b/packages/vchart/src/typings/visual.ts
@@ -641,16 +641,31 @@ export interface IArcMarkSpec extends IFillMarkSpec {
 
 // 3d arc，有高度配置
 export interface IArc3dMarkSpec extends IArcMarkSpec {
+  /**
+   * 3d圆弧的高度
+   */
   height?: number;
 }
 
 export interface ICellMarkSpec extends ISymbolMarkSpec {
+  /**
+   * 内边距
+   */
   padding?: number | number[] | IPadding;
 }
 
 export interface IGroupMarkSpec extends IFillMarkSpec {
+  /**
+   * 是否开启裁剪
+   */
   clip?: boolean;
+  /**
+   * 宽度
+   */
   width?: number;
+  /**
+   * 高度
+   */
   height?: number;
   /**
    * 圆角配置。
@@ -661,6 +676,9 @@ export interface IGroupMarkSpec extends IFillMarkSpec {
 }
 
 export interface IPolygonMarkSpec extends ICommonSpec, IFillMarkSpec {
+  /**
+   * 顶点坐标
+   */
   points?: IPoint[];
   /**
    * 圆角配置，支持数组配置，数组的顺序同组成 polygon 的顺序对应