TypeScript Type Definitions

This document details the TypeScript definitions of various core data structures in fcDesigner. These data structures define how to generate components, drag components, configure designers, etc. Understanding these data structures helps you customize and extend designer functionality to meet different business requirements.

Component Generation Rules

Component JSON Data Structure

Rule is the core data structure describing component generation rules. Each component has a unique _fc_id identifier and other properties used to define the component's type, style, events, validation rules, etc. See Complete Configuration.

type Rule = {
    // Rule unique value
    _fc_id: string;
    // Drag rule ID
    _fc_drag_tag: string;
    // Drag template rule ID
    _fc_template?: string;
    // Generated component name
    type: string;
    // Field ID
    field?: string;
    // Number
    name?: string;
    // Field name
    title?: string;
    // Hint information
    info?: string;
    // Component value
    value?: any;
    // Component configuration
    props: Object;
    // Component style
    style: string | Object;
    // Component class
    class: string | Array;
    // Component events
    on?: { [key: string]: Function | Function[] };
    // Slot name
    slot?: string;
    // Component key
    key?: string;
    // Whether required
    $required: boolean | string;
    // Component options
    options?: Array;
    // Component prop name corresponding to options
    optionsTo?: string;
    // Do not wrap with formItem and wrap
    native?: boolean;
    // Whether to hide component (no dom)
    hidden?: boolean;
    // Whether to display component (has dom)
    display?: boolean;
    // Whether to enter read mode
    preview?: boolean;
    // Custom read mode echo
    readMode?: 'custom';
    // Component validation rules
    validate?: Object[];
    // Child components
    children?: Rule[];
    // Linkage data
    control?: Array;
    // FormItem configuration
    wrap?: Object;
    // Logical conditions/calculation formulas
    computed?: {
        [key: string]: string | Object;
    };
    // Custom properties
    effect?: {
        // Remote data
        fetch?: Object,
    };
    // Other extended properties
    [key: string]: any;
}

Description

• _fc_id: Unique identifier for component rules, used to uniquely locate each component in the designer.
• props: Component property configuration, used to define component behavior and appearance.
• on: Component event handlers, can configure multiple event listeners.
• validate: List of rules for form validation.
• children: Can contain child components, used to generate complex component structures.

Container Component Draggable Rules

AllowDrag and DenyDrag are used to define drag rules for container components, controlling which components can be dragged into the container and which cannot.

// List of components that can be dragged in
type AllowDrag = string[] | {
    // List of menus that can be dragged in
    menu: string[];
    // List of components that can be dragged in
    item: string[];
}
// List of components that cannot be dragged in
type DenyDrag = string[] | {
    // List of menus that cannot be dragged in
    menu: string[];
    // List of components that cannot be dragged in
    item: string[];
}

Description

• AllowDrag: Defines components or menus allowed to be dragged in the container. Can be an array of component names, or an object where menu and item specify allowed menus and components respectively.
• DenyDrag: Defines components or menus not allowed to be dragged in the container. Can be an array of component names, or an object where menu and item specify forbidden menus and components respectively.
• Priority: AllowDrag configuration has higher priority than DenyDrag.

Usage

Configure these rules in container components or config to control drag behavior:

// Set draggable rules
const allowDrag = {
    menu: ['main'],
    item: ['button', 'checkbox']
};
// Set non-draggable rules
const denyDrag = {
    menu: ['subform'],
    item: ['date-picker']
};

Drag Components

Description Rule Structure

DragRule is used to define drag component rules in the designer. Each drag component has a unique name identifier and generates component rules through the rule method.

