「表单设计器开发指南」的内容补充*

官方使用 designable 工程开发了“表单设计器”，事实上 designable 不局限于此，做页面设计器、bi设计器都可以。

目前designable 工程暂时没有开发文档，可以参看这篇文章进行了解。当然不看也可以，因为我们并不是要去开发 designable 工程，而是使用 designable 里的模块而已，就像我们只需要会用 antd 的组件库，而不需要掌握 antd 开源工程一样。

@designable/react

observer

observer 是一个 HOC， Function Component 变成 Reaction，每次视图重新渲染就会收集依赖，依赖更新会自动重渲染

使用方式参看：

• @formily/react 文档的observer部分。
• @formily/reactive 文档的observer部分。

SettingsPanel

右侧配置表单布局面板。

Workspace

工作区组件，是一个 HOC。用于管理工作区内的拖拽行为，树节点数据等等。

title 和 description 字段在源码中没有看到使用，应该是预留字段。

WorkspacePanel

工作区布局面板，纯粹的布局组件（如果把设计器分为左中右三部分，工作区布局面板就是中间部分的“壳”），挂了.dn-workspace-panel样式，仅此而已。

不过它的子组件WorkspacePanel.Item在其它地方用的满多的，比如 ToolbarPanel、ViewportPanel 都是用它做跟组件。

WorkspacePanel.Item

设置display:flex对容器里，使用本组件，可以方便的通过flexable属性配置 flex-grow 和 flex-shrink 的开启与关闭。

如果对 flex-grow、flex-shrink 不了解，可以看这里。

一码胜千言：

WorkspacePanel.Item = (props) => {
  const prefix = usePrefix('workspace-panel-item');
  return (
    <div
      className={prefix}
      style={{
        ...props.style,
        flexGrow: props.flexable ? 1 : 0,
        flexShrink: props.flexable ? 1 : 0,
      }}
    >
      {props.children}
    </div>
  );
};

ToolbarPanel

工具栏布局面板（设计器最中心区域上面的“操作区”），包括撤销、选择、视图切换等操作。

一码胜千言：

<WorkspacePanel.Item
  {...props}
  style={{
    display: 'flex',
    justifyContent: 'space-between',
    marginBottom: 4,
    padding: '0 4px',
    ...props.style,
  }}
>
  {props.children}
</WorkspacePanel.Item>

ViewportPanel

工具栏布局面板（设计器最中心区域的“编辑区”），它用模拟器组件Simulator给子组件做了布局（它的介绍就在楼下）。

一码胜千言：

<WorkspacePanel.Item {...props} flexable>
  <Simulator>{props.children}</Simulator>
</WorkspacePanel.Item>

Simulator

视图模拟器组件，通过适当配置，可以实现给中间的操作区套上“手机壳”、“自适应壳“的展示。

一码胜千言：

export const Simulator: React.FC<ISimulatorProps> = observer(
  (props: ISimulatorProps) => {
    const screen = useScreen(); // useScreen()的返回值等于`globalThisPolyfill['__DESIGNABLE_ENGINE__'].screen`
    if (screen.type === ScreenType.PC)
      return <PCSimulator {...props}>{props.children}</PCSimulator>;
    if (screen.type === ScreenType.Mobile)
      return <MobileSimulator {...props}>{props.children}</MobileSimulator>;
    if (screen.type === ScreenType.Responsive)
      return (
        <ResponsiveSimulator {...props}>{props.children}</ResponsiveSimulator>
      );
    return <PCSimulator {...props}>{props.children}</PCSimulator>;
  },
  {
    scheduler: requestIdle,
  },
);

ViewPanel

视图布局面板，也就是设计器最中心区域的“壳”。它是四种视图模式（可视化设计、json、jsx、预览）的容器组件，并给子组件赋能。

子组件的上下文中可以获取到ViewPanel提供的 tree 变量，完成一次配置多处使用的设计。如下：

<ViewportPanel style={{ height: '100%' }}>
  <ViewPanel type="DESIGNABLE" dragTipsDirection="left">
    {() => <ComponentTreeWidget components={{ Input }} />}
  </ViewPanel>
  <ViewPanel type="JSONTREE" scrollable={false}>
    {(tree, onChange) => <SchemaEditorWidget tree={tree} onChange={onChange} />}
  </ViewPanel>
  <ViewPanel type="MARKUP" scrollable={false}>
    {(tree) => <MarkupSchemaWidget tree={tree} />}
  </ViewPanel>
  <ViewPanel type="PREVIEW">
    {(tree) => <PreviewWidget tree={tree} />}
  </ViewPanel>
