微程式表單控制項開發手冊

1664439610757-502efa30-7dc2-4ac1-8799-c7bdc7b63521.png

微程式表單設計時頁面佈局.

左側: 控制項面板.

中間: 控制項佈局.

右側: 控制項屬性欄.

控制項構成

一個表單控制項有四個部分組成:

  1. 控制項訊息(Info) - 說明控制項的名稱,資料類型,所屬的控制項分組.
  2. 控制項屬性(Schema) - 聲明控制項所擁有的屬性和屬性的類型.
  3. 控制項屬性行爲(Conduct) - 定義控制項屬性在控制項屬性欄的特定動作.
  4. Vue控制項 - 控制項在admin設計時和PC、Mobile運行時的控制項.

推薦控制項目錄結構:

--- NewComponent

--- index.ts



--- schema.ts



--- conduct.ts



--- components



	--- design.vue



	--- pc.vue



	--- mobile.vue

一個控制項應遵循的接口ComponentAsset:

interface ComponentAsset {
  info: ComponentInfo;

  schema: ObjectPropertyInfo;

  conduct: ControllerConduct;

  /**
   * 控制項 design/設計時 pc/電腦端瀏覽器 mobile/行動端h5
   */
  components: {
    design: Component<any, any, any, any> | AsyncComponent<any, any, any, any>; // VueConstructor<Vue> | (() => Promise<typeof import('*.vue')>)
    pc?: Component<any, any, any, any> | AsyncComponent<any, any, any, any>;
    mobile?: Component<any, any, any, any> | AsyncComponent<any, any, any, any>;
  };
}

import { ComponentAsset } from "@cloudpivot/form/typings";
export default {
  info,
  schema,
  conduct,
  components: {
    design,
    pc,
    mobile,
  },
} as ComponentAsset;

控制項訊息(Info)

import { ComponentInfo } from "@cloudpivot/form/typings";
import { DataItemType, FormControlType } from "@cloudpivot/form/schema";
export const info: ComponentInfo = {
  title: "單行文本", // 控制項名稱,在控制項面板展示的名稱
  type: "single-line", // 控制項的type, 控制項的唯一標識之一. 在HTML自定模式下 標籤名
  icon: "h-icon-all-single-line-text", // 控制項icon,在控制項面板和控制項名稱一起展示
  dataItemType: DataItemType.ShortText, // 控制項資料項類型, 控制項在運行時的資料類型.可以重複.
  formControllerType: FormControlType.Text, // 控制項控制編碼類型, 控制項唯一標識之一.應該是number類型.
  group: "基礎控制項", // 控制項分組類型, 在控制項面板展示的分類.
};

⚠️控制項的訊息應該遵循接口ComponentInfo

interface ComponentInfo {
  /**
   * 控制項名稱
   */
  title: string;

  /**
   * 控制項類型
   */
  type: string;
  /**
   * 資料項類型
   */
  dataItemType?: DataItemType;
  /**
   * 控制器類型
   */
  formControllerType: FormControlType;
  /**
   * 強制替換原生控制項. ps.佈局控制項無法被替換.
   */
  force?: boolean;
  /**
   * 控制項圖標
   */
  icon?: string;

  /**
   * 控制項所屬分組
   */
  group?: string;
}

title

title 必填. 類型: String

type

type 必填,唯一. 類型: String

⚠️如果要替換微程式原生控制項,需要結合force使用. 微程式佈局控制項不能替換.

icon

icon 非必填. 類型: String

⚠️icon已經引入admin設計時,可使用的icon 請查看entries\admin\src\assets\icons\demon_index.html

dataItemType

dataItemType 非必填. 類型: Number

import { DataItemType } from "@cloudpivot/form/schema";

/**
 * 資料項類型
 */
export enum DataItemType {
  /**
   * 簡短文字
   */
  ShortText = 0,

  /**
   * 多行文字
   */
  LongText = 1,

  /**
   * 數值
   */
  Number = 2,

  /**
   * 日期
   */
  Date = 3,

  /**
   * 邏輯
   */
  Logic = 4,

  /**
   * 選人控制項
   */
  StaffSelector = 5,

  /**
   * 附件
   */
  Attachment = 6,

  /**
   * 審批意見
   */
  ApprovalOpinion = 7,

