ApostropeCMS 窗体构建器

让内容团队在没有开发者干预的情况下建立和管理表格. 编辑器可以直接在CMS中创建联系表,调查,申请和注册,然后将它们放置在您网站的任何地方. 表格自动处理提交、电子邮件通知、验证和垃圾邮件保护.

为什么是造型器?

• 无代码窗体创建: 编辑器通过可配置的字段部件构建窗体——没有给开发者的票
• 自动数据收集: 以可选电子邮件通知保存到 MongoDB 的提交
• * 内设安保: reCAPTCHA v3 整合和验证防止垃圾邮件
• 设计自由: 品牌一致性定制CSS课程和样式钩
• 方便开发者: 事件钩、自定义验证符和可扩展字段类型
• 电子邮件准备: 自动向多个收件人提交路由

目录

• 安装
• 使用量
  • 模块配置
  • 如何运作
  • 将窗体部件添加到区域
  • 编辑工作流程
• 配置
  • 主要模块选项
  • 可用的字段类型
• 处理提交材料
  • 数据库存储
  • 电子邮件通知
  • 服务器系统事件
  • 浏览器事件
• reCAPTCHA 一体化
  • 配置选项
• 样式
  • 自定义 CSS 类
• 字段特定选项
  • 选择字段
  • 文件上传字段
• 自定义字段验证
  • 以超级模式扩展收藏器
  • 示例: 最小字数验证
  • 处理错误
• 使用大小写
• 准备好了吗?
  • 🚀 表单的特征

安装

npm install @apostrophecms/form

使用量

模块配置

配置您的窗体模块 app.js 文件 :

import apostrophe from 'apostrophe';

apostrophe({
  root: import.meta,
  shortName: 'my-project',
  modules: {
    // Main form module (must come first)
    '@apostrophecms/form': {},
    // Form widget for adding forms to areas
    '@apostrophecms/form-widget': {},
    // Field widgets (include only the types you need)
    '@apostrophecms/form-text-field-widget': {},
    '@apostrophecms/form-textarea-field-widget': {},
    '@apostrophecms/form-select-field-widget': {},
    '@apostrophecms/form-radio-field-widget': {},
    '@apostrophecms/form-file-field-widget': {},
    '@apostrophecms/form-checkboxes-field-widget': {},
    '@apostrophecms/form-boolean-field-widget': {},
    '@apostrophecms/form-conditional-widget': {},
    '@apostrophecms/form-divider-widget': {},
    '@apostrophecms/form-group-widget': {}
  }
});

模块顺序事项 : @apostrophecms/form 必须在部件模块前显示。 只包含您想要编辑器使用的字段类型 .

如何运作

这个 @apostrophecms/form 模块创建新 块类型 在您的CMS中被称为"Forms". 这表示表格是编辑一次创造的内容, 创建“ 联系表单” 一次, 然后用窗体部件将其放入联系页、 页脚和侧边栏 .

将窗体部件添加到区域

要让编辑器在页面或块类型中添加表单,请在一区域中包含表单部件:

// modules/contact-page/index.js
export default {
  extend: '@apostrophecms/piece-page-type',
  options: {
    label: 'Contact Page'
  },
  fields: {
    add: {
      contactForm: {
        type: 'area',
        options: {
          max: 1,
          widgets: {
            '@apostrophecms/form': {}
          }
        }
      }
    },
    group: {
      basics: {
        fields: ['contactForm']
      }
    }
  }
};

编辑工作流程

一旦配置,编辑器可以创建和管理表格:

1. 创建窗体:在管理员栏中点击"Forms"并创建新的窗体(如"接触表")
2. 构建窗体: 添加字段部件(文本字段、电子邮件、复选框等)并配置选项
3. 配置提交处理: 在“ 提交后” 标签中设置电子邮件通知和确认信件
4. 放置窗体: 编辑带有窗体区域的任何页面,添加窗体部件,并选择您创建的窗体

编辑器现在可以独立创建和管理表格.

配置

主要模块选项

配置 @apostrophecms/form 使用这些选项:

可用的字段类型

