# Esurvey.js

**Repository Path**: xing_young/esurvey.js

## Basic Information

- **Project Name**: Esurvey.js
- **Description**: Esurvey.js 是一个通过json格式的数据或js对象来自动生成表单的js库。表单样式依赖于bootstrap5，也可以自行修改样式。目前 Esurvey.js 支持五种最常用的题型：单选题、多选题、填空题、多行文本题、量表题。适用于多数量表和测试表。同时 Esurvey.js 内置了简单的前端校验。你也可以通过 onsubmit 方法重写更复杂的校验方法。
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2022-10-03
- **Last Updated**: 2023-02-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Esurvey.js

## 项目介绍

`Esurvey.js`是一个可以通过 json 格式的数据来自动生成表单的 js 库。它也支持直接识别文本转化为json配置数据的功能。

目前`Esurvey.js`支持六种最常用的题型：单选题、多选题、填空题、多行文本题、量表题、李克特量表题。适用于多数量表和测试表。同时`Esurvey.js`内置了简单的前端校验。你也可以通过`onsubmit`方法重写更复杂的校验方法。

## 安装依赖

`Esurvey.js`的样式依赖于`bootstrap5`，因此要使用`Esurvey.js` 需要先安装相关以来，此处可以使用 npm 包管理工具下载，也可自行到中文网网站下载`https://v5.bootcss.com/docs/getting-started/download/`。

```shell
npm i bootstrap@5
```

## 安装 Esurvey.js

### cdn

直接复制下列代码到您的html中，注意先导入`bootstrap5`，以免产生错误。

```html
<script src="https://cdn.jsdelivr.net/gh/xingyoung6/esurvey@main/esurvey.min.js"></script>
```

### 下载到本地

你也可以选择下载到本地，下载后通过<script>标签引入。注意，在导入`Esurvey.js`之前，先导入`bootstrap5`，以免产生错误。

```html
<script src="./esurvey.js"></script>
```

## 使用 Esurvey.js 创建表单

### 准备一个根元素

首先需要准备一个父级元素作为表单的根结点。我们建议使用<div>标签进行创建，并设置 class 或 id 以便选择。

```html
<div class="esurvey-root"></div>
```

### 准备配置数据

除了准备一个根元素，`Esurvey.js`需要根据一些配置数据来生成表单。其中有一些配置项是必要的，有一些是可选的

必要元素：

- title
- introduction
- questions

```js
const surveyOptions = {
  title: "这里是问卷标题",
  introduction: "这是问卷的导语。",
  settings: {
    formId: "formSample01", // 为表单设置一个独一无二id
    formMethod: "POST",
    showHead: true,
    submitBtn: {
      text: "立即提交",
    },
  },
  questions: [
    // 单选题
    {
      id: 1,
      name: "sample",
      title: "这是一个样例题目",
      desc: "这是一个简单的题目描述",
      type: "select",
      required: true,
      options: [
        { id: 1, value: 0, label: "选项一" },
        { id: 2, value: 1, label: "选项二" },
        { id: 3, value: 2, label: "选项三" },
        { id: 4, value: 3, label: "选项四" },
      ],
    },
  ],
};
```

### 初始化一个 Esurvey 表单

做好上述准备工作之后，我们就可以开始创建表单了。方法很简单，只需要一行代码即可完成。

```js
initSurvey(surveyOptions, ".esurvey-root");
```

其中，`surveyOptions`为配置数据，`".esurvey-root"`为 css 选择器，用于选择我们的根元素。

此时一个简单的表单就创建好了。

### 配置项说明

配置数据主要分为两大部分：问卷配置和问题配置

#### 问卷配置

问卷配置必须设置`title、introduction、questions`这三个配置

```js
const surveyOptions = {
        title: "这里是问卷标题",
        introduction: "这是问卷的导语。",
        settings: {
            formId: "formSample01",	// 为表单设置一个独一无二id
            formMethod: "POST",
            showHead: true,
            submitBtn: {
                text: "立即提交",
            },
        },
        questions: []
```

##### title

- 值：string
- 用途：规定了问卷的标题

##### introduction

- 值：string
- 用途：规定了问卷的导语

##### settings

- 类型：对象
- 规定表单的一些功能和属性
- 内容：

###### formId

- 类型：string
- 用途：规定了<form>表单的 id 属性

###### formMethod

- 值："GET" or "POST"
- 类型：string
- 用途：规定<form>表单的 mthod

###### showHead

- 类型：boolean
- 用途：规定是否展示头部信息（问卷标题和导语）

###### submitBtn

- 用途：规定是否自动生成 submit 按钮
- text：
  - 规定 submit 标签的文字内容

#### 问题配置

所有的问题都配置在`questions`配置项中，每个问题都有几个相同的必需项。下面挑几处重要的部分进行详细解释。

##### type

- 值：可选`['select', 'multi-select', 'input', 'textarea', 'slider']`其中之一。分别代表单选题、多选题、填空题、多行文本题、量表题。
- 作用：规定了本题目的类型