  /**
   * 子表
   */
  Sheet = 8,

  /**
   * 關聯表單
   */
  RelevanceForm = 9,

  /**
   * 地理位置
   */
  Address = 10,
}

⚠️資料項類型是和後臺同步的.不要修改或新增.

formControllerType

formControllerType 必填,唯一.類型: Number.

⚠️控制器類型編碼應該小於90.並且不應該和現有的控制項控制編碼重複.已有的控制項控制器編碼,請看_微程式已有控制項_一節.

group

group 非必填.類型:String.

聲明控制項所屬的分類, 目前已有控制項分類有: 基礎控制項、佈局控制項、系統控制項、進階控制項

控制項屬性(Schema)

Schema應該遵循接口ObjectPropertyInfo .

export interface PropertyInfo {
  title?: string;

  type?: string;

  default?: any;
}
export interface ObjectPropertyInfo extends PropertyInfo {
  $id: string;
  $ref?: string;
  properties: {
    [key: string]: PropertyInfo;
  };
}

Schema描述控制項所擁有屬性和它的資料類型和預設值.

⚠️Schema是參考 JSON Schema Specification.但它並沒有實現JSON Schema Specification所有的能力.

import { ObjectPropertyInfo, DataType } from "@cloudpivot/form/typings";
export default {
  $id: "shortText", // schema id. 具有唯一
  type: DataType.Object,
  properties: {
    name: {
      type: DataType.String,
      title: "控制項名稱",
      default: "",
    },
    name_i18n: {
      type: DataType.Object,
      title: "多語言",
    },
    visible: {
      type: DataType.Boolean,
      title: "是否可見",
      default: true,
    },
    style: {
      type: DataType.String,
      title: "控制項樣式",
    },
    tips: {
      type: DataType.String,
      title: "控制項Tips",
    },
    dataItemName: {
      type: DataType.String,
      title: "綁定資料項編碼",
    },
  }
} as ObjectPropertyInfo;

⚠️定製開發控制項需要在Schema定義  name,name_i18n ,visible,style,tips,dataItemName

type

type 必填.類型:String

屬性類型:"@cloudpivot/form/typings"

export enum DataType {
  Object = "object",
  String = "string",
  Boolean = "boolean",
  Integer = "integer",
  Array = "array",
  Number = "number",
}

title

title 必填.類型:String

title是屬性在控制項屬性欄展示的名稱.

default

default 非必填.類型: DataType

屬性預設值.

控制項屬性行爲(Conduct)

Conduct應該遵循接口ControllerConduct.

import {ControllerConduct,ControlAttributeType,} from "@cloudpivot/form/typings";

enum ControlAttributeType {
  Boolean,
  String,
  Dropdown,
  Modal,
  Date,
  Array,
}
interface ControllerConduct {
  groups: { 
    [key: 'base'|'controller']: {
      label: string;
      keys: string[];
    };
  };
  properties?: {
    [key: string]: {
      inputMethod?: ControlAttributeType; 
      inputComponent?:
        | Component<any, any, any, any>
        | AsyncComponent<any, any, any, any>; // 引入vue標準的控制項
      options?: ControllerOptions;
      [key: string]: any;
    };
  };
}

ControllerConduct

groups

groups 控制項屬性分組,在控制項屬性欄展示的資料.

必填. 類型:Object.

  groups: {
    base: {
      label: "基礎訊息",
      keys: ["name", "visible", "style", "tips", "dataItemName", "widgetType"],
    },
    controller: {
      label: "控制屬性",
      keys: [
        "defaultValue",
        "displayFormula",
        "requiredFormula",
        "options",
        "direction",
      ],
    },
  }

groups 類型是Object.key是分組的code,目前key只支持 case和controller兩個.

如上面例子: keys是在Schema中定義的屬性. 它在keys中的順序就是在控制項屬性欄中的順序.

properties

properties 定義屬性在的輸入行爲.

非必填. 類型: Object.

properties: {
  displayFormula: {
    inputMethod: ControlAttributeType.Modal,
    inputComponent: () =>
        import("@cloudpivot/form/src/common/components/required-condition.vue"),
    options: {
      formatter: (val) {
          if (val) {
    				return '已設定';
  				}
  				return '未設定';
      },
    },
  }
}

