3. 添加属性_多端低代码开发平台魔笔(Mobi)-阿里云帮助中心

本文介绍如何给自定义组件添加属性。

组件的属性

当我们在搭建页面使用系统组件时，每个组件会有属性、样式、事件等等设置。

以文本组件为例，如下：

我们把所有这些可以设置的内容称为组件的属性。

属性对应到组件的实现，就是组件的 Props 参数。平台用户在搭建页面时，通过设置组件属性，传递 Props 参数给组件。

添加属性

这里我们以一个字符串类型的属性为例，展示如何添加属性：

在组件的配置文件（src/config.ts）中增加配置，如下：

import { API_VERSION, Category } from './api';

export default {
  apiVersion: API_VERSION,
  version: '1.0',
  isContainer: false,
  title: '',
  componentName: 'MobiPcComponentABC',
  category: Category.COMMON,
  icon: 'https://img.alicdn.com/imgextra/i1/O1CN01oufFHB266LbYRkVr3_!!6000000007612-55-tps-20-20.svg',
  configure: [
    {
      title: '基础数据类型的Prop设置',
      type: 'group',
      display: 'block',
      items: [
        {
          name: 'aText',
          title: '字符串Prop',
          setter: {
            type: 'text',
          },
        },
      ],
    },
  ],
};

组件加载后，效果如下，可以看到右边多出了属性分组（基础数据类型的Prop设置）和一个属性设置项（字符串Prop）。此时输入字符串，不会对组件产生任何影响。

修改组件代码（src/index.tsx），添加 Props 参数。

import React from 'react';
import config from './config';
import './index.scss';

interface Props {
  aText: string;
}

const MobiPcComponentABC = (props: Props) => {
  return (
    <div className="MobiPcComponentABC">
      <div>{`Hello XXXComponent ~ ${props.aText}`}</div>
    </div>
  );
};

MobiPcComponentABC.config = config;

export default MobiPcComponentABC;

组件加载后，效果如下，可以看到属性设置生效了：

组件属性是什么

通过上述例子，我们可以看到，添加属性就是通过配置文件，声明属性和对应的 Props 参数。当平台用户设置属性时，组件的 Props 参数就对应改变。

所以属性就是一种方式：让平台用户通过搭建的方式设置组件 Props 参数。

这里的 Props 参数就是指 React 组件声明的 Props 中的参数。

在搭建页面时，右边设置属性的UI组件称为属性设置器。

对于一个独立的组件来说，和外界交互的边界就是自身的 Props 参数，也就是组件的属性。所以平台的所有能力都是基于属性这一机制来实现的，包括组件的样式、数据、事件等等。

针对不同类型或者不同交互方式的属性，平台提供了各种属性设置器来满足不同场景。本教程后续会有不同的属性设置器的使用场景说明。

属性配置的核心参数说明

针对这个示例，我们简单说明下属性配置的一些关键参数。完整参数说明请参考PropGroup 属性组。

    {
      title: '基础数据类型的Prop设置',
      type: 'group',
      display: 'block',
      items: [
        {
          name: 'aText',
          title: '字符串Prop',
          setter: {
            type: 'text',
          },
        },
      ],
    }

属性分组参数：

字段	类型	含义	备注
title	string	分组的名称
type	string	配置的类型	这里固定为group，表示分组配置
display	string	分组展示的形式	一般情况用block
items	Array<object>	此分组下的属性配置

属性参数：

字段	类型	含义	备注
name	string	对应Props参数的key
title	string	展示的名称	这里可以用用户方便理解的描述
setter	object	属性设置器的配置

属性设置器参数

字段

类型

含义

备注

type

string

属性设置器的标示

用于声明使用什么样的属性设置器。

参考属性设置器

props

object

属性设置器的Props参数配置

不同的属性设置器会接受不同的参数，

提供不同的设置效果

警告

属性配置必须是在分组中，而且只能有一层分组。

基础数据类型的属性

当组件需要一些基础数据类型（string number boolean）的 Props 参数时，我们就可以添加一些基础数据的属性。

步骤和添加属性一样。

string类型的属性设置器，请参考 text。

number类型的属性设置器，请参考 number。

boolean类型的属性设置器，请参考 bool。

可枚举值的属性

有些组件的 Props 参数可以设置的值是有限的，比如枚举类型，或者按钮的样式，只能取主要、次要等等。

特点是用户只需要从有限的几个值中选择一个，针对这种场景，我们提供了两个属性设置器choice和select。

重要

choice和select属性设置器的重点在于从几个固定值中选择一个，但是对值的类型是没有约束的，所以可以是string number boolean 甚至数组、对象混合使用，但不能是function。

我们看下如何使用。

配置文件修改：

import { API_VERSION, Category } from './api';

