表單輔助函數 · CodeIgniter3.0 中文用戶指南

# 表單輔助函數表單輔助函數包含了一些函數用于幫助你處理表單。 [TOC=2,3] ## [加載輔助函數](http://codeigniter.org.cn/user_guide/helpers/form_helper.html#id5) 使用下面的代碼來加載表單輔助函數: ~~~ $this->load->helper('form'); ~~~ ## [對域值轉義](http://codeigniter.org.cn/user_guide/helpers/form_helper.html#id6) 你可能會需要在表單元素中使用 HTML 或者諸如引號這樣的字符，為了安全性，你需要使用?[通用函數](http://codeigniter.org.cn/user_guide/general/common_functions.html)?html_escape()?。考慮下面這個例子: ~~~ $string = 'Here is a string containing "quoted" text.'; <input type="text" name="myfield" value="<?php echo $string; ?>" /> ~~~ 因為上面的字符串中包含了一對引號，它會破壞表單，使用?[html_escape()](http://codeigniter.org.cn/user_guide/general/common_functions.html#html_escape "html_escape")?函數可以對 HTML 的特殊字符進行轉義，從而可以安全的在域值中使用字符串: ~~~ <input type="text" name="myfield" value="<?php echo html_escape($string); ?>" /> ~~~ 注解如果你使用了這個頁面上介紹的任何一個函數，表單的域值會被自動轉義，所以你無需再調用這個函數。只有在你創建自己的表單元素時需要使用它。 ## [可用函數](http://codeigniter.org.cn/user_guide/helpers/form_helper.html#id7) 該輔助函數有下列可用函數： form_open([$action = ''[,?$attributes = ''[,?$hidden = array()]]]) 參數: * **$action**?(string) -- Form action/target URI string * **$attributes**?(array) -- HTML attributes * **$hidden**?(array) -- An array of hidden fields' definitions 返回: An HTML form opening tag 返回類型: string 生成一個 form 起始標簽，并且它的 action URL 會根據你的配置文件自動生成。你還可以給表單添加屬性和隱藏域，另外，它還會根據你配置文件中的字符集參數自動生成?accept-charset?屬性。使用該函數來生成標簽比你自己寫 HTML 代碼最大的好處是：當你的 URL 變動時，它可以提供更好的可移植性。這里是個簡單的例子: ~~~ echo form_open('email/send'); ~~~ 上面的代碼會創建一個表單，它的 action 為根 URL 加上 "email/send"，向下面這樣: ~~~ <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send"> ~~~ **添加屬性** > > > 可以通過第二個參數傳遞一個關聯數組來添加屬性，例如: > > > > > > ~~~ > $attributes = array('class' => 'email', 'id' => 'myform'); > echo form_open('email/send', $attributes); > ~~~ > > > > > > 另外，第二個參數你也可以直接使用字符串: > > > > > > ~~~ > echo form_open('email/send', 'class="email" id="myform"'); > ~~~ > > > > > > 上面的代碼會創建一個類似于下面的表單: > > > > > > ~~~ > <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send" class="email" id="myform"> > ~~~ > > > > > > **添加隱藏域** > > > 可以通過第三個參數傳遞一個關聯數組來添加隱藏域，例如: > > > > > > ~~~ > $hidden = array('username' => 'Joe', 'member_id' => '234'); > echo form_open('email/send', '', $hidden); > ~~~ > > > > > > 你可以使用一個空值跳過第二個參數。 > > 上面的代碼會創建一個類似于下面的表單: > > > > > > ~~~ > <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send"> > <input type="hidden" name="username" value="Joe" /> > <input type="hidden" name="member_id" value="234" /> > ~~~ > > > > > > form_open_multipart([$action = ''[, $attributes = array()[, $hidden = array()]]) 參數: * **$action**?(string) -- Form action/target URI string * **$attributes**?(array) -- HTML attributes * **$hidden**?(array) -- An array of hidden fields' definitions 返回: An HTML multipart form opening tag 返回類型: string 這個函數和上面的?[form_open()](http://codeigniter.org.cn/user_guide/helpers/form_helper.html#form_open "form_open")?函數完全一樣，只是它會給表單添加一個?multipart?屬性，在你使用表單上傳文件時必須使用它。 form_hidden($name[,?$value = '']) 參數: * **$name**?(string) -- Field name * **$value**?(string) -- Field value 返回: An HTML hidden input field tag 返回類型: string 生成隱藏域。你可以使用名稱和值兩個參數來創建一個隱藏域: ~~~ form_hidden('username', 'johndoe'); // Would produce: <input type="hidden" name="username" value="johndoe" /> ~~~ ... 或者你可以使用一個關聯數組，來生成多個隱藏域: ~~~ $data = array( 'name' => 'John Doe', 'email' => 'john@example.com', 'url' => 'http://example.com' ); echo form_hidden($data); /* Would produce: <input type="hidden" name="name" value="John Doe" /> <input type="hidden" name="email" value="john@example.com" /> <input type="hidden" name="url" value="http://example.com" /> */ ~~~ 你還可以向第二個參數傳遞一個關聯數組: ~~~ $data = array( 'name' => 'John Doe', 'email' => 'john@example.com', 'url' => 'http://example.com' ); echo form_hidden('my_array', $data); /* Would produce: <input type="hidden" name="my_array[name]" value="John Doe" /> <input type="hidden" name="my_array[email]" value="john@example.com" /> <input type="hidden" name="my_array[url]" value="http://example.com" /> */ ~~~ 如果你想創建帶有其他屬性的隱藏域，可以這樣: ~~~ $data = array( 'type' => 'hidden', 'name' => 'email', 'id' => 'hiddenemail', 'value' => 'john@example.com', 'class' => 'hiddenemail' ); echo form_input($data); /* Would produce: <input type="hidden" name="email" value="john@example.com" id="hiddenemail" class="hiddenemail" /> */ ~~~ form_input([$data = ''[, $value = ''[, $extra = '']]) 參數: * **$data**?(array) -- Field attributes data * **$value**?(string) -- Field value * **$extra**?(string) -- Extra attributes to be added to the tag?as is 返回: An HTML text input field tag 返回類型: string 用于生成標準的文本輸入框，你可以簡單的使用文本域的名稱和值: ~~~ echo form_input('username', 'johndoe'); ~~~ 或者使用一個關聯數組，來包含任何你想要的數據: ~~~ $data = array( 'name' => 'username', 'id' => 'username', 'value' => 'johndoe', 'maxlength' => '100', 'size' => '50', 'style' => 'width:50%' ); echo form_input($data); /* Would produce: <input type="text" name="username" value="johndoe" id="username" maxlength="100" size="50" style="width:50%" /> */ ~~~ 如果你還希望能包含一些額外的數據，譬如 JavaScript ，你可以通過第三個參數傳一個字符串: ~~~ $js = 'onClick="some_function()"'; echo form_input('username', 'johndoe', $js); ~~~ form_password([$data = ''[,?$value = ''[,?$extra = '']]]) 參數: * **$data**?(array) -- Field attributes data * **$value**?(string) -- Field value * **$extra**?(string) -- Extra attributes to be added to the tag?as is 返回: An HTML password input field tag 返回類型: string 該函數和上面的?form_input()?函數一樣，只是生成的輸入框為 "password" 類型。 form_upload([$data = ''[,?$value = ''[,?$extra = '']]]) 參數: * **$data**?(array) -- Field attributes data * **$value**?(string) -- Field value * **$extra**?(string) -- Extra attributes to be added to the tag?as is 返回: An HTML file upload input field tag 返回類型: string 該函數和上面的?form_input()?函數一樣，只是生成的輸入框為 "file" 類型，可以用來上傳文件。 form_textarea([$data = ''[,?$value = ''[,?$extra = '']]]) 參數: * **$data**?(array) -- Field attributes data * **$value**?(string) -- Field value * **$extra**?(string) -- Extra attributes to be added to the tag?as is 返回: An HTML textarea tag 返回類型: string 該函數和上面的?form_input()?函數一樣，只是生成的輸入框為 "textarea" 類型。注解對于 textarea 類型的輸入框，你可以使用?rows?和?cols?屬性，來代替上面例子中的?maxlength?和?size?屬性。 form_dropdown([$name = ''[,?$options = array()[,?$selected = array()[,?$extra = '']]]]) 參數: * **$name**?(string) -- Field name * **$options**?(array) -- An associative array of options to be listed * **$selected**?(array) -- List of fields to mark with the?selected?attribute * **$extra**?(string) -- Extra attributes to be added to the tag?as is 返回: An HTML dropdown select field tag 返回類型: string 用于生成一個標準的下拉框域。第一個參數為域的名稱，第二個參數為一個關聯數組，包含所有的選項，第三個參數為你希望默認選中的值。你也可以把第三個參數設置成一個包含多個值的數組，CodeIgniter 將會為你生成多選下拉框。例如: ~~~ $options = array( 'small' => 'Small Shirt', 'med' => 'Medium Shirt', 'large' => 'Large Shirt', 'xlarge' => 'Extra Large Shirt', ); $shirts_on_sale = array('small', 'large'); echo form_dropdown('shirts', $options, 'large'); /* Would produce: <select name="shirts"> <option value="small">Small Shirt</option> <option value="med">Medium Shirt</option> <option value="large" selected="selected">Large Shirt</option> <option value="xlarge">Extra Large Shirt</option> </select> */ echo form_dropdown('shirts', $options, $shirts_on_sale); /* Would produce: <select name="shirts" multiple="multiple"> <option value="small" selected="selected">Small Shirt</option> <option value="med">Medium Shirt</option> <option value="large" selected="selected">Large Shirt</option> <option value="xlarge">Extra Large Shirt</option> </select> */ ~~~ 如果你希望為起始標簽添加一些額外的數據，例如 id 屬性或 JavaScript ，你可以通過第四個參數傳一個字符串: ~~~ $js = 'id="shirts" onChange="some_function();"'; echo form_dropdown('shirts', $options, 'large', $js); ~~~ 如果你傳遞的?$options?數組是個多維數組，form_dropdown()?函數將會生成帶的下拉框，并使用數組的鍵作為 label 。 form_multiselect([$name = ''[,?$options = array()[,?$selected = array()[,?$extra = '']]]]) 參數: * **$name**?(string) -- Field name * **$options**?(array) -- An associative array of options to be listed * **$selected**?(array) -- List of fields to mark with the?selected?attribute * **$extra**?(string) -- Extra attributes to be added to the tag?as is 返回: An HTML dropdown multiselect field tag 返回類型: string 用于生成一個標準的多選下拉框。第一個參數為域的名稱，第二個參數為一個關聯數組，包含所有的選項，第三個參數為你希望默認選中的一個或多個值。參數的用法和上面的?[form_dropdown()](http://codeigniter.org.cn/user_guide/helpers/form_helper.html#form_dropdown "form_dropdown")?函數一樣，只是域的名稱需要使用數組語法，例如：foo[] form_fieldset([$legend_text = ''[,?$attributes = array()]]) 參數: * **$legend_text**?(string) -- Text to put in the tag * **$attributes**?(array) -- Attributes to be set on the tag 返回: An HTML fieldset opening tag 返回類型: string 用于生成 fieldset 和 legend 域。例如: ~~~ echo form_fieldset('Address Information'); echo "<p>fieldset content here</p>\n"; echo form_fieldset_close(); /* Produces: <fieldset> <legend>Address Information</legend> <p>form content here</p> </fieldset> */ ~~~ 和其他的函數類似，你也可以通過給第二個參數傳一個關聯數組來添加額外的屬性: ~~~ $attributes = array( 'id' => 'address_info', 'class' => 'address_info' ); echo form_fieldset('Address Information', $attributes); echo "<p>fieldset content here</p>\n"; echo form_fieldset_close(); /* Produces: <fieldset id="address_info" class="address_info"> <legend>Address Information</legend> <p>form content here</p> </fieldset> */ ~~~ form_fieldset_close([$extra = '']) 參數: * **$extra**?(string) -- Anything to append after the closing tag,?as is 返回: An HTML fieldset closing tag 返回類型: string 用于生成結束標簽，使用這個函數唯一的一個好處是，它可以在結束標簽的后面加上一些其他的數據。例如： ~~~ $string = '</div></div>'; echo form_fieldset_close($string); // Would produce: </fieldset></div></div> ~~~ form_checkbox([$data = ''[,?$value = ''[,?$checked = FALSE[,?$extra = '']]]]) 參數: * **$data**?(array) -- Field attributes data * **$value**?(string) -- Field value * **$checked**?(bool) -- Whether to mark the checkbox as being?checked * **$extra**?(string) -- Extra attributes to be added to the tag?as is 返回: An HTML checkbox input tag 返回類型: string 用于生成一個復選框，例如: ~~~ echo form_checkbox('newsletter', 'accept', TRUE); // Would produce: <input type="checkbox" name="newsletter" value="accept" checked="checked" /> ~~~ 第三個參數為布爾值 TRUE 或 FALSE ，用于指定復選框默認是否為選定狀態。和其他函數一樣，你可以傳一個屬性的數組給它: ~~~ $data = array( 'name' => 'newsletter', 'id' => 'newsletter', 'value' => 'accept', 'checked' => TRUE, 'style' => 'margin:10px' ); echo form_checkbox($data); // Would produce: <input type="checkbox" name="newsletter" id="newsletter" value="accept" checked="checked" style="margin:10px" /> ~~~ 另外，如果你希望向標簽中添加額外的數據如 JavaScript ，也可以傳一個字符串給第四個參數: ~~~ $js = 'onClick="some_function()"'; echo form_checkbox('newsletter', 'accept', TRUE, $js) ~~~ form_radio([$data = ''[,?$value = ''[,?$checked = FALSE[,?$extra = '']]]]) 參數: * **$data**?(array) -- Field attributes data * **$value**?(string) -- Field value * **$checked**?(bool) -- Whether to mark the radio button as being?checked * **$extra**?(string) -- Extra attributes to be added to the tag?as is 返回: An HTML radio input tag 返回類型: string 該函數和?[form_checkbox()](http://codeigniter.org.cn/user_guide/helpers/form_helper.html#form_checkbox "form_checkbox")?函數完全一樣，只是它生成的是單選框。 form_label([$label_text = ''[,?$id = ''[,?$attributes = array()]]]) 參數: * **$label_text**?(string) -- Text to put in the tag * **$id**?(string) -- ID of the form element that we're making a label for * **$attributes**?(string) -- HTML attributes 返回: An HTML field label tag 返回類型: string 生成標簽，例如: ~~~ echo form_label('What is your Name', 'username'); // Would produce: <label for="username">What is your Name</label> ~~~ 和其他的函數一樣，如果你想添加額外的屬性的話，可以傳一個關聯數組給第三個參數。例如: ~~~ $attributes = array( 'class' => 'mycustomclass', 'style' => 'color: #000;' ); echo form_label('What is your Name', 'username', $attributes); // Would produce: <label for="username" class="mycustomclass" style="color: #000;">What is your Name</label> ~~~ form_submit([$data = ''[,?$value = ''[,?$extra = '']]]) 參數: * **$data**?(string) -- Button name * **$value**?(string) -- Button value * **$extra**?(string) -- Extra attributes to be added to the tag?as is 返回: An HTML input submit tag 返回類型: string 用于生成一個標準的提交按鈕。例如: ~~~ echo form_submit('mysubmit', 'Submit Post!'); // Would produce: <input type="submit" name="mysubmit" value="Submit Post!" /> ~~~ 和其他的函數一樣，如果你想添加額外的屬性的話，可以傳一個關聯數組給第一個參數，第三個參數可以向表單添加額外的數據，例如 JavaScript 。 form_reset([$data = ''[,?$value = ''[,?$extra = '']]]) 參數: * **$data**?(string) -- Button name * **$value**?(string) -- Button value * **$extra**?(string) -- Extra attributes to be added to the tag?as is 返回: An HTML input reset button tag 返回類型: string 用于生成一個標準的重置按鈕。用法和?form_submit()?函數一樣。 form_button([$data = ''[,?$content = ''[,?$extra = '']]]) 參數: * **$data**?(string) -- Button name * **$content**?(string) -- Button label * **$extra**?(string) -- Extra attributes to be added to the tag?as is 返回: An HTML button tag 返回類型: string 用于生成一個標準的按鈕，你可以簡單的使用名稱和內容來生成按鈕: ~~~ echo form_button('name','content'); // Would produce: <button name="name" type="button">Content</button> ~~~ 或者使用一個關聯數組，來包含任何你想要的數據: ~~~ $data = array( 'name' => 'button', 'id' => 'button', 'value' => 'true', 'type' => 'reset', 'content' => 'Reset' ); echo form_button($data); // Would produce: <button name="button" id="button" value="true" type="reset">Reset</button> ~~~ 如果你還希望能包含一些額外的數據，譬如 JavaScript ，你可以通過第三個參數傳一個字符串: ~~~ $js = 'onClick="some_function()"'; echo form_button('mybutton', 'Click Me', $js); ~~~ form_close([$extra = '']) 參數: * **$extra**?(string) -- Anything to append after the closing tag,?as is 返回: An HTML form closing tag 返回類型:string 用于生成結束標簽，使用這個函數唯一的一個好處是，它可以在結束標簽的后面加上一些其他的數據。例如： > $string = ''; echo form_close($string); // Would produce: set_value($field[,?$default = ''[,?$html_escape = TRUE]]) 參數: * **$field**?(string) -- Field name * **$default**?(string) -- Default value * **$html_escape**?(bool) -- Whether to turn off HTML escaping of the value 返回: Field value 返回類型: string 用于你顯示 input 或者 textarea 類型的輸入框的值。你必須在第一個參數中指定名稱，第二個參數是可選的，允許你設置一個默認值，第三個參數也是可選，可以禁用對值的轉義，當你在和?form_input()?函數一起使用時，可以避免重復轉義。例如: ~~~ <input type="text" name="quantity" value="<?php echo set_value('quantity', '0'); ?>" size="50" /> ~~~ 當上面的表單元素第一次加載時將會顯示 "0" 。 set_select($field[,?$value = ''[,?$default = FALSE]]) 參數: * **$field**?(string) -- Field name * **$value**?(string) -- Value to check for * **$default**?(string) -- Whether the value is also a default one 返回: 'selected' attribute or an empty string 返回類型: string 如果你使用下拉菜單，此函數允許你顯示選中的菜單項。第一個參數為下拉菜單的名稱，第二個參數必須包含每個菜單項的值。第三個參數是可選的，用于設置菜單項是否為默認選中狀態（TRUE / FALSE）。例如: ~~~ <select name="myselect"> <option value="one" <?php echo set_select('myselect', 'one', TRUE); ?> >One</option> <option value="two" <?php echo set_select('myselect', 'two'); ?> >Two</option> <option value="three" <?php echo set_select('myselect', 'three'); ?> >Three</option> </select> ~~~ set_checkbox($field[,?$value = ''[,?$default = FALSE]]) 參數: * **$field**?(string) -- Field name * **$value**?(string) -- Value to check for * **$default**?(string) -- Whether the value is also a default one 返回: 'checked' attribute or an empty string 返回類型: string 允許你顯示一個處于提交狀態的復選框。第一個參數必須包含此復選框的名稱，第二個參數必須包含它的值，第三個參數是可選的，用于設置復選框是否為默認選中狀態（TRUE / FALSE）。例如: ~~~ <input type="checkbox" name="mycheck" value="1" <?php echo set_checkbox('mycheck', '1'); ?> /> <input type="checkbox" name="mycheck" value="2" <?php echo set_checkbox('mycheck', '2'); ?> /> ~~~ set_radio($field[,?$value = ''[,?$default = FALSE]]) 參數: * **$field**?(string) -- Field name * **$value**?(string) -- Value to check for * **$default**?(string) -- Whether the value is also a default one 返回: 'checked' attribute or an empty string 返回類型: string 允許你顯示那些處于提交狀態的單選框。該函數和上面的?[set_checkbox()](http://codeigniter.org.cn/user_guide/helpers/form_helper.html#set_checkbox "set_checkbox")?函數一樣。例如: ~~~ <input type="radio" name="myradio" value="1" <?php echo set_radio('myradio', '1', TRUE); ?> /> <input type="radio" name="myradio" value="2" <?php echo set_radio('myradio', '2'); ?> /> ~~~ 注解如果你正在使用表單驗證類，你必須為你的每一個表單域指定一個規則，即使是空的，這樣可以確保?set_*()?函數能正常運行。這是因為如果定義了一個表單驗證對象，set_*()?函數的控制權將移交到表單驗證類，而不是輔助函數函數。 form_error([$field = ''[,?$prefix = ''[,?$suffix = '']]]) 參數: * **$field**?(string) -- Field name * **$prefix**?(string) -- Error opening tag * **$suffix**?(string) -- Error closing tag 返回: HTML-formatted form validation error message(s) 返回類型: string 從?[表單驗證類](http://codeigniter.org.cn/user_guide/libraries/form_validation.html)?返回驗證錯誤消息，并附上驗證出錯的域的名稱，你可以設置錯誤消息的起始和結束標簽。例如: ~~~ // Assuming that the 'username' field value was incorrect: echo form_error('myfield', '<div class="error">', '</div>'); // Would produce: <div class="error">Error message associated with the "username" field.</div> ~~~ validation_errors([$prefix = ''[,?$suffix = '']]) 參數: * **$prefix**?(string) -- Error opening tag * **$suffix**?(string) -- Error closing tag 返回: HTML-formatted form validation error message(s) 返回類型: string 和?[form_error()](http://codeigniter.org.cn/user_guide/helpers/form_helper.html#form_error "form_error")?函數類似，返回所有?[表單驗證類](http://codeigniter.org.cn/user_guide/libraries/form_validation.html)?生成的錯誤信息，你可以為為每個錯誤消息設置起始和結束標簽。例如: ~~~ echo validation_errors('<span class="error">', '</span>'); /* Would produce, e.g.: <span class="error">The "email" field doesn't contain a valid e-mail address!</span> <span class="error">The "password" field doesn't match the "repeat_password" field!</span> */ ~~~ form_prep($str) 參數: * **$str**?(string) -- Value to escape 返回: Escaped value 返回類型: string 允許你在表單元素中安全的使用 HTML 和譬如引號這樣的字符，而不用擔心對表單造成破壞。注解如果你使用了這個頁面上介紹的任何一個函數，表單的域值會被自動轉義，所以你無需再調用這個函數。只有在你創建自己的表單元素時需要使用它。注解該函數已經廢棄，現在只是?[通用函數](http://codeigniter.org.cn/user_guide/general/common_functions.html)?html_escape()?的一個別名，請使用?html_escape()?代替它。