快速开始

技术栈：

vue >= 3.4
FormMaking 3.8.2
ElementPlus

环境：

NodeJS >= 20

项目集成

su-ui 以 git 仓库地址类型 npm 包的形式提供，提供了一系列的组件，可以帮助用户快速搭建页面。具体使用可以先安装 su-ui，然后引入对应的组件，使用组件的 api

在控制台安装

代码仓库包括两个，分别是 su-ui-prod 和 su-ui，默认安装 su-ui-prod 主分支最新稳定版本，但建议在集成开发之后修改安装路径，使用指定版本，以避免依赖版本升级为开发者造成的意外情况，导致时间和精力的浪费

yarn add git+https://codeup.aliyun.com/5f0573846a575d7f236616f1/suconnect/su-ui-prod.git;

安装指定仓库的指定版本/指定分支，以${var}表示需要替换的部分

yarn add git+https://codeup.aliyun.com/5f0573846a575d7f236616f1/suconnect/${仓库名}.git#${版本名称/分支名称};

附加文档

该部分文档为集成过程中常见的问题，按理不属本文档范围，特此解释以减少开发者时间精力成本的浪费

saber 依赖安装

项目根目录下找到 .npmrc 文件，如没有自行新建，对应资源令牌可以进入 BladeX 官网获取

@saber:registry=https://center.javablade.com/api/packages/blade/npm/
//center.javablade.com/api/packages/blade/npm/:_authToken=如何配置请见BladeX开发手册 1.3.0配置资源令牌 章节

加密密钥

前端项目 saber <= 4.0.1 时无需关注该项配置

在对应路径找到指定文件，该公共密钥由后端同学项目生成，请向后端同学获取并配置

// src/config/website.js

/**
 * 全局配置文件
 */
export default {
  //oauth2配置
  oauth2: {
    // 使用后端工程 @org.springblade.test.Sm2KeyGenerator 获取
    publicKey: "请配置国密sm2公钥",
  },
};

集成

// 引入
import {
  SuCrud, // 业务表格组件
  MakingForm, // 设计器组件
  GenerateForm, // 生成器组件
  SuPage, // 页面渲染器组件
  db, // db链式请求工具
  GlobalVariable, // 全局变量状态池
} from "su-ui";
import "su-ui/dist/style.css";

// 根据需要自行安装，该依赖为低码内置富文本编辑器组件
import { QuillEditor } from "@vueup/vue-quill";
import "@vueup/vue-quill/dist/vue-quill.snow.css";

// 将db命令注册到全局
window.db = db;

// 注册组件
app.use(SuCrud, { locale: messages[language] });
app.use(MakingForm, { locale: "zh-cn", i18n });
app.use(GenerateForm, { locale: "zh-cn", i18n });

修改 i18n 配置

// src/lang/index.js
export default createI18n({
  legacy: false, // 增加 legacy 配置项
  locale: language,
  messages,
});

添加页面

src/views/sucode
├─ design
│ └─ index.vue
├─ su-page
│ └─ index.vue

html

<!-- src/views/sucode/design/index.vue -->
<template>
  <fm-making-form
    :class="$style.Component"
    ref="makingForm"
    preview
    generate-code
    generate-json
    upload
    clearable
    :pageRoutes
    :appId="$route.params.appId"
    :handleRemoveMenu="remove"
  />
</template>

<script setup>
  import { remove } from "@/api/system/menu";

  const pageRoutes = {
    appManage: "/",
  };
</script>

<style lang="scss" module>
  .Component {
    height: 100%;
  }
</style>

html

<!-- src/views/sucode/su-page/index.vue -->
<template>
  <basic-container>
    <SuPage :permission />
  </basic-container>
</template>

<script setup>
  import { computed } from "vue";
  import { useStore } from "vuex";
  import { SuPage } from "su-ui";

  const store = useStore();

  const permission = computed(() => store.getters.permission);
</script>

注册路由

// src/router/views/index.js
// 在默认导出中加入以下内容
export default [
  {
    // 该路径指向设计器组件页面，id 为低码应用id
    path: "/sucode/design/:appId",
    meta: {
      keepAlive: false,
      isTab: false,
      isAuth: true,
    },
    component: () =>
      import(/* webpackChunkName: "views" */ "@/views/sucode/design/index.vue"),
  },
  {
    path: "/sucode",
    component: Layout,
    children: [
      {
        // 页面渲染器组件，进入该路由以渲染指定id的设计完成的页面
        path: "page/:id",
        name: "su-page",
        meta: {
          keepAlive: false,
          isTab: true,
          isAuth: true,
        },
        component: () =>
          import(
            /* webpackChunkName: "views" */ "@/views/sucode/su-page/index.vue"
          ),
      },
    ],
  },
];

处理页面标签名称

