EP046. “抽出可复用的 pageBanner() 函数”

首页 › WordPress 开发课程 › 自定义字段与 PHP WARNING · EP046

约 11 分钟· #EP046#自定义字段与 PHP WARNING

📌 并入 EP045（Note About PHP Warning In The Next Lesson）：Brad 在这一讲之前先发了个提醒——下一讲（EP047）网站上会开始出现 "Undefined array key" 的 PHP Warning，先别慌，那是故意留到下一讲才修的。他解释这是因为旧版 PHP 允许你直接判断一个可能不存在的数组键（比如 !$args['title']）不会报错，但很多真实项目（尤其是接手别人代码、或者升级 PHP 版本时）都会撞到这种警告，所以想让大家先亲眼看到问题、理解原因，下一讲再讲怎么修。这一讲的代码本身就是触发这个警告的原因。

之前的讲座里 single-professor.php 已经写了一段能显示动态背景图 + 动态副标题的 page banner 代码，但这段代码只服务于 professor 这一个模板。这一讲把它抽成 functions.php 里的一个可复用函数 pageBanner()，先套到 single-professor.php 和 page.php（About Us 页面）上，然后让这个函数支持传参（$args 数组的 title / subtitle / photo），没传参数时智能地 fallback 到当前文章/页面自己的标题、ACF 副标题字段、ACF 背景图字段，最后统一 fallback 到主题自带的 ocean.jpg。

涉及文件

wp-content/themes/fictional-university-theme/functions.php （修改：新增 pageBanner() 函数）
wp-content/themes/fictional-university-theme/single-professor.php （修改：把原本写死的 page-banner div 换成调用 pageBanner()）
wp-content/themes/fictional-university-theme/page.php （修改：同上，删除写死的 div，改调用 pageBanner()）

代码实现

functions.php 最前面新增整个函数（代码以 sources/Section 10/38-2021/38-end 为准）：

// wp-content/themes/fictional-university-theme/functions.php

// 新增：可复用的 page banner 函数
function pageBanner($args = NULL) {

  if (!$args['title']) {
    $args['title'] = get_the_title();
  }

  if (!$args['subtitle']) {
    $args['subtitle'] = get_field('page_banner_subtitle');
  }

  if (!$args['photo']) {
    if (get_field('page_banner_background_image')) {
      $args['photo'] = get_field('page_banner_background_image')['sizes']['pageBanner'];
    } else {
      $args['photo'] = get_theme_file_uri('/images/ocean.jpg');
    }
  }

  ?>
  <div class="page-banner">
    <div class="page-banner__bg-image" style="background-image: url(<?php echo $args['photo']; ?>);"></div>
    <div class="page-banner__content container container--narrow">
      <h1 class="page-banner__title"><?php echo $args['title'] ?></h1>
      <div class="page-banner__intro">
        <p><?php echo $args['subtitle']; ?></p>
      </div>
    </div>
  </div>
<?php }

single-professor.php 和 page.php 的改法完全一样——删掉原本那一大块写死的 <div class="page-banner">...</div>，改成一行函数调用：

// wp-content/themes/fictional-university-theme/single-professor.php
// wp-content/themes/fictional-university-theme/page.php

  while(have_posts()) {
    the_post();
    pageBanner(); // 修改：原本这里是一整块写死的 page-banner div
     ?>

要点：

$args = NULL 是关键：函数签名如果不给默认值（写成 pageBanner($args)），调用 pageBanner() 不传参数会直接抛 Fatal error（transcript 里演示过这个报错）。给了 NULL 默认值之后，$args 参数就变成可选的。
三个 if (!$args['xxx']) 判断是「智能默认值」：只有调用时没传对应参数，才去 fallback 到 get_the_title() / get_field('page_banner_subtitle') / ACF 背景图字段（裁切成 pageBanner 尺寸）/ 最终兜底的 ocean.jpg。
传参时用关联数组：pageBanner(array('title' => 'xxx', 'subtitle' => 'yyy'))，参数名是自己定的，没有固定写法，args 这个变量名也只是 WordPress 里的行业惯例。

Hook / Function 速查

名称	类型	用途
`pageBanner($args = NULL)`	自定义 function	统一渲染 page banner，支持传 `title`/`subtitle`/`photo`，没传时智能 fallback
`get_theme_file_uri($path)`	WP 内建 function	返回当前主题文件夹下某个文件的绝对 URL，这里用来指向默认的 `ocean.jpg`

常见坑

函数签名不给 $args 默认值的话，调用时不传参数会报 Fatal error（transcript 里实际演示了这个报错，加上 = NULL 才解决）。
这一讲用的 !$args['title'] 这类写法在现代 PHP 里会触发 "Undefined array key" Warning——这是 EP045 提前预告、EP047 才会修的坑，这一讲先别管它。

延伸 / 后续讲座会用到

下一讲 EP047 会把这三处 !$args['xxx'] 判断全部改成 isset($args['xxx']) 来消除警告；EP048 会再给 photo 判断加两个防护条件；EP049 会把 pageBanner() 套用到项目里剩下的所有模板文件。

Sources

Udemy：

Become a WordPress Developer: Unlocking Power With Code — Section 10, EP045
Become a WordPress Developer: Unlocking Power With Code — Section 10, EP046