BannerSlider横幅轮播插件使用教程

一款支持多图自动轮播、外链图片、点击跳转、移动端独立高度的 Typecho 顶部横幅插件，兼容 Typecho 2.0 新版插件规范。

一、插件简介

BannerSlider 横幅轮播插件可以在站点顶部展示一张或多张横幅图片，支持：

• 多张图片自动轮播，间隔可调
• 图片使用外链 URL，无需上传到服务器
• 每张图可配置跳转链接
• 桌面端 / 移动端可设置不同高度
• 指示器圆点、左右切换箭头可单独开关
• 纯原生 CSS/JS 实现，无 jQuery 依赖，样式带 bslider- 前缀，不与主题冲突

二、安装步骤

1. 将插件目录改名为 BannerSlider
2. 上传到 Typecho 的 usr/plugins/ 目录下，最终路径为 usr/plugins/BannerSlider/Plugin.php
3. 登录后台 → 「控制台」→「插件」→ 找到「横幅轮播」→ 点击「启用」
4. 启用后点击「设置」，填写图片地址等配置

注意：目录名必须为 BannerSlider，与插件命名空间 TypechoPlugin\BannerSlider 保持一致。

三、配置说明

配置示例：

图片地址列表：
https://example.com/banner1.jpg
https://example.com/banner2.jpg
https://example.com/banner3.jpg

跳转链接列表：
https://example.com/post/1
https://example.com/post/2

四、使用效果

• 横幅挂在 index.php 的 begin 钩子上，显示在页面最顶部，无需修改主题
• 自动轮播，鼠标悬停暂停，移开继续
• 只有 1 张图时自动禁用轮播
• 图片用 background-image 展示，等比覆盖、居中，适配各种尺寸

五、踩坑记录：启用后报 Deprecated 错误

报错信息

Deprecated: strip_tags(): Passing null to parameter #1 ($string) of type string is deprecated in /www/wwwroot/xxx.cn/var/Typecho/Common.php on line 448

原因分析

这个报错不是插件的问题，而是 Typecho 2.0 核心代码的兼容性 bug：

• var/Typecho/Common.php 中的 Common::stripTags() 方法，签名上允许传入 null
• 但方法内部直接调用 strip_tags($html)，没有对 null 做空值保护
• PHP 8.1 之前传 null 给 strip_tags 只是普通警告，PHP 8.1 开始升级为 Deprecated 级别错误并在页面上显示

触发场景：评论内容过滤（var/Widget/Base/Comments.php）或 Pingback 服务处理时，遇到空字段（null）就会触发。

解决方法

方法一：抑制 Deprecated 警告（推荐，一行搞定）

编辑站点根目录的 config.inc.php，在 <?php 下面加一行：

error_reporting(E_ALL & ~E_DEPRECATED);

这是 PHP 8.1+ 运行 Typecho 的标准兼容做法，警告不再显示，功能完全不受影响。

方法二：修复核心代码（根治）

编辑 var/Typecho/Common.php，找到 stripTags() 方法，在 $html = strip_tags($html, $normalizeTags); 这一行之前加：

if (null === $html) {
    $html = '';
}

注意：修改核心文件后，Typecho 升级时会被覆盖，需要重新修改。

验证方法

停用横幅插件后刷新首页，如果报错依然存在，即可确认与插件无关，是 Typecho 本身的兼容性问题。