WordPress自定义短代码，页面快速插入功能块
WordPress自定义短代码可以让你在页面或文章里用一个方括号标签，快速插入按钮、提示框、联系信息等功能块，不用每次重复写HTML。本文按零基础可照做的顺序，讲清代码放哪里、短代码怎么注册、页面怎么调用，以及不显示或报错时怎么排查。
## 先判断你适合用短代码还是区块
如果你只是偶尔插入一个固定样式的按钮或提示条，用短代码最省事；如果你需要频繁调整样式和布局，建议优先用区块编辑器或页面构建器。短代码的优势是**一次定义，多处复用**，适合在多个页面插入同一类功能块。
动手前确认三件事：
- 你能通过宝塔面板或FTP访问网站根目录，找到当前主题文件夹。
- 你准备把代码放在**子主题**的 `functions.php`，或使用代码片段插件，避免主题更新后代码丢失。
- 你已经备份数据库和主题文件，至少能回滚。
宝塔面板操作路径：`文件` → 进入网站根目录 → `wp-content/themes/你的子主题/functions.php`。如果没有子主题，可以先用代码片段插件（如Code Snippets）代替，路径是后台 `插件` → `安装插件` → 搜索并启用。
## 注册一个可复用的功能块短代码
下面以插入一个“提示框”为例。打开子主题的 `functions.php`，在文件末尾的 `?>` 之前（如果没有 `?>` 就直接追加）加入以下代码：
```php
function wpkb_notice_shortcode( $atts, $content = null ) {
$atts = shortcode_atts( array(
'type' => 'info',
'title' => '提示',
), $atts, 'wpkb_notice' );
$type = esc_attr( $atts['type'] );
$title = esc_html( $atts['title'] );
$text = wp_kses_post( $content );
return '
' .
'' . $title . '' .
'
';
}
add_shortcode( 'wpkb_notice', 'wpkb_notice_shortcode' );
```
关键点说明：
- `add_shortcode( 'wpkb_notice', ... )` 注册的短代码标签就是 `[wpkb_notice]`，前缀 `wpkb_` 用来避免和插件冲突。
- `shortcode_atts` 给参数设默认值，调用时不传参数也能正常显示。
- `esc_attr`、`esc_html`、`wp_kses_post` 是安全过滤函数，能降低XSS风险，**不要省略**。
保存文件后，如果宝塔开启了PHP缓存或OPcache，建议在宝塔 `软件商店` → `PHP` → `性能调整` 里重载一次，或直接重启PHP服务。
## 在页面里调用并控制显示样式
进入后台 `页面` → `新建页面`，在区块编辑器中添加“短代码”区块，输入：
```text
[wpkb_notice type="warning" title="注意"]提交前请先备份数据库。[/wpkb_notice]
```
也可以放在经典编辑器的正文里，效果相同。参数说明：
- `type`：控制样式类，示例中会输出 `wpkb-notice-warning`，你可以在主题CSS里为不同type写不同颜色。
- `title`：标题文字，不传时显示“提示”。
- 标签中间的内容就是提示正文，支持基础HTML。
如果要插入按钮类功能块，把上面的 `return` 部分换成 `` 标签，并增加 `url` 参数即可。核心逻辑不变：**短代码负责生成HTML，页面只负责调用**。
## 短代码不生效或报错的排查顺序
遇到短代码原样显示、页面空白或500错误，按下面顺序检查：
1. 短代码是否注册成功：在 `functions.php` 里临时加 `error_log( shortcode_exists('wpkb_notice') ? 'yes' : 'no' );`，查看宝塔 `网站` → `日志` 里的PHP错误日志。
2. 代码是否放错位置：必须放在PHP标签内，不能放在 `?>` 之后。
3. 是否有语法错误：宝塔 `网站` → `PHP日志` 出现 `Parse error` 时，优先检查分号、括号和引号是否配对。
4. 是否被缓存：清空WordPress缓存插件、浏览器缓存，宝塔里重载PHP。
5. 是否和插件冲突：临时停用其他短代码类插件，再测试一次。
修改 `functions.php` 前先备份，出现白屏时通过宝塔文件管理把备份文件恢复，或把新增代码删除。
## 验证功能块是否真正可用
发布页面后，前台右键“查看页面源代码”，搜索 `wpkb-notice`。如果能看到对应 `div` 和样式类，说明短代码已正常输出。再检查移动端显示是否错位，必要时在主题自定义CSS里补充：
```css
.wpkb-notice { padding: 12px 16px; border-left: 4px solid #2271b1; background: #f0f6fc; }
.wpkb-notice-warning { border-left-color: #dba617; background: #fcf9e8; }
```
如果页面里短代码标签原样显示，通常是短代码没有注册或被编辑器转义，回到排查顺序第1步确认。
## 常见疑问
**短代码可以放在小工具或模板文件里吗？**
可以。小工具里需要确保启用了短代码解析；模板文件里用 `do_shortcode('[wpkb_notice]内容[/wpkb_notice]')` 输出。
**主题更新后短代码失效怎么办？**
说明代码写在了父主题。把代码迁移到子主题的 `functions.php`，或用代码片段插件管理，更新主题不会丢失。
**一个短代码能带多个参数吗？**
能。在 `shortcode_atts` 数组里增加键名，调用时按 `key="value"` 格式传入，注意不要用中文引号。
**短代码内容里能再嵌套短代码吗？**
可以，但需要额外处理嵌套解析，零基础阶段建议先避免嵌套，减少排错难度。
按本文步骤完成后，你应该已经能在WordPress页面通过自定义短代码快速插入功能块。后续新增功能块时，复制注册函数、改标签名和输出HTML即可，不用重复折腾页面结构。 ' . $text . '
' . '