inputMethod

屬性輸入值的方式,它的類型有:

enum ControlAttributeType {
  Boolean,
  String,
  Dropdown,
  Modal,
  Date,
  Array,
}

ControlAttributeType.Dropdown

表示通過下拉框選值. 可以在options.list或options.dataList定義下拉框的值.

options.list應該是個Array類型的值, options.dataList是一個Function,應該返回一個數組.

ControlAttributeType.Modal

表示通過彈框輸入值. 彈框Vue控制項變數給inputComponent

inputComponent

inputMethod 值類型是 ControlAttributeType.Modal時,inputComponent 是必填.

inputComponent要是標準的Vue控制項

彈框控制項約定:

@Prop({type: Object})
 	modalData!: any; // modalData.data.value
@Prop({type:Object})
	modalOptions // 可以獲得到屬性設定中其他內容,除了 inputMethod, inputComponent.

this.$emit("backData", {value: modalValue}); // 彈框出確定, modalValue會被寫給 屬性欄 
this.$emit("closeModal") // 關閉彈出框

⚠️自定義的Vue控制項中可以獲得到這些訊息.

options

interface ControllerOptions {
  dateFormat?: string; // 時間格式
  formatter?: Function; //格式化 （value, attr: ControlAttributeOptions, attrs: ControlAttributeOptions[]）
  regexps?: any; // 文本正則匹配 regexp message
  maxLength?: number; // 最多行文字數量
  pickerOptions?: any; // 用戶控制項設定項
  disabled?: Boolean; // 目前控制項是否可以交互
  dataList?: Function; // 通過函數獲得下拉控制項值
  list?: any; // 下拉控制項值
  fieldDisplay?: Array<Array<string>>; // 針對於Bool類型 需要顯示或者隱藏欄位 根據目前value [ [],[] ] 0 是true是需要隱藏的欄位，1 是false 需要隱藏的欄位
  hideField?: Function | string[]; // 所有控制項需要隱藏欄位的方法 fun返回一個字符串數組 或者 欄位數字
  transaction?: Function; //事務處理 { attr，attrs, displayFields, allControls}
  callback?: Function; //事件回調
  importModal?: Function; //彈窗輸入重載  return {value:value, default:default};
  exportModal?: Function; ///彈窗輸出重載 return data: any;
  allowClear?: boolean; // 下拉框鼠標移上去可刪除
}

options 提供屬性欄輸入值鉤子方法.最常用的有:

options.formatter

格式話顯示值.

類型: (value,attr,attrs):any

在屬性欄展示的值,不會修改實際的值.

options.hideField

根據目前資料值隱藏其他屬性.

類型: hideField : string[] or hideField:(value):string[]

options.list

下拉控制項值.

類型: any[]

options.dataList

下拉控制項值

類型: ():any[]

options.disabled

屬性欄是否可以操作

類型: Boolean

options.callback

屬性值變化後回調方法

類型:callback:(key, attr,attrs,vm):vold

attr 目前屬性訊息

attrs 所有屬性訊息

vm vue實例

Vue控制項

控制項的view要求是標準的Vue控制項.

控制項分爲

設計時:design

運行時: PC、Mobile

design

設計時的控制項可以獲得到控制項控制器.

@Prop()
control!:any // control.options可以獲得到控制項的屬性

PC、Mobile

運行時的控制項做了約定.需要繼承BaseControl控制器.

<template>
  <div>
    <a-rate v-model="ctrl.value" :allowHalf="allowHalf" :count="count" />
  </div>
</template>
<script lang="ts">
import { Component, Vue, Prop, Watch, Inject } from "vue-property-decorator";
import {BaseControl} from "@cloudpivot/form/src/renderer/controls"
import * as typings from "@cloudpivot/form/schema";
import { Rate } from "@h3/antd-vue";
@Component({
  name: "Rate",
  components: {
    ARate: Rate,
  }
})
export default class ETRate extends BaseControl<typings.FormControlOptions> {
  // this.ctrl 控制項的控制器. 控制項的value 通過 this.ctrl獲得
  get allowHalf() {
    return this.options.allowHalf
  }
  get count() {
    return this.options.count
  }
  // 那控制項設定的屬性
  get options() {
    return this.control.options // 控制項的所有屬性
  }
  created() {
    this.ctrl.value // 控制項的值
  }
}

