nocobase/packages/core/client/src/schema-settings/index.md

group

group
title order Client 1

SchemaSettings

API

new SchemaSettings(options)

创建一个 Schema 配置实例。

参数类型

interface SchemaSettingOptions<T = {}>{
  name: string;
  Component?: ComponentType<T>;
  componentProps?: T;
  style?: React.CSSProperties;
  items: SchemaSettingsItemType[];
}

参数详细信息

• name

用于标识 Schema 配置的名称。

会用在 schema 中的 x-settings 配置值以及读取 schema 的值会传给 useSchemaSettingRender() 的第一个参数。

const mySettings = new SchemaSettings({
   //  定义 name
  name: 'MySettings',
})

• Component、componentProps & style

Component 默认是一个 Icon，如果需要定制化，可以为一个 React 组件。

import { SettingOutlined } from '@ant-design/icons';
const mySettings = new SchemaSettings({
  Component: () => <SettingOutlined style={{ cursor: 'pointer' }} />
})

如果你使用的是一个公共的组件，不同的 Settings 有定制化的诉求，那么你可以使用 componentProps 和 style。

import { Button } from '@ant-design/icons';
const mySettings = new SchemaSettings({
  Component: Button,
  componentProps: {
    type: 'primary'
  }
})

当然也可以这样是使用。

const mySettings = new SchemaSettings({
  Component: () => <Button type="primary" />
})

• items

items 的类型为 SchemaSettingsItemType[]，具体如下：

export type SchemaSettingsItemType<T = {}> = {
  name: string;
  type?: string;
  sort?: number;
  Component?: string | ComponentType<T>;
  componentProps?: T;
  useComponentProps?: () => T;
  useVisible?: () => boolean;
  children?: SchemaSettingsItemType[];
  [index]: any;
};

最简单的配置如下：

const mySettings = new SchemaSettings({
  items: [
    {
      name: 'edit',
      Component: MyComponent,
    },
  ],
})

type 内置类型：为了更简单的使用，我们提供了一些内置的类型，可以直接使用。

const mySettings = new SchemaSettings({
  items: [
    {
      name: 'edit',
      type: 'modal', // 弹窗
    },
  ],
})

其底层对应的是 SchemaSettingsModalItem 组件。具体内置类型和对应的组件如下：

type	Component	效果
item	SchemaSettingsItem	文本
itemGroup	SchemaSettingsItemGroup	分组，同 Menu 组件的 type: 'group'
subMenu	SchemaSettingsSubMenu	子菜单，同 Menu 组件的子菜单
divider	SchemaSettingsDivider	分割线，同 Menu 组件的 type: 'divider'
remove	SchemaSettingsRemove	删除，用于删除一个区块
select	SchemaSettingsSelectItem	下拉选择
cascader	SchemaSettingsCascaderItem	级联选择
switch	SchemaSettingsSwitchItem	开关
popup	SchemaSettingsPopupItem	弹出层
actionModal	SchemaSettingsActionModalItem	操作弹窗
modal	SchemaSettingsModalItem	弹窗

componentProps 和 useComponentProps：用于定制化内置组件的 props，两者的区别是后面的可以使用一些 hooks。

const mySettings = new SchemaSettings({
  items: [
    {
      name: 'allowAddNew',
      type: 'switch',
      useComponentProps() {
        // 可以在这里使用 hooks
        const { t } = useTranslation();
        const field = useField<Field>();
        return {
          title: t('Allow add new data'),
          checked: fieldSchema['x-add-new'] as boolean,
        }
      }
    },
    {
      name: 'remove',
      type: 'remove',
      componentProps: {
        removeParentsIfNoChildren: true
      },
    },
  ],
})

useVisible 则是控制组件是否显示，可以使用 hooks。

const mySettings = new SchemaSettings({
  items: [
    {
      name: 'upload',
      type: 'switch',
      useVisible() {
        // 这里使用了 hooks
        const { form } = useFormBlockContext();
        return !!form?.readPretty;
      }
    },
  ],
})

schemaSetting 实例方法

schemaSetting 实例用于对 items 进行增删改查。

schemaSetting.get()

用于获取一个 item，并且可以通过 . 获取子 item。

• 类型

interface SchemaSettings {
  get(name: string): SchemaSettingsItemType | undefined;
}

• 示例

const mySchemaSettings = new SchemaSettings({
  name: 'MySchemaSettings',
  items: [
    {
      name: 'demo',
      type: 'itemGroup',
      children: [
        {
          name: 'child1',
          type: 'modal',
        },
      ],
    },
  ],
});

// 获取 item
const demo = mySchemaSettings.get('demo');

// 获取子 item
const child1 = mySchemaSettings.get('demo.child1');

schemaSetting.remove()

用于删除一个 item。

• 类型

