FcDesigner Pro

Appearance

修改组件默认规则与配置项 ​

内置组件（如 input、select、upload 等）在设计器里“拖入后生成什么默认 rule、右侧属性面板显示哪些配置项”，本质都由 DragRule（拖拽规则） 决定。本文说明如何在源码层二开：修改内置组件的默认规则（rule） 与 右侧 props 配置项的渲染规则（props 面板）。

如果你还不熟悉 DragRule 的整体链路，建议先阅读：添加新组件（里面对 DragRule、渲染器注册、设计态注册的分层解释最完整）。

你要改哪些地方？ ​

按影响范围从小到大排序，通常有两类改法：

  • 仅改某个内置组件

    • 改默认 rule：编辑 src/config/rule/<name>.js 中的 rule() 方法返回值
    • 改右侧 props 面板：编辑同文件中的 props() 方法返回的配置项数组

  • 改所有组件共享的基础面板（影响全局）

    • 改字段/标题/提示等：src/config/base/field.js
    • 改表单级配置：src/config/base/form.js
    • 改样式面板：src/config/base/style.js
    • 改校验面板：src/config/base/validate.js
    • 改高级（computed）面板：src/config/base/advanced.js

重要提醒

修改默认 rule（DragRule.rule()）只对“新拖入组件”生效。已保存的历史规则不会自动补齐/回填，需要单独做迁移（见下文“兼容性与迁移说明”）。

DragRule 结构速览 ​

一个典型的内置组件 DragRule（以 input 为例）通常长这样：

js
export default {
  menu: 'main',
  icon: 'icon-input',
  label: '输入框',
  name: 'input',              // 关键：对应 rule.type
  input: true,
  event: ['blur', 'focus'],
  validate: ['string', 'email'],

  // 1) 默认规则：拖入后生成的 rule
  rule({ t }) {
    return {
      type: 'input',
      field: uniqueId(),
      title: t('com.input.name'),
      info: '',
      $required: false,
      props: {},
    };
  },

  // 2) 右侧 props 面板：显示哪些配置项、怎么渲染
  props(_, { t }) {
    return localeProps(t, 'input.props', [
      { type: 'switch', field: 'disabled' },
      { type: 'input', field: 'placeholder' },
      // ...
    ]);
  },
};

你这篇文档要做的改动，基本都集中在 rule() 与 props() 两个方法里。

修改内置组件的默认规则 ​

默认规则的核心目标是：让“新拖入的组件”带着你想要的初始配置，例如默认 placeholder、默认 clearable: true、默认上传 action、默认 options 等。

1. 定位 DragRule 文件 ​

内置组件规则都在：

  • src/config/rule/<name>.js

其中 <name> 通常等于 DragRule 的 name（也就是 rule.type）。

例如：

  • 输入框：src/config/rule/input.js
  • 选择器：src/config/rule/select.js
  • 上传：src/config/rule/upload.js

2. 修改 rule() 返回的默认 rule ​

以 input 为例：如果你想让新拖入的输入框默认带占位和可清空按钮，可以这样改：

js
rule({ t }) {
  return {
    type: name,
    field: uniqueId(),
    title: t('com.input.name'),
    info: '',
    $required: false,
    props: {
      placeholder: t('com.input.props.placeholder') || '请输入',
      clearable: true,
    },
  };
}

以 upload 为例：很多项目希望默认 listType、action、onSuccess 都有“可直接跑通”的值，则在 rule() 里设置 props 默认值即可（项目内 upload 就是这种写法）。

建议

  • 默认值尽量放在 rule().props 里，让“默认行为”与“右侧 props 面板修改的字段”保持一致。
  • 如果某个默认值会影响渲染结构（例如 select 的 options、layout 的 children），建议同时检查该组件是否存在 watch、loadRule/parseRule 等特殊处理逻辑，避免默认值与转换逻辑冲突。

修改右侧配置项 ​

props() 返回的是一个“配置表单的规则数组”，每一项描述一个配置控件如何渲染、绑定到哪个字段、有哪些选项/提示/校验等。

1. field 的绑定规则（非常关键） ​

在 DragRule.props() 中：

  • 默认绑定目标是 rule.props
    例如 { field: 'disabled' } 表示绑定到 rule.props.disabled。