</ViewportPanel>

另外，ViewPanel 会在被导入时自动获取workbench.type，在四种视图模式中选择需要展示的状态。

StudioPanel

主布局面板，整个工程的壳。

CompositePanel

左侧组合布局面板

CompositePanel.Item

各布局面板的配置

ResourceWidget

组件资源编组容器。

useTheme

获取主题函数。执行useTheme()可获得darkorlight。

• 如果什么都不干，获取到的永远都是’light’。
• 如果希望自己的设计器可以切换主题可以使用@designable/react里的Layout组件做配置（需放在项目根目录）。

下面是“跟随系统的暗黑模式改变主题”的示例。

import React, { useMemo } from 'react';
import {
  Layout,
} from '@designable/react';
import App from './App';
// 设置UI主题（是否暗黑模式）
const designerTheme = !window.matchMedia('(prefers-color-scheme: dark)').matches
  ? 'light'
  : 'dark';
export default function IndexPage() {
  return (
    <Layout theme={designerTheme}>
      <App />
    </Layout>
  );

@designable/shared

该模块（主模块）里包含多个子模块。

• animation：组件的拖拽动画
• array：基础的的数组函数
• clone：拷贝函数
• coordinate：实现拖拽功能的计算函数集
• element：dom 元素的计算函数集
• event：事件引擎
• keycode：快捷键管理
• lru：实现动态缓存管理
• request-idle：封装了一下requestIdleCallback
• scroller：实现拖拽自动滚动
• type：验证数据类型
• uid：提供了一个 uid 方法，用于给每个元素指定唯一的 key

它们里面的 api 均被注册在主模块的入口文件中，可以直接在顶层应用，例如：

import { isPlainObj } from '@designable/shared'; // isPlainObj是子模块types里的函数
const a={a:1};
const b=[1,2,3];
const c='123';
console.log(isPlainObj(a)); // true
console.log(isPlainObj(b)); // false
console.log(isPlainObj(c)); // false

types

做数据类型的验证。

除此之外，还提供了一个取值函数。

element

dom 元素的计算函数集。

coordinate

实现拖拽功能的计算函数集。

先看下定义的几个接口类型，内部一直在使用（外面能用，export 出去了）。

// 点的位置
export interface IPoint {
  x: number;
  y: number;
}
// 点的类形态
export class Point implements IPoint {
  x: number;
  y: number;
  constructor(x: number, y: number) {
    this.x = x;
    this.y = y;
  }
}
// 矩形，包含起点坐标以及宽高
export interface IRect {
  x: number;
  y: number;
  width: number;
  height: number;
}
// 象限，框选多个组件时使用（猜测：内部指试图区域内，外部指试图区域外）
export enum RectQuadrant {
  Inner1 = 'I1', //内部第一象限
  Inner2 = 'I2', //内部第二象限
  Inner3 = 'I3', //内部第三象限
  Inner4 = 'I4', //内部第四象限
  Outer1 = 'O1', //外部第一象限
  Outer2 = 'O2', //外部第二象限
  Outer3 = 'O3', //外部第三象限
  Outer4 = 'O4', //外部第四象限
}
export interface IPointToRectRelative {
  quadrant: RectQuadrant;
  distance: number;
}

request-idle

基于requestIdleCallback实现“函数在浏览器空闲时被调用”。

uid

只提供了一个 uid 方法，返回指定长度的随机字符串（字母+数字），用于给每个元素指定唯一的 key

文件里代码蛮短的，可以读一下：

let IDX = 36,
  HEX = '';
while (IDX--) HEX += IDX.toString(36); // 通过依次从36到1转十六进制，最终返回`zyxwvutsrqponmlkjihgfedcba9876543210`
export function uid(len?: number) {
  let str = '',
    num = len || 11;
  while (num--) str += HEX[(Math.random() * 36) | 0]; // 根据长度，给str拼接随机字符
  return str;
}

globalThisPolyfill

全局变量，从模块里解构出来直接用就行了。

如果在浏览器环境就是 window，如果是 node 环境 就是 global。

可以给全局对象增加 globalThisPolyfill 属性。

返回优先级：window > 全局变量的 globalThisPolyfill 属性 > global

@designable/react-settings-form

SettingsForm

右侧设置面板组件（具体如何作拓展配置，待完善）