后臺表單 · October Cms 筆記

# 后臺表單 ### 介紹 **表單行為**是控制器修改器，用于輕松地將表單功能添加到后端頁面。該行為提供了三個頁面，分別稱為“創建”，“更新”和“預覽”。“預覽”頁面是“更新”頁面的只讀版本。當您使用表單行為時，無需在控制器中定義`create`，`update`和`preview`操作-該行為將為您完成。但是，您應該提供相應的視圖文件。表單行為取決于表單[字段定義](https://octobercms.com/docs/backend/forms#form-fields)和[模型類](https://octobercms.com/docs/database/model)。為了使用表單行為，您應該將其添加到`$implement`控制器類的屬性中。另外，`$formConfig`應該定義class屬性，并且其值應引用用于配置行為選項的YAML文件。 ~~~ namespace Acme\Blog\Controllers; class Categories extends \Backend\Classes\Controller { public $implement = ['Backend.Behaviors.FormController']; public $formConfig = 'config_form.yaml'; } ~~~ > \*\*注意：\*\*通常，表單和[列表行為](https://octobercms.com/docs/backend/lists)在同一控制器中一起使用。 ### [](https://octobercms.com/docs/backend/forms#configuring-form)配置表單行為 `$formConfig`屬性中引用的配置文件以YAML格式定義。該文件應放置在控制器的[views目錄中](https://octobercms.com/docs/backend/controllers-ajax/#introduction)。下面是一個典型的表單行為配置文件的示例： ~~~ # =================================== # Form Behavior Config # =================================== name: Blog Category form: $/acme/blog/models/post/fields.yaml modelClass: Acme\Blog\Post create: title: New Blog Post update: title: Edit Blog Post preview: title: View Blog Post ~~~ 表單配置文件中必須包含以下字段： | 領域 | 描述 | | --- | --- | | **name** | 此表單管理的對象的名稱。 | | **form** | 配置數組或對表單域定義文件的引用，請參見[表單域](https://octobercms.com/docs/backend/forms#form-fields)。 | | **modelClass** | 如果是模型類名稱，則會針對此模型加載并保存表單數據。 | 下面列出的配置選項是可選的。如果您希望表單行為支持“[創建”](https://octobercms.com/docs/backend/forms#form-create-page)，“[更新”](https://octobercms.com/docs/backend/forms#form-update-page)或“[預覽”](https://octobercms.com/docs/backend/forms#form-preview-page)頁面，請定義它們。 | 選項 | 描述 | | --- | --- | | **defaultRedirect** | 未定義特定重定向頁面時，用作后備重定向頁面。 | | **create** | 創建頁面的配置數組或對配置文件的引用。 | | **update** | 更新頁面的配置數組或對配置文件的引用。 | | **preview** | 預覽頁面的配置數組或對配置文件的引用。 | ### [](https://octobercms.com/docs/backend/forms#form-create-page)建立頁面要支持“創建”頁面，請將以下配置添加到YAML文件： ~~~ create: title: New Blog Post redirect: acme/blog/posts/update/:id redirectClose: acme/blog/posts flashSave: Post has been created! ~~~ “創建”頁面支持以下配置選項： | 選項 | 描述 | | --- | --- | | **title** | 頁面標題，可以引用[本地化字符串](https://octobercms.com/docs/plugin/localization)。 | | **redirect** | 保存記錄時的重定向頁面。 | | **redirectClose** | 保存記錄并且**關閉**后變量隨請求一起發送時的重定向頁面。 | | **flashSave** | 保存記錄時顯示的Flash消息，可以引用[本地化字符串](https://octobercms.com/docs/plugin/localization)。 | | **form** | 僅覆蓋創建頁面的默認表單字段定義。 | ### [](https://octobercms.com/docs/backend/forms#form-update-page)更新頁面要支持“更新”頁面，請在YAML文件中添加以下配置： ~~~ update: title: Edit Blog Post redirect: acme/blog/posts flashSave: Post updated successfully! flashDelete: Post has been deleted. ~~~ “更新”頁面支持以下配置選項： | 選項 | 描述 | | --- | --- | | **title** | 頁面標題，可以引用[本地化字符串](https://octobercms.com/docs/plugin/localization)。 | | **redirect** | 保存記錄時的重定向頁面。 | | **redirectClose** | 保存記錄并**關閉**請求變量發送時的重定向頁面。 | | **flashSave** | 保存記錄時顯示的Flash消息，可以引用[本地化字符串](https://octobercms.com/docs/plugin/localization)。 | | **flashDelete** | 刪除記錄時顯示的Flash消息，可以引用[本地化字符串](https://octobercms.com/docs/plugin/localization)。 | | **form** | 僅覆蓋更新頁面的默認表單字段定義。 | ### [](https://octobercms.com/docs/backend/forms#form-preview-page)預覽頁面要支持“預覽”頁面，請在YAML文件中添加以下配置： ~~~ preview: title: View Blog Post ~~~ “預覽”頁面支持以下配置選項： | 選項 | 描述 | | --- | --- | | **title** | 頁面標題，可以引用[本地化字符串](https://octobercms.com/docs/plugin/localization)。 | | **form** | 僅覆蓋預覽頁面的默認表單字段定義。 | ### [](https://octobercms.com/docs/backend/forms#form-fields)定義表格欄位表單字段是使用YAML文件定義的。表單行為使用表單字段配置來創建表單控件并將其綁定到模型字段。該文件放置在插件的**models**目錄的子目錄中。子目錄名稱與小寫的模型類名稱匹配。文件名無關緊要，但是**fields.yaml**和**form\_fields.yaml**是通用名稱。表單字段示例文件位置： ~~~ plugins/ acme/ blog/ models/ <=== Plugin models directory post/ <=== Model configuration directory fields.yaml <=== Model form fields config file Post.php <=== model class ~~~ 字段可以放在三個區域中，即**外部區域**，**主選項卡**或**輔助選項卡**。下一個示例顯示了表單字段定義文件的典型內容。 ~~~ # =================================== # Form Field Definitions # =================================== fields: blog_title: label: Blog Title description: The title for this blog published_at: label: Published date description: When this blog post was published type: datepicker [...] tabs: fields: [...] secondaryTabs: fields: [...] ~~~ 可以使用“[關系小部件”](https://octobercms.com/docs/backend/forms#widget-relation)或“[關系管理器”](https://octobercms.com/docs/backend/relations#relationship-types)呈現相關模型中的字段。一個例外是OneToOne或morphOne相關字段，必須將其定義為related\*\*\[field\]\*\*，然后可以將其指定為模型的任何其他字段： ~~~ user_name: label: User Name description: The name of the user avatar[name]: label: Avatar description: will be saved in the Avatar table published_at: label: Published date description: When this blog post was published type: datepicker [...] ~~~ ### [](https://octobercms.com/docs/backend/forms#form-tab-options)標簽選項對于每個選項卡定義（即`tabs`和）`secondaryTabs`，您可以指定以下選項： | 選項 | 描述 | | --- | --- | | **stretch** | 指定此選項卡是否拉伸以適合父級高度。 | | **defaultTab** | 分配字段的默認選項卡。默認值：其他。 | | **icons** | 使用標簽名稱作為鍵將圖標分配給標簽。 | | **lazy** | 單擊時動態加載的選項卡數組。對于包含大量內容的選項卡很有用。 | | **cssClass** | 為選項卡容器分配CSS類。 | | **paneCssClass** | 將CSS類分配給單個選項卡窗格。值是一個數組，鍵是制表符索引或標簽，值是CSS類。也可以將其指定為字符串，在這種情況下，該值將應用于所有選項卡。 | > \*\*注意：\*\*建議不要在具有受觸發器影響的字段的選項卡上使用延遲加載。 ~~~ tabs: stretch: true defaultTab: User cssClass: text-blue lazy: - Groups paneCssClass: 0: first-tab 1: second-tab icons: User: icon-user Groups: icon-group fields: username: type: text label: Username tab: User groups: type: relation label: Groups tab: Groups ~~~ ### [](https://octobercms.com/docs/backend/forms#form-field-options)欄位選項您可以為每個字段指定以下選項（如果適用）： | 選項 | 描述 | | --- | --- | | **label** | 向用戶顯示表單字段時的名稱。 | | **type** | 定義應如何呈現此字段（請參見下面的“[可用字段”類型](https://octobercms.com/docs/backend/forms#field-types)）。默認值：文本。 | | **span** | 將表單字段對齊到一側。選項：自動，左，右，風暴，滿。默認值：完整。該參數`storm`允許您使用`cssClass`屬性將表單顯示為Bootstrap網格`cssClass: col-xs-4`。 | | **size** | 指定使用它的字段的字段大小，例如textarea字段。選項：微小，較小，較大，巨大，巨型。 | | **placeholder** | 如果該字段支持占位符值。 | | **comment** | 在該字段下放置一個描述性注釋。 | | **commentAbove** | 在字段上方添加評論。 | | **commentHtml** | 允許在注釋內添加HTML標記。選項：true，false。 | | **default** | 指定該字段的默認值。對于`dropdown`，`checkboxlist`，`radio`和`balloon-selector`窗口小部件，可以在此處指定一個選項鍵，把它選擇默認。 | | **defaultFrom** | 從另一個字段的值中獲取默認值。 | | **tab** | 將字段分配給選項卡。 | | **cssClass** | 將CSS類分配給字段容器。 | | **readOnly** | 防止修改字段。選項：true，false。 | | **disabled** | 防止修改字段并將其從保存的數據中排除。選項：true，false。 | | **hidden** | 從視圖中隱藏該字段，并將其從保存的數據中排除。選項：true，false。 | | **stretch** | 指定此字段是否拉伸以適合父級高度。 | | **context** | 指定顯示字段時應使用的上下文。也可以通過`@`在字段名稱中使用符號來傳遞上下文，例如`name@update`。 | | **dependsOn** | 此字段所[依賴](https://octobercms.com/docs/backend/forms#field-dependencies)的其他字段名稱的數組，當修改其他字段時，此字段將更新。 | | **trigger** | 使用[觸發事件](https://octobercms.com/docs/backend/forms#field-trigger-events)為該字段指定條件。 | | **preset** | 允許該字段值最初由另一個字段的值設置，并使用[輸入預設轉換器進行轉換](https://octobercms.com/docs/backend/forms#field-input-preset)。 | | **required** | 在字段標簽旁邊放置一個紅色星號以指示它是必需的（請確保在模型上設置驗證，因為這不是由表單控制器強制執行的）。 | | **attributes** | 指定要添加到表單字段元素的自定義HTML屬性。 | | **containerAttributes** | 指定要添加到表單字段容器的自定義HTML屬性。 | | **permissions** | 當前后端用戶必須具有的[權限](https://octobercms.com/docs/backend/users#users-and-permissions)才能使用該字段。支持單個權限的字符串或僅需要一個權限即可授予訪問權限的一組權限。 | ### [](https://octobercms.com/docs/backend/forms#field-types)可用字段類型有多種本機字段類型可用于**類型**設置。對于更高級的表單字段，可以使用[表單窗口小部件](https://octobercms.com/docs/backend/forms#form-widgets)來代替。 * [文本](https://octobercms.com/docs/backend/forms#field-text) * [數](https://octobercms.com/docs/backend/forms#field-number) * [密碼](https://octobercms.com/docs/backend/forms#field-password) * [電子郵件](https://octobercms.com/docs/backend/forms#field-email) * [文字區](https://octobercms.com/docs/backend/forms#field-textarea) * [落下](https://octobercms.com/docs/backend/forms#field-dropdown) * [電臺清單](https://octobercms.com/docs/backend/forms#field-radio) * [氣球選擇器](https://octobercms.com/docs/backend/forms#field-balloon) * [復選框](https://octobercms.com/docs/backend/forms#field-checkbox) * [復選框清單](https://octobercms.com/docs/backend/forms#field-checkboxlist) * [開關](https://octobercms.com/docs/backend/forms#field-switch) * [部分](https://octobercms.com/docs/backend/forms#field-section) * [部分的](https://octobercms.com/docs/backend/forms#field-partial) * [暗示](https://octobercms.com/docs/backend/forms#field-hint) * [小部件](https://octobercms.com/docs/backend/forms#field-widget) ### [](https://octobercms.com/docs/backend/forms#field-text)文本 `text`\-呈現單行文本框。如果未指定，則使用默認類型。 ~~~ blog_title: label: Blog Title type: text ~~~ ### [](https://octobercms.com/docs/backend/forms#field-number)數 `number`\-渲染僅包含數字的單行文本框。 ~~~ your_age: label: Your Age type: number step: 1 # defaults to 'any' min: 1 # defaults to not present max: 100 # defaults to not present ~~~ 如果要在保存時在服務器端驗證此字段以確保其為數字，請使用`$rules`模型上的屬性，如下所示： ~~~ /** * @var array Validation rules */ public $rules = [ 'your_age' => 'numeric', ]; ~~~ 有關模型驗證的更多信息，請訪問[文檔頁面](https://octobercms.com/docs/services/validation#rule-numeric)。 ### [](https://octobercms.com/docs/backend/forms#field-password)密碼 `password`\-呈現單行密碼字段。 ~~~ user_password: label: Password type: password ~~~ ### [](https://octobercms.com/docs/backend/forms#field-email)電子郵件 `email`\-呈現類型為的單行文本框`email`，從而觸發移動瀏覽器中的電子郵件專用鍵盤。 ~~~ user_email: label: Email Address type: email ~~~ 如果您想在保存時驗證此字段以確保它是格式正確的電子郵件地址，請使用`$rules`模型上的屬性，如下所示： ~~~ /** * @var array Validation rules */ public $rules = [ 'user_email' => 'email', ]; ~~~ 有關模型驗證的更多信息，請訪問[文檔頁面](https://octobercms.com/docs/services/validation#rule-email)。 ### [](https://octobercms.com/docs/backend/forms#field-textarea)文字區 `textarea`\-呈現多行文本框。還可以使用可能的值指定大小：微小，較小，較大，巨大，巨大。 ~~~ blog_contents: label: Contents type: textarea size: large ~~~ ### [](https://octobercms.com/docs/backend/forms#field-dropdown)落下 `dropdown`\-使用指定的選項呈現下拉菜單。有6種方式提供下拉選項。第一種方法`options`直接在YAML文件中定義（兩個變體）：（僅值）： ~~~ status_type: label: Blog Post Status type: dropdown default: published options: draft published archived ~~~ （核心價值）： ~~~ status_type: label: Blog Post Status type: dropdown default: published options: draft: Draft published: Published archived: Archived ~~~ 第二種方法使用在模型類中聲明的方法定義選項。如果省略options元素，則框架期望使用`get*FieldName*Options`在模型中定義名稱的方法。使用上面的示例，模型應具有該`getStatusTypeOptions`方法。此方法的第一個參數是該字段的當前值，第二個參數是整個表單的當前數據對象。此方法應以格式**key => label**返回一個選項數組。 ~~~ status_type: label: Blog Post Status type: dropdown ~~~ 在模型類中提供下拉選項： ~~~ public function getStatusTypeOptions($value, $formData) { return ['all' => 'All', ...]; } ~~~ `getDropdownOptions`也可以在模型中定義第三個全局方法，該方法將用于模型的所有下拉字段類型。此方法的第一個參數是字段名稱，第二個參數是字段的當前值，第三個參數是整個表單的當前數據對象。它應該以格式**key => label**返回一個選項數組。 ~~~ public function getDropdownOptions($fieldName, $value, $formData) { if ($fieldName == 'status') { return ['all' => 'All', ...]; } else { return ['' => '-- none --']; } } ~~~ 第四個方法使用在模型類中聲明的特定方法。在下一個示例中，`listStatuses`方法應在模型類中定義。此方法接收與該方法相同的所有參數`getDropdownOptions`，并應以格式**key => label**的形式返回選項數組。 ~~~ status: label: Blog Post Status type: dropdown options: listStatuses ~~~ 為模型類提供下拉選項： ~~~ public function listStatuses($fieldName, $value, $formData) { return ['published' => 'Published', ...]; } ~~~ 第五個方法允許您在類上指定靜態方法以返回選項： ~~~ status: label: Blog Post Status type: dropdown options: \MyAuthor\MyPlugin\Classes\FormHelper::staticMethodOptions ~~~ 為模型類提供下拉選項： ~~~ public static function staticMethodOptions($fieldName, $value, $formData) { return ['published' => 'Published', ...]; } ~~~ 第六個方法允許您通過數組定義指定可調用對象。如果使用PHP，則可以提供一個數組，其中第一個元素是對象，第二個元素是要在該對象上調用的方法。如果您使用的是YAML，則只能將靜態方法定義為第二個元素，并將對類的命名空間引用作為第一個元素： ~~~ status: label: Blog Post Status type: dropdown options: [\MyAuthor\MyPlugin\ClassesFormHelper, staticMethodOptions] ~~~ 為模型類提供下拉選項： ~~~ public static function staticMethodOptions($fieldName, $value, $formData) { return ['published' => 'Published', ...]; } ~~~ 要定義沒有選擇時的行為，您可以指定一個`emptyOption`值以包含可以重新選擇的空選項。 ~~~ status: label: Blog Post Status type: dropdown emptyOption: -- no status -- ~~~ 或者，您可以使用該`placeholder`選項來使用無法單選的“單向”空選項。 ~~~ status: label: Blog Post Status type: dropdown placeholder: -- select a status -- ~~~ 默認情況下，下拉菜單具有搜索功能，可以快速選擇一個值。可以通過將`showSearch`選項設置為禁用此功能`false`。 ~~~ status: label: Blog Post Status type: dropdown showSearch: false ~~~ ### [](https://octobercms.com/docs/backend/forms#field-radio)電臺清單 `radio`\-呈現一個單選選項列表，一次只能選擇一項。 ~~~ security_level: label: Access Level type: radio default: guests options: all: All registered: Registered only guests: Guests only ~~~ 單選列表還可以支持輔助描述。 ~~~ security_level: label: Access Level type: radio options: all: [All, Guests and customers will be able to access this page.] registered: [Registered only, Only logged in member will be able to access this page.] guests: [Guests only, Only guest users will be able to access this page.] ~~~ 單選列表支持將選項定義為[下拉字段類型](https://octobercms.com/docs/backend/forms#field-dropdown)的相同方法。對于單選列表，該方法可以返回簡單數組：**key => value**或用于提供描述的數組數組：**key => \[label，description\]**。通過`cssClass: 'inline-options'`在單選字段配置中指定，選項可以彼此內聯顯示，而不是單獨顯示。 ### [](https://octobercms.com/docs/backend/forms#field-balloon)氣球選擇器 `balloon-selector`\-呈現一個列表，一次只能選擇一項。 ~~~ gender: label: Gender type: balloon-selector default: female options: female: Female male: Male ~~~ 氣球選擇器支持與[下拉字段類型](https://octobercms.com/docs/backend/forms#field-dropdown)相同的方法來定義選項。 ### [](https://octobercms.com/docs/backend/forms#field-checkbox)復選框 `checkbox`\-呈現一個復選框。 ~~~ show_content: label: Display content type: checkbox default: true ~~~ ### [](https://octobercms.com/docs/backend/forms#field-checkboxlist)復選框清單 `checkboxlist`\-呈現復選框列表。 ~~~ permissions: label: Permissions type: checkboxlist # set to true to explicitly enable the "Select All", "Select None" options # on lists that have <=10 items (>10 automatically enables it) quickselect: true default: open_account options: open_account: Open account close_account: Close account modify_account: Modify account ~~~ 復選框列表支持將選項定義為[下拉字段類型](https://octobercms.com/docs/backend/forms#field-dropdown)的相同方法，還支持在[單選字段類型中](https://octobercms.com/docs/backend/forms#field-radio)找到的輔助描述。通過`cssClass: 'inline-options'`在復選框列表字段config中指定，選項可以彼此內聯顯示，而不是單獨顯示。 ### [](https://octobercms.com/docs/backend/forms#field-switch)開關 `switch`\-呈現一個開關箱。 ~~~ show_content: label: Display content type: switch comment: Flick this switch to display content on: myauthor.myplugin::lang.models.mymodel.show_content.on off: myauthor.myplugin::lang.models.mymodel.show_content.off ~~~ ### [](https://octobercms.com/docs/backend/forms#field-section)部分 `section`\-呈現節標題和副標題。該`label`和`comment`值是可選的，包含標題和副標題的內容。 ~~~ user_details_section: label: User details type: section comment: This section contains details about the user. ~~~ ### [](https://octobercms.com/docs/backend/forms#field-partial)部分的 `partial`\-渲染部分，該`path`值可以引用部分視圖文件，否則，將字段名稱用作部分名稱。在部分變量中，這些變量可用：`$value`是默認字段值，`$model`是用于字段的模型，`$field`是配置的類對象`Backend\Classes\FormField`。 ~~~ content: type: partial path: $/acme/blog/models/comments/_content_field.htm ~~~ ### [](https://octobercms.com/docs/backend/forms#field-hint)暗示 `hint`\-與`partial`字段相同，但在提示容器內部呈現，用戶可以將其隱藏。 ~~~ content: type: hint path: content_field ~~~ ### [](https://octobercms.com/docs/backend/forms#field-widget)小部件 `widget`\-呈現自定義表單窗口小部件，該`type`字段可以直接引用該窗口小部件的類名或注冊的別名。 ~~~ blog_content: type: Backend\FormWidgets\RichEditor size: huge ~~~ ### [](https://octobercms.com/docs/backend/forms#validate-form-fields)驗證表單字段要驗證表單的字段，您可以在模型中使用[Validation](https://octobercms.com/docs/database/traits#validation)特性。