// Multi-language read function
type t = (name, ...args) => string;
// Drag component description rule structure
interface DragRule {
    // Component ID, cannot be duplicated
    name: string;
    // Component name
    label: string;
    // Component icon
    icon: string;
    // Insertion category
    menu?: 'main' | 'aide' | 'layout' | 'template' | string;
    // Whether to support style configuration
    style?: boolean;
    // Whether it is an inline component
    inline?: boolean;
    // Whether it is a form component
    input?: boolean;
    // Control maximum number of child components that can be dragged in
    maxChildren?: number;
    // Determine if component can be dragged in
    checkDrag?: (drag: {rule: Rule | undefined, menu: DragRule, toRule: Rule, toMenu: DragRule})=> boolean;
    // If it is a sub-form component, need to define `value` type
    subForm?: 'object' | 'array';
    // List of components that can be dragged in (available for container components)
    allowDrag?: AllowDrag;
    // List of components that cannot be dragged in (available for container components)
    denyDrag?: DenyDrag;
    // Allow dragging into which components
    allowDragTo?: string | string[];
    // Component, not recommended to use
    component?: Component;
    // Multi-language configuration items
    languageKey: string[];
    // Form global configuration
    formOptions?: {
        globalClass?: GlobalClass;
        globalVariable?: GlobalVariable;
        globalData?: GlobalData;
        globalEvent?: GlobalEvent;
        language?: Object;
        style?: string;
    } | string;
    // Component generation rules
    rule(arg: { t: t }): Rule;
    // Component property configuration rules
    props(rule: Rule, arg: { t: t, api: Api }): Rule[];
    // When exporting rules, convert to final rules through this method
    parseRule?: (rule: Rule) => void;
    // When importing rules, convert to rendering rules in designer through this method
    loadRule?: (rule: Rule) => void;
    // Triggered when fields in props change
    watch?: {
        [key: string]: (arg: { value: any, rule: Rule, api: Api, field: string }) => void;
    };
    // Whether there are matching child components, e.g., Row and Col
    children?: string;
    // Number of child components to render on initialization
    childrenLen?: number;
    // Whether the current component's operation container is displayed inside the component, when false the operation container wraps the current component
    inside?: true | boolean;
    // Whether other components can be dragged into the current component
    drag?: true | string | boolean;
    // Whether to show drag button
    dragBtn?: false | boolean;
    // Control whether operation buttons are displayed, which ones to show
    handleBtn?: true | boolean | Array<'create' | 'copy' | 'addChild' | 'delete'>;
    // Hide fields in basic configuration
    hiddenBaseField?: string[];
    // Whether to show mask, to avoid operating on component. Recommended true when there are child components, false otherwise
    mask?: false | boolean;
    // Whether only one can be dragged in
    only?: boolean;
    // Whether to generate name
    aide?: boolean;
    // Events supported by current component
    event?: string[];
    // Data type of current component's `value`
    validate?: string[] | 'required' | boolean;
}

Description

• rule method: Generates component rules, returns a Rule object.
• props method: Used to define component property configuration forms.
• watch: Listens to component property changes and handles accordingly.
• children: Used to support components with child components, such as Row and Col.

Usage

After defining DragRule, import component rules through the designer.addComponent method. For example:

designer.addComponent(dragRule);

You can also batch import multiple rules:

designer.addComponent([dragRule1, dragRule2, dragRule3]);

Designer Left Menu List

// Drag component
interface MenuItem {
    // Drag component name
    label: string;
    // Drag component ID
    name: string;
    // Drag component icon
    icon: string;
}
// Menu
interface Menu {
    // Menu name
    title: string;
    // Menu ID
    name: string;
    // Drag component list
    list: MenuItem[];
    // Place at the top of the list
    before?: boolean;
}
type MenuList = Menu[];

Description Built-in menu IDs are template, main, subform, aide, layout (5 total)

• template Template components
• main Basic components
• subform Sub-form components
• aide Auxiliary components
• layout Layout components

Designer Configuration

Designer props.config Configuration

props.config is used to configure various behaviors and interface elements of the designer. Through these configuration items, you can customize the designer to better meet project requirements. Below is the detailed data structure and usage instructions for this configuration.

// Define function to return rules or return rules through rule field
type extendRule = ((arg: { t: t }) => Rule[]) | {
    // Generate rules
    rule: (arg: { t: t }) => Rule[];
    // Append
    append?: boolean;
    // Prepend
    prepend?: boolean;
};

