外掛選項設定頁設計

許多外掛需要讓管理者在後台調整設定，或讓使用者透過短代碼把功能放進文章與頁面。本章介紹設定頁、Options API 與 Shortcode 的基本設計。

12.1 外掛在控制台中的操作

設定頁通常會掛在後台選單中。建立設定頁時，要檢查使用者權限，並讓輸入資料經過清理。

加入後台選單

add_action('admin_menu', 'wp2026_register_settings_page');
function wp2026_register_settings_page() {
    add_options_page(
        'WP2026 設定',
        'WP2026 設定',
        'manage_options',
        'wp2026-settings',
        'wp2026_render_settings_page'
    );
}

設定頁輸出與權限檢查

後台設定頁的 callback 不應假設所有使用者都有權限。即使選單已設定 manage_options，頁面輸出時仍建議再次檢查。

function wp2026_render_settings_page() {
    if (!current_user_can('manage_options')) {
        return;
    }
    ?>
    <div class="wrap">
      <h1>WP2026 設定</h1>
      <form method="post" action="options.php">
        <?php
        settings_fields('wp2026_settings_group');
        do_settings_sections('wp2026-settings');
        submit_button();
        ?>
      </form>
    </div>
    <?php
}

settings_fields() 會輸出 nonce 與 option group 相關欄位，能減少手寫表單處理時的安全錯誤。

儲存選項

簡單外掛可使用 get_option() 與 update_option()。資料寫入前要使用 sanitize_text_field() 等函式清理。

$message = isset($_POST['message'])
    ? sanitize_text_field(wp_unslash($_POST['message']))
    : '';
update_option('wp2026_message', $message);

使用 Settings API 註冊欄位

Settings API 能把欄位註冊、資料清理與表單輸出集中管理，適合正式外掛使用。

add_action('admin_init', 'wp2026_register_settings');
function wp2026_register_settings() {
    register_setting('wp2026_settings_group', 'wp2026_message', [
        'type' => 'string',
        'sanitize_callback' => 'sanitize_text_field',
        'default' => '歡迎學習 WP2026',
    ]);

    add_settings_section(
        'wp2026_main_section',
        '主要設定',
        '__return_false',
        'wp2026-settings'
    );

    add_settings_field(
        'wp2026_message',
        '提示文字',
        'wp2026_message_field',
        'wp2026-settings',
        'wp2026_main_section'
    );
}

function wp2026_message_field() {
    $value = get_option('wp2026_message', '歡迎學習 WP2026');
    echo '<input type="text" name="wp2026_message" value="' . esc_attr($value) . '" class="regular-text">';
}

選項命名與預設值

選項名稱應加上外掛前綴，例如 wp2026_message，避免與其他外掛衝突。讀取選項時也應提供預設值，避免尚未儲存設定時前台出現空白或錯誤。

12.2 短代碼 shortcode 的應用

Shortcode 讓使用者在文章或頁面中插入外掛輸出，例如 [wp2026_message]。它適合簡短、可重用、由內容編輯者自行放置的功能。

建立 Shortcode

add_shortcode('wp2026_message', 'wp2026_message_shortcode');
function wp2026_message_shortcode($atts) {
    $atts = shortcode_atts(['type' => 'info'], $atts);
    $message = get_option('wp2026_message', '歡迎學習 WP2026');
    return '<div class="notice notice-' . esc_attr($atts['type']) . '">' . esc_html($message) . '</div>';
}

Shortcode 屬性設計

Shortcode 屬性應該少而清楚，並設定預設值。屬性值也要限制在可接受範圍內，避免使用者輸入任意 class 或 HTML 導致安全與樣式問題。

function wp2026_notice_shortcode($atts) {
    $atts = shortcode_atts([
        'type' => 'info',
        'title' => '提醒',
    ], $atts);

    $allowed_types = ['info', 'success', 'warning'];
    if (!in_array($atts['type'], $allowed_types, true)) {
        $atts['type'] = 'info';
    }

    return sprintf(
        '<aside class="notice notice-%s"><strong>%s</strong></aside>',
        esc_attr($atts['type']),
        esc_html($atts['title'])
    );
}

Shortcode 與區塊的取捨

Shortcode 適合快速、相容性高的功能，但在區塊編輯器中不如自訂區塊直覺。若功能需要可視化設定、即時預覽或複雜欄位，未來可考慮改寫成 Gutenberg block。

輸出快取與效能

若 shortcode 會查詢大量資料，可以考慮使用 transient 暫存結果，避免每次頁面載入都重新查詢。

$html = get_transient('wp2026_notice_html');
if (false === $html) {
    $html = wp2026_build_notice_html();
    set_transient('wp2026_notice_html', $html, HOUR_IN_SECONDS);
}
return $html;

本章練習

1. 建立一個外掛設定頁。
2. 儲存一段自訂提示文字。
3. 建立 [wp2026_message] 短代碼。
4. 在頁面中插入短代碼並確認輸出。