文档

自定义组件API

更新时间:

本文为您详细介绍自定义组件API。

Lifecycle

自定义组件本质上是一个对象, 其接口为:

interface Lifecycle {
  bootstrap?: LifecycleBootstrap;
  mount?: LifecycleMount;
  unmount?: LifecycleUnmount;
  update?: LifecycleUpdate;
}
  • bootstrap

    开机生命周期,当进入 Quick BI 仪表板时,首先会注册自定义组件元信息,此时会调用 bootstrap 函数,其接口为:

    type LifecycleBootstrap<T = LifecycleProps, P = any> = (props?: LifecycleProps<T>) => void | Promise<P>;
    说明

    同一个自定义组件无论在仪表板上创建了多少个图表,boostrap都只会触发1次。

  • mount

    渲染生命周期,当需要渲染自定义组件时,系统会创建一个 DOM 节点,并将自定义组件渲染到其中。此时会调用mount函数,其接口为:

    type LifecycleMount<T = LifecycleProps, P = any> = (props?: LifecycleProps<T>) => void | Promise<P>;
  • unmount

    卸载生命周期,当在仪表板中删除自定义组件时,会调用unmount函数,其接口为:

    type LifecycleUnmount<T = LifecycleProps, P = any> = (props?: LifecycleProps<T>) => void | Promise<P>;
  • update

    更新生命周期,当自定义组件的数据或者其他属性有更新时,会调用update函数,其接口为:

    type LifecycleUpdate<T = LifecycleProps, P = any> = (props?: LifecycleProps<T>) => void | Promise<P>;

    示例如下:

    // 这是一个自定义组件
    const CustomComponent = {
        bootstrap: (props) => {},
      mount: (props) => {},
      unmount: (props) => {},
      update: (props) => {},
    }

LifecycleProps

LifecycleProps描述的是传入自定义组件各个生命周期的props参数类型。包含了containercustomProps两个属性,其接口为:

interface LifecycleProps {
  container?: HTMLElement;
  customProps?: ComponentProps;
}

示例如下:

class MyComponent {
    mount(props: LifecycleProps) {...}// props 是 LifecycleProps 类型
  update(props: LifecycleProps) {...}
  unmount(props: LifecycleProps) {...}
}

