docs: update comments

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

@@ -18,6 +18,9 @@ export type ICartesianAxisSpec =
   | ICartesianSymlogAxisSpec;
 
 export type ICartesianVertical = {
+  /**
+   * 坐标轴的位置
+   */
   orient: 'left' | 'right';
   /**
    * 内padding/留白
@@ -35,6 +38,9 @@ export type ICartesianVertical = {
   };
 };
 export type ICartesianHorizontal = {
+  /**
+   * 坐标轴的位置
+   */
   orient: 'top' | 'bottom';
   /**
    * 内padding/留白
@@ -52,6 +58,9 @@ export type ICartesianHorizontal = {
   };
 };
 export type ICartesianZ = {
+  /**
+   * 坐标轴的位置
+   */
   orient: 'z';
 };
 
@@ -139,6 +148,9 @@ export interface ILinearAxisSync {
 
 export type ICartesianLinearAxisSpec = ICartesianAxisCommonSpec &
   ILinearAxisSpec & {
+    /**
+     * 设置轴同步相关内容，包含0值对齐和刻度对齐功能
+     */
     sync?: ILinearAxisSync;
   };
 

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

@@ -22,12 +22,24 @@ export interface IAxis extends IComponent {
 }
 
 export interface IAxisItem<T> {
+  /**
+   * 是否显示
+   */
   visible?: boolean;
+  /**
+   * 样式配置
+   */
   style?: Omit<T, 'visible'>;
 }
 
 export interface IAxisItemTheme<T> {
+  /**
+   * 是否显示
+   */
   visible?: boolean;
+  /**
+   * 主题样式配置
+   */
   style?: Omit<T, 'visible'>;
 }
 export type AxisAnimationPreset = 'groupFadeIn' | 'fadeIn' | 'grow';

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

@@ -141,7 +141,13 @@ export interface ILinearAxisSpec {
    * @description 当配置了 min和 max，该配置项失效
    */
   expand?: {
+    /**
+     * 轴范围扩展的最小比例
+     */
     min?: number;
+    /**
+     * 轴范围扩展的最大比例
+     */
     max?: number;
   };
 

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

@@ -15,8 +15,13 @@ export type CrossHairTrigger = 'click' | 'hover' | ['click', 'hover'];
 
 export interface ICommonCrosshairSpec extends IComponentSpec {
   /**
-   * 是否和tooltip保持同步
+   * 是否和tooltip保持同步，默认为false
    * tooltip出现的时候crosshair出现；tooltip隐藏的时候crsshair隐藏；
+   * 默认只要有tooltip显示，都会显示crosshair
+   * 也可以通过设置 followTooltip.dimension 为 `false` 来实现显示dimension tooltip的时候不显示crosshair
+   * 设置 followTooltip.mark 为 `false` 来实现显示mark tooltip的时候不显示crosshair
+   * 设置 followTooltip.group 为 `false` 来实现显示group tooltip的时候不显示crosshair
+   *
    * @since 1.11.1
    */
   followTooltip?: boolean | Partial<ITooltipActiveTypeAsKeys<boolean, boolean, boolean>>;
@@ -110,19 +115,21 @@ export type ICrosshairRectStyle = ICrosshairLineStyle & Pick<IRectMarkSpec, 'fil
 
 export interface ICrosshairLineSpec {
   /**
-   * 是否显示
+   * 是否显示辅助图形
    */
   visible?: boolean;
   /**
-   * 辅助图形的类型
+   * 辅助图形的类型设置为'line'
    */
   type?: 'line';
   /**
    * 线宽
    * @default 2
    */
   width?: number;
-  /** 极坐标系下是否平滑 */
+  /**
+   * 极坐标系下是否平滑
+   */
   smooth?: boolean;
   /**
    * 辅助图形的样式配置
@@ -133,18 +140,30 @@ export interface ICrosshairLineSpec {
 export type ICrosshairRectWidthCallback = (axisSize: { width: number; height: number }, axis: IAxis) => number;
 
 export interface ICrosshairRectSpec {
+  /**
+   * 是否显示辅助图形
+   */
   visible?: boolean;
+  /**
+   * 辅助图形的类型设置为'rect'
+   */
   type?: 'rect';
   /**
    * 字符串xx%表示此处是内容区间的百分比，数字表示宽度像素，
    * 仅支持笛卡尔坐标系下的 crosshair 配置
    * @default '100%''
    */
   width?: number | string | ICrosshairRectWidthCallback;
+  /**
+   * 辅助图形的样式配置
+   */
   style?: ICrosshairRectStyle;
 }
 
 export interface ICrosshairLabelSpec {
+  /**
+   * 十字准星辅助标签是否展示
+   */
   visible?: boolean;
   /**
    * label 文本格式化方法
@@ -186,6 +205,9 @@ export interface ICrosshairLabelBackgroundSpec {
    * 内部边距
    */
   padding?: IPadding | number | number[];
+  /**
+   * 标签背景的样式配置
+   */
   style?: Partial<IRectMarkSpec>;
 }
 

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

@@ -115,15 +115,15 @@ export interface IDataZoomStyle {
 /** spec */
 export interface IDataZoomSpec extends IDataZoomStyle, IDataFilterComponentSpec {
   /**
-   * @since 1.11.3
    * 是否展示背景图
+   * @since 1.11.3
    */
   showBackgroundChart?: boolean;
   /**
    * 数据过滤模式
-   * @default 'filter' （dataZoom默认数据过滤模式）
    * 'filter' 为过滤数据从而达到缩放轴的效果, 'axis'为直接缩放轴, 不过滤数据
    * 具体效果可参考: https://www.visactor.io/vchart/demo/sequence-chart/social-media-event?keyword=dataZoom
+   * @default 'filter' （dataZoom默认数据过滤模式）
    */
   filterMode?: IFilterMode;
   /**

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

@@ -82,9 +82,13 @@ export interface ILabelSpec extends IComponentSpec, ILabelAnimationSpec {
    * @since 1.3.0
    */
   customOverlapFunc?: BaseLabelAttrs['customOverlapFunc'];
-  /** 标签布局 */
+  /**
+   * 标签布局
+   */
   labelLayout?: 'series' | 'region';
-  /** 是否支持3D */
+  /**
+   * 是否支持3D
+   */
   support3d?: boolean;
   /**
    * 是否同步数据图元的状态变化

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

@@ -158,6 +158,9 @@ export type IMarkerPositionsSpec = {
 };
 
 export type IMarkerLabelWithoutRefSpec = {
+  /**
+   * 是否展示标注标签
+   */
   visible?: boolean;
   /**
    * label整体 - 是否自动旋转
@@ -176,6 +179,9 @@ export type IMarkerLabelWithoutRefSpec = {
    * label整体 - 背景面板配置
    */
   labelBackground?: {
+    /**
+     * 标签背景是否显示，是否可见
+     */
     visible?: boolean;
     /**
      * 标签背景支持自定义path
@@ -192,7 +198,10 @@ export type IMarkerLabelWithoutRefSpec = {
     padding?: IPadding | number[] | number;
   } & Partial<IMarkerState<Omit<IRectMarkSpec, 'visible'>>>;
 
-  /** @deprecated  */
+  /**
+   * @deprecated
+   * 设置文本类型为富文本或者普通文本，已废弃
+   **/
   type?: 'rich' | 'text';
   /**
    * 文本内容，如果需要进行换行，则使用数组形式，如 ['abc', '123']
@@ -211,7 +220,13 @@ export type IMarkerLabelWithoutRefSpec = {
    * label文本 - 文本前 mark 图元
    */
   shape?: {
+    /**
+     * 是否显示标签文本前的图形
+     */
     visible?: boolean;
+    /**
+     * 标签文本前的图形对应的样式设置
+     */
     style: Omit<ISymbolMarkSpec, 'visible'>;
   };
   /**
@@ -255,17 +270,30 @@ export interface IMarkerRef {
 // 跨越系列的配置
 export interface IMarkerCrossSeriesSpec {
   /**
-   * 起点和终点关联的series（仅在标注目标：坐标空间下有效）
+   * 设置起点关联的系列，设置该系列的序号（仅在标注目标：坐标空间下有效）
    */
   startRelativeSeriesIndex?: number;
+  /**
+   * 设置终点关联的系列，设置该序列的序号（仅在标注目标：坐标空间下有效）
+   */
   endRelativeSeriesIndex?: number;
+  /**
+   * 设置起点关联的系列，设置该系列的id（仅在标注目标：坐标空间下有效）
+   */
   startRelativeSeriesId?: string;
+  /**
+   * 设置终点关联的系列，设置该序列的id（仅在标注目标：坐标空间下有效）
+   */
   endRelativeSeriesId?: string;
   /**
-   * 数据处理需要单独关联系列, 当配置为'all'时代表关联当前region下所有系列
+   * 数据处理需要单独关联系列, 设置序列的序号来进行关联，当配置为'all'时代表关联当前region下所有系列
    * @since 1.11.0
    */
   specifiedDataSeriesIndex?: 'all' | number | number[];
+  /**
+   * 数据处理需要单独关联系列, 设置序列的id来进行关联，当配置为'all'时代表关联当前region下所有系列
+   * @since 1.11.0
+   */
   specifiedDataSeriesId?: 'all' | string | string[];
 }
 

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

@@ -53,6 +53,9 @@ export interface IMarkAreaXSpec extends IMarkerCrossSeriesSpec {
    * 可以将 x 配置为 '15%' 百分比的形式，用于表示将 x 绘制在 marker 所在 region 横轴（从左往右）的百分之 15 位置处
    */
   x: IDataPos | IDataPosCallback;
+  /**
+   * 设置x轴上的第二个值，如果同时设置了x 和 x1，会形成一个范围
+   */
   x1: IDataPos | IDataPosCallback;
 }
 
@@ -62,6 +65,9 @@ export interface IMarkAreaYSpec extends IMarkerCrossSeriesSpec {
    * 可以将 y 配置为 '15%' 百分比的形式，用于表示将 y 绘制在 marker 所在 region 纵轴（从上到下）的百分之 15 位置处
    */
   y: IDataPos | IDataPosCallback;
+  /**
+   * 设置y轴上的第二个值，如果同时设置了y 和 y1，会形成一个范围
+   */
   y1: IDataPos | IDataPosCallback;
 }
 
@@ -71,12 +77,18 @@ export interface IMarkAreaXYSpec extends IMarkerCrossSeriesSpec {
    * 可以将 x 配置为 '15%' 百分比的形式，用于表示将 x 绘制在 marker 所在 region 横轴（从左往右）的百分之 15 位置处
    */
   x: IDataPos | IDataPosCallback;
+  /**
+   * 设置x轴上的第二个值，如果同时设置了x 和 x1，会形成一个范围
+   */
   x1: IDataPos | IDataPosCallback;
   /**
    * y轴上的参考线。可以配置参考线在y轴上的值，或者聚合计算类型
    * 可以将 y 配置为 '15%' 百分比的形式，用于表示将 y 绘制在 marker 所在 region 纵轴（从上到下）的百分之 15 位置处
    */
   y: IDataPos | IDataPosCallback;
+  /**
+   * 设置y轴上的第二个值，如果同时设置了y 和 y1，会形成一个范围
+   */
   y1: IDataPos | IDataPosCallback;
 }
 

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

@@ -3,8 +3,13 @@ import type { IArcMarkSpec, IPolygonMarkSpec } from '../../../../typings';
 import type { IMarkerLabelWithoutRefSpec, IMarkerState } from '../../interface';
 
 export interface IMarkAreaTheme {
+  /**
+   * 标记区域的样式
+   */
   area?: Partial<IMarkerState<IPolygonMarkSpec | IArcMarkSpec>>;
-
+  /**
+   * 标记区域的标签样式配置
+   */
   label?: {
     /**
      * label整体 - 相对line的位置

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

@@ -63,7 +63,13 @@ interface ITitleSpecWithoutText extends Omit<IComponentSpec, 'orient'> {
    * 主标题样式
    */
   textStyle?: {
+    /**
+     * 给主标题设置给定的宽度
+     */
     width?: number;
+    /**
+     * 给主标题设置给定的高度
+     */
     height?: number;
     /**
      * 文字水平对齐方式

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

@@ -20,6 +20,9 @@ export interface ITooltipSpec
      */
     ITooltipActiveTypeAsKeys<
       ITooltipPattern & {
+        /**
+         * mark tooltip是否展示触发点所在的所有图形的数据
+         */
         checkOverlap?: boolean;
       },
       ITooltipPattern,
@@ -129,7 +132,13 @@ export interface ITooltipSpec
    * 计算tooltip位置时候的偏移量
    */
   offset?: {
+    /**
+     * x 方向的偏移量
+     */
     x?: number;
+    /**
+     * y 方向的偏移量
+     */
     y?: number;
   };
 }