这个 formWidgets 选项控制组件编辑器在构建窗体时可以使用。 在您的工程级别配置此选项 /modules/@apostrophecms/form/index.js 要覆盖内置默认值的文件。 这是一个 全球环境 适用于项目中的所有表格.

默认配置 :

// modules/@apostrophecms/form/index.js
export default {
  options: {
    formWidgets: {
      '@apostrophecms/form-text-field': {},
      '@apostrophecms/form-textarea-field': {},
      '@apostrophecms/form-boolean-field': {},
      '@apostrophecms/form-select-field': {},
      '@apostrophecms/form-radio-field': {},
      '@apostrophecms/form-checkboxes-field': {},
      '@apostrophecms/form-conditional': {},
      '@apostrophecms/form-divider': {},
      '@apostrophecms/rich-text': {
        toolbar: [
          'styles', 'bold', 'italic', 'link',
          'orderedList', 'bulletList'
        ]
      }
    }
  }
};

丰富的文本部件允许编辑器在表格中添加指令. 任何部件类型都可以包含在这个配置中 .

不同形式需要不同的字段类型吗? 这个 formWidgets 选项是全局的,不能设置每个区域或每页。 如果需要单独的一组允许的字段(例如,简单的联系表对详细的申请表),则扩展 @apostrophecms/form 模块以创建第二个形式块类型 formWidgets 配置 . 不过,没有额外的控制,所有编辑器都可以使用两种形式类型. 使用 @apostrophecms-pro/advanced-permission 限制哪些用户群体可以创建和管理每一种表格——确保初级编辑只能访问基本表格,而高级工作人员可以使用高级表格. 更多了解 Pro 特性。 。 。 .

处理提交材料

数据库存储

提交文件自动保存到 aposFormSubmissions 芒果DB收藏. 要禁用数据库存储 :

// modules/@apostrophecms/form/index.js
export default {
  options: {
    saveSubmissions: false
  }
};

电子邮件通知

若为 @apostrophecms/email 被配置,表格可以自动向多个收件人发送电子邮件。 在窗体编辑器中,导航到"After-Submission"分页,并在"Email address (es) for Results"字段中输入以逗号分隔的电子邮件地址.

隐藏电子邮件通知字段 :

// modules/@apostrophecms/form/index.js
export default {
  options: {
    emailSubmissions: false
  }
};

QQ 电子邮件配置: 要通过电子邮件发送表单, 您必须首先配置 @apostrophecms/email 模块。 见 电子邮件配置指南 用于设置指令。 表格仍然可以在没有电子邮件配置的情况下保存提交到数据库.

服务器系统事件

表格提交会触发您可以在代码中处理的事件,用于自定义处理,集成,或修改提交数据. 例如,您可以向外部的CRM发送提交,添加像查询参数这样的服务器侧元数据,或者触发自定义工作流程.

submission 事件 - 每一份表格均开火:

// modules/@apostrophecms/form/index.js
export default {
  handlers(self) {
    return {
      'submission': {
        async handleSubmission(req, form, submission) {
          // Your custom logic here
          console.log('Form submitted:', form.title);
          console.log('Data:', submission);
        }
      }
    };
  }
};

beforeSaveSubmission 事件 - 在救救之前先开火 info.submission 至数据库(如果启用)

// modules/@apostrophecms/form/index.js
export default {
  handlers(self) {
    return {
      'beforeSaveSubmission': {
        async modifySubmission(req, info) {
          // Modify info.submission before it's saved
          info.submission.processedAt = new Date();
        }
      }
    };
  }
};

事件处理器参数 :

浏览器事件

窗体模块释放浏览器事件 body 提交尝试后的元素。 你可以听这些添加 自定义客户端反馈或分析。 。 。 .

成功活动

@apostrophecms/form:submission-form 成功处理提交文件时开火。 活动细节包括: form 属性.

document.body.addEventListener('@apostrophecms/form:submission-form', e => {
  // e.detail.form contains the form element/config
  console.log('Form submitted successfully:', e.detail.form);

  // Example: show a toast notification
  apos.notify('✅ Thanks for your submission!', { type: 'success' });

  // Example: send analytics event
  gtag('event', 'form_submission', {
    formTitle: e.detail.form.title || 'Untitled Form'
  });
});