export default {
  apiVersion: API_VERSION,
  version: '1.0',
  isContainer: false,
  title: '',
  componentName: 'MobiPcComponentABC',
  category: Category.COMMON,
  icon: 'https://img.alicdn.com/imgextra/i1/O1CN01oufFHB266LbYRkVr3_!!6000000007612-55-tps-20-20.svg',
  configure: [
    {
      title: '选项风格的Prop设置',
      type: 'group',
      display: 'block',
      items: [
        {
          name: 'configByRadio',
          title: '选项类型的Prop',
          setter: {
            type: 'choice',
            props: {
              options: [
                { value: 'primary', tip: '可以是字符串', title: '字符串' },
                { value: 4, tip: '可以是数字', title: '数字' },
                { value: true, tip: '可以是bool', title: '布尔' },
                {
                  value: {
                    key: 'value',
                  },
                  tip: '可以是对象',
                  title: '对象',
                },
              ],
            },
          },
        },
        {
          name: 'configBySelect',
          title: '下拉类型的Prop',
          setter: {
            type: 'select',
            props: {
              options: [
                { value: 'primary', title: '字符串' },
                { value: 4, title: '数字' },
                { value: true, title: '布尔' },
                {
                  value: {
                    key: 'value',
                  },
                  title: '对象',
                },
              ],
            },
          },
        },
      ],
    },
  ],
};

组件实现修改：

import React from 'react';
import {
  PropsWithPageContext
} from './api';
import config from './config';
import './index.scss';

interface Props {
  configByRadio: 'primary' | 4 | true | { key: string };
  configBySelect: 'primary' | 4 | true | { key: string };
}

const MobiPcComponentABC = (props: PropsWithPageContext<Props>) => {


  return (
    <div className="MobiPcComponentABC">
      <div>{`Hello MobiPcComponentABC ~`}</div>
      <div>{`选项类型的Prop : ${props.configByRadio} ${typeof props.configByRadio}`}</div>
      <div>{`下拉类型的Prop : ${props.configBySelect} ${typeof props.configBySelect}`}</div>
     
    </div>
  );
};

MobiPcComponentABC.config = config;

export default MobiPcComponentABC;

加载效果：

样式类型的属性

当前平台没有提供直接编辑样式的属性，即不能直接把一个 style 作为 Props 参数传递给组件。

所以对于组件的样式设置，是通过其它的属性设置 Props 参数，组件内部再解析 Props 参数封装为 style，传递给dom元素。

比如字体大小，可以设置一个 name 为 fontSize 的数字类型的属性，然后组件内再把 fontSize 传递给 style 使用。

为了提高交互体验，平台提供了几个专门用于样式的属性设置器：new-size-setter、color、margin-padding。

我们看下如何使用。

配置文件修改：

import { API_VERSION, Category } from './api';

export default {
  apiVersion: API_VERSION,
  version: '1.0',
  isContainer: false,
  title: '',
  componentName: 'MobiPcComponentABC',
  category: Category.COMMON,
  icon: 'https://img.alicdn.com/imgextra/i1/O1CN01oufFHB266LbYRkVr3_!!6000000007612-55-tps-20-20.svg',
  configure: [
    {
      title: '样式相关的Prop设置',
      type: 'group',
      display: 'block',
      items: [
        {
          name: 'aSize',
          title: '尺寸',
          defaultValue: {
            unit: 'auto',
            value: 0,
          },
          setter: {
            type: 'new-size-setter',
          },
        },
        {
          name: 'aColor',
          title: '颜色',
          setter: {
            type: 'color',
          },
        },
        {
          name: 'aSpace',
          title: '间距',
          setter: {
            type: 'margin-padding',
          },
        },
      ],
    },
  ],
};

组件实现修改：

import React from 'react';
import {
  Margin,
  Padding,
  PropsWithPageContext, Size
} from './api';
import config from './config';
import './index.scss';

interface Props {
  aSize: Size;
  aColor: string;
  aSpace: Margin & Padding;
}

const MobiPcComponentABC = (props: PropsWithPageContext<Props>) => {
  
  const style = {
    width: props.aSize.toValue(),
    height: '100px',
    backgroundColor: props.aColor,
    ...props.aSpace,
  };

  return (
    <div className="MobiPcComponentABC">
      <div>{`Hello MobiPcComponentABC ~`}</div>
      <div style={style}>
        <div> {`尺寸用于样式中的宽高等地方 ${props.aSize.toValue()}`}</div>
        <div> {`颜色用于样式中的背景色等地方 ${props.aColor}`}</div>
        <div> {`间距用于配置margin和padding ${JSON.stringify(props.aSpace)}`}</div>
      </div>
     
    </div>
  );
};

MobiPcComponentABC.config = config;

export default MobiPcComponentABC;

组件加载效果：

接下来

本文说明了如何通过属性设置组件的 Props 参数，基于此我们可以解决组件开发中基础的参数设置和样式设置的问题。接下来请查看4. 事件响应，了解如何处理事件回调。