interface SchemaSettings {
  remove(name: string): void;
}

• 示例

mySchemaSettings.remove('demo2');

mySchemaSettings.remove('demo.child2');

schemaSetting.add()

用于新增一个 item。

• 类型

interface SchemaSettings {
  add(name: string, item: Omit<SchemaSettingsItemType, 'name'>): void;
}

• 示例

mySchemaSettings.add('demo2', { type: 'switch' });

mySchemaSettings.add('demo.child2', { type: 'actionModel' });

app.schemaSettingsManager 管理器

app.schemaSettingsManager.getAll()

获取所有的 schemaSetting 实例。

• 类型

interface SchemaSettingsManager {
  getAll(): SchemaSettings[];
}

• 示例

import { Plugin } from '@nocobase/plugin'
class MyPlugin extends Plugin {
  load() {
    const allSchemaSettings = this.app.schemaSettingsManager.getAll();
  }
}

app.schemaSettingsManager.get()

用于获取一个 schemaSetting 实例，

• 类型

interface SchemaSettingsManager {
  get(name: string): SchemaSettings | undefined;
}

• 参数说明

name 为 new SchemaSettings(options) 中的 name。

• 示例

import { Plugin } from '@nocobase/plugin'
class MyPlugin extends Plugin {
  load() {
    const mySchemaSettings = this.app.schemaSettingsManager.get('MySchemaSettings');
  }
}

app.schemaSettingsManager.remove()

用于删除一个 schemaSetting 实例。

• 类型

interface SchemaSettingsManager {
  remove(name: string): void;
}

• 参数说明

name 为 new SchemaSettings(options) 中的 name。

• 示例

import { Plugin } from '@nocobase/plugin'
class MyPlugin extends Plugin {
  load() {
    this.app.schemaSettingsManager.remove('MySchemaSettings');
  }
}

app.schemaSettingsManager.add()

新增一个 schemaSetting 实例。

• 类型

interface SchemaSettingsManager {
  add(schemaSetting: SchemaSettings): void;
}

• 示例

import { Plugin } from '@nocobase/plugin'

const mySchemaSettings = new SchemaSettings({
  name: 'MySchemaSettings',
  items: [],
});

class MyPlugin extends Plugin {
  load() {
    this.app.schemaSettingsManager.add(mySchemaSettings);
  }
}

app.schemaSettingsManager.has()

判断是否存在一个 schemaSetting 实例。

• 类型

interface SchemaSettingsManager {
  has(name: string): boolean;
}

• 示例

import { Plugin } from '@nocobase/plugin'

class MyPlugin extends Plugin {
  load() {
    const hasMySchemaSettings = this.app.schemaSettingsManager.has('MySchemaSettings');
  }
}

Hooks

useSchemaSettingsRender()

用于渲染 schemaSetting 实例。

• 类型

interface SchemaSettingOptions<T = {}>{
  name: string;
  Component?: ComponentType<T>;
  componentProps?: T;
  style?: React.CSSProperties;
  items: SchemaSettingsItemType[];
}

interface SchemaSettingsRenderResult {
  render: (options?: SchemaSettingOptions) => React.ReactElement;
  exists: boolean;
}

function useSchemaSettingsRender(
  name: string,
  options?: SchemaSettingsRenderOptions,
): SchemaSettingsRenderResult;

• 示例

const MyDesigner = (props) => {
  const { modalTip } = props;

  const { render, exists } = useSchemaSettingsRender(fieldSchema['x-settings'], fieldSchema['x-settings-props']);

  return <div>{render()}</div>
}

useSchemaSettings()

获取 schemaSetting 上下文数据。

上下文数据包含了 schemaSetting 实例化时的 options 以及调用 useSchemaSettingsRender() 时传入的 options。

• 类型

interface UseSchemaSettingsResult<T> extends SchemaSettingOptions {
  dn?: Designable;
  field?: GeneralField;
  fieldSchema?: Schema;
}

function useSchemaSettings(): UseSchemaSettingsResult;

• 示例

const { dn } = useSchemaSettings();

useSchemaSettingsItem()

用于获取一个 item 的数据。

• 类型

export type SchemaSettingsItemType<T = {}> = {
  name: string;
  type?: string;
  sort?: number;
  Component?: string | ComponentType<T>;
  componentProps?: T;
  useComponentProps?: () => T;
  useVisible?: () => boolean;
  children?: SchemaSettingsItemType[];
  [index]: any;
};

function useSchemaSettingsItem(): SchemaSettingsItemType;

• 示例

const { name } = useSchemaSettingsItem();

Components

TODO: 文档待补充

Examples

基础用法

自定义按钮

内置类型

NocoBase 提供了几个内置的组件，可以直接使用。

Schema

动态显示、隐藏

Designer 上下文