style: add comment of layout and visual

packages/vchart/src/typings/layout.ts

@@ -1,3 +1,10 @@
+/**
+ * 布局特定方向的大小配置，支持四种格式：
+ * * 数值类型
+ * * 以%结束的百分比字符串
+ * * 返回类型为数值的函数
+ * * 格式为{percent: number, offset: number}的对象
+ */
 export type ILayoutNumber = number | IPercent | ((layoutRect: ILayoutRect) => number) | IPercentOffset;
 
 export interface ILayoutPoint {
@@ -30,10 +37,25 @@ export type ILayoutType =
   | 'absolute'
   | 'normal-inline';
 
+/**
+ * 布局各个方向的padding配置
+ */
 export type ILayoutOrientPadding = {
+  /**
+   * 左侧边距配置
+   */
   left?: ILayoutNumber;
+  /**
+   * 右侧边距配置
+   */
   right?: ILayoutNumber;
+  /**
+   * 顶部边距配置
+   */
   top?: ILayoutNumber;
+  /**
+   * 底部边距配置
+   */
   bottom?: ILayoutNumber;
 };
 

packages/vchart/src/typings/visual.ts

@@ -107,37 +107,100 @@ export type ConvertToMarkStyleSpec<T extends Record<string, any>> = {
  * border
  */
 export interface IBorder {
+  /**
+   * 边框离图形边缘的距离
+   */
   distance: number | string;
+  /**
+   * 边框的颜色
+   */
   stroke?: string | IGradient;
+  /**
+   * 边框的透明度
+   */
   strokeOpacity?: number;
+  /**
+   * 边框线的宽度
+   */
   lineWidth?: number;
+  /**
+   * 给边框配置虚线模式。它使用一组值来指定描述模式的线和间隙的交替长度
+   */
   lineDash?: number[];
+  /**
+   * 设置边框的虚线偏移量
+   */
   lineDashOffset?: number;
 }
 
 export interface ICommonSpec {
+  /**
+   * 图形是否可见
+   */
   visible?: boolean;
+  /**
+   * 图形的x坐标
+   */
   x?: number;
+  /**
+   * 图形的y坐标
+   */
   y?: number;
+  /**
+   * 图形的z坐标，仅适用于3D图表
+   */
   z?: number;
   /**
+   * 图形的描边颜色。
+   * 支持使用 'rgb(255,255,255)'，'rgba(255,255,255,1)'，'#fff' 等方式设置为纯色，也支持设置为渐变色描边
    * @todo 隔离主题和 spec 配置
    * IColorKey 类型只适用于主题
    */
   stroke?: string | IGradient | false | (number | boolean)[] | IColorKey;
+  /**
+   * 描边透明度
+   */
   strokeOpacity?: number;
+  /**
+   * 图形的透明度，既影响描边也影响填充
+   */
   opacity?: number;
+  /**
+   * 图形的描边宽度
+   */
   lineWidth?: number;
+  /**
+   * 给描边配置虚线模式。它使用一组值来指定描述模式的线和间隙的交替长度
+   */
   lineDash?: number[];
+  /**
+   * 设置虚线偏移量的属性
+   */
   lineDashOffset?: number;
-
+  /**
+   * 设置图形的鼠标样式
+   */
   cursor?: Cursor;
+  /**
+   * 设置图形的层级，主意这个是相对层级，图形引擎绘制的时候，会对相同group下的所有图形根据zIndex进行排序，然后从小到大进行渲染
+   */
   zIndex?: number;
+  /**
+   * 图形的旋转角度
+   */
   angle?: number;
+  /**
+   * 基于AABB的锚点位置，用于简单的定位某些path的位置
+   */
   anchor?: [number, number];
 
-  // 缩放属性
+  /**
+   * x方向的缩放比例，默认为1，即不进行缩放
+   */
   scaleX?: number;
+  /**
+   * y方向的缩放比例，默认为1，即不进行缩放
+   */
   scaleY?: number;
   /**
    * 图形缩放中心
@@ -147,14 +210,26 @@ export interface ICommonSpec {
   scaleCenter?: [number | string, number | string];
 
   // 3d旋转的属性
-  beta?: number;
+  /**
+   * x方向的旋转角度
+   */
   alpha?: number;
+  /**
+   * y方向的旋转角度
+   */
+  beta?: number;
+  /**
+   * 3d的锚点位置
+   */
   anchor3d?: [number, number];
 
   /**
    * 选择模式，精确模式，粗糙模式（包围盒模式），自定义模式
    */
   pickMode?: 'accurate' | 'imprecise' | 'custom';
+  /**
+   * bounds的计算模式
+   */
   boundsMode?: 'accurate' | 'imprecise';
 
   /**
@@ -183,11 +258,11 @@ export interface ICommonSpec {
   texturePadding?: number;
 
   /**
-   * 外边框
+   * 外边框，外描边，描边位于图形外侧
    */
   outerBorder?: IBorder;
   /**
-   * 内边框
+   * 内边框，内描边，描边位于图形内侧
    */
   innerBorder?: IBorder;
   /**
@@ -202,28 +277,51 @@ export interface ICommonSpec {
 
 export interface IFillMarkSpec extends ICommonSpec {
   /**
+   * 图形的填充颜色
    * @todo 隔离主题和 spec 配置
    * IColorKey 类型只适用于主题
    */
   fill?: VisualType<string> | IGradient | false | IColorKey;
+  /**
+   * 填充的透明度
+   */
   fillOpacity?: number;
-  // TODO：waite VRender support this api
-  // backgroundMode: number; // 填充模式（与具体图元有关）
-  // can coexist with fill
+
+  /**
+   * 图形的背景色，支持纯色、image元素、canvas元素
+   */
   background?: IColor | HTMLImageElement | HTMLCanvasElement | null;
 }
 
 export type IMarkHtmlSpec = Partial<IGraphicStyle['html']>;
 
 export interface ISymbolMarkSpec extends IFillMarkSpec {
+  /**
+   * x方向的偏移量
+   */
   dx?: number;
+  /**
+   * y方向的偏移量
+   */
   dy?: number;
+  /**
+   * 大小，相当于外接圆的半径
+   */
   size?: number | number[];
   /** 对外声明使用shape，vrender图形属性对应的是shape */
   shape?: ShapeType | string;
-  /** FIXME:  vrender Symbol接收的图形属性，暂时都申明一下 */
+  /**
+   * 标记的类型
+   * FIXME:  vrender Symbol接收的图形属性，暂时都申明一下
+   * */
   symbolType?: ShapeType | string;
+  /**
+   * x方向的缩放比例，默认为1，即不进行缩放
+   */
   scaleX?: number;
+  /**
+   * y方向的缩放比例，默认为1，即不进行缩放
+   */
   scaleY?: number;
 }
 
@@ -234,21 +332,49 @@ export interface ILineLikeMarkSpec extends IFillMarkSpec {
 }
 
 export interface IAreaMarkSpec extends ILineLikeMarkSpec {
+  /**
+   * 面积的x1值
+   */
   x1?: number;
+  /**
+   * 面积的y1值
+   */
   y1?: number;
-
+  /**
+   * 面积图元的方向，
+   * horizontal - 水平方向
+   * vertical - 垂直方向
+   */
   orient?: 'horizontal' | 'vertical';
 }
 
 export interface ILineMarkSpec extends ILineLikeMarkSpec {
+  /**
+   * 指定如何绘制每一条线段末端的属性。有 3 个可能的值，分别是：'butt', 'round' and 'square'。默认值是 butt。
+   */
   lineCap?: LineStrokeCap;
+  /**
+   * 用来设置 2 个长度不为 0 的相连部分（线段、圆弧、曲线）如何连接在一起的属性（长度为 0 的变形部分，其指定的末端和控制点在同一位置，会被忽略）。此属性有 3 个值： 'round', 'bevel' and 'miter'。默认值是 'miter'
+   */
   lineJoin?: LineStrokeJoin;
+  /**
+   * 设置斜接面限制比例的属性。当获取属性值时，会返回当前的值（默认值是 10.0 ）。当给属性赋值时，0、负数、 Infinity 和 NaN 都会被忽略；除此之外都会被赋予一个新值。
+   */
   miterLimit?: number;
+  /**
+   * stroke 的有界缓冲区
+   */
   strokeBoundsBuffer?: number;
 }
 
 export interface IRuleMarkSpec extends ILineMarkSpec {
+  /**
+   * 终点x坐标
+   */
   x1?: number;
+  /**
+   * 终点y坐标
+   */
   y1?: number;
 }
 
@@ -344,14 +470,30 @@ export interface IRectMarkSpec extends IFillMarkSpec {
    * 2. 如果传入数组，则分别为 [上左, 上右, 下右, 下左]
    */
   cornerRadius?: number | number[];
+  /**
+   * 宽度
+   */
   width?: number;
+  /**
+   * 高度
+   */
   height?: number;
+  /**
+   * x方向终点坐标
+   */
   x1?: number;
+  /**
+   * y方向终点坐标
+   */
+
   y1?: number;
 }
 
 // 3d rect，支持length表示长宽高中的长属性（深度属性）
 export interface IRect3dMarkSpec extends IRectMarkSpec {
+  /**
+   * 3d柱子的深度
+   */
   length?: number;
 }
 
@@ -416,9 +558,13 @@ export interface ILiquidOutlineSpec extends ISymbolMarkSpec {
 }
 
 export interface IOutlierMarkSpec {
-  //异常点填充颜色
+  /**
+   * 异常点填充颜色
+   */
   fill?: string;
-  //异常点大小
+  /**
+   * 异常点大小
+   */
   size?: number;
 }
 
@@ -448,16 +594,40 @@ export interface ILinkPathMarkSpec extends IFillMarkSpec {
   direction?: 'horizontal' | 'vertical' | 'LR' | 'RL' | 'TB' | 'BL' | 'radial';
 }
 
+/**
+ * arc图元的视觉通道配置
+ */
 export interface IArcMarkSpec extends IFillMarkSpec {
+  /**
+   * 圆弧的开始角度
+   */
   startAngle?: number;
+  /**
+   * 圆弧的结束角度
+   */
   endAngle?: number;
+  /**
+   * 间隙角度；间隔角度会转换为一个在两个相邻的弧之间的确定的线性距离，定义为 padRadius * | padAngle |
+   * 这个距离在弧的开始和结束处都是相等的；
+   * 间隔角度通常只应用于环形扇区（即当内半径大于 0）
+   */
   padAngle?: number;
 
+  /**
+   * 外径，既外半径
+   */
   outerRadius?: number;
+  /**
+   * 内径，既内半径
+   */
   innerRadius?: number;
+  /**
+   * 圆角
+   */
   cornerRadius?: number;
-
+  /* 内边距 */
   innerPadding?: number;
+  /* 外边距 */
   outerPadding?: number;
 
   /** arc的中心点偏移距离 */
@@ -496,7 +666,13 @@ export interface IPolygonMarkSpec extends ICommonSpec, IFillMarkSpec {
    * 圆角配置，支持数组配置，数组的顺序同组成 polygon 的顺序对应
    */
   cornerRadius?: number | number[];
+  /**
+   * x方向的缩放比例，默认为1，即不进行缩放
+   */
   scaleX?: number;
+  /**
+   * y方向的缩放比例，默认为1，即不进行缩放
+   */
   scaleY?: number;
 }