docs: update comments

packages/vchart/src/animation/spec.ts

@@ -2,11 +2,7 @@ import type { IAnimationConfig, IStateAnimationConfig } from '@visactor/vgrammar
 import type { EasingType } from '@visactor/vrender-core';
 export type { IRunningConfig as IMorphConfig, IMorphAnimationConfig } from '@visactor/vgrammar-core';
 
-export type IStateAnimateSpec<Preset extends string> = {
-  /**
-   * 预设动画效果
-   */
-  preset?: Preset | false;
+export interface ICommonStateAnimateSpec {
   /**
    * 图表动画时长
    */
@@ -23,7 +19,14 @@ export type IStateAnimateSpec<Preset extends string> = {
    * 是否轮流执行
    */
   oneByOne?: boolean;
-};
+}
+
+export interface IStateAnimateSpec<Preset extends string> extends ICommonStateAnimateSpec {
+  /**
+   * 预设动画效果
+   */
+  preset?: Preset | false;
+}
 
 export type IMarkAnimateSpec<MarkName extends string> = Partial<
   Record<MarkName, false | IAnimationConfig | IAnimationConfig[]>
@@ -38,19 +41,19 @@ export interface IAnimationSpec<MarkName extends string, Preset extends string>
   /**
    * 数据更新 - 新增数据动画
    */
-  animationEnter?: boolean | Omit<IStateAnimateSpec<Preset>, 'preset'> | IMarkAnimateSpec<MarkName>;
+  animationEnter?: boolean | ICommonStateAnimateSpec | IMarkAnimateSpec<MarkName>;
   /**
    * 数据更新 - 数据更新动画
    */
-  animationUpdate?: boolean | Omit<IStateAnimateSpec<Preset>, 'preset'> | IMarkAnimateSpec<MarkName>;
+  animationUpdate?: boolean | ICommonStateAnimateSpec | IMarkAnimateSpec<MarkName>;
   /**
    * 数据更新 - 数据删除动画
    */
-  animationExit?: boolean | Omit<IStateAnimateSpec<Preset>, 'preset'> | IMarkAnimateSpec<MarkName>;
+  animationExit?: boolean | ICommonStateAnimateSpec | IMarkAnimateSpec<MarkName>;
   /**
    * 图表退场动画
    */
-  animationDisappear?: boolean | Omit<IStateAnimateSpec<Preset>, 'preset'> | IMarkAnimateSpec<MarkName>;
+  animationDisappear?: boolean | ICommonStateAnimateSpec | IMarkAnimateSpec<MarkName>;
   /**
    * 状态切换动画
    * @since 1.12.0

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/legend/continuous/interface.ts

@@ -41,7 +41,7 @@ export type HandlerTextAttribute = {
 // 连续图例通用配置
 export type IContinuousLegendSpec = ILegendCommonSpec & {
   /**
-   * 是否开启反向展示
+   * 连续图例是否开启反向展示，最小值和最大值会发生反向
    * @default false
    * @since 1.11.0
    */

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

@@ -67,12 +67,24 @@ export type ILegendCommonSpec = {
    */
   visible?: boolean;
   /**
-   * 图例位置
+   * 图例的位置，相对于region区域的四个方位，
+   * left - 图例在左侧
+   * right - 图例在右侧
+   * top - 图例在上方
+   * bottom - 图例在下方
    * @default 'left'
    */
   orient?: IOrientType;
   /**
-   * 图例在当前行列的对齐方式，起始 | 居中 | 末尾
+   * 图例在当前行或者列的对齐方式，起始 | 居中 | 末尾，
+   * 对于orient为'left'或者'right'的图例，
+   * start - 图例在左侧
+   * middle - 图例居中
+   * end - 图例在右侧
+   * 对于orient为'top'或者'bottom'的图例，
+   * start - 图例在上方
+   * middle - 图例居中
+   * end - 图例在下方
    * @default 'middle'
    */
   position?: 'start' | 'middle' | 'end';

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[];
 }