萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

Drupal 7 表單 API 進階:Redirect、Destination 控制與多步驟表單實作

Drupal 7 Form API 的提交流程控制是開發者常見痛點:表單提交後導向、destination 參數干擾、多步驟表單狀態保持。本文系統解決這三大核心問題,提供可直接套用的模式與代碼範本。

核心概念:$form_state 的關鍵屬性

屬性型別用途
$form_state['redirect']string|array|FALSE提交後導向目標,FALSE 表示不導向(留在當頁)
$form_state['rebuild']boolTRUE 重建表單(多步驟、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('資料已儲存,繼續編輯。'));
}

場景二:覆蓋 Destination 參數強制導向

問題:URL 帶 `?destination=admin/content` 時,`drupal_goto()` 優先導向 destination,忽略 `$form_state['redirect']`。

解決方案 A:Submit 中移除 destination

<?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';
}

解決方案 B:保留 destination 但改變導向目標

<?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']);
    }
}

解決方案 C:按鈕層級控制(多按鈕表單)

<?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'; }

進階技巧:AJAX 多步驟表單

<?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; // 回傳整個重建後的表單 }

關鍵 API 快速參考

  • `drupal_goto($path, $options)`:執行導向(內部處理 destination)
  • `drupal_get_destination()`:取得當前 destination 查詢字串
  • `drupal_redirect_form($form_state)`:表單提交後自動處理 redirect/destination 邏輯
  • `$form_state['rebuild'] = TRUE`:強制重建表單流程(保留 $form_state['storage'])
  • `$form_state['no_redirect'] = TRUE`:禁止任何導向(AJAX、測試用)
copyright © 萬盛學電腦網 all rights reserved