失败事件

@apostrophecms/form:submission-failed 当一个提交由于验证错误,垃圾邮件保护,或服务器问题而失败时会起火. 活动细节包括: formError 属性.

document.body.addEventListener('@apostrophecms/form:submission-failed', e => {
  // e.detail.formError contains the error info
  console.error('Form submission failed:', e.detail.formError);

  // Example: show a custom error banner
  apos.notify('⚠️ Something went wrong. Please try again.', { type: 'danger' });

  // Example: track failed attempts
  gtag('event', 'form_submission_failed', {
    error: e.detail.formError.message || 'Unknown'
  });
});

使用大小写

• 将默认“ 谢谢” UI 替换为自定义成功消息
• 将事件推入 Google 标签管理器、 片段或其他分析
• 成功提交后重定向或滚动页面
• 失败时显示定制错误信息

说明: 提交后消息中已包含的窗体支持( E)thankYouHeading, (中文(简体) ), thankYouBody)和内置错误处理。 您只需要这些浏览器事件, 只要您想要额外的客户端行为, 超出模块提供的选项 .

reCAPTCHA 一体化

使用 Google reCAPTCHA v3 保护表格免受垃圾邮件影响 google.com/ recaptcha (英语) 使用版本 3,然后配置您的站点和密钥.

配置选项

备选方案1:模块配置中的硬码

// modules/@apostrophecms/form/index.js
export default {
  options: {
    recaptchaSecret: 'YOUR_SECRET_KEY',
    recaptchaSite: 'YOUR_SITE_KEY'
  }
};

选项2:允许编辑器在 UI 中配置

如果您不使用硬码两种密钥, 则会出现全局设置 UI , 管理员可以输入它们 。 一旦配置,每个表单都有一个复选框,可以独立启用 reCAPTCHA.

样式

自定义 CSS 类

添加您自己的类前缀以形成完整的样式控制元素 :

// modules/@apostrophecms/form/index.js
export default {
  options: {
    classPrefix: 'my-form'
  }
};

这产生了 BEM 风格的类 my-form__input, (中文(简体) ), my-form__label,以及 my-form__error 关于形式要素.

对于更喜欢外观设计工具的团队,Aposrope的内置 全局样式 让编辑器从管理员界面中调整 CSS 属性,而不写入代码.

字段特定选项

选择字段

选定字段部件支持多个选择 :

// modules/@apostrophecms/form-select-field-widget/index.js
export default {
  options: {
    allowMultiple: true  // Default: false
  }
};

当启用时, 部件计划中会出现另外两个字段 :

文件上传字段

⚠️ 安全警告:文件上传字段允许任何访问者将文件上传到您的服务器,从而造成存储滥用和恶意上传的潜在风险. 这个部件是 默认未包含- 你必须明确允许它.

何处执行安全措施:

1. 储存提供者级别 (AWS S3,谷歌云存储,Azure Blob):

   • 在您的服务商控制台中配置文件类型限制、大小限制和生命周期政策
   • 设置桶配额和异常上传模式的提示
   • 查看您的提供者关于内容验证功能的文档

2. ApostropeCMS 附加模块 (单位:千美元)modules/@apostrophecms/attachment/index.js:

   export default {
     options: {
       // Restrict file types (extension allowlist)
       fileGroups: [
         {
           name: 'images',
           label: 'Images',
           extensions: [ 'jpg', 'jpeg', 'png', 'gif', 'webp' ],
           extensionMaps: { jpeg: 'jpg' }
         },
         {
           name: 'office',
           label: 'Documents',
           extensions: [ 'pdf', 'doc', 'docx', 'xls', 'xlsx' ],
           extensionMaps: {}
         }
       ],
       // Set maximum file size (in bytes)
       maxSize: 10485760  // 10MB
     }
   };
   

   见 附件模块文档 用于完整的配置选项.

