---
order: 1
---

# 客户端内核

<img src="https://nocobase.oss-cn-beijing.aliyuncs.com/5be7ebc2f47effef85be7a0c75cf76f9.png" style="max-width: 800px;" />

示例:

```tsx | pure
const app = new Application();

app.use([MemoryRouter, { initialEntries: ['/'] }]);

app.use(({ children }) => {
  const location = useLocation();
  if (location.pathname === '/hello') {
    return <div>Hello NocoBase!</div>;
  }
  return children;
});

export default app.compose();
```

## RouteSwitch

稍微复杂的应用都会用到路由来管理前端的页面,如下:

```jsx
/**
 * defaultShowCode: true
 * title: Router
 */
import React from 'react';
import { Route, Switch, Link, MemoryRouter as Router } from 'react-router-dom';

const Home = () => <h1>Home</h1>;
const About = () => <h1>About</h1>;

const App = () => (
  <Router initialEntries={['/']}>
    <Link to={'/'}>Home</Link>, <Link to={'/about'}>About</Link>
    <Switch>
      <Route exact path="/">
        <Home />
      </Route>
      <Route path="/about">
        <About />
      </Route>
    </Switch>
  </Router>
);

export default App;
```

上述例子,组件经由路由转发,`/` 转发给 `Home`,`/about` 转发给 `About`。这种 JSX 的写法,对于熟悉 JSX 的开发来说,十分便捷,但需要开发来编写和维护,不符合 NocoBase 低代码、无代码的设计理念。所以将 Route 做了封装和配置化改造,如下:

```tsx
/**
 * defaultShowCode: true
 * title: RouteSwitch
 */
import React from 'react';
import { Link, MemoryRouter as Router } from 'react-router-dom';
import { RouteRedirectProps, RouteSwitchProvider, RouteSwitch } from '@nocobase/client';

const Home = () => <h1>Home</h1>;
const About = () => <h1>About</h1>;

const routes: RouteRedirectProps[] = [
  {
    type: 'route',
    path: '/',
    exact: true,
    component: 'Home',
  },
  {
    type: 'route',
    path: '/about',
    component: 'About',
  },
];

export default () => {
  return (
    <RouteSwitchProvider components={{ Home, About }}>
      <Router initialEntries={['/']}>
        <Link to={'/'}>Home</Link>, <Link to={'/about'}>About</Link>
        <RouteSwitch routes={routes} />
      </Router>
    </RouteSwitchProvider>
  );
};
```

- 由 RouteSwitchProvider 配置 components,由开发编写,以 Layout 或 Template 的方式提供给 RouteSwitch 使用。
- 由 RouteSwitch 配置 routes,JSON 的方式,可以由后端获取,方便后续的动态化、无代码的支持。

## SchemaComponent

路由可以通过 JSON 的方式配置,可以注册诸多可供路由使用的组件模板,以方便各种场景支持,但是这些组件还是需要开发编写和维护,所以进一步将组件抽象,转换成配置化的方式。如:

```tsx
/**
 * defaultShowCode: true
 * title: Schema Component
 */
import React from 'react';
import { ISchema } from '@formily/react';
import { SchemaComponentProvider, SchemaComponent } from '@nocobase/client';

const schema: ISchema = {
  name: 'hello',
  'x-component': 'Hello',
  'x-component-props': {
    name: 'World',
  },
};

const Hello = ({ name }) => <h1>Hello {name}!</h1>;

export default function App() {
  return (
    <SchemaComponentProvider components={{ Hello }}>
      <SchemaComponent schema={schema} />
    </SchemaComponentProvider>
  )
};
```