const MyReactComponent: React.FC<LifecycleProps> = (props) => <div>...<div/> // props 是 LifecycleProps 类型
  • container

    props.container是Quick BI仪表板上的一个div DOM元素,作为自定义组件的容器。如果开启了 Shadow DOM, 则props.container的父元素会变成ShadowRoot元素。

  • customProps

    props.customProps是自定义组件运行时的一些信息。其接口为:

    interface ComponentProps {
      viewConfig: ComponentPropsViewConfig;
      dataConfig: AreaModel[];
      advancedConfig: object;
      globalConfig?: ComponentPropsGlobalConfig;
      data: DataCell[][];
      dispatch?: ComponentPropsDispatch;
      cubeConfig?: ComponentPropsCubeConfig[];
      sql?: string[];
    }
  • customProps.data

    自定义图表的数据,其数据结构是一个二维数组。

    interface DataCell {
      fieldId: string;
      originValue: string;
      value: string;
      geoInfo?: object;
    }
    • fieldId:数据字段ID,与customProps.dataConfig 中的ID一一对应。

    • originValue:数据的原始值。

    • value:数据的展示值。

    • geoInfo:维度字段的地理信息。

  • customProps.dataConfig

    自定义图表数据面板的数据字段配置,其接口为:

    interface AreaModel {
      areaType: 'row' | 'column' | 'drill' | 'filter';
      fields: FieldModel[];
    }
    • areaType:字段类型,可能有以下几种取值。

      • row:维度类型字段。

      • column:度量类型字段。

      • drill:钻取类型字段。

      • filter:过滤器类型字段。

    • fields:字段数组,同一种字段类型下可能有多个字段。其接口为:

      interface FieldModel {
        /** 唯一Id */
        fieldId: string;
        /** 字段名 */
        fieldName: string;
        /** 最终展示别名 */
        showName: string;
        /** 是否计算字段 */
        isCalc?: boolean;
        /** 如:calc */
        skin?: string;
        /** 值的类型 */
        valueType?: FieldValueType;
        /** 字段类型: 维度或度量 */
        fieldType: FieldCommonType;
        /** 聚合方式 */
        aggregation?: FieldAggregation | string;
        /** [QBI特有] 数据渲染形式,目前有imageUrl用于交叉表、排行榜图片渲染 */
        displayType?: 'imageUrl' | '';
        /** [QBI特有] 数据集格式化配置,如#,##0.00% */
        rawFormat?: string;
        /** [QBI特有] 数据集维度类型, TimeRegionInBackend, 需迁移,防止循环依赖 */
        dimGranularity?: any;
        /** 最终格式化配置(注:qbi目前是放在styleConfig中,该字段并未被使用) */
        /** !!首先得产品层面统一 */
        format?: QbiFormatModel | FbiFormatModel;
        /** 排序 */
        order?: FieldOrder;
        /** 高级计算:同环比等 */
        advancedCalculation?: 'year-to-year' | 'month-to-year';
        /** 当前图表的过滤条件集合 */
        complexFilter: {
          limitNum: number;
          filter: any;
        };
        // 真·字段唯一标识
        uuid: string;
        /** 不同图表字段特殊扩展信息 */
        extends?: FieldModelExtends;
      }
  • customProps.viewConfig

    自定义图表样式面板的数据,其接口如下:

    interface ComponentPropsViewConfig {
      caption?: string;
      chartColorSeries?:  {
        key: string;
        name: string;
        colors: string[];
      };
      chartSkin?: {
        key: 'black' | 'default';
      };
      title?: {
        show: boolean;
        viceName?: string;
        color?: string;
        showLink?: boolean;
        link?: string;
        linkName?: string;
      };
      fieldSettingMap?: { [fieldId: string]: ComponentPropsFieldSettingConfig };
      width?: number;
      height?: number;
      [key: string]: any;
    }
    • caption:组件主标题。

    • title:组件标题配置。

      • title.show:是否显示主标题/备注。

      • title.viceName:主标题备注。

      • title.color:主标题颜色。

      • title.showLink:是否展示链接跳转。

      • title.link:跳转链接地址。

      • title.linkName:跳转链接文案。

    • chartColorSeries:仪表板主题色系。

      • chartColorSeries.key:主题色系key。

      • chartColorSeries.name:主题色系名称。

      • chartColorSeries.colors:主题色系颜色,共有10中颜色。

    • chartSkin:仪表板皮肤。

      chartSkin.key:仪表板皮肤key。

      • default代表浅色版。

      • black代表深色版。

    • fieldSettingMap字段展示设置,例如字段别名,数据展示格式等都配置都存放在其中。其接口为:

      interface ComponentPropsFieldSettingConfig {
        aliasName: string;
        numberFormat: NumberFormat;
        [key: string]: any;
      }
      • fieldSettingMap.aliasName:字段的展示别名。

      • fieldSettingMap.numberFormat:字段的数据展示格式。

    • height:自定义图表高度。

    • widith:自定义图表宽度。

    • 自定义属性除上述的属性外,viewConfig中还包含了在meta.js中定义的styleSchema配置所生成的表单值。

    示例如下:

    // meta.js
    const componentMeta = {
      // ...
      propsSchema: {
        styleSchema: {
          schema: {
            type: 'object',
            properties: {
              display: {
                type: 'object',
                title: t('显示设置'),
                properties: {
                                // ...
                  startAngle: {
                    title: t('起始角度'),
                    id: 'startAngle',
                    type: 'number',
                    defaultValue: 0,
                  },
                },
              },
            },
          },
        },
      }
    }
    
    props.customProps.viewConfig.startAngle // 0
  • customProps.globalConfig

    自定义图表全局配置数据,建设中。

  • customProps.dispatch

    自定义图表修改属性或触发行为的函数。

    (param: {
      type: 'select' | 'changeViewConfig' | 'cancelDrill' | 'cancelLinkage'
         paylpad: any
    }) => void

    param:行为类型参数。

    param.type共有以下类型:

    • select:自定义图表的下钻、联动、跳转、联动加下钻等操作,调用后会触发取数请求,并更新图表。

      此时,payload的类型为payload: { dataIndex: number },其中dataIndex是需要下钻的维度在customProps.data数组中的数组下标。

    • cancelDrill:自定义图表的取消下钻操作。调用后会触发取数请求,并更新图表。

      此时无需传入payload

    • cancelLinkage:自定义图表的取消联动操作。调用后会触发取数请求,并更新图表。

      此时无需传入payload

    • changeViewConfig:自定义图表的变更操作。调用后可以修改样式面板的数据,并更新图表。

      此时payload的类型为payload: { [key: string]: any } ,需要更新的属性通过key value的方式传入payload中。

    示例如下:

    props.customProps.dispatch({ type: 'select', payload: { dataIndex: 1 } })
    props.customProps.dispatch({ type: 'cancelDrill' })
    props.customProps.dispatch({ type: 'cancelLinkage' })
    props.customProps.dispatch({ type: 'changeViewConfig', payload: { caption: '新标题' } })
  • customProps.advanceConfig

    自定义图表高级面板配置,建设中。

  • customProps.cubeConfig

    自定义图表数据集配置,其数据结构是一个二维数组。

    interface ComponentPropsCubeConfig {
      /** 数据集ID */
      cubeId: string;
      /** 数据集名称 */
      cubeName: string;
    }
  • customProps.sql

    自定义图表查询SQL,其数据结构是一个字符串二维数组。

ComponentMeta

自定义组件的元信息是一个描述组件样式面板、数据面板、高级面板等配置的对象,其接口为:

