WordPress get_search_form 函數完整解析：自訂搜尋表單與預設表單的載入機制

在 WordPress 主題開發中，get_search_form() 是一個核心函數，用於輸出或獲取搜尋表單。它的運作邏輯相當智慧：系統會優先檢查主題目錄（包含子主題）下是否存在 searchform.php 檔案；若存在則直接載入該自訂模板，否則輸出 WordPress 內建的預設搜尋表單 HTML。這篇文章將詳細解析該函數的參數、使用範例、原始碼邏輯，以及如何整合 Google 自訂搜尋等進階應用。

函數基本語法

<?php get_search_form( $echo = true ); ?>

參數說明

核心運作機制

函數執行流程如下：

1. 觸發 get_search_form Action Hook，方便外掛或主題在表單前插入 JavaScript 或樣式
2. 呼叫 locate_template('searchform.php') 尋找自訂模板
3. 若找到模板檔，直接 require 載入並結束函數
4. 若無自訂模板，組裝預設 HTML 表單結構
5. 經過 get_search_form Filter Hook 過濾後，根據 $echo 參數輸出或回傳

預設表單 HTML 結構

<form role="search" method="get" id="searchform" action="'. esc_url( home_url( '/' ) ) .'" >
    <div>
        <label class="screen-reader-text" for="s">'. __('Search for:') .'</label>
        <input type="text" value="'. get_search_query() .'" name="s" id="s" />
        <input type="submit" id="searchsubmit" value="'. esc_attr__('Search') .'" />
    </div>
</form>

常見使用範例

1. 直接輸出預設搜尋表單（最常用）

<?php get_search_form(); ?>

2. 獲取表單字串供後續處理

<?php $form_html = get_search_form( false ); // 回傳字串不直接輸出 ?>

3. 建立自訂搜尋模板 searchform.php

在主題根目錄建立 searchform.php，系統會自動偵測並載入。範例內容：

<form role="search" method="get" class="search-form" action="<?php echo esc_url( home_url( '/' ) ); ?>">
    <label>
        <span class="screen-reader-text"><?php _e( 'Search for:', 'textdomain' ); ?></span>
        <input type="search" class="search-field" placeholder="<?php echo esc_attr_x( 'Search …', 'placeholder', 'textdomain' ); ?>" value="<?php echo get_search_query(); ?>" name="s" />
    </label>
    <input type="submit" class="search-submit" value="<?php echo esc_attr_x( 'Search', 'submit button', 'textdomain' ); ?>" />
</form>

進階應用：整合 Google 自訂搜尋

若需使用 Google Custom Search Engine (CSE)，只需在 searchform.php 中放入 Google 提供的程式碼片段，並調整對應 CSS 樣式即可。例如：

<script async src="https://cse.google.com/cse.js?cx=YOUR_ENGINE_ID"></script>
<div class="gcse-search"></div>

原始碼深度解析

以下是 WordPress 核心原始碼（以 6.x 版本為例），已加上關鍵註解：

function get_search_form( $echo = true ) {
    // 1. 觸發 Action，常用於載入搜尋相關 JS/CSS
    do_action( 'get_search_form' );

    // 2. 尋找 searchform.php（優先子主題，再父主題）
    $search_form_template = locate_template( 'searchform.php' );

    // 3. 若存在自訂模板，直接載入並返回
    if ( '' !== $search_form_template ) {
        require $search_form_template;
        return;
    }

    // 4. 組裝預設表單 HTML
    $form = '<form role="search" method="get" id="searchform" action="' . esc_url( home_url( '/' ) ) . '">';
    $form .= '<div><label class="screen-reader-text" for="s">' . __( 'Search for:' ) . '</label>';
    $form .= '<input type="text" value="' . get_search_query() . '" name="s" id="s" />';
    $form .= '<input type="submit" id="searchsubmit" value="' . esc_attr__( 'Search' ) . '" />';
    $form .= '</div></form>';

    // 5. 套用 Filter Hook 允許修改表單，再決定輸出或回傳
    $result = apply_filters( 'get_search_form', $form );

    if ( $echo ) {
        echo $result;
    } else {
        return $result;
    }
}

相關 Hook 總結

• Action: get_search_form - 表單輸出前觸發，適合 enqueue scripts/styles
• Filter: get_search_form - 可完整替換或修改表單 HTML 字串

開發者提示

1. 建議優先使用子主題建立 searchform.php，避免主題更新覆蓋修改
2. 預設表單包含無障礙屬性（role="search"、screen-reader-text），自訂模板請保留
3. 若需多個不同樣式的搜尋表單，可透過 get_search_form Filter 根據條件回傳不同 HTML