@jxyszb/jxy-form-designer

@jxyszb/jxy-form-designer

A schema-driven form designer and runtime for Vue 3, Pinia, and Element Plus.

Features

• Drag-and-drop form design with fields, titles, grids, and scoped repeat sections.
• Runtime rendering from JSON Schema.
• Static, dictionary, API, and on-demand template-download data sources.
• Validation, field reactions, import/export, and preview.
• Host adapters for request clients, file upload, rich-text editors, and custom fields.

Upload-button scoped slots, compact repeat layouts and decimal display behavior: Integration and examples.

Installation

npm install @jxyszb/jxy-form-designer

Peer dependencies:

vue >=3.2.45 <4
pinia >=2.0.22 <3
element-plus >=2.7.0 <3

Setup

import { createApp } from 'vue';
import { createPinia } from 'pinia';
import ElementPlus from 'element-plus';
import 'element-plus/dist/index.css';
import '@jxyszb/jxy-form-designer/style.css';
import { createJxyFormPlugin } from '@jxyszb/jxy-form-designer';

const app = createApp(App);
app.use(createPinia());
app.use(ElementPlus);
app.use(createJxyFormPlugin());
app.mount('#app');

Dynamic data sources, uploads, and rich-text fields can use host adapters:

app.use(createJxyFormPlugin({
  request: requestClient,
  // JXY framework example: keep the method receiver so its internal this remains valid.
  downloadFile: (url, params, fileName) =>
    app.config.globalProperties.$custom.downFile(params, fileName, url),
  components: {
    fileUpload: FileUpload,
    editor: RichTextEditor
  }
}));

Usage

<script setup>
import { ref } from 'vue';
import {
  JXYFormDesigner,
  JXYFormRuntime,
  createDefaultSchema
} from '@jxyszb/jxy-form-designer';

const designerRef = ref();
const schema = ref(createDefaultSchema());
const formData = ref({});

function handleSaveDraft({ schema: draftSchema }) {
  localStorage.setItem('business-form-draft', JSON.stringify(draftSchema));
}

async function handlePublish({ schema: publishedSchema, warnings }) {
  await publishFormSchema(publishedSchema);
  console.log('publish warnings', warnings);
}

function handlePublishInvalid({ errors }) {
  console.warn('schema cannot be published', errors);
}
</script>

<template>
  <JXYFormDesigner
    ref="designerRef"
    save-draft-button-label="保存草稿"
    :show-save-draft-button="true"
    publish-button-label="发布"
    :show-publish-button="true"
    @save-draft="handleSaveDraft"
    @publish="handlePublish"
    @publish-invalid="handlePublishInvalid"
  />
  <JXYFormRuntime v-model="formData" :schema="schema" />
</template>

Designer emits independent, normalized Schema snapshots. It does not persist drafts or published schemas by default. Publish validation remains inside the package; the host owns storage, API calls, loading, and result messages.

Schema utilities are also available from @jxyszb/jxy-form-designer/schema. The testing subpath contains demo and mock helpers and should not be used by production code.

Documentation

Normal upload fields (file) support a template download button:

1. Add a templateDownload data source with a relative url, params, and optional fileName.
2. Enable template download in the field properties and select that source.
3. Provide downloadFile through the plugin, or downloadTemplate(url, params, fileName) through a custom provider.

The button appears after the upload component and only requests on click. Required parameters use current form values. A configured file name overrides the backend name; leave it empty to use the host downloader's response-header handling. Global form disabled/view mode hides the button; individual field disabled states do not. Existing synchronous JXY download utilities are supported without download loading or duplicate-click protection.

An explicit Runtime provider overrides the plugin provider entirely. Preview providers must implement downloadTemplate; the included mock displays request details and never downloads a real file. Upgrade Runtime before publishing Schema jxy-form-schema@1.5.0 (package 0.4.0).

0.4 Compatibility

• Existing date ranges without props.valueMode keep array data under prop. New createFieldNode('daterange' | 'datetimerange' | 'numberRange') factories use split: configure props.startProp/endProp; only those two keys are submitted, not the design-only prop. Numeric ranges support numericType: 'integer' | 'decimal', decimal, min, and max.
• createRepeatNode() is exported from the root and /schema. A repeat stores an array of row objects under its prop. Missing repeat data initializes initialCount blank rows; explicit [] stays empty even when minCount is positive (validation reports it). Child defaults are ignored for all repeat rows. The first initialCount rows are protected from UI removal; minCount/maxCount constrain row count.
• Repeat children may contain fields, titles, and grids, but no repeat. Grid columns accept fields only, never grid/repeat. Reactions are scoped to the root or one row; use sourceScope: 'root' with a root sourceField to read root data from a row. API/template parameters use the same sourceScope setting with field.
• Suffix slots add fieldPath, rowId, and zero-based rowIndex. Keep external evaluation state keyed by (fieldId, rowId), not by row index. field-change adds path and row context; row-add/row-remove expose repeat fieldId, prop, path, rowId, rowIndex, and the row value. IDs are runtime-only, not business data.
• reloadOptions('projects.0.role') and getOptions('projects.0.role') target concrete row paths; root keys remain supported.
• number/floatNum support props.min, including zero and negatives; omitted min adds no lower bound. All upload variants forward props.uploadTip to the host fileUpload component's uploadTip prop. A nonblank tip replaces default guidance; blank uses the host default. Custom adapters must implement that prop and preserve isShowTip behavior.

Playground's project section demonstrates a repeat containing a grid, decimal number range, split date range, and per-row evaluation slots. Its deliberately nonblank child defaults must still produce blank rows.

• Field suffix extension
• Designer configuration and template downloads
• Designer developer guide
• 0.4 manual verification checklist

License

MIT