將控制項注入微程式表單

定製開發控制項需要引入到@cloudpivot/form/registerComponent.ts

import component from "@cloudpivot/form/src/components"; // 微程式原生組件
import { register } from "@cloudpivot/form/utils/register";
import { ComponentInfo, ComponentAsset } from "@cloudpivot/form/typings";
import extendComponent from "@cloudpivot/form/components-extend"; // 擴展組件

const components = [...component,...extendComponent];
export default function () {
  for (let cmp of components) {
    register.append(cmp);
  }
}

微程式已有控制項

基礎控制項

控制項名稱,控制項type,控制器編碼

控制項名稱控制項Type控制器編碼
單行文本single-line1
多行文字text-multiline2
日期calendar3
數值number4
單選框single-selection5
複選框check-square6
下拉框drop-down7
邏輯logic8
附件attachment9
圖片picture-card10
手寫簽名signature15
地址inputAddress14
人員單選staffSelector50
人員多選staffMultiSelector51
部門單選departmentSelector60
部門多選departmentMultiSelector61

佈局控制項

控制項名稱控制項Type控制器編碼
分組標題group200
描述說明description202
子表sheet201
標籤頁tabs500

系統控制項

控制項名稱控制項Type控制器編碼
單據號sequence-number100
建立人create101
建立人部門createDept102
擁有者ownerId106
建立時間createdTime104
修改時間modifiedTime105
修改人modifier103

進階控制項

控制項名稱控制項Type控制器編碼
關聯表單relevance-form80
關聯查詢reverse-relevance90

other

控制項名稱控制項Type控制器編碼
位置inputLocation11
日期範圍dateRange12
數值範圍numberRange13
Tipstips16
審批意見approvalOpinion70
系統-其他systemOther107
單據狀態sequenceStatus108
子表統計sheetStatistic300
Htmlhtml400
標籤頁面板tabsPanel501

⚠️other是系統存在但不在控制項面板上的控制項. 這些控制項也不要複寫.

微程式控制項之間的連動

每一個運行時的微程式控制項應該繼承base-control.ts,在base-control.ts已經注入了valChange方法用來獲得其它控制項的值變化的訂閱.

1612678426597-ef8b7e4e-9476-4110-8813-0e2012af34d3.png

valChange(key:string, fun: Function) => void

key

key 控制項的綁定資料項編碼(dataItemName)

fun

fun 值變化回掉方法.fun 函數的參數是一個對象:{value:新值, oldValue:舊值}

更多的控制項能力請查看微程式幫助中心: http://help.cloudpivot.cn/channels/3.html

微程式自定義控制項開發目錄

1612678426411-7d652521-ccbf-4a33-a79e-620a440c736b.png

自定控制項建議放置:modules/@cloudpovot/form/components-extend目錄中.

然後需要在registerComponent.ts中引入自定義控制項

1612678426398-c832434e-2f32-46ad-9139-e2ad7a8c3a77.png

啓動微程式項目即可看到

F&Q

是否可替換或擴展微程式原生控制項?

基礎控制項可以替換. 在控制項info中將type設定成和基礎控制項一樣,並設定force:true.

爲什麼只能替換基礎控制項

佈局控制項是和運行時的平臺有關聯.

系統控制項是預設和後端有關聯.

進階控制項和其他模型有關聯.

爲啥是conduct而不是setting

表單控制項開發規範和頁面設計器控制項開發規範是不一樣. 避免一致的映像.

爲什麼運行時的控制項需要繼承 base-controls.ts

在運行時,微程式每個控制項會被構建成單獨的controller,這些controller會有相同的能力,而這些能力是通過base-controls提供.

爲什麼控制項需要有 type和formControllerType兩個唯一的標識

微程式控制項可以被視爲一個DOM標籤和被視爲具有特殊能力的controller. type是在控制項掛載DOM的時候做爲唯一的表示.而 formControllerType 是作爲控制項庫中唯一的controller標識使用.

控制項庫中如果替換微程式基礎控制項type是可以重複,但formControllerType不能重複.

更新: 2022-09-29 16:20:17
原文: https://www.yuque.com/skwme4/hyk0u0/on0lo5