interface ComponentMeta {
  propsSchema: {
    dataSchema?: DataSchema;
    styleSchema?: StyleSchema;
    advancedSchema?: StyleSchema;
  };
}
  • propsSchema.syleSchema

    描述自定义组件样式面板表单的JSON规范,其接口为:

    interface StyleSchema {
      schema: StyleSchemaBase;
      localEditors?: {
        [key: string]: React.ComponentType<any>;
      };
      validation?: StyleSchemaValidation;
    }

    示例如下:

    // meta.js 中配置了
    "myData": {
      "title": "someTitle",
      "type": "number",
    }

    此时在样式面板中,可以看到一个数字输入框。显示设置此时在输入框内输入123,则产出结果:

    {
      "myData": 123
    }
    • schema:编辑器和表单配置,其接口为:

      interface StyleSchemaBase<P = any, T = string> {
        type: T;
        title?: string;
        titleAlign?: 'left' | 'center' | 'right';
        properties?: StyleSchemaProperties;
        className?: string;
        description?: string;
        propertyOrder?: number;
        id?: StyleSchemaDependId;
        hide?: boolean;
        visibleDepends?: StyleSchemaDepend[];
        disabled?: boolean;
        disableDepends?: StyleSchemaDepend[];
        hideIfDisable?: boolean;
        validation?: StyleSchemaValidationRule[];
        showRequiredMark?: boolean;
        hideValidateTips?: boolean;
        defaultValue?: any;
        props?: P;
        redirect?: string;
        relatedToData?: boolean;
        suffix?: string;
        grid?: { row: number; col: number };
      }
    • schema.type:编辑器类型,其中arrayobject是逻辑编辑器,其余的是基础编辑器(Editor)类型。目前支持的type如下表。

      编辑器类型

      预览

      编辑器属性

      类型

      默认值

      说明

      object

      object

      mode

      'tabs' | 'collapse'

      分组类型, 支持 tabs 和 collapse 两种模式

      array

      array

      -

      -

      数组类型, 多个编辑器可以任意增加删除

      number

      number

      max

      number

      最大值

      min

      number

      最小值

      changeOnBlur

      boolean

      是否blur才触发change

      string

      string

      maxLength

      number

      最大长度

      placeholder

      string

      ""

      占位符

      info

      string

      提示icon

      debounceTime

      number

      0

      延迟change(毫秒)

      textArea

      boolean

      false

      是否是textarea

      select

      select

      suffix

      string

      后缀。例如,数量:下拉框

      multiple

      boolean

      是否是多选

      style

      object

      { width: '100%' }

      样式

      options

      { label: string; value: string | number;}[]

      []

      下拉选项

      switch

      switch

      size

      'default' | 'small'

      'small'

      大小

      loading

      boolean

      false

      是否加载中

      info

      string

      气泡提示

      label

      string

      展示标签

      mode

      'default' | 'checkbox'

      'default'

      模式:

      • default为switch控件模式

      • checkbox为checkbox形式

      checkbox

      checkbox

      options

      { label: string; value: string | number; disabled?: boolean;}[]

      []

      选项配置

      maxCheckNum

      number

      最大可选数量,超过这个值,其他选项未选择options置为disabled

      label

      string

      展示标签

      tooltip

      string

      tooltip提示

      radio

      radio

      options

      { label: string; value: string | number; info?: string; iconClassName?: string; img?: string; disabled?: boolean;}[]

      []

      选项配置

      mode

      'img' | 'icon' | 'default'

      'default'

      模式,支持img和icon,default(加了tooltip提示和省略号)模式

      useRadioButton

      boolean

      false

      是否采用radio-button

      slider

      slider

      max

      number

      1

      最大值

      min

      number

      0

      最小值

      step

      number

      0.01

      步长

      isPercent

      boolean

      true

      是否展示为百分比模式

      color

      color

      mode

      'default' | 'classic'

      'default'

      模式:

      • default默认模式

      • classic经典模式

      classicSize

      'large' | 'middle' | 'small'

      'large'

      大小。仅在 classic模式下生效

      placement

      'top' | 'left' | 'right' | 'bottom' | 'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight' | 'leftTop' | 'leftBottom' | 'rightTop' | 'rightBottom'

      'bottom'

      颜色框弹出的方向

      isFontMode

      boolean

      false

      是否为字体颜色模式

      disableAlpha

      boolean

      false

      是否禁用透明度

      allowClear

      boolean

      false

      是否允许清除颜色

      toRgb

      boolean

      false

      导出rgb

      tab

      tab
      • tab1

      • tab2

      options

      { text: string; value: string | number; disable?: boolean;}[]

      []

      tab选项

      style

      object

      tab样式

      • object:当typeobject时,可以把一系列表单聚合在一起,包括配置项和值,类似于分组。示例如下:

        // meta.js
        export default = {
          "propsSchema": {
            "styleSchema": {
              "schema": {
                "title": "基本设置",
                "type": "object",
                "properties": {
                  "group1": {
                      "type": 'object',
                    "properties": {
                      "address": {
                        "title": "住址",
                        "type": "string",
                        "defaultValue": "aaaa",
                      },
                      "phone": {
                        "title": "电话",
                        "type": "string" ,
                        "defaultValue": "1234567",
                      }
                      }
                  }
                }
              }
            }
          }
        }
        
        // 最终会输出这个 value 结构, 并可以从组件的 props.customProps.viewConfig 中获取
        props.customProps.viewConfig = {
          // ...
          group1: {
            "address": "aaaa",
              "phone": "1234567"
          }
        }
      • array:当typearray时,可以将一个或多个编辑器组成数组表单。此时 properties表示每一项使用的编辑器类型,可以是numberstring或者object等任意支持的Editor类型。您还可以通过arrayItemDefaultValue添加数组每一项的默认值。示例如下:

        // meta.js
        export default = {
          "propsSchema": {
            "styleSchema": {
              "schema": {
                "title": "Group1",
                "type": "object",
                "properties": {
                  "simpleArray": {
                    "title": "数组",
                    "type": "array",
                    "properties": "number", // 每一项使用什么类型编辑器
                    "arrayItemDefaultValue": 5 // 数组每一项默认值
                  },
                  "multiArray": {
                    title: "数组2",
                    type: "array",
                    properties: {
                        name: {
                          type: "string",
                        props: {
                            // ...
                        }
                      },
                      age: {
                          type: "number",
                          props: {
                            // ...
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
        
        // 最终会输出这个 value 结构, 并可以从组件的 props.customProps.viewConfig 中获取
        props.customProps.viewConfig = {
          // ...
          "simpleArray": [1, 2, 3, 4, 5],
          "multiArray": [{
              name: 'aa',
            age: 12
          }, {
              name: 'bb',
            age: 13
          }]
        }
    • schema.title:编辑器的标题。示例如下:

      // ...
      phone: {
        title: '电话',
        type: 'string',
      },
      schema
    • schema.titleAlign:编辑器标题的对齐方式。

    • schema.properties:当schema.typeobjectarray时,编辑器的值类型就不是基本类型了,而是objectarray结构。此时schema.properties 可以定义编辑器的每一项值的结构。其接口为:

      type StyleSchemaProperties =
        | {
            [key: string]: StyleSchemaBase;
          }
        | string

      schema.properties为字符串类型时, 其代表的含义与schema.type相同,schema.props中的属性会传入每一个自编辑器中。此时编辑器的值的类型取决于schema.properties的类型。示例如下:

      {
          a: {
            type: 'array',
          properties: 'string', // 数组的每一项都是 string 类型
          // props 的属性会传入每个输入框中
          props: {
              placeholder: '请输入'
          }
        }
      }
      // 最终输出: 数组的每一项都是 string
      {
        a: ['xx', 'xx']
      }

      schema.properties类型为对象时,此时编辑器的每一项值都是一个对象,结构取决于properties的配置。示例如下:

      // meta.js
      {
          a: {
            type: 'object',
          properties: {
              c: {
                type: 'string'
            }
          }
        },
          b: {
            type: 'array',
          properties: {
              c: {
                type: 'string'
            }
          }
        },
      }
      
      // 最终输出
      {
          a: {
            c: 'xxxx'
        },
        b: [{
            c: 'xxx'
        }]
      }
    • schema.className:编辑器标题的类名。

    • schema.description:编辑器的描述,在编辑器下方展示。

      示例如下:

      // ...
      phone: {
        title: '电话',
        type: 'string',
        description: 'this is description',
      },
      编辑器描述
    • schema.propertyOrder:编辑器的展示顺序,按照从上到下,从小到大的顺序排列。

    • schema.id:编辑器标题的标识,一般用于控制显示、隐藏或禁用。

    • schema.hide:编辑器是否隐藏。

    • schema.visibleDepends:根据条件控制编辑器显示或隐藏。

      通过给编辑器添加ID,可以设置当某几个编辑器的值分别为 X 的时候,才展现自身

      说明
      • 当编辑器自身不展现时,不会触发onChange

      • 当编辑器自身不展现时,其所有子编辑器都会隐藏。

      StyleSchemaDepend接口为:

      type StyleSchemaDependId = number | string;
      
      interface ValueDepend {
        /** 用于标识编辑器的id */
        id: StyleSchemaDependId;
        /** 编辑器的值 */
        value: any | any[];
      }
      
      interface PatternDepend {
        id: StyleSchemaDependId;
        /** 正则表达式 */
        pattern: string;
      }
      
      type StyleSchemaBaseDepend = ValueDepend | PatternDepend;
      
      interface StyleSchemaAndDepend {
        $and?: StyleSchemaDepend[];
      }
      
      interface StyleSchemaOrDepend {
        $or?: StyleSchemaDepend[];
      }
      
      type StyleSchemaDepend = StyleSchemaBaseDepend | StyleSchemaAndDepend | StyleSchemaOrDepend;

      示例如下:

      // ...
      {
        a: {
          title: 'a',
          type: 'string',
          id: 'a',
        },
        b: {
          title: 'b',
          type: 'string',
          id: 'b',
          visibleDepends: [{ id: 'a', value: 'china' }], // 当 id=a 的编辑器的值等于 china 时,此组件才展现
        },
        c: {
          title: 'c',
          type: 'string',
          id: 'c',
          visibleDepends: [{ id: 'a', pattern: '^china' }], // 当 id=a 的编辑器的值以 china 开头时,此组件才展现
        },
      }

      当需要组合多个条件时,可以使用$and 或者$or对多个条件进行组合。示例如下:

      // ...
      {
        d: {
          title: 'd',
          type: 'string',
          id: 'd',
          visibleDepends: [
            {
              $or: [
                { id: 'a', value: 'china' },
                { id: 'a', value: 'usa' },
              ],
            },
          ], // 当 ID=a 的编辑器的值等于 china 或 usa 时,此组件才展现
        },
      }
    • schema.disabled:编辑器是否禁用。

    • schema.diableDepends:控制编辑器是否禁用的条件,其配置方式和visibleDepends一致。

    • schema.hideIfDisable:编辑器禁用时是否隐藏。

    • schema.validation:编辑器校验规则,用于校验表单值。

      声明validation为对象数组,可支持单规则或多规则场景。当有多条规则存在时,所有规则必须全部通过才可校验通过。

      // 校验规则接口
      interface StyleSchemaValidationRule {
        message: string;
        [rule: string]: any;
        funcName?: string;
      }
      • message:未通过校验时的错误信息。

      • [rule: string]:校验配置属性。

        以下列举常用的配置属性。

        校验属性

        取值类型

        说明

        type

        string(默认)

        字符串类型

        number

        数字类型

        boolean

        布尔值

        integer

        整型

        float

        浮点型

        array

        数组类型

        enum

        类型枚举

        date

        日期类型

        url

        url格式的字符串

        email

        email格式的字符串

        required

        boolean

        是否必填

        pattern

        string

        正则表达式

        min

        number

        • typestring时,校验字符串最小长度

        • typenumber时,校验数字最小值

        max

        number

        • typestring时,校验字符串最大长度。

        • typenumber时,校验数字最大值。

        len

        number

        • typestring 时,校验字符串长度。

        • typearray时,校验数组长度。

      • funcName:自定义校验的函数名。

        当传入了funcName时, 其他的校验配置属性会失效,详情请参见validation。示例如下:

        // ...
        {
          address: {
            title: '住址',
            type: 'string',
            validation: [
              {
                required: true,
                message: '该项是必填项',
              },
              {
                message: '长度必须等于7',
                len: 7,
              },
              {
                message: '必须以 china 开头',
                pattern: '^china',
              },
            ],
          },
          population: {
            title: '人口',
            type: 'number',
            validation: [
              {
                type: 'integer',
                min: 1000,
                message: '最少1000人',
              },
              {
                type: 'integer',
                max: 100000,
                message: '最多100000人',
              },
            ],
          },
          url: {
            title: 'url',
            type: 'string',
            validation: [
              {
                type: 'url',
                message: '当前格式不满足url格式',
              },
            ],
          },
          email: {
            title: 'email',
            type: 'string',
            validation: [
              {
                type: 'email',
                message: '当前格式不满足email格式',
              },
            ],
          },
        }
                                                        
    • schema.showRequiredMark:是否显示必填星号标记。

    • schema.hideValidateTips:是否隐藏校验错误信息。

    • schema.defaultValue:编辑器的默认值。

    • schema.propsprops属性是传入各个编辑器内部的属性。

      示例如下:

      // ...
      "phone": {
        "title": "电话",
        "type": "string",
      
        // 这部分属性是传入 "string" 这个编辑器内的
        "props": {
          placeholder: "请输入电话号码"
        }
      }

      其中,placeholderstring 是这个编辑器的属性,各编辑器属性详情请参见schema.type

    • schema.redirect:重命名表单字段名。

      通常表单输出的key是以styleSchema中配置的key为准。示例如下:

      styleSchema: {
          schema: {
            type: 'object',
            properties: {
                a: {
                  type: 'object',
                properties: {
                    b: {
                    type: 'string'
                  }
                }
              }
            }
        }
      }
      
      // 最终输出结构
      {
          a.b: '...'
      }

      如果您觉得输出层级太深,可以使用redirect重命名key。示例如下:

      styleSchema: {
          schema: {
            type: 'object',
            properties: {
                a: {
                  type: 'object',
                properties: {
                    b: {
                    type: 'string',
                    redirect: 'b'
                  }
                }
              }
            }
        }
      }
      
      // 最终输出结构
      {
          b: '...'
      }
    • schema.suffix:编辑器后缀。例如xx: [select] 天

    • schema.grid:编辑器布局属性,目前支持纵向排列、分栏排列等布局。

      • col:宽度,遵循24-col规则。

        例如,输入12,则表示50%宽度。

      • row:行号。

      示例如下:

      {
        title: '',
        type: 'object',
        properties: { // 项目名称和绑定工程名称两个字段并排显示
          projectName: {
            title: '项目名称:',
            type: 'string',
            props: {
              placeholder: '请输入项目名称描述'
            }
            grid: {
              row: 0, // 行号
              col: 12 // 列宽(遵循 24-col 规则,12则是50%宽)
            }
          }
        }
      };
                                      
    • validation:自定义校验函数可以通过validation对象传入到编辑器中。其接口为:

      interface StyleSchemaValidation {
        [validateFuncName: string]: (
          rule?: any,
          currentValue?: any,
          extras?: { data?: any; schema?: Schema; keyPaths?: string[] },
        ) => string | Promise<any> | void;
      }
      • rule:当前校验规则。

      • currentValue:当前编辑器的值。

      • extras:当前编辑器的附加信息。

      示例如下:

      // meta.js
      export default {
          propsSchema: {
            schema: {
              ...
            test: {
                type: 'string',
              validation: [
                {
                    funcName: 'isNum'
                }
              ]
            }
          },
          validation: {
            isNum: function(rule, currentValue) {
                if (typeof currentValue !== 'number') {
                return `${currentValue} 不是数字`
              }
            }
            }
        }
      }
    • localEditors:自定义编辑器,建设中。

  • propsSchema.dataSchema

    描述的是自定义组件取数的数据模型,通过定义该模型可以实现对组件数据面板的定制。

    interface DataSchema {
      /** 字段设置 */
      areas: DataSchemaArea;
      /** 结果展示配置 */
      resultDisplay: ResultDisplay;
    }

    在Quick BI数据面板中, 数据集有维度度量两种类型的字段, 不同字段可以拖入到不同的区块中实现不同的取数方式。数据面板有以下几种区块:

    • 钻取区块

    • 维度区块

    • 度量区块

    • 过滤器区块

    数据面板
    • propsSchema.dataSchema.areas

      数据面板区块设置,其接口为:

      interface DataSchemaArea {
        /** 字段id */
        id?: 'area_column' | 'area_row' | 'drill' | 'filters';
        /** 字段类型 */
        queryAxis?: 'dimension' | 'measure' | 'drill' | 'filters';
        /** 字段名 */
        name: string;
        /** 字段提示 */
        nameTip?: string;
        /** 规则配置 */
        rule: DataSchemaAreaRule;
      }
      • propsSchema.dataSchema.areas[].id:区块的ID标识。

        可能有以下几种取值:

        • area_column:度量区块ID。

        • area_row:维度区块ID。

        • drill:钻取区块ID。

        • filters:过滤器区块ID。

      • propsSchema.dataSchema.areas[].rule:区块配置规则,其接口为:

        interface DataSchemaAreaRule {
          /** 占位显示内容 */
          placeholder?: string;
          /** 允许拖入的字段类型 */
          fieldTypes: ('dimension' | 'measure')[];
          /** 是否必填 */
          required?: boolean;
          /** 字段配置个数限制 */
          maxColNum?: number;
        }
        • rule.fieldTypes:设置区块能拖入的字段类型。

          可能的取值:

          • dimension:只接收维度字段。

          • measure:只接收度量字段。

          其类型为数组,当所有的类型都可以拖入时,可以按以下方式配置。

          fieldTypes: ['dimension', 'measure']
        • rule.required:当前区块能否为空。

        • rule.maxColNum:当前区块最多能接收的字段数量。

      • propsSchema.dataSchema.areas[].queryAxis:区块功能类型。

        可能有以下几种取值:

        • column:度量类型。

        • row:维度类型。

        • drill:钻取类型。

          此时rule.type 必须是dimension

        • filters:过滤器类型。

      • propsSchema.dataSchema.areas[].name:区块的展示名称。

        示例如下:

        const componentMeta = {
          // ...
          dataSchema: {
            areas: [
              {
                id: 'drill',
                name: '钻取/维度',
                queryAxis: 'drill',
                rule: {
                  fieldTypes: ['dimension'],
                  required: false,
                  maxColNum: 6,
                },
              },
              {
                id: 'area_row',
                name: '维度',
                queryAxis: 'row',
                rule: {
                  fieldTypes: ['dimension'], // 维度还是计量
                  maxColNum: 1, // 最多允许的字段数
                  required: true, // 是否是更新图标必须字段
                },
              },
              {
                id: 'area_column',
                name: '度量',
                queryAxis: 'column',
                rule: {
                  fieldTypes: ['measure', 'dimension'],
                  maxColNum: 3,
                  required: true,
                },
              },
              {
                id: 'filters',
                name: '过滤器', //  名称
                queryAxis: 'filters',
                rule: {
                  fieldTypes: ['dimension', 'measure'],
                  required: false,
                },
              },
            ],
            resultDisplay: {
              upLimit: 1000,
            },
          }
        }
    • propsSchema.dataSchema.resultDisplay

      数据面板结果展示区的配置,其接口为:

      interface ResultDisplay {
        /** 上限 */
        upLimit?: number;
          /** 下限 */
        downLimit?: number;
        /** 是否隐藏展示结果设置 */
        hide?: boolean;
      }
      结果展示
      • propsSchema.dataSchema.resultDisplay.upLimit:图表取数数量上限。

      • propsSchema.dataSchema.resultDisplay.downLimit:图表取数数量下限,默认值是1

      • propsSchema.dataSchema.resultDisplay.hide:是否隐藏结果展示区块,默认值是false

  • 废弃API

    说明

    Quick BI v4.1.1.1版本升级了数据面板,以下deprecated的老API 已弃用。若您当前的版本低于Quick BI v4.1.1.1版本,请参考以下API。

    • (deprecated in v4.1.1.1) schema:数据面板配置,其接口为:

      interface DataSchema {
        schema: DataSchemaBase;
      }
      
      interface DataSchemaBase {
        area: DataSchemaArea[];
        limitNum: number;
      }
    • (deprecated in v4.1.1.1) schema.area:数据面板区块设置,其接口为:

      interface DataSchemaArea {
        id?: 'area_column' | 'area_row' | 'drill' | 'filters';
        queryAxis?: 'dimension' | 'measure' | 'all';
        areaName: string;
        columnList?: any[];
        rule: DataSchemaRule;
      }
      • (deprecated in v4.1.1.1) schema.area[].id:区块的ID标识。

        能有以下几种取值:

        • area_column:度量区块ID。

        • area_row:维度区块ID。

        • drill:钻取区块ID。

        • filters:过滤器区块ID。

      • (deprecated in v4.1.1.1) schema.area[].rule:区块配置规则,其接口为:

        interface DataSchemaRule {
          type: 'dimension' | 'measure' | 'all';
          required?: boolean;
          maxColNum?: number;
          show?: boolean;
        }
        • rule.type:设置区块能接收的字段类型。

          可能的取值:

          • dimension:只接收维度字段。

          • measure:只接收度量字段。

          • all:维度字段和度量字段都能接收。

        • rule.required:当前区块能否为空。

        • rule.maxColNum:当前区块最多能接收的字段数量。

      • (deprecated in v4.1.1.1) schema.area[].queryAxis:区块功能类型。

        有以下几种取值:

        • column:度量类型。

        • row:维度类型。

        • drill:钻取类型。

          此时rule.type必须是dimension

        • filters:过滤器类型。

      • (deprecated in v4.1.1.1) schema.area[].areaName:区块的名称。

        示例如下:

        {
          "area": [
            {
              "id": "drill",
              "areaName": "钻取/维度",
              "queryAxis": "drill",
              "rule": {
                "show": false,
                "type": "dimension",
                "required": false,
                "maxColNum": 6
              },
              "columnList": []
            },
            {
              "id": "area_onerow",
              "areaName": "维度",
              "queryAxis": "row",
              "rule": {
                "type": "dimension",
                "maxColNum": 1,
                "required": true
              },
              "columnList": []
            },
            {
              "id": "area_column",
              "areaName": "度量",
              "queryAxis": "column",
              "rule": {
                "type": "measure",
                "maxColNum": 3,
                "required": true
              },
              "columnList": []
            },
            {
              "id": "filters",
              "areaName": "过滤器",
              "queryAxis": "filters",
              "rule": {
                "type": "all",
                "required": false
              },
              "columnList": []
            }
          ],
          "limitNum": 1000
        }
    • (deprecated in v4.1.1.1) schema.limitNum:最大的取数数量限制。数量限制

  • propsSchema.advancedSchema

    描述自定义组件高级面板表单的配置规范。建设中。

bi-open-sdk API

bi-open-sdkbi-open-react-sdk是针对不同框架所提供的SDK,其API完全一致。

  • createBIComponent

    创建Quick BI自定义组件的函数。返回一个自定义组件对象。

    (option: IOption) => Lifecycle

    option参数的配置。

    interface IBiComponent {
      mount?: Interfaces.LifecycleMount<Interfaces.ComponentProps>;
      umount?: Interfaces.LifecycleUnmount<Interfaces.ComponentProps>;
      update?: Interfaces.LifecycleUpdate<Interfaces.ComponentProps>;
    }
    
    interface IBiComponentConstructor {
      new (): IBiComponent;
    }
    
    interface IOption {
        element: IBiComponentConstructor | React.ComponentType
    }
    说明

    element自定义组件createBIComponent

    • 如果通过bi-open-sdk引入,则类型为IBiComponent

    • 如果通过bi-open-react-sdk引入,则类型为React.ComponentType

    示例如下:

    import { createBIComponent } from 'bi-open-sdk'
    
    class MyComponent {
        mount() {}
      update() {}
      umount() {}
    }
    
    const { bootstrap, mount, unmount, update } = createBIComponent({
      element: MyComponent,
    })

    基于react框架:

    import { createBIComponent } from 'bi-open-react-sdk'
    
    const MyComponent = (props) => <div>...</div>
    
    const { bootstrap, mount, unmount, update } = createBIComponent({
      element: MyComponent,
    })
  • Interfaces

    Quick BI自定义组件的类型定义。

  • Utils

    Quick BI 自定义组件的工具库。

    • Utils.getStringRealLength:获取字符串的实际长度。

      (str: string) => number

      str:需要获取实际长度的字符串。示例如下:

       getStringRealLength('abc') // 3
       getStringRealLength('中文') // 4 中文占2位
    • Utils.formatNumber:格式数字。

      (num: number | string, partten?: 'CN' | 'CNT' | 'CN2' | 'EN' | 'KMG' | string, invalidString = 'N/A' ) => string
      • partten:需要转换的格式,不指定时返回原始值。

      • invalidString:数字不合法时的返回值,默认是N/A

      示例如下:

      formatNumber(1234, '#,##0') // 1,234
      formatNumber(1.234, '0.##') //1.234
      formatNumber(12, '0.##') // 12
      formatNumber(12.34, '0') // 12
      formatNumber(12.34, '0.#') // 12.3
      formatNumber(0.1, '%') // 10%
      formatNumber(0.001, '0.#%') // 0.1%
      formatNumber(0.01, '‰') // 10‰
      
      // 当数字大于10000时
      formatNumber(12345, 'CN') // 1.234万
      formatNumber(12345, 'EN') // 12.34K
      formatNumber(12345, 'CNT') // 1.234萬
      formatNumber(12345, 'CN2') // 1.23万
      formatNumber(12345, 'KMG') // 12.3K
    • Utils.formatNumberWithConfig:根据仪表板数据面板中配置的数值展示格式格式化数字。

      (num: number | string, config: object) => string
      数据展示格式
      • num:需要转换格式的数字。

      • config:数值展示格式,不指定时返回原始值。

        该配置一般从props.customProps.viewConfig.fieldSettingMap中获取。

      示例如下:

      // 可以通过 props 获取数值展示格式的配置
      update(props) {
        // ...
        const fieldSettingMap = props.customProps.viewConfig.fieldSettingMap
        const config = fieldSettingMap[fieldId].numberFormat;
        const value = formatNumberWithConfig(12345, config)
      }
  • I18n

    Quick BI自定义组件的国际化类,I18nInstance是通过I18n.initnew I18n()创建的实例。

    • I18n.init:创建国际化实例的静态方法,返回I18nInstance实例。

      static (options: IOption, appendTarget?: object) => I18nInstance
      • options:配置项参数。

        type Lng = "zh-CN" | "en-US" | "zh-TW" | "zh-MO" | "ja-JP"
        interface IOption {
            lng?: Lng,
          resources: Partial<{
              [key in Lng]: {
                [key: string]: string
            }
          }>
        }
        • lng:设置当前语言,如果没有传入,则当前语言默认为Quick BI当前语言。

        • resources:语言包配置。与词条的key与t函数的第一个参数一一对应。

      • appendTarget:绑定的对象,如果传入,则i18n实例会绑定到该对象上。 一般用于性能优化中。

      示例如下:

      import { I18n } form 'bi-open-sdk'
      I18n.init({
        resources: {
          // 英文 key
          'en-US': {
            我的: 'my',
            苹果: 'apple',
            '{{who}}{{count}}个苹果': '{{who}} {{count}} apple',
            '{{who}}{{count}}个苹果_plural': '{{who}} {{count}} apples', // 当有 {{count}} 时, 可以添加 _plural 处理复数情况
          },
          // 日文 key
          'ja-JP': {
            苹果: '苹果',
            ...
          }
        },
      })
      
      I18n.init(option, window.biI18n)
      window.biI18n // { t, i18n } 绑定在 window.biI18n 上
    • I18nInstance.t:翻译函数。

      (text: string, param?: object) => string;
      • text:需要翻译的文字。

      • param:需要替换的参数。

        可以替换text中通过 {{}} 包裹的表达式。如果传入count,则还可以区分单复数。

      示例如下:

      const t = i18n.t.bind(i18n)
      
      t('苹果') // apple
      t('{{who}}{{count}}个苹果', {
        who: t('我的'),
        count: 2
      }) // my 2 apples
    • I18nInstance.addResources:追加翻译词条。

      (lng: "zh-CN" | "en-US" | "zh-TW" | "zh-MO" | "ja-JP", resource: IResource) => I18nInstance
      • lng:需要添加的语言。

      • resource:追加的语言包。

      示例如下:

      i18n.addResources('en-US', {
          '苹果': 'apple',
      })
    • I18nInstance.changeLanguage:切换当前语言。

      (lng: "zh-CN" | "en-US" | "zh-TW" | "zh-MO" | "ja-JP") => I18nInstance

      lng:需要切换的语言。

      示例如下:

      i18n.t('苹果') // 苹果
      i18n.changeLanguage('en-US')
      i18n.t('苹果') // apple
  • 本页导读 (0)
文档反馈