在 base/*.js（通用面板）里：

  • field 往往直接指向 rule 顶层字段 或一个 嵌套路径
    例如 field: 'field'（rule.field），以及 field: 'wrap>style>marginBottom' 这种路径写法。
  • 也存在使用点号路径的情况（例如高级面板中 field: 'props.disabled'），用于直接定位到 rule.props.disabled。

实战建议：在 rule/*.js 里优先用“相对 props”的写法（disabled、placeholder）；在 base/*.js 里用“完整路径”的写法（wrap>style>... / props.xxx）。

2. 常见配置项结构（你能改什么） ​

一个配置项通常包含这些字段（按常见程度排序）：

  • type：配置控件类型（如 switch、input、select、inputNumber、FnInput、TableOptions 等）
  • field：绑定字段（见上文）
  • title：标题（多语言时通常由 localeProps 自动补）
  • value：默认值（仅对“配置面板首次生成/回填”有意义，是否生效依赖设计器实现）
  • props：传给该配置控件组件的参数（例如 slider 的 min/max）
  • options：select/radio 等组件的选项（常配合 localeOptions）
  • warning：警告/提示文案
  • children：复杂配置项的子项（例如 ConfigItem 容器包裹）

3. 示例：给 input 增加一个右侧配置项 ​

假设你想在 input 的 props 面板里新增 showPassword（仅当 type=password 时有意义，这里先给通用开关示例），在 src/config/rule/input.js 的 props() 数组里追加：

js
props(_, { t }) {
  return localeProps(t, name + '.props', [
    { type: 'switch', field: 'disabled' },
    { type: 'switch', field: 'readonly' },
    // ...原有项

    // 新增：显示密码切换按钮（业务自定义示例）
    { type: 'switch', field: 'showPassword' },
  ]);
}

如果你需要一个带选项的配置项（例如 input 的 type），参考项目内写法：

js
{
  type: 'select',
  field: 'type',
  options: localeOptions(t, [
    { label: 'text', value: 'text' },
    { label: 'number', value: 'number' },
    { label: 'date', value: 'date' },
  ]),
}

4. 示例：调整 select 的 options / 远程配置能力 ​

select 是典型的“既要 options，又可能要 remoteMethod”的组件。项目内已经提供了：

  • makeOptionsRule(t, 'options')：生成 options 配置项
  • FnInput + getInjectArg(t)：生成函数输入配置（remoteMethod）

你可以用同样方式“改默认 options 结构”或“新增/删减远程相关项”：

js
return localeProps(t, name + '.props', [
  makeOptionsRule(t, 'options'),
  { type: 'switch', field: 'filterable' },
  { type: 'switch', field: 'remote' },
  {
    type: 'FnInput',
    field: 'remoteMethod',
    props: {
      body: true,
      button: true,
      fnx: true,
      name: 'remoteMethod',
      args: [getInjectArg(t)],
    },
  },
]);

常见坑

右侧配置项“加了但没效果”，最常见原因是：

  • 配置项 field 写错（你以为写到了 rule.props.xxx，但实际绑定到别处）
  • 运行态组件并没有消费这个 prop（比如组件内部没读 props.showPassword）
  • 多语言 key 缺失导致标题/提示为空（尤其当项目强制依赖 localeProps 时）

修改通用基础配置 ​

如果你要修改的是“所有组件都共有的面板项”，例如：

  • 字段 ID、标题、提示
  • form-item 布局（labelWidth、span、margin）
  • 全局样式项（id/class/style）
  • 全局校验/高级 computed 项

那么应该改 src/config/base/*.js。

示例：在“样式”面板增加一个全局配置项 ​

src/config/base/style.js 本质上返回一组配置项（示例中已有 id/class/style）。你可以在这里新增你的全局配置组件/输入项。

示例：在“表单配置”里增加一个可视化配置块 ​

src/config/base/form.js 里大量使用 ConfigItem 容器来组织复杂配置，并用 update() 回调把“是否已配置”的信息写回 UI（例如给配置块显示 info）。

如果你想新增一个“高级配置块”，可以复用相同模式：

  • 用 ConfigItem 包裹
  • 内部 children 用 StyleConfig / TableOptions / FnConfig 等配置组件
  • 需要“已配置提示”时，参考 updateConfigInfo(...) 写法

常见问题排查 ​

1. 改了 rule() 但拖入还是旧默认值 ​

  • 现象：新拖入组件仍然是旧的默认 props
  • 排查：
    • 是否改错了文件（确认 src/config/rule/<name>.js 与 name 匹配）
    • 是否存在多入口/多构建目标，实际运行引用的是另一份配置目录
    • 是否有缓存产物未刷新（重启 dev、清缓存）

2. 右侧配置项显示了，但改动不影响组件 ​

  • 最可能原因：运行态组件未消费对应 prop，或该 prop 名在 UI 框架里不同（例如 Element Plus 与 AntDV 的 prop 命名差异）
  • 排查：
    • 对照 UI 组件文档确认 prop 名是否正确
    • 在运行态渲染组件中查找该 prop 是否被读取/透传

3. 历史表单不生效 ​

  • 原因：默认 rule 只对新拖入生效
  • 处理：见下文“兼容性与迁移说明”

兼容性与迁移说明 ​

当你修改了默认 rule 或新增了 props 字段：

  • 对新拖入组件：立即生效
  • 对历史保存规则：不会自动补齐字段（仍然是旧数据）

附录：相关文件路径速查 ​

  • 内置 DragRule 列表入口：src/config/index.js
  • 内置组件 DragRule 目录：src/config/rule/
  • 基础面板配置（全局）：src/config/base/
  • 左侧面板菜单分组：src/config/menu.js