// src/page/index/sidebar/sidebarItem.vue
// 修改组件的 open 方法为以下内容
export default {
  methods: {
    open(item) {
      this.$router.push({
        path: item[this.pathKey],
        query: { ...item[this.queryKey], name: item.name },
      });
    },
  },
};

项目结构概览

项目的目录结构清晰地展示了各个模块和组件的组织方式。以下是对主要目录和文件的详细介绍：

dist: 该目录通常用于存放项目的构建输出文件。
src: 源代码目录，包含项目的核心代码。
index.html: HTML 入口文件。
package.json: 项目配置文件。
vite.config.js: Vite 配置文件。

源代码目录

main.js: 主文件。
App.vue: 应用入口组件。
views: 视图目录。
- index.vue: 视图入口文件。
router: 路由配置。
- index.js: 路由配置文件。

SuUI

index.js: 入口文件。
apis: 存放与 API 相关的文件，如 history.js。
assets: 存放静态资源文件。
components: 存放项目的各个组件。
iconfont: 图标字体文件。
lang: 语言文件。
styles: 样式文件。
util: 工具文件。

DB 命令

src/libs/db/
├─ axios.js
├─ config.js
├─ index.js
└─ tool.js

引入&使用

import { db } from "db";

// 新增
db.collection("demo_table").add({
  name: "demo_name",
});

// 修改
db.collection("demo_table")
  .doc("1805228911439687682")
  .update({ name: "demo_name_update" });

// 删除
db.collection("demo_table")
  .where({
    id: "1805228911439687682",
  })
  .remove();

// 查询
db.collection("demo_table")
  .where({
    id: "1805228911439687682",
  })
  .get();

// 参数
// {
//   getTree: true,
//   getCount: true,
//   getDict: true,
// };

// 1、getTree:true，如果查询的表是树结构返回树结构JSON
// 2、getCount:true，同时返回纪录总数
// 3、getDict:true, 同时返回查询字段的字典值

表格样式自定义

项目中的表格组件支持高度定制，开发者可以通过 styles/ 目录中的 SCSS 文件，轻松调整表格的样式，确保其与项目设计风格一致。

src/components/widgets/crud
├─ index.js
├─ src
├─ custom-column
│  ├─ custom-column-filter.js
│  └─ index.vue
├─ search
│  ├─ index.vue
│  ├─ week-range.vue
│  └─ year-range.vue

设计器 API-MakingForm

设计器提供了丰富的 API，开发者可以通过这些 API 自定义组件的行为，动态设置表单项，实时监听用户操作，满足各种复杂场景下的表单需求。低代码表单设计器，支持通过拖拽组件快速生成表单，具备页面布局、表单校验、数据回显等功能，简化复杂表单的设计与管理。

FormMaking 文档地址

src/components
├─ AsideLeft
├─ AsideRight
├─ ContainerHeader
├─ ContainermMain
├─ states
│  ├─ current.js
│  ├─ variable.js
│  └─ version.js
├─ ConfigGenerateForm.vue
├─ Container.vue // 入口文件
├─ Outline.vue
├─ PreviewDialog.vue
└─ componentsConfig.js

设计器 API-GenerateForm

低代码表单渲染器，通过配置数据驱动页面渲染，支持自动化表单校验和数据回显，适应多种业务场景的页面展示需求。

FormMaking 文档地址

src/components
├─ GenerateBoxItem.vue
├─ GenerateCard.vue
├─ GenerateColItem.vue
├─ GenerateCollapse.vue
├─ GenerateDialog.vue
├─ GenerateElementItem.vue
├─ GenerateFlex.vue
├─ GenerateForm.vue  // 入口文件
├─ GenerateFormBox.vue
├─ ...

设计器 API-SuPage

基于 GenerateForm 的页面渲染器，进行了功能扩展与优化，提供更高级的页面渲染功能，可以方便快速的渲染低代码设计的页面。

src/components/SuPage
├─ index.js
└─ index.vue

自定义组件开发

您可以通过自定义组件的方式为业务场景提供灵活的解决方案。自定义组件采用模块化设计，方便开发者根据业务需求进行扩展与集成。

项目中的 src/components/widgets 目录为开发者提供了创建自定义组件的支持。开发者可以根据业务需求，设计新的 Vue 组件，并将其集成到表单设计器中，提升表单的多样性与灵活性。

目录说明

src/components/widgets
├─ demo-component        // 组件目录
│  ├─ index.js        // 组件的入口文件，用于注册和导出组件
│  ├─ index.vue       // 组件的渲染代码，包含组件的主要逻辑与样式
│  └─ panel.vue       // 组件的配置面板代码，用于管理和编辑组件的配置

