表單組件 · October Cms 筆記

# 表單組件 ### [](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 |