Drupal 7 Form API 的提交流程控制是開發者常見痛點:表單提交後導向、destination 參數干擾、多步驟表單狀態保持。本文系統解決這三大核心問題,提供可直接套用的模式與代碼範本。
| 屬性 | 型別 | 用途 |
|---|---|---|
| $form_state['redirect'] | string|array|FALSE | 提交後導向目標,FALSE 表示不導向(留在當頁) |
| $form_state['rebuild'] | bool | TRUE 重建表單(多步驟、AJAX、動態欄位) |
| $form_state['storage'] | array | 跨請求持久化資料(多步驟表單核心) |
| $form_state['values'] | array | 使用者提交的表單值 |
| $form_state['input'] | array | 原始輸入(含未驗證資料) |
<?php
function mymodule_form_submit($form, &$form_state) {
// 1. 簡單路徑導向
$form_state['redirect'] = 'node/123';
// 2. 帶查詢參數與錨點
$form_state['redirect'] = [
'node/123',
[
'query' => ['tab' => 'edit', 'msg' => 'saved'],
'fragment' => 'content',
],
];
// 導向:node/123?tab=edit&msg=saved#content
// 3. 導向外部 URL
$form_state['redirect'] = 'https://example.com/thankyou';
// 4. 禁止導向(停留在表單頁,顯示訊息)
$form_state['redirect'] = FALSE;
drupal_set_message(t('資料已儲存,繼續編輯。'));
}
問題:URL 帶 `?destination=admin/content` 時,`drupal_goto()` 優先導向 destination,忽略 `$form_state['redirect']`。
<?php
function mymodule_form_submit($form, &$form_state) {
// 刪除 $_GET['destination'],讓 redirect 生效
if (isset($_GET['destination'])) {
unset($_GET['destination']);
}
// 也要清除 request 物件(Drupal 7 無 Request 物件,但可清除 $_REQUEST)
unset($_REQUEST['destination']);
$form_state['redirect'] = 'custom/path';
}
<?php
function mymodule_form_submit($form, &$form_state) {
if (isset($_GET['destination'])) {
// 將原 destination 保留為查詢參數,導向新頁面
$destination = $_GET['destination'];
$form_state['redirect'] = [
'next/step',
['query' => ['destination' => $destination]],
];
unset($_GET['destination']);
}
}
<?php
function mymodule_form($form, &$form_state) {
$form['actions']['save'] = [
'#type' => 'submit',
'#value' => t('儲存並繼續編輯'),
'#submit' => ['mymodule_form_save_continue_submit'],
];
$form['actions']['save_exit'] = [
'#type' => 'submit',
'#value' => t('儲存並返回列表'),
'#submit' => ['mymodule_form_save_exit_submit'],
];
return $form;
}
function mymodule_form_save_continue_submit($form, &$form_state) {
// 刪除 destination,導向當前編輯頁
unset($_GET['destination'], $_REQUEST['destination']);
$form_state['redirect'] = "node/{$form_state['values']['nid']}/edit";
}
function mymodule_form_save_exit_submit($form, &$form_state) {
// 保留 destination 或導向列表頁
$form_state['redirect'] = 'admin/content';
}
<?php
function mymodule_multistep_form($form, &$form_state) {
// 步驟狀態機
$steps = ['step1' => '基本資料', 'step2' => '詳細設定', 'step3' => '確認送出'];
$currentStep = $form_state['storage']['step'] ?? 'step1';
// 共同欄位
$form['progress'] = [
'#markup' => theme('progress_bar', ['percent' => array_search($currentStep, array_keys($steps)) / (count($steps)-1) * 100]),
'#weight' => -10,
];
// 步驟 1:基本資料
if ($currentStep === 'step1') {
$form['title'] = [
'#type' => 'textfield',
'#title' => t('標題'),
'#required' => TRUE,
'#default_value' => $form_state['storage']['values']['title'] ?? '',
];
$form['type'] = [
'#type' => 'select',
'#title' => t('類型'),
'#options' => ['article' => '文章', 'page' => '單頁'],
'#default_value' => $form_state['storage']['values']['type'] ?? 'article',
];
}
// 步驟 2:詳細設定
elseif ($currentStep === 'step2') {
$form['body'] = [
'#type' => 'textarea',
'#title' => t('內容'),
'#default_value' => $form_state['storage']['values']['body'] ?? '',
];
$form['tags'] = [
'#type' => 'textfield',
'#title' => t('標籤(逗號分隔)'),
'#default_value' => $form_state['storage']['values']['tags'] ?? '',
];
}
// 步驟 3:確認預覽
elseif ($currentStep === 'step3') {
$vals = $form_state['storage']['values'];
$form['preview'] = [
'#markup' => "{$vals['title']}
類型: {$vals['type']}
{$vals['body']}",
];
}
// 導航按鈕
$form['actions'] = ['#type' => 'actions'];
$isFirst = ($currentStep === 'step1');
$isLast = ($currentStep === 'step3');
if (!$isFirst) {
$form['actions']['prev'] = [
'#type' => 'submit',
'#value' => t('上一步'),
'#submit' => ['mymodule_multistep_prev_submit'],
'#limit_validation_errors' => [], // 上一步不驗證
];
}
if (!$isLast) {
$form['actions']['next'] = [
'#type' => 'submit',
'#value' => t('下一步'),
'#submit' => ['mymodule_multistep_next_submit'],
];
} else {
$form['actions']['submit'] = [
'#type' => 'submit',
'#value' => t('確認送出'),
'#submit' => ['mymodule_multistep_final_submit'],
];
}
$form['actions']['cancel'] = [
'#type' => 'submit',
'#value' => t('取消'),
'#submit' => ['mymodule_multistep_cancel_submit'],
'#limit_validation_errors' => [],
];
return $form;
}
// 共用驗證:只驗證當前步驟欄位
function mymodule_multistep_form_validate($form, &$form_state) {
$step = $form_state['storage']['step'] ?? 'step1';
$trigger = $form_state['triggering_element']['#name'] ?? '';
// 上一步、取消不驗證
if (in_array($trigger, ['prev', 'cancel'])) return;
if ($step === 'step1') {
if (empty($form_state['values']['title'])) {
form_set_error('title', t('標題為必填'));
}
}
}
// 下一步:儲存值、推進步驟、重建表單
function mymodule_multistep_next_submit($form, &$form_state) {
_mymodule_multistep_save_values($form_state);
$steps = ['step1', 'step2', 'step3'];
$current = array_search($form_state['storage']['step'], $steps);
$form_state['storage']['step'] = $steps[$current + 1];
$form_state['rebuild'] = TRUE; // 關鍵:重建表單顯示下一步
}
// 上一步:儲存值、退回步驟、重建表單
function mymodule_multistep_prev_submit($form, &$form_state) {
_mymodule_multistep_save_values($form_state);
$steps = ['step1', 'step2', 'step3'];
$current = array_search($form_state['storage']['step'], $steps);
$form_state['storage']['step'] = $steps[$current - 1];
$form_state['rebuild'] = TRUE;
}
// 儲存當前步驟值到 storage
function _mymodule_multistep_save_values(&$form_state) {
$step = $form_state['storage']['step'];
foreach ($form_state['values'] as $key => $value) {
if (!in_array($key, ['form_id', 'form_token', 'form_build_id', 'op', 'prev', 'next', 'submit', 'cancel'])) {
$form_state['storage']['values'][$key] = $value;
}
}
}
// 最終送出
function mymodule_multistep_final_submit($form, &$form_state) {
_mymodule_multistep_save_values($form_state);
$values = $form_state['storage']['values'];
// 實際儲存邏輯
$nid = db_insert('node')->fields([
'title' => $values['title'],
'type' => $values['type'],
'body' => $values['body'],
'uid' => $GLOBALS['user']->uid,
'created' => REQUEST_TIME,
])->execute();
drupal_set_message(t('已建立節點 @nid', ['@nid' => $nid]));
$form_state['redirect'] = "node/$nid";
// 清除 storage
unset($form_state['storage']);
}
// 取消
function mymodule_multistep_cancel_submit($form, &$form_state) {
unset($form_state['storage']);
$form_state['redirect'] = 'admin/content';
}
<?php
// 下一步按鈕使用 AJAX 部分重建
$form['actions']['next'] = [
'#type' => 'submit',
'#value' => t('下一步'),
'#ajax' => [
'callback' => 'mymodule_multistep_ajax_callback',
'wrapper' => 'multistep-form-wrapper',
'method' => 'replace',
'effect' => 'fade',
],
'#submit' => ['mymodule_multistep_next_submit'],
];
// 表單包裝器
$form['#prefix'] = '';
$form['#suffix'] = '';
function mymodule_multistep_ajax_callback($form, $form_state) {
return $form; // 回傳整個重建後的表單
}