index.js：组件的入口文件，负责注册组件和配置组件的默认属性、事件以及相关设置。该文件包含了组件的配置项、组件注册、以及配置面板的引入等内容。
index.vue：组件的核心逻辑和渲染代码。在这里，您可以定义组件的 UI 结构、交互逻辑和样式。它包含了与组件展示相关的一切内容。
panel.vue：这是配置面板文件，提供组件的自定义配置功能。开发者可以在此定义组件的属性、样式和行为，使用户在使用时能够进行个性化设置。

组件注册

组件的注册通过在 index.js 文件中导出 panel、component 和 config 来实现。其中，component 和 config 是必须的，而 panel 是可选的。

export { default as panel } from "./panel.vue";
export { default as component } from "./index.vue";

export const config = {...};

组件配置: index.js > config

定义组件的配置信息，包括组件名称、标识符、所属分组等基础信息。同时还包含组件的默认值和自定义属性。

export const config = {
  name: "图标按钮", // 组件名称，展示在表单设计器中的名称
  el: "su-fm-icon-button", // 组件的唯一标识符，用于渲染时的引用
  mainIcon: "图标按钮", // 组件主图标，用于表示按钮的视觉效果
  group: "Buttons", // 组件所属的分组，用于在设计器中进行分类
  groupSort: 3, // 组件在分组中的排序权重，决定展示顺序
  enableScopes: ["Component", "Table", "Page"], // 组件可用的场景范围，例如页面或表格
  // deactivate: true,             // 是否禁用组件，默认注释掉表示组件启用
  options: {},
  events: {},
};

组件配置: index.js > config.options

组件的配置项。开发者可以通过该配置自定义组件的外观和行为，例如是否隐藏、是否必填等。customProps 提供了自定义属性，支持更灵活的组件功能。

export const config = {
  options: {
    defaultValue: false, // 组件的默认值
    customClass: "", // 用户自定义的 CSS 类名
    labelWidth: 100, // 标签宽度
    isLabelWidth: false, // 是否启用标签宽度
    hidden: false, // 组件是否隐藏
    dataBind: true, // 是否绑定数据
    required: false, // 是否为必填项
    validator: "", // 验证规则
    hideLabel: true, // 是否隐藏标签
    customProps: {}, // 自定义属性
  },
};

组件配置: index.js > config.events

组件的 events 属性用于定义开发者自定义的事件列表。

export const config = {
  events: {
    onClick: "", // 自定义点击事件的处理函数，由开发者实现
    onChange: "", // 自定义值变化时的处理函数，由开发者实现
  },
};

开发者可以通过在相应的事件处理函数中编写逻辑，实现各种自定义交互行为。
所有事件都由开发者根据具体业务需求自行配置，组件没有预设的默认事件。
通过灵活配置事件处理函数，开发者可以在组件交互时动态处理相关逻辑，提升组件的定制化能力。

组件配置: index.vue

index.vue 文件是组件的核心渲染逻辑，负责组件的外观展示和交互行为。

html

<template>
  <div>{{ model.options.defaultValue }}</div>
</template>

<script setup>
  const widget = inject("widget");
  const model = defineModel();
</script>

组件配置: panel.vue

panel.vue 文件是组件的配置面板，负责提供用户界面对组件的自定义配置功能。在配置面板中，用户可以根据具体需求修改组件的属性。通过配置面板的设置，组件的表现和交互可以灵活调整，提升了组件的可定制性。

html

<template>
  <el-form-item label="默认值">
    <el-input v-model="model.options.defaultValue" />
  </el-form-item>
</template>

<script setup>
  const widget = inject("widget");
  const model = defineModel();
</script>

快速开始 ​

技术栈： ​

环境： ​

项目集成 ​

在控制台安装 ​

附加文档 ​

saber 依赖安装 ​

加密密钥 ​

集成 ​

修改 i18n 配置 ​

添加页面 ​

注册路由 ​

处理页面标签名称 ​

项目结构概览 ​

源代码目录 ​

SuUI ​

DB 命令 ​

表格样式自定义 ​

设计器 API-MakingForm ​

设计器 API-GenerateForm ​

设计器 API-SuPage ​

自定义组件开发 ​

目录说明 ​

组件注册 ​

组件配置: index.js > config ​

组件配置: index.js > config.options ​

组件配置: index.js > config.events ​

组件配置: index.vue ​

组件配置: panel.vue ​

快速开始

技术栈：

环境：

项目集成

在控制台安装

附加文档

saber 依赖安装

加密密钥

集成

修改 i18n 配置

添加页面

注册路由

处理页面标签名称

项目结构概览

源代码目录

SuUI

DB 命令

表格样式自定义

设计器 API-MakingForm

设计器 API-GenerateForm

设计器 API-SuPage

自定义组件开发

目录说明

组件注册

组件配置: index.js > config

组件配置: index.js > config.options

组件配置: index.js > config.events

组件配置: index.vue

组件配置: panel.vue