// Display method
type Device = 'pc' | 'pad' | 'mobile';
// Designer component props.config configuration
export interface Config {
    fontFamily?: Array<string | {label: string, value: string}>;
    // Configure design area display method
    device?: Device;
    // Whether component types can be switched, or fields that can be switched to each other
    switchType?: false | Array<string[]>;
    // Whether to automatically select dragged components
    autoActive?: boolean;
    // Multi-language types
    localeOptions?: Array<{
        value: string;
        label: string;
    }>;
    // Pre-delete component event, return false to cancel deletion
    beforeRemoveRule?: (data: { rule: Rule }) => false|void;
    // Pre-select component event, return false to cancel selection
    beforeActiveRule?: (data: { rule: Rule }) => false|void;
    // Order of component configuration items
    configFormOrder?: Array<'base' | 'advanced' | 'props' | 'slots' | 'style' | 'event' | 'validate'>;
    // Determine if component can be dragged in
    checkDrag?: (drag: {rule: Rule | undefined, menu: DragRule, toRule: Rule, toMenu: DragRule})=> boolean;
    // Whether to enable keyboard shortcuts, enabled by default
    hotKey?: boolean;
    // Whether to automatically reset component name when copying, enabled by default
    autoResetName?: boolean;
    // Whether to automatically reset component field when copying, enabled by default
    autoResetField?: boolean;
    // Right-side configuration update method
    updateConfigOnBlur?: boolean;
    // Whether to generate Vue2 syntax template components
    useTemplate?: boolean;
    // Define form configuration default values
    formOptions?: Object;
    // Configure whether field can be edited
    fieldReadonly?: boolean;
    // Configure whether name can be edited
    nameReadonly?: boolean;
    // Control whether sub-form component fields are linked with sub-form fields, enabled by default
    relationField?: boolean;
    // Control whether component validation only shows required validation
    validateOnlyRequired?: boolean;
    // Hide drag operation buttons
    hiddenDragMenu?: boolean;
    // Hide drag buttons
    hiddenDragBtn?: boolean;
    // Control component configuration permissions
    componentPermission?: {
        // Component field
        field?: string | string[];
        // Component name
        name?: string | string[];
        // Component _fc_drag_tag
        tag?: string | string[];
        // Component _fc_id
        id?: string | string[];
        // Permissions
        permission: {
            // Whether can delete
            delete?: false,
            // Whether can copy
            copy?: false,
            // Whether can drag
            move?: false,
            // Whether can configure validation
            validate?: false,
            // Whether can configure events
            event?: false,
            // Whether can configure advanced configuration
            advanced?: false,
            // Whether can configure basic configuration
            base?: false,
            // Whether can configure component configuration
            props?: false,
            // Whether can configure style
            style?: false,
            // Whether can configure slots
            slots?: false,
            // Whether can switch components
            switchType?: false,
            // Whether to show name
            name?: false,
            // Define hidden configuration items
            hiddenConfig?: string[],
            // Define disabled configuration items
            disabledConfig?: string[]
        },
    }[],
    // Hide some menus
    hiddenMenu?: MenuName[];
    // Hide some components
    hiddenItem?: string[];
    // Hide some form configuration items
    hiddenFormConfig?: string[];
    // Disable some form configuration items
    disabledFormConfig?: string[];
    // Hide some component configuration items
    hiddenItemConfig?: {
        default?: string[];
        // Drag rule name: hidden field names
        [id: string]: string[];
    };
    // Disable some component configuration items
    disabledItemConfig?: {
        default?: string[];
        // Drag rule name: disabled field names
        [id: string]: string[];
    };
    // List of components that can be dragged in
    allowDrag?: {
        // Drag rule name: draggable rules
        [id: string]: AllowDrag;
    };
    // List of components that cannot be dragged in
    denyDrag?: {
        // Drag rule name: non-draggable rules
        [id: string]: DenyDrag;
    };
    // Whether to show left side
    showMenuBar?: boolean;
    // Whether to show save button
    showSaveBtn?: boolean;
    // Whether to show preview button
    showPreviewBtn?: boolean;
    // Whether to show right-side configuration interface
    showConfig?: boolean;
    // Whether to show component's basic configuration form
    showBaseForm?: boolean;
    // Whether to show component number
    showComponentName?: boolean;
    // Whether to show component linkage
    showControl?: boolean;
    // Whether to show JSON preview button
    showJsonPreview?: boolean;
    // Whether to show custom props button
    showCustomProps?: boolean;
    // Whether to show module management
    showPageManage?: boolean;
    // Whether to show component's advanced configuration form
    showAdvancedForm?: boolean;
    // Whether to show component's property configuration form
    showPropsForm?: boolean;
    // Whether to show component's style configuration form
    showStyleForm?: boolean;
    // Whether to show component's event configuration form
    showEventForm?: boolean;
    // Whether to show component's validation configuration form
    showValidateForm?: boolean;
    // Whether to show form configuration
    showFormConfig?: boolean;
    // Whether to show left template list
    showTemplate?: boolean;
    // Whether to show multi-device adaptation options
    showDevice?: boolean;
    // Whether to show input button
    showInputData?: boolean;
    // Whether to show internationalization configuration
    showLanguage?: boolean;
    // Confirmation dialog when closing page
    exitConfirm?: boolean;
    // Define formData required for rendering rules
    appendConfigData?: string[] | ((rule: Rule) => Object);
    // Rendering rules for basic configuration, can override default rules. When append is true, append after default rules
    baseRule?: extendRule;
    // Rendering rules for validation configuration, can override default rules. When append is true, append after default rules
    validateRule?: extendRule;
    // Rendering rules for form, can override default rules. When append is true, append after default rules
    formRule?: extendRule;
    // Rendering rules for component configuration, can override default rules. When append is true, append after default rules
    componentRule?: {
        default: (rule: Rule, arg: { t: t }) => Rule[] | {
            rule: (rule: Rule, arg: { t: t }) => Rule[];
            append?: boolean;
            prepend?: boolean;
        };
        // Component drag rule ID, rule is the current component's generation rule
        [id: string]: (rule: Rule, arg: { t: t }) => Rule[] | {
            rule: (rule: Rule, arg: { t: t }) => Rule[];
            append?: boolean;
            prepend?: boolean;
        };
    };
    updateDefaultRule?: {
        // Component drag rule ID, set component initialization rules
        [id: string]: Partial<Omit<Rule, "field" | "children" | "component">> | ((Rule) => void);
    };
}

