自定义组件API

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

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描述的是传入自定义组件各个生命周期的props参数类型。包含了container和customProps两个属性，其接口为：

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 类型

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

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：编辑器类型，其中array，object是逻辑编辑器，其余的是基础编辑器（Editor）类型。目前支持的type如下表。

    编辑器类型	预览	编辑器属性	类型	默认值	说明
    object		mode	'tabs' | 'collapse'	无	分组类型, 支持 tabs 和 collapse 两种模式
    array		-	-	无	数组类型, 多个编辑器可以任意增加删除
    number		max	number	无	最大值
    		min	number	无	最小值
    		changeOnBlur	boolean	无	是否blur才触发change
    string		maxLength	number	无	最大长度
    		placeholder	string	""	占位符
    		info	string	无	提示icon
    		debounceTime	number	0	延迟change（毫秒）
    		textArea	boolean	false	是否是textarea
    select		suffix	string	无	后缀。例如，数量：下拉框个
    		multiple	boolean	无	是否是多选
    		style	object	{ width: '100%' }	样式
    		options	{ label: string; value: string | number;}[]	[]	下拉选项
    switch		size	'default' | 'small'	'small'	大小
    		loading	boolean	false	是否加载中
    		info	string	无	气泡提示
    		label	string	无	展示标签
    		mode	'default' | 'checkbox'	'default'	模式： default为switch控件模式 checkbox为checkbox形式
    checkbox		options	{ label: string; value: string | number; disabled?: boolean;}[]	[]	选项配置
    		maxCheckNum	number	无	最大可选数量，超过这个值，其他选项未选择options置为disabled
    		label	string	无	展示标签
    		tooltip	string	无	tooltip提示
    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		max	number	1	最大值
    		min	number	0	最小值
    		step	number	0.01	步长
    		isPercent	boolean	true	是否展示为百分比模式
    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	tab1 tab2	options	{ text: string; value: string | number; disable?: boolean;}[]	[]	tab选项
    		style	object	无	tab样式

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

      // 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：当type为array时，可以将一个或多个编辑器组成数组表单。此时 properties表示每一项使用的编辑器类型，可以是number、string或者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.titleAlign：编辑器标题的对齐方式。

  • schema.properties：当schema.type为object和array时，编辑器的值类型就不是基本类型了，而是object 和array结构。此时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	type为string时，校验字符串最小长度 type为number时，校验数字最小值
      max	number	type为string时，校验字符串最大长度。 type为number时，校验数字最大值。
      len	number	type为string 时，校验字符串长度。 type为array时，校验数组长度。

    • 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.props：props属性是传入各个编辑器内部的属性。

    示例如下：

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

    其中，placeholder中string 是这个编辑器的属性，各编辑器属性详情请参见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和bi-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.init或new 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