# 表单组件
### [](https://octobercms.com/docs/backend/forms#form-widgets)表单组件
尽管插件通常会提供自己的自定义表单小部件，但标准包含各种表单小部件。您可以在“[表单小部件”](https://octobercms.com/docs/backend/widgets#form-widgets)文章中阅读更多内容。
* [代码编辑器](https://octobercms.com/docs/backend/forms#widget-codeeditor)
* [颜色选择器](https://octobercms.com/docs/backend/forms#widget-colorpicker)
* [数据表](https://octobercms.com/docs/backend/forms#widget-datatable)
* [日期选择器](https://octobercms.com/docs/backend/forms#widget-datepicker)
* [上传文件](https://octobercms.com/docs/backend/forms#widget-fileupload)
* [Markdown编辑器](https://octobercms.com/docs/backend/forms#widget-markdowneditor)
* [媒体搜寻器](https://octobercms.com/docs/backend/forms#widget-mediafinder)
* [嵌套表格](https://octobercms.com/docs/backend/forms#widget-nestedform)
* [记录查找器](https://octobercms.com/docs/backend/forms#widget-recordfinder)
* [关系](https://octobercms.com/docs/backend/forms#widget-relation)
* [直放站](https://octobercms.com/docs/backend/forms#widget-repeater)
* [丰富的编辑器/所见即所得](https://octobercms.com/docs/backend/forms#widget-richeditor)
* [敏感](https://octobercms.com/docs/backend/forms#widget-sensitive)
* [标签清单](https://octobercms.com/docs/backend/forms#widget-taglist)
### [](https://octobercms.com/docs/backend/forms#widget-codeeditor)代码编辑器
`codeeditor`\-呈现用于格式代码或标记的纯文本编辑器。请注意，这些选项可以由后端为管理员定义的代码编辑器首选项继承。
~~~
css_content:
type: codeeditor
size: huge
language: html
~~~
| 选项 | 描述 |
| --- | --- |
| **language** | 代码语言，例如php，css，js，html。默认值：php。 |
| **showGutter** | 显示带有行号的装订线。默认值：true。 |
| **wrapWords** | 将长行换成新行。默认为true。 |
| **fontSize** | 文字字体大小。默认值：12 |
### [](https://octobercms.com/docs/backend/forms#widget-colorpicker)颜色选择器
`colorpicker`\-呈现控件以选择十六进制颜色值。
~~~
color:
label: Background
type: colorpicker
~~~
| 选项 | 描述 |
| --- | --- |
| **availableColors** | 可用颜色列表。 |
| **allowEmpty** | 允许输入值为空。默认值：false |
有两种方法可以为选色器提供可用的颜色。第一种方法`availableColors`直接将YAML文件中的十六进制颜色代码列表定义为：
~~~
color:
label: Background
type: colorpicker
availableColors: ['#000000', '#111111', '#222222']
~~~
第二种方法使用在模型类中声明的特定方法。此方法应以与上述示例相同的格式返回十六进制颜色的数组。此方法的第一个参数是字段名称，第二个参数是字段的当前值，第三个参数是整个表单的当前数据对象。
~~~
color:
label: Background
type: colorpicker
availableColors: myColorList
~~~
在模型类中提供可用的颜色：
~~~
public function myColorList($fieldName, $value, $formData)
{
return ['#000000', '#111111', '#222222']
}
~~~
如果`availableColors`YAML文件中未定义该字段，则颜色选择器将使用一组20种默认颜色。
### [](https://octobercms.com/docs/backend/forms#widget-datatable)数据表
`datatable`\-呈现可编辑的记录表，格式为网格。单元格内容可以直接在网格中进行编辑，从而可以管理几行和几列信息。
> \*\*注意：\*\*为了与模型一起使用，应将字段定义为一个`jsonable`属性，或定义为可以处理存储数组数据的另一个属性。
~~~
data:
type: datatable
adding: true
btnAddRowLabel: Add Row Above
btnAddRowBelowLabel: Add Row Below
btnDeleteRowLabel: Delete Row
columns: []
deleting: true
dynamicHeight: true
fieldName: null
height: false
keyFrom: id
recordsPerPage: false
searching: false
toolbar: []
~~~
#### 表配置
以下列出了数据表窗口小部件本身的配置值。
| 选项 | 描述 |
| --- | --- |
| **adding** | 允许将记录添加到数据表中。默认值：`true`。 |
| **btnAddRowLabel** | 为“在上方添加行”按钮定义自定义标签。 |
| **btnAddRowBelowLabel** | 为“在下面添加行”按钮定义自定义标签。 |
| **btnDeleteRowLabel** | 为“删除行”按钮定义自定义标签。 |
| **columns** | an array representing the column configuration of the data table. See the*Column configuration*section below. |
| **deleting** | allow records to be deleted from the data table. Default:`false`. |
| **dynamicHeight** | if`true`, the data table's height will extend or shrink depending on the records added, up to the maximum size defined by the`height`configuration value. Default:`false`. |
| **fieldName** | defines a custom field name to use in the POST data sent from the data table. Leave blank to use the default field alias. |
| **height** | the data table's height, in pixels. If set to`false`, the data table will stretch to fit the field container. |
| **keyFrom** | the data attribute to use for keying each record. This should usually be set to`id`. Only supports integer values. |
| **postbackHandlerName** | 指定用于发送数据表内容的AJAX处理程序名称。设置为`null`（默认）时，将从包含数据表的表单使用的请求名称中自动检测处理程序名称。建议将此设置为`null`。 |
| **recordsPerPage** | 每页显示的记录数。如果设置为`false`，则分页将被禁用。 |
| **searching** | 允许通过搜索框搜索记录。默认值：`false`。 |
| **toolbar** | 表示数据表的工具栏配置的数组。 |
#### 列配置
数据表窗口小部件允许通过`columns`配置变量将列指定为数组。每列应使用字段名称作为键，并使用以下配置变量来设置字段。
例：
~~~
columns:
id:
type: string
title: ID
validation:
integer:
message: Please enter a number
name:
type: string
title: Name
~~~
| 选项 | 描述 |
| --- | --- |
| **type** | 此列单元格的输入类型。必须是下列之一：`string`，`checkbox`，`dropdown`或`autocomplete`。 |
| **options** | 仅用于`dropdown`和`autocomplete`列-这指定AJAX处理程序，它将以数组形式返回可用选项。数组键用作选项的值，而数组值用作选项标签。 |
| **readOnly** | 此列是否为只读。默认值：`false`。 |
| **title** | 定义列的标题。 |
| **validation** | 一个数组，用于指定对列单元格内容的验证。请参阅下面的“\*列验证”\*部分。 |
| **width** | 定义列的宽度，以像素为单位。 |
#### 列验证
可以根据以下验证类型来验证列单元格。验证应指定为一个数组，并将验证类型用作键，并将可选消息指定`message`为该验证的属性。
| 验证方式 | 描述 |
| --- | --- |
| **float** | 将数据验证为浮点型。`allowNegative`可以提供可选的布尔属性，以允许负浮点数。 |
| **integer** | 将数据验证为整数。`allowNegative`可以提供可选的布尔属性，允许使用负整数。 |
| **length** | 验证数据是否具有一定长度。必须提供一个整数`min`和`max`属性，代表必须输入的最小和最大字符数。 |
| **regex** | 根据正则表达式验证数据。`pattern`必须提供一个字符串属性，定义用于测试数据的正则表达式。 |
| **required** | 验证在保存之前必须输入数据。 |
### [](https://octobercms.com/docs/backend/forms#widget-datepicker)日期选择器
`datepicker`\-呈现用于选择日期和时间的文本字段。
~~~
published_at:
label: Published
type: datepicker
mode: date
~~~
| 选项 | 描述 |
| --- | --- |
| **mode** | 预期的结果，日期，日期时间或时间。默认值：日期时间。 |
| **format** | 提供明确的日期显示格式。例如：Ymd |
| **minDate** | 可以选择的最短/最早日期。默认值：2000-01-01 |
| **maxDate** | 可以选择的最大/最新日期。默认值：2020-12-31 |
| **firstDay** | 一周的第一天。默认值：0（星期日）。 |
| **showWeekNumber** | 在行首显示星期数。默认值：false |
| **ignoreTimezone** | 完全按照显示的日期和时间存储日期和时间，而忽略后端指定的时区首选项。 |
### [](https://octobercms.com/docs/backend/forms#widget-fileupload)上传文件
`fileupload`\-呈现图像或常规文件的文件上传器。**字段名称必须使用attachOne或attachMany关系。**
~~~
avatar:
label: Avatar
type: fileupload
mode: image
imageHeight: 260
imageWidth: 260
thumbOptions:
mode: crop
offset:
- 0
- 0
quality: 90
sharpen: 0
interlace: false
extension: auto
~~~
| 选项 | 描述 |
| --- | --- |
| **mode** | 预期的文件类型，文件或图像。默认值：图像。 |
| **imageWidth** | 如果使用图像类型，则图像将被调整为该宽度，可选。 |
| **imageHeight** | 如果使用图像类型，图像将被调整为该高度，可选。 |
| **fileTypes** | 上传者接受的文件扩展名（可选）。例如：`zip,txt` |
| **mimeTypes** | 上传者接受的MIME类型，可以是文件扩展名或完全限定名称（可选）。例如：`bin,txt` |
| **maxFilesize** | 上传者接受的文件大小（Mb），可选。默认值：来自“ upload\_max\_filesize”参数值 |
| **useCaption** | 允许为文件设置标题和描述。默认值：true |
| **prompt** | 上载按钮显示的文本，仅适用于文件，可选。 |
| **thumbOptions** | 传递给文件的缩略图生成方法的选项 |
| **attachOnUpload** | 如果存在父记录，则在上传时自动附加上载的文件，而不是使用延迟绑定在保存父记录时附加。默认为false。 |
### [](https://octobercms.com/docs/backend/forms#widget-markdowneditor)Markdown编辑器
`markdown`\-呈现降价格式文本的基本编辑器。
~~~
md_content:
type: markdown
size: huge
mode: split
~~~
| 选项 | 描述 |
| --- | --- |
| **mode** | 预期的查看模式（制表符或拆分）。默认标签页。 |
### [](https://octobercms.com/docs/backend/forms#widget-mediafinder)媒体搜寻器
`mediafinder`\-呈现一个用于从媒体管理器库中选择项目的字段。展开该字段将显示媒体管理器以找到文件。结果选择是一个字符串作为文件的相对路径。
~~~
background_image:
label: Background image
type: mediafinder
mode: image
~~~
| 选项 | 描述 |
| --- | --- |
| **mode** | 预期的文件类型，文件或图像。默认值：文件。 |
| **prompt** | 未选择任何项目时显示的文本。该`%s`字符代表的媒体管理器图标。 |
| **imageWidth** | 如果使用图像类型，则预览图像将以该宽度显示（可选）。 |
| **imageHeight** | 如果使用图像类型，则预览图像将显示为此高度，可选。 |
> \*\*注意：\*\*与“[文件上载”表单窗口小部件不同](https://octobercms.com/docs/backend/forms#widget-fileupload)，“媒体查找器”表单窗口小部件将其数据存储为字符串，该字符串表示在“媒体库”中选择的图像的路径。
### [](https://octobercms.com/docs/backend/forms#widget-nestedform)嵌套表格
`nestedform`\-将嵌套表单呈现为该字段的内容，以包含的字段数组的形式返回数据。
> \*\*注意：\*\*为了与模型一起使用，应将字段定义为一个`jsonable`属性，或定义为可以处理存储数组数据的另一个属性。
~~~
content:
type: nestedform
usePanelStyles: false
form:
fields:
added_at:
label: Date added
type: datepicker
details:
label: Details
type: textarea
title:
label: This the title
type: text
tabs:
meta_title:
lable: Meta Title
tab: SEO
color:
label: Color
type: colorpicker
tab: Design
secondaryTabs:
is_active:
label: Active
type: checkbox
logo:
label: Logo
type: mediafinder
mode: image
~~~
嵌套表单支持与表单本身相同的语法，包括制表符和secondaryTabs。jsonsable属性具有表单定义的结构。甚至可以在嵌套表单中使用嵌套表单。
| 选项 | 描述 |
| --- | --- |
| **form** | 与[表格定义](https://octobercms.com/docs/backend/forms#form-fields)相同[](https://octobercms.com/docs/backend/forms#form-fields) |
| **usePanelStyles** | 定义是否应用外观类似的面板（默认为true） |
### [](https://octobercms.com/docs/backend/forms#widget-recordfinder)记录查找器
`recordfinder`\-呈现一个包含相关记录详细信息的字段。展开该字段将显示一个弹出列表，以搜索大量记录。仅受单数关系支持。
~~~
user:
label: User
type: recordfinder
list: ~/plugins/rainlab/user/models/user/columns.yaml
recordsPerPage: 10
title: Find Record
prompt: Click the Find button to find a user
keyFrom: id
nameFrom: name
descriptionFrom: email
conditions: email = "bob@example.com"
scope: whereActive
searchMode: all
searchScope: searchUsers
useRelation: false
modelClass: RainLab\User\Models\User
~~~
| 选项 | 描述 |
| --- | --- |
| **keyFrom** | 在用于键的关系中使用的列的名称。默认值：id。 |
| **nameFrom** | 在用于显示名称的关系中使用的列名称。默认值：名称。 |
| **descriptionFrom** | 在用于显示描述的关系中使用的列名。默认值：描述。 |
| **title** | 文本显示在弹出窗口的标题部分。 |
| **prompt** | 没有选择记录时显示的文本。该`%s`字符代表的搜索图标。 |
| **list** | 配置数组或对列表列定义文件的引用，请参阅[列表列](https://octobercms.com/docs/backend/lists#list-columns)。 |
| **recordsPerPage** | 每页显示的记录，无页使用0。默认值：10 |
| **conditions** | 指定要应用于列表模型查询的原始where查询语句。 |
| **scope** | 指定在**相关表单模型中**定义的[查询范围方法](https://octobercms.com/docs/database/model#query-scopes)，以始终应用于列表查询。第一个参数将包含小部件将其值附加到的模型，即父模型。 |
| **searchMode** | 将搜索策略定义为包含所有单词，任何单词或确切短语。支持的选项：所有，任何，确切。默认值：全部。 |
| **searchScope** | 指定在**相关表单模型中**定义的[查询范围方法](https://octobercms.com/docs/database/model#query-scopes)以应用于搜索查询，第一个参数将包含搜索项。 |
| **useRelation** | 用于将字段名称用作关系名称以直接在父模型上进行交互的标志。默认值：true。禁用仅返回所选模型的ID |
| **modelClass** | useRelation = false时用于列出记录的模型的类 |
### [](https://octobercms.com/docs/backend/forms#widget-relation)关系
`relation`\-根据字段关系类型呈现下拉列表或复选框列表。单个关系显示一个下拉列表，多个关系显示一个复选框列表。用于显示每个关系的标签来自`nameFrom`或`select`定义。
~~~
categories:
label: Categories
type: relation
nameFrom: title
~~~
或者，您可以使用自定义`select`语句填充标签。任何有效的SQL语句在这里都有效。
~~~
user:
label: User
type: relation
select: concat(first_name, ' ', last_name)
~~~
您还可以提供模型作用域，以用于使用该`scope`属性过滤结果。
| 选项 | 描述 |
| --- | --- |
| **nameFrom** | 用于显示关系标签的模型属性名称。默认值：名称。 |
| **select** | 用于名称的定制SQL select语句。 |
| **order** | 用于对选项进行排序的order子句。范例：`name desc`。 |
| **emptyOption** | 没有可用选择时显示的文本。 |
| **scope** | 指定在**相关表单模型中**定义的[查询范围方法](https://octobercms.com/docs/database/model#query-scopes)，以始终应用于列表查询。 |
### [](https://octobercms.com/docs/backend/forms#widget-repeater)直放站
`repeater`\-呈现其中定义的一组重复的表单字段。
~~~
extra_information:
type: repeater
titleFrom: title_when_collapsed
form:
fields:
added_at:
label: Date added
type: datepicker
details:
label: Details
type: textarea
title_when_collapsed:
label: This field is the title when collapsed
type: text
~~~
| 选项 | 描述 |
| --- | --- |
| **form** | 表单域定义文件的参考，请参阅[后端表单域](https://octobercms.com/docs/backend/forms#form-fields)。内联字段也可以使用。 |
| **prompt** | 用于创建按钮的文本。默认值：添加新项目。 |
| **titleFrom** | 项目中用作折叠项目标题的字段名称。 |
| **minItems** | 所需的最少物品。不使用组时预显示这些项目。例如，如果您设置\*\*“ minItems：1”，\*\*则第一行将显示而不是隐藏。 |
| **maxItems** | 转发器中允许的最大项目数。 |
| **groups** | 引用一组将转发器置于组模式的表单字段（请参见下文）。也可以使用内联定义。 |
| **style** | 申请重复项目的行为方式。可以是下列之一：`default`，`collapsed`或`accordion`。有关更多信息，请参见下面的“\*\*中继器样式”\*\*部分。 |
~~~
content:
type: repeater
prompt: Add content block
groups: $/acme/blog/config/repeater_fields.yaml
~~~
这是一个组配置文件的示例，该文件位于\*\*/plugins/acme/blog/config/repeater\_fields.yaml中\*\*。另外，这些定义可以在转发器内联指定。
~~~
textarea:
name: Textarea
description: Basic text field
icon: icon-file-text-o
fields:
text_area:
label: Text Content
type: textarea
size: large
quote:
name: Quote
description: Quote item
icon: icon-quote-right
fields:
quote_position:
span: auto
label: Quote Position
type: radio
options:
left: Left
center: Center
right: Right
quote_content:
span: auto
label: Details
type: textarea
~~~
每个组必须指定一个唯一键，并且该定义支持以下选项。
| 选项 | 描述 |
| --- | --- |
| **name** | 组的名称。 |
| **description** | 小组的简要说明。 |
| **icon** | 为该组定义一个图标（可选）。 |
| **fields** | 属于该组的[表单字段](https://octobercms.com/docs/backend/forms#form-fields)，请参阅[后端表单字段](https://octobercms.com/docs/backend/forms#form-fields)。 |
> **注意**：组密钥与保存的数据一起作为`_group`属性存储。
#### 中继器样式
`styles`转发器小部件的属性控制转发器项目的行为。开发人员可以使用三种不同类型的样式：
* \*\*默认值：\*\*显示页面加载时扩展的所有转发器项目。这是当前的默认行为，如果在中继器小部件的配置中未定义样式，则将使用此行为。
* \*\*折叠：\*\*在页面加载时将所有转发器项目显示为折叠（最小化）。用户可以根据需要折叠或展开项目。
* \*\*手风琴：\*\*仅显示第一个转发器项在负载下已扩展，其他所有项都已折叠。展开另一个项目时，任何其他展开的项目都将折叠，从而有效地使其一次只能展开一个项目。
### [](https://octobercms.com/docs/backend/forms#widget-richeditor)丰富的编辑器/所见即所得
`richeditor`\-呈现用于格式丰富的文本的可视编辑器，也称为WYSIWYG编辑器。
~~~
html_content:
type: richeditor
toolbarButtons: bold|italic
size: huge
~~~
| 选项 | 描述 |
| --- | --- |
| **toolbarButtons** | 在编辑器工具栏上显示哪些按钮。 |
可用的工具栏按钮为：
~~~
fullscreen, bold, italic, underline, strikeThrough, subscript, superscript, fontFamily, fontSize, |, color, emoticons, inlineStyle, paragraphStyle, |, paragraphFormat, align, formatOL, formatUL, outdent, indent, quote, insertHR, -, insertLink, insertImage, insertVideo, insertAudio, insertFile, insertTable, undo, redo, clearFormatting, selectAll, html
~~~
> **注意**：`|`将在工具栏中插入垂直分隔线，在`-`水平插入线。
### [](https://octobercms.com/docs/backend/forms#widget-sensitive)敏感
`sensitive`\-呈现一个可显示的密码字段，该字段可用于敏感信息，例如API密钥或机密，配置值等。可以根据用户的请求切换显示和隐藏敏感字段。
包含先前输入值的敏感字段将在加载时用占位符值替换该值，以防止按长度猜测或复制该值。揭示该值后，原始值将由AJAX检索并填充到该字段中。
~~~
api_secret:
type: sensitive
allowCopy: false
hideOnTabChange: true
~~~
| 选项 | 描述 |
| --- | --- |
| **allowCopy** | 在敏感字段中添加“复制”操作，允许用户复制密码而不显示密码。默认值：false |
| **hiddenPlaceholder** | 设置用于模拟隐藏的，未公开的值的占位符文本。您可以将其更改为长字符串或短字符串以模拟不同的长度值。默认：`__hidden__` |
| **hideOnTabChange** | 如果为true，则在用户导航到其他选项卡或最小化其浏览器时，敏感字段将自动隐藏。默认值：true |
### [](https://octobercms.com/docs/backend/forms#widget-taglist)标签清单
`taglist`\-渲染一个用于输入标签列表的字段。
~~~
tags:
type: taglist
separator: space
~~~
标签列表支持将选项定义为[下拉字段类型](https://octobercms.com/docs/backend/forms#field-dropdown)的相同方法。
~~~
tags:
type: taglist
options:
- Red
- Blue
- Orange
~~~
您可以在字段名称是[多对多](https://octobercms.com/docs/database/relations#many-to-many)**关系的情况**下使用被`mode`调用的[关系](https://octobercms.com/docs/database/relations#many-to-many)。这将通过该关系自动获取和分配标签。如果支持自定义标签，则会在分配之前创建它们。[](https://octobercms.com/docs/database/relations#many-to-many)
~~~
tags:
type: taglist
mode: relation
~~~
| 选项 | 描述 |
| --- | --- |
| **mode** | 控制如何返回值（字符串，数组或关系）。默认值：字符串 |
| **separator** | 用指定字符（逗号或空格）分隔标签。默认值：逗号 |
| **customTags** | 允许用户手动输入自定义标签。默认值：true |
| **options** | 指定预定义选项的方法或数组。设置为true以使用模型`get*Field*Options`方法。可选的。 |
| **nameFrom** | 如果使用关系模式，则显示标签名称的模型属性名称。默认值：名称 |
| **useKey** | 使用键代替值来保存和读取数据。默认值：false |
- 基本说明
- 基本操作
- October cms 安装
- 后台控制器路径
- 图标
- 获取安装网上的插件/主题
- 插件构造器使用
- 定时任务
- October后台控制器
- vscode编辑器
- ajax操作
- 使用
- ajax更新组件
- ajax属性API
- JavaScript API
- ajax综合使用
- 主题
- 多语言主题
- 安装市场主题
- 主题程序处理
- 主题
- 页面
- 部件
- 布局
- 内容
- 组件
- 媒体
- 主题表单操作
- 表单使用
- 表单后端程序处理
- 插件
- 自定义插件
- 插件说明
- 插件导航条
- 插件数据库设置
- 插件的设置管理
- 插件的配置文件config
- 组件
- app服务
- app容器
- 扩展行为
- 缓存
- Collection类
- Lazy Collections
- Collection方法
- 助手函数
- 数组助手函数
- 路径助手函数
- 玄乐助手函数
- 其他助手函数
- 错误与记录
- 事件处理
- HTML页面
- 文件与目录操作
- 散列和加密
- 邮件
- 邮件内容
- 邮件发送
- 分页
- 模板解析器
- 动态解析器语法
- 队列消息
- 请求与输入
- 响应
- 视图
- 路由器
- 配置
- 验证操作
- 处理错误消息
- 错误消息与视图
- 可用的验证规则
- 有条件的验证规则
- 验证数组
- 错误消息
- 自定义验证规则
- 模型操作
- 定义模型与其属性
- 检索模型
- 插入与更新
- 删除模型
- 查询范围
- 事件操作
- 关联操作
- 定义关系
- 关系类型
- 多肽关系
- 关系查询
- 渴望加载
- 插入模型
- 数据库操作
- 基本用法
- 数据表结构
- 查询连贯操作
- 结果检索
- select子句
- 插入更新
- where子句
- 排序，分组，限制和偏移
- 文件附件
- Collection操作
- 属性操作
- 系列化json
- 数据库属性
- 数据库行为
- 控制器
- 后台控制器定义
- 后台页面
- 后台组件
- 后台表单
- 表单组件
- 表单视图
- 表单行为
- 后台列表
- 列表行为
- 列表过滤器
- 可用列类型
- 关系行为
- 关系行为类型
- 扩展关系行为
- 列表排序操作
- 导入导出操作
- 用于与权限
- corlate模板修改
- 修改顶部导航
- laravel问题
- 控制器不存在
- 控制器
- 路由组
- laravel笔记
- laravel 安装
- 伪静态配置
- 依赖注入 & 控制器
- 中间件
- 路由文件
- 视图