Usage

Set designer behavior through props.config. For example:

<fc-designer :config="designerConfig" />

Where designerConfig is a configuration object based on the structure described above.

export default {
    data() {
        return {
            designerConfig: {
                formOptions: {},
                fieldReadonly: false,
                hiddenMenu: ['layout'],
                showConfig: true,
                // Other configuration items...
            }
        };
    }
}

By reasonably configuring these options, you can customize the designer's behavior and display content according to project requirements.

Extended Operations

Extended operations are used to define additional operation buttons available in the designer and their handler functions.

type Handle = Array<{
    // Button name
    label: string;
    // Callback function
    callback: Function;
}>

You can extend designer operations through config.handle

Hierarchical Structure

Hierarchical structure is used to describe the hierarchical relationships and properties of components in forms.

type TreeData = Array<{
  	// Unique value
    _fc_uni: string;
  	// Component type
    type: string;
  	// Field ID
    field?: string;
  	// Field name
    title?: string;
  	// Slot
    slot?: string;
  	// Properties
    props: Object;
  	// Children
    children?: TreeData;
}>

You can get description rules through getDescription and getFormDescription methods

Calculation Functions

Calculation functions are used to define custom calculation logic, which can be used for various calculation operations in forms.

type Formula = {
    // Menu
    menu: 'math' | 'string' | 'date' | 'collection' | 'condition';
    // Calculation function name
    name: string;
    // Calculation function description
    info: string;
    // Calculation function usage example
    example: string;
    // Calculation function
    handle: Function;
};

You can extend calculation rules through the FcDesigner.setFormula method

Behavior

The type defines extensible behavior modules, allowing you to add custom operations in the form designer.

Type Behavior = {
    // Menu
    menu: 'model' | 'form' | 'other';
    // Behavior method ID
    name: string;
    // Behavior name
    label: string;
    // Behavior description
    info: string;
    // Configuration parameter generation rules
    rule?: (designer: Object) => Rule[];
    // Behavior function
    handle: Function;
};

You can extend calculation rules through the FcDesigner.setBehavior method