可以通过 schema 方式配置的组件,称之为 schema 组件。在 SchemaComponentProvider 里注册各种 JSX 组件,编写相应的 schema,再通过 SchemaComponent 渲染。SchemaComponent 的 schema 就是 Formily 的 [Schema](https://react.formilyjs.org/zh-CN/api/shared/schema)。实际上 SchemaComponent 就是 Formily 的 [SchemaField](https://react.formilyjs.org/zh-CN/api/components/schema-field),之所以叫 SchemaComponent,是因为 SchemaComponent 可用于构建页面的各个部分,不局限于表单场景。

**思维转换:**

虽然 Formily 的核心是致力于解决表单的复杂问题,但是随着不断的演变,已经不局限在表单层面了。Formily 核心提供了 Form 和 Field 两个非常重要的模型,Form 提供了路径系统和联动模型也同样适用于页面视图,Field 实际上也可以理解为组件,分为有值组件和无值组件两类,有值组件例如 Input、Select 等,无值组件例如 Drawer、Button 等。有值组件的数值又可以分不同类型:String、Number、Boolean、Object、Array 等等,无值组件没有数值,所以用 Void 表示,和 Formily 的 Field、ArrayField、ObjectField、VoidField 都对应上了。

为了适应动态的配置化表单解决方案,Formily 又提炼了 Schema 协议(DSL),这个协议完全适用于描述组件模型,用类 JSON Schema 的语法描述组件结构和对应的数值类型,这个 Schema 也是 SchemaComponent 的重要组成部分。

- Schema 是一个树结构,多个节点以树形结构连接起来,其中的一个 property 表示的就是其中的一个 Schema 节点。
- 单 Schema 节点(不包括 properties)由核心 `x-component`、包装器 `x-decorator`、设计器 `x-designable` 三个组件构成。
  - `x-component` 核心组件
  - `x-decorator` 包装器,不同场景中,同一个核心组件,可能使用不同的包装器,如 FormItem、CardItem、BlockItem、Editable 等
  - `x-designable` 节点设计器(NocoBase 的扩展参数),一般为当前 schema 节点的配置表单。与 Formily 提供的 Designable 解决方案不同,`x-designable` 直接作用于当前 schema 节点,使用和配置不分离。

理论上,很多现有组件都可以直接转为 schema 组件,但是并不一定好用。以 Drawer 为例,常规 JSX 的写法一般是这样的:

```tsx
/**
 * defaultShowCode: true
 * title: JSX Drawer
 */
import React, { useState } from 'react';
import { Drawer, Button } from 'antd';

const App: React.FC = () => {
  const [visible, setVisible] = useState(false);
  const showDrawer = () => {
    setVisible(true);
  };
  const onClose = () => {
    setVisible(false);
  };
  return (
    <>
      <Button type="primary" onClick={showDrawer}>
        Open
      </Button>
      <Drawer 
        title="Basic Drawer" 
        placement="right" 
        onClose={onClose} 
        visible={visible} 
        footer={
          <Button onClick={onClose}>关闭</Button>
        }
      >
        <p>Some contents...</p>
        <p>Some contents...</p>
        <p>Some contents...</p>
      </Drawer>
    </>
  );
};

export default App;
```

将组件转换成 schema,如果 1:1 转换是这样的:

```tsx
/**
 * defaultShowCode: true
 * title: Drawer Schema
 */
import React, { useMemo } from 'react';
import { SchemaComponentProvider, SchemaComponent } from '@nocobase/client';
import { Drawer as AntdDrawer, Button } from 'antd';
import { createForm } from '@formily/core';
import { RecursionField } from '@formily/react';

const Drawer = (props) => {
  const { footerSchema, ...others } = props;
  return (
    <AntdDrawer
      footer={
        footerSchema && <RecursionField schema={footerSchema} onlyRenderProperties />
      }
      {...others}
    />
  );
};

const schema = {
  type: 'object',
  properties: {
    b1: {
      type: 'void',
      'x-component': 'Button',
      'x-component-props': {
        children: 'Open',
        type: 'primary',
        onClick: '{{showDrawer}}',
      },
    },
    d1: {
      type: 'void',
      'x-component': 'Drawer',
      'x-component-props': {
        title: 'Basic Drawer',
        onClose: '{{onClose}}',
        footerSchema: {
          type: 'object',
          properties: {
            fb1: {
              type: 'void',
              'x-component': 'Button',
              'x-component-props': {
                children: 'Close',
                onClick: '{{onClose}}',
              },
            },
          },
        },
      },
    },
  },
};

export default function App() {
  const form = useMemo(() => createForm(), []);
  const showDrawer = () => {
    form.query('d1').take((field) => {
      field.componentProps.visible = true;
    });
  };
  const onClose = () => {
    form.query('d1').take((field) => {
      field.componentProps.visible = false;
    });
  };
  return (
    <SchemaComponentProvider 
      form={form} 
      components={{ Drawer, Button }}
    >
      <SchemaComponent schema={schema} scope={{ showDrawer, onClose }} />
    </SchemaComponentProvider>
  );
}
```

这个例子讲述了怎么将组件转换为可 Schema 配置,虽然达成了某种效果,但并不是一个很好的示例。

- 一个 property 就是一个 Schema 节点,Drawer 的 Schema 由平行的两个 schema 节点组成,不利于管理;
- 需要额外的自定义 scope 支持 drawer 组件 visible 的状态管理,而且这里自定义的 scope 复用性差;
- footer 需要特殊处理。在 x-component-props 里加了个 footerSchema 参数。但这个 footerSchema 并不是一个常规的 schema 节点,因为不是在 properties 里,不利于后端 schema 存储的统一规划;
- 删除 drawer,需要删除两个 schema 节点;
- 后端如何输出 drawer 这部分的 schema 也非常不方便,因为 drawer 由平行的两个节点组成。

为了解决上述问题,从结构上做了一些改良:

```ts
{
  type: 'object',
  properties: {
    a1: {
      'x-component': 'Action',
      title: 'Open',
      properties: {
        d1: {
          'x-component': 'Action.Drawer',
          title: 'Drawer Title',
          properties: {
            c1: {
              'x-content': 'Hello',
            },
            f1: {
              'x-component': 'Action.Drawer.Footer',
              properties: {
                a1: {
                  'x-component': 'Action',
                  title: 'Close',
                  'x-component-props': {
                    useAction: '{{ useCloseAction }}',
                  },
                },
              },
            },
          },
        },
      },
    },
  },
}
```

以上示例,自定义了一个 Action 组件,用于配置按钮操作,又扩展了 Action.Drawer 和 Action.Drawer.Footer 两个特殊节点,分别用于配置抽屉弹框和抽屉的 footer。以上 schema 是个标准的组件树结构,层次十分分明。组件树的各个节点层次分明,schema 的增删改查就完全是标准流程了。

- 查询 Drawer 的 schema,只需要把 a1 节点的 json 全部输出就可以。
- 修改各个节点和子节点都可以单节点独立处理,逻辑一致。
- 删除时,直接删除不需要的节点就可以了。
- 有利于扩展,比如继续增加 Action.Modal、Action.Modal.Footer 两个节点用于配置对话框。

Action.Drawer 完整的例子如下:

```tsx
/**
 * title: Action.Drawer
 */
import React, { createContext, useContext, useMemo, useState } from 'react';
import { createPortal } from 'react-dom';
import { Button, Drawer } from 'antd';
import { SchemaComponentProvider, SchemaComponent } from '@nocobase/client';
import { observer, RecursionField, useField, useFieldSchema, ISchema } from '@formily/react';

const VisibleContext = createContext(null);

const useA = () => {
  return {
    async run() {},
  };
};

function useCloseAction() {
  const [, setVisible] = useContext(VisibleContext);
  return {
    async run() {
      setVisible(false);
    },
  };
}

const Action: any = observer((props: any) => {
  const { useAction = useA, onClick, ...others } = props;
  const [visible, setVisible] = useState(false);
  const schema = useFieldSchema();
  const field = useField();
  const { run } = useAction();
  return (
    <VisibleContext.Provider value={[visible, setVisible]}>
      <Button
        {...others}
        onClick={() => {
          onClick && onClick();
          setVisible(true);
          run();
        }}
      >
        {schema.title}
      </Button>
      <RecursionField basePath={field.address} schema={schema} onlyRenderProperties />
    </VisibleContext.Provider>
  );
});

Action.Drawer = observer((props: any) => {
  const [visible, setVisible] = useContext(VisibleContext);
  const schema = useFieldSchema();
  const field = useField();
  return (
    <>
      {createPortal(
        <Drawer
          title={schema.title}
          visible={visible}
          onClose={() => setVisible(false)}
          footer={
            <RecursionField
              basePath={field.address}
              schema={schema}
              onlyRenderProperties
              filterProperties={(s) => {
                return s['x-component'] === 'Action.Drawer.Footer';
              }}
            />
          }
        >
          <RecursionField
            basePath={field.address}
            schema={schema}
            onlyRenderProperties
            filterProperties={(s) => {
              return s['x-component'] !== 'Action.Drawer.Footer';
            }}
          />
        </Drawer>,
        document.body,
      )}
    </>
  );
});

Action.Drawer.Footer = observer((props: any) => {
  const field = useField();
  const schema = useFieldSchema();
  return <RecursionField basePath={field.address} schema={schema} onlyRenderProperties />;
});

const schema: ISchema = {
  type: 'object',
  properties: {
    a1: {
      'x-component': 'Action',
      'x-component-props': {
        type: 'primary',
      },
      title: 'Open',
      properties: {
        d1: {
          'x-component': 'Action.Drawer',
          title: 'Drawer Title',
          properties: {
            c1: {
              'x-content': 'Hello',
            },
            f1: {
              'x-component': 'Action.Drawer.Footer',
              properties: {
                a1: {
                  'x-component': 'Action',
                  title: 'Close',
                  'x-component-props': {
                    useAction: '{{ useCloseAction }}',
                  },
                },
              },
            },
          },
        },
      },
    },
  },
};

export default function App() {
  return (
    <SchemaComponentProvider components={{ Action }} scope={{ useCloseAction }}>
      <SchemaComponent schema={schema} />
    </SchemaComponentProvider>
  );
}
```

## RouteSwitch + SchemaComponent

当路由和组件都可以配置之后,可以进一步将二者结合,例子如下:

```tsx
/**
 * defaultShowCode: true
 * title: RouteSwitch + SchemaComponent
 */
import React, { useMemo, useEffect } from 'react';
import { Link, MemoryRouter as Router } from 'react-router-dom';
import {
  RouteRedirectProps,
  RouteSwitchProvider,
  RouteSwitch,
  useRoute,
  SchemaComponentProvider,
  SchemaComponent,
  useDesignable,
  useSchemaComponentContext,
} from '@nocobase/client';
import { Spin, Button } from 'antd';
import { observer, Schema } from '@formily/react';

const Hello = observer(({ name }) => {
  const { patch, remove } = useDesignable();
  return (
    <div>
      <h1>Hello {name}!</h1>
      <Button
        onClick={() => {
          patch('x-component-props.name', Math.random());
        }}
      >更新</Button>
    </div>
  )
});

const RouteSchemaComponent = (props) => {
  const route = useRoute();
  const { reset } = useSchemaComponentContext();
  useEffect(() => {
    reset();
  }, route.schema);
  return <SchemaComponent schema={route.schema}/>
}

const routes: RouteRedirectProps[] = [
  {
    type: 'route',
    path: '/',
    exact: true,
    component: 'RouteSchemaComponent',
    schema: {
      name: 'home',
      'x-component': 'Hello',
      'x-component-props': {
        name: 'Home',
      },
    },
  },
  {
    type: 'route',
    path: '/about',
    component: 'RouteSchemaComponent',
    schema: {
      name: 'home',
      'x-component': 'Hello',
      'x-component-props': {
        name: 'About',
      },
    },
  },
];

export default () => {
  return (
    <SchemaComponentProvider components={{ Hello }}>
      <RouteSwitchProvider components={{ RouteSchemaComponent }}>
        <Router initialEntries={['/']}>
          <Link to={'/'}>Home</Link>, <Link to={'/about'}>About</Link>
          <RouteSwitch routes={routes} />
        </Router>
      </RouteSwitchProvider>
    </SchemaComponentProvider>
  );
};
```

以上例子实现了路由和组件层面的配置化,在开发层面配置了两个组件:

- `<RouteSchemaComponent/>` 简易的可以在路由里配置 schema 的方案
- `<Hello/>` 自定义的 Schema 组件

为了让大家更加能感受到 Schema 组件的不一样之处,例子添加了一个简易的随机更新 `x-component-props.name` 值的按钮,当路由切换后,更新后的 name 并不会被重置。这也是 Schema 组件的 Designable 的能力,可以任意的动态更新 schema 配置,实时更新,实时渲染。

## Designable

SchemaComponent 基于 Formily 的 SchemaField,Formily 提供了 [Designable](https://github.com/alibaba/designable) 来解决 Schema 的配置问题,但是这套方案:

- 需要维护两套代码,以 antd 为例,需要同时维护 @formily/antd 和 @designable/formily-antd 两套代码
- 使用和设计分离,在设计器界面表单无法正常工作

另辟蹊径,NocoBase 构想了一种更为便捷的配置方案,使用和配置也可以兼顾,只需要维护一套代码。为此,提炼了一个简易的 `useDesignable()` Hook,可用于任意 Schema 组件中,动态配置 Schema,实时更新,实时渲染。

Hook API:

```ts
const {
  designable,         // 是否可以配置
  patch,              // 更新当前节点配置
  remove,             // 移除当前节点
  insertAdjacent,     // 在当前节点的相邻位置插入,四个位置:beforeBegin、afterBegin、beforeEnd、afterEnd
  insertBeforeBegin,  // 在当前节点的前面插入
  insertAfterBegin,   // 在当前节点的第一个子节点前面插入
  insertBeforeEnd,    // 在当前节点的最后一个子节点后面
  insertAfterEnd,     // 在当前节点的后面
} = useDesignable();

const schema = {
  'x-component': 'Hello',
};

// 在当前节点的前面插入
insertBeforeBegin(schema);
// 等同于
insertAdjacent('beforeBegin', schema);

// 在当前节点的第一个子节点前面插入
insertAfterBegin(schema);
// 等同于
insertAdjacent('afterBegin', schema);

// 在当前节点的最后一个子节点后面
insertBeforeEnd(schema);
// 等同于
insertAdjacent('beforeEnd', schema);

// 在当前节点的后面
insertAfterEnd(schema);
// 等同于
insertAdjacent('afterEnd', schema);
```

insertAdjacent 的几个插入的位置:

```ts
{
  properties: {
    // beforeBegin 在当前节点的前面插入
    node1: {
      properties: {
        // afterBegin 在当前节点的第一个子节点前面插入
        // ...
        // beforeEnd 在当前节点的最后一个子节点后面
      },
    },
    // afterEnd 在当前节点的后面
  },
}
```

并不是所有场景都能使用 hook,所以提供了 `createDesignable()` 方法(实际上 `useDesignable()` 也是基于它来实现):

```ts
const dn = createDesignable({
  current: schema,
});

dn.on('afterInsertAdjacent', (position, schema) => {

});

dn.insertAfterEnd(schema);
```

相关例子如下:

<code src="./src/schema-component/demos/demo1.tsx" />

insertAdjacent 操作不仅可以用于新增节点,也可以用于现有节点的位置移动,如以下拖拽排序的例子:

```tsx
/**
 * title: 拖拽排序
 */
import React from 'react';
import { uid } from '@formily/shared';
import { observer, useField, useFieldSchema } from '@formily/react';
import { DndContext, DragEndEvent, useDraggable, useDroppable } from '@dnd-kit/core';
import { SchemaComponent, SchemaComponentProvider, createDesignable, useDesignable } from '@nocobase/client';

const useDragEnd = () => {
  const { refresh } = useDesignable();

  return ({ active, over }: DragEndEvent) => {
    const activeSchema = active?.data?.current?.schema;
    const overSchema = over?.data?.current?.schema;

    if (!activeSchema || !overSchema) {
      return;
    }

    const dn = createDesignable({
      current: overSchema,
    });

    dn.on('afterInsertAdjacent', refresh);
    dn.insertBeforeBeginOrAfterEnd(activeSchema);
  };
};

const Page = observer((props) => {
  return <DndContext onDragEnd={useDragEnd()}>{props.children}</DndContext>;
});

function Draggable(props) {
  const { attributes, listeners, setNodeRef, transform } = useDraggable({
    id: props.id,
    data: props.data,
  });
  const style = transform
    ? {
        transform: `translate3d(${transform.x}px, ${transform.y}px, 0)`,
      }
    : undefined;

  return (
    <button ref={setNodeRef} style={style} {...listeners} {...attributes}>
      {props.children}
    </button>
  );
}

function Droppable(props) {
  const { isOver, setNodeRef } = useDroppable({
    id: props.id,
    data: props.data,
  });
  const style = {
    color: isOver ? 'green' : undefined,
  };

  return (
    <div ref={setNodeRef} style={style}>
      {props.children}
    </div>
  );
}

const Block = observer((props) => {
  const field = useField();
  const fieldSchema = useFieldSchema();
  return (
    <Droppable id={field.address.toString()} data={{ schema: fieldSchema }}>
      <div style={{ marginBottom: 20, padding: '20px', background: '#f1f1f1' }}>
        Block {fieldSchema.name}{' '}
        <Draggable id={field.address.toString()} data={{ schema: fieldSchema }}>
          Drag
        </Draggable>
      </div>
    </Droppable>
  );
});

export default function App() {
  return (
    <SchemaComponentProvider components={{ Page, Block }}>
      <SchemaComponent
        schema={{
          type: 'void',
          name: 'page',
          'x-component': 'Page',
          properties: {
            block1: {
              'x-component': 'Block',
            },
            block2: {
              'x-component': 'Block',
            },
            block3: {
              'x-component': 'Block',
            },
          },
        }}
      />
    </SchemaComponentProvider>
  );
}
```

## APIClient

在 WEB 应用里,客户端请求无处不在。为了便于客户端请求,提供的 API 有:

- APIClient:客户端 SDK
- APIClientProvider:提供 APIClient 实例的 Context,全局共享
- useRequest():需要结合 APIClientProvider 来使用
- useApiClient():获取到当前配置的 apiClient 实例

```tsx | pure
const api = new APIClient({
  request, // 将 request 抛出去,方便各种自定义适配
});
api.request(options);
api.resource(name);

<APIClientProvider apiClient={api}>
  {/* children */}
</APIClientProvider>
```

useRequest() 需要结合 APIClientProvider 一起使用,是对 ahooks 的 useRequest 的封装,支持 resource 请求。

```ts
const { data, loading } = useRequest();
```


## Providers

客户端的扩展以 Providers 的形式存在,提供各种可供组件使用的 Context,可全局也可以局部使用。上文我们已经介绍了核心的三个 Providers:

- RouteSwitchProvider,提供配置路由所需的 Layout 和 Template 组件
- SchemaComponentProvider,提供配置 Schema 所需的各种组件
- ApiClientProvider,提供客户端 SDK

除此之外,还有:

- Router,实际也是 Provider,提供 History 的 Context,对应的有 BrowserRouter,HashRouter、MemoryRouter、NativeRouter、StaticRouter 几种可选方案
- AntdConfigProvider,为 antd 组件提供统一的全局化配置
- I18nextProvider,提供国际化解决方案
- ACLProvider,提供权限配置,plugin-acl 的前端模块
- CollectionManagerProvider,提供全局的数据表配置,plugin-collection-manager 的前端模块
- SystemSettingsProvider,提供系统设置,plugin-system-settings 的前端模块
- 其他扩展

多个 Providers 需要嵌套使用:

```tsx | pure
<ApiClientProvider>
  <SchemaComponentProvider>
    <RouteSwitchProvider>
      {...}
    </RouteSwitchProvider>
  </SchemaComponentProvider>
</ApiClientProvider>
```

但是这样的方式不利于 Providers 的管理和扩展,为此提炼了 `compose()` 函数用于配置多个 providers,如下:

<code defaultShowCode="true" titile="compose" src="./src/application/demos/demo1/index.tsx"/>

## Application

上文例子的 Providers 还是差点意思,再进一步封装改造:

```tsx | pure
const app = new Application({});

app.use(ApiClientProvider);
app.use([SchemaComponentProvider, { components: { Hello } }]);
app.use((props) => {
  return (
    <div>
      <Link to={'/'}>Home</Link>,<Link to={'/about'}>About</Link>
      <RouteSwitch routes={routes} />
    </div>
  );
});

app.mount('#root');
// 等于
ReactDOM.render(<App/>, document.getElementById('root'));
```

对比 NocoBase Server Application 中间件的核心实现:

```ts
app.use((ctx, next) => {});
const ctx = this.createContext(req, res)
await compose(app.middleware)(ctx);
await respond(ctx);
```

通过 app.use() 方法注册各种中间件插件,最后由 compose 来处理中间件,如果有需要也可以往 app.context 里添加各种东西待用。前端在处理 Provider 时也是类似的机制,这也是为什么客户端的扩展是以 Provider 的形式存在的原因。

从例子来看,以 Provider 的形式扩展是个不错的方案,但是还有两个问题没有解决:

- Provider 的顺序怎么处理
- 如何动态的加载前端模块

未完待续...