##### required

- 类型：boolean
- 规定本题目是否为必填写

```js
const surveyOptions = {
  title: "这里是问卷标题",
  introduction: "这是问卷的导语。",
  questions: [
    {
      id: 1, // 必需，且须唯一
      name: "sample", // 必需，且须唯一
      title: "这是一个样例题目", // 必需
      desc: "这是一个简单的题目描述",
      type: "select", // 必需
      required: true,
      options: [
        // 单选、多选必需
        { id: 1, value: 0, label: "选项一" },
        { id: 2, value: 1, label: "选项二" },
        { id: 3, value: 2, label: "选项三" },
        { id: 4, value: 3, label: "选项四" },
      ],
    },
  ],
};
```

##### 量表题配置项

```js
{
	id: 2,
	title: "下面哪几个选项最符合实际",
	type: "slider",
	min: 0,
	minText: "我很沮丧",
	max: 10,
	maxText: "我很快乐",
    options: [
        // 如果配置，则会转换为李克特量表题
        { id: 1, value: 0, label: "选项一" },
        { id: 2, value: 1, label: "选项二" },
        { id: 3, value: 2, label: "选项三" },
        { id: 4, value: 3, label: "选项四" },
      ],
},
```

###### minText

- 最小值的指示文字说明

###### maxText

- 最大值的指示文字说明

##### 填空题配置项

```js
{
        id: 3,
        title: "您的姓名",
        required: true,
        type: "input",
        min: 0,
        max: 10,
        valueType: "number",
        placeholder: "请问您的姓名是？",
},
```

###### valueType

- 填空值的类型，相当于配置<input>标签的 type 属性

###### placeholder

- 相当于配置<input>标签的 placeholder 属性

###### min

- 最小值或最小字数

###### max

- 最大值或最大字数

##### 多行文本题配置项

```js
const a = {
  id: 4,
  title: "您的评价",
  type: "textarea",
  rows: 5,
  min: 0,
  max: 10,
};
```

###### rows

- 若不配置，默认值为 3，相当于设置<textarea>标签的 rows 属性

###### min

- 最小字数限制

###### max

- 最大字数限制

## 利用esurvey.js识别文本生成表单

#### 1、准备一个<textarea>元素来输入文本，同时准备一个<div>元素来生成表单

```html
<textarea class="edit" placeholder="输入文本转换为问卷"></textarea>
<div class="esurvey-root"></div>
```

#### 2、通过`formFormatter()`函数来将<textarea>里的内容转换成esurvey表单的配置对象

```js
let options = formFormatter(".edit");
```

#### 3、通过`initSurvey()`函数和上一步的配置对象在根元素`<div class="esurvey-root"></div>`生成表单

```js
initSurvey(options, ".esurvey-root");
```

#### 4、如果要实现根据编辑区域内容实时渲染表单的功能，可以为<textarea>绑定`oninput`事件，并调用esurvey内置的防抖函数。

```js
edit.oninput = debounce(function () {
    options = formFormatter(".edit");
    initSurvey(options, ".preview");
    if (edit.value.trim() === "") options = null;
}, 1000);
```

#### 5、文本识别生成的配置数据默认为不显示头部和提交按钮的最基础的表单，如果需要更详细的配置，可以直接对于`formFormatter()`函数生成的配置对象进行修改。

#### 6、文本格式及常用配置

##### 文本样例及效果样例

```
标题写在第一行（记得换行）

第二行是导语，目前这个自动识别和表单生成只支持单选、下拉框、多选、文本、填空、量表这几种题型。可以在题目所在的那一行通过【】进行配置，如果不配置则默认为单选题。同时也可以在题目所在行的末尾加上“@R”表示必填项目。量表题目还可以通过{最小值文字说明/最小值/最大值文字说明/最大值}的格式来配置。在每个选项的末尾，还能通过“@[int]”设置分值。此外遇到反向记分的量表题，还可以通过@r进行配置，如果你想隐藏量表的真实分值，那么用@h标识即可。

1. 这是一道单选题@R
选项一@4
选项二@3
选项三@2
选项四@1

2. 这是一道下拉单选题【下拉】@R
选项一
选项二
选项三
选项四

3. 这是一道多选题【多选】
选项一
选项二
选项三
选项四

4. 这是一道填空题【填空】

5. 这是一道文本题【文本】

6. 这是一道量表题【量表】{我很快乐/0/我很悲伤/10}

7. 这是一道李克特量表题【量表】{非常不同意/1/非常同意/5}
非常不同意
不同意
不一定
同意
非常同意

8. 这是一道反向记分的李克特量表题【量表】{非常同意/1/非常不同意/5}@r
非常不同意@5
不同意@4
不一定@3
同意@2
非常同意@1

9. 这是一道反向记分并且隐藏真实分值的李克特量表题【量表】{非常同意/1/非常不同意/5}@r@h
非常不同意@5
不同意@4
不一定@3
同意@2
非常同意@1
```

<img src="./image/文本生成表单样例.png" alt="文本生成表单样例"  />