3. 表格提交处理器 (用于补充审定):

   // modules/@apostrophecms/form/index.js
   export default {
     handlers(self) {
       return {
         'beforeSaveSubmission': {
           async validateFiles(req, info) {
             // Add custom file validation logic here
             // Access uploaded files via info.data
           }
         }
       };
     }
   };
   

4. 垃圾邮件保护: 启用 reCAPTCHA v3(参见 reCAPTCHA 一体化 页:1

文件存储在您配置的附件存储中( 本地上传或云桶) 。 提交表保存附件 URL,而不是文件本身 .

多个文件上传: 与所选字段一样,文件字段部件支持一个 allowMultiple 选项 :

// modules/@apostrophecms/form-file-field-widget/index.js
export default {
  options: {
    allowMultiple: true  // Default: false
  }
};

启用时,用户可以选择并上传多个格式提交文件.

自定义字段验证

需要商业特定规则,如最小字数、格式要求或跨字段依赖性? 扩展内置的字段收藏器在提交前添加自定义验证逻辑. 这将运行客户端以获取即时反馈而无需服务器回路 .

每个字段从位于 apos.aposForm.collectors 浏览器中的数组。 您可以将这些收藏器的功能扩展为调整值或在表单发布到服务器之前进行额外的验证. 如果需要,可以将收集器函数写成同步函数.

收集器函数将部件元素作为参数,并在成功提交时返回响应对象。 响应对象属性为:

以超级模式扩展收藏器

这些功能可以被扩展为使用超级模式进行项目级验证. 这包括:

1. 将原始函数指定为变量
2. 创建使用原始功能、添加功能并返回结构相同的响应的新函数
3. 将新函数指派到原函数属性

示例: 最小字数验证

// modules/@apostrophecms/form-textarea-field-widget/ui/src/index.js

export default () => {
  const TEXTAREA_WIDGET = '@apostrophecms/form-textarea-field';

  // 1️⃣ Store the original collector function on `superCollector`.
  const superCollector = apos.aposForm.collectors[TEXTAREA_WIDGET].collector;

  // 2️⃣ Create a new collector function that accepts the same widget element
  // parameter.
  function newCollector(el) {
    // Get the response from the original collector.
    const response = superCollector(el);

    if (response.value && response.value.split(' ').length < 10) {
      // Throwing an object if there are fewer than ten words.
      throw {
        field: response.field,
        message: 'Write at least 10 words'
      };
    } else {
      // Returning the original response if everything is okay.
      return response;
    }
  }

  // 3️⃣ Assign our new collector to the original property.
  apos.aposForm.collectors[TEXTAREA_WIDGET].collector = newCollector;
};

处理错误

如果您想要在字段上显示错误, throw a 对象,其数值如下(如上所示):

使用大小写

联系人表格:让团队在没有开发者参与的情况下创建部门特定的联系表格.

铅生成: 以有条件的字段来构建转换-优化的形态并重新CAPTCHA保护.

事件登记:通过文件上传来文件或照片来收集参与者信息.

用户反馈: 创建调查和反馈表,向适当的团队成员提供路径.

工作应用程序: 接受带有验证和电子邮件路由的恢复和应用材料.

准备好了吗?

开源造型器提供了强大的造型能力,但企业团队往往需要先进的控制和工作流程功能. ApostropheCMS 磁带控制系统 赞成 具有专业级特性的扩展形式功能 :

🚀 表单的特征

• 高级权限 - 控制哪些团队可以创建、编辑和管理特定的形式类型。 限制获取人力资源应用程序或客户数据收集等敏感表格. 适合不同部门需要不同形式能力的多团队组织.

• 自动翻译 - 自动将表格和确认信息翻译成多种语言,并配备AI动力翻译服务(DeepL、Google Translate、Azure)。 在不进行人工翻译的情况下部署多语种表格.

• 文件管理 - 对有完整审计线索的表格进行版本控制。 跟踪更改来组成字段,恢复以前的版本,并保持遵守格式修改历史.

创建 Aposrophe 工作空间账户并升级到 ApostropheCMS 磁带控制系统 赞成 或者说 联系我们的团队 了解促进形式管理、合规和团队合作的Pro许可和准入企业特征.