Zibll 附加插件开发精简速查手册

适配子比 Zibll 主题 WP 插件开发，遵循zib_require_end加载规范、CSF 后台、前端复用主题资源规范

class="heading-2 ace-line old-record-id-NNOTfZ2dhditFOcS467ojlwAAJQ"

class="heading-3 ace-line old-record-id-DCNRf457ldowLXcZdmsiAHNXw6b"

1. 插件文件夹名 = 主 PHP 文件名，例：zib-demo → zib-demo.php
2. 头部标准插件注释，非 ABSPATH 直接 exit
   代码

   代码

   <?php /** * Plugin Name: 子比示例插件 * Plugin URI: https://1z345.cn/ * Version:1.0.0 * Author:小武 * Requires PHP:7.4 */ if(!defined('ABSPATH')) exit;

   复制

   复制

    

3. 主题校验：非 zibll 主题，后台弹窗提示 + 终止加载
   代码

   代码

   if(get_stylesheet()!='zibll'){
       add_action('admin_notices',function(){echo '<div class="notice notice-error">需安装启用子比Zibll主题</div>';});
       return;
   }

   复制

   复制

    

4. 目录分层规范

   代码

   代码

   插件目录/
   ├─插件主文件.php  #入口：依赖检测+引入子文件
   ├─inc/
   │  ├─options.php #CSF后台配置（挂载zib_require_end）
   │  ├─widget.php  #CSF侧边小工具（挂载zib_require_end）
   │  └─ajax.php    #ajax业务
   └─assets/
      ├─css/frontend.css
      └─js/frontend.js

   复制

   复制

    

class="heading-3 ace-line old-record-id-EGGKfXagqdzGSTcX69oorryzDDS"

1. CSF 类、CSF_Widget 必须挂载zib_require_end，禁止文件顶层直接实例化（主题未加载报错）
2. 插件全局统一唯一前缀：函数名、option 键、widget 标识、脚本 handle，杜绝命名冲突
3. CSF 配置存储$options_key全局唯一，不可复用主题 / 其他插件 key
4. CSF 优先引用路径：csf-framework/，废弃codestar-framework/旧目录

class="heading-2 ace-line old-record-id-XNQ4fhvJQdX369cirzJnVW23u8h"

class="heading-3 ace-line old-record-id-OHLWf6amoduHRZcepwLgLRRUu89"

function zb_demo_csf(){
    if(!is_admin()) return;
    $opt_key='zb_demo_opt';//唯一配置键
    CSF::createOptions($opt_key,[
        'menu_title'=>'插件设置','menu_slug'=>$opt_key,'show_in_customizer'=>false
    ]);
    CSF::createSection($opt_key,[
        'id'=>'base','title'=>'基础配置','icon'=>'fa fa-cog',
        'fields'=>[
            ['id'=>'open','type'=>'switcher','title'=>'启用','default'=>true],
            ['id'=>'text','type'=>'text','title'=>'文本配置']
        ]
    ]);
}
add_action('zib_require_end','zb_demo_csf');

class="heading-3 ace-line old-record-id-OHLWf6amoduHRZcepwLgLRRUu89"

class="heading-3 ace-line old-record-id-DyKMfT0cedoAFGcO39fhosENoZ9"

function zb_get_opt($key,$def=false){
    static $opt=null;
    if($opt===null)$opt=get_option('zb_demo_opt');
    return $opt[$key]??$def;
}

class="heading-3 ace-line old-record-id-DyKMfT0cedoAFGcO39fhosENoZ9"

class="heading-2 ace-line old-record-id-FMSYf28hjduyLYcZ2gqcvwxFoOX"

//注册小工具
function zb_reg_widget(){
    CSF::createWidget('zb_demo_widget',[
        'title'=>'插件小工具','classname'=>'zb-demo-widget','width'=>'350px',
        'fields'=>[['id'=>'w_title','type'=>'text','title'=>'标题']]
    ]);
}
add_action('zib_require_end','zb_reg_widget');

//前端渲染【函数名必须=createWidget第一个参数】
function zb_demo_widget($args,$ins){
    $title=esc_html($ins['w_title']??'');
    echo '<div class="zib-widget padding-10">'.$title.'</div>';
}

class="heading-2 ace-line old-record-id-TJN2fbkxAdEGJScY7egkkstytBK"

function zb_load_asset(){
    $url=plugin_dir_url(__FILE__);$v='1.0.0';
    //css依赖main，保证在主题样式后加载
    wp_enqueue_style('zb-css',$url.'assets/css/frontend.css',['main'],$v);
    //js依赖jquery，底部加载
    wp_enqueue_script('zb-js',$url.'assets/js/frontend.js',['jquery'],$v,true);
    //注入ajax地址+nonce
    wp_localize_script('zb-js','ZB_VAR',[
        'ajax_url'=>admin_url('admin-ajax.php'),
        'nonce'=>wp_create_nonce('zb_ajax_nonce')
    ]);
}
add_action('wp_enqueue_scripts','zb_load_asset');

class="heading-2 ace-line old-record-id-ROV8fhhwLdU68bcdmmviyAOQlWa"

//仅登录可用，公开接口加nopriv钩子
add_action('wp_ajax_zb_act','zb_ajax_handle');

function zb_ajax_handle(){
    check_ajax_referer('zb_ajax_nonce','nonce');//校验令牌
    if(!current_user_can('read')) wp_send_json_error('权限不足',403);
    $data=sanitize_text_field(wp_unslash($_POST['data']??''));
    //业务逻辑
    wp_send_json_success(['res'=>$data]);
}

class="heading-2 ace-line old-record-id-ROV8fhhwLdU68bcdmmviyAOQlWa"

class="heading-2 ace-line old-record-id-OquxfMSY7dbcqucyKOXk16iikqy"

class="heading-3 ace-line old-record-id-CuINfTWZcdmBCOc12anhrFSZj4g"

• _pz($name,$def='',$sub='')：读取 zibll 主题配置（带静态缓存）
• _spz($name,$val)：修改主题配置字段

class="heading-3 ace-line old-record-id-QMQRf1dpvdyGGOc27kmoppsHzIV"

• zib_get_user_id($user)：ID / 邮箱 / 用户对象→用户 ID
• zib_get_data_avatar($uid,$size)：输出头像 HTML
• zib_user_is_ban($uid)：判断用户是否封禁
• zib_user_is_checkined($uid)：当日是否签到
• zib_modal($args)：快速生成 bootstrap 弹窗

class="heading-3 ace-line old-record-id-ZDGLfQ2hwdEHTYcbjotfGSZ0l0b"

• zib_get_current_url()：获取当前页面 URL
• zib_get_time_ago($time)：人性化时间
• zib_is_show_sidebar()：是否展示侧边栏
• zib_get_theme_mode()：获取亮 / 暗色模式

class="heading-3 ace-line old-record-id-FFNXfY9fpdyJV3c334iewFNQj0d"

• zibpay_is_paid($post_id,$uid)：用户是否购买文章付费内容

class="heading-2 ace-line old-record-id-MAN0f8lqtdFPW1c9fuAfBHJKhS6"

class="heading-3 ace-line old-record-id-TEJTf29htdzIR4cabjmmmtwymGM"

//站点、ajax地址、登录状态、nonce等 _win.www,//网站根地址 _win.ajax_url,//ajax地址 _win.is_signin,//是否登录 _win.post_action_nonce//通用操作令牌

class="heading-3 ace-line old-record-id-IDNZfeiuJdLTU7c8isHlOT89wmB"

1. zib_ajax($dom,data,success,is_tip)：主题封装 ajax，自动带验证码、loading
2. notyf('提示内容','success/danger/warning')：右下角弹窗
3. refresh_modal({remote:'url'})：动态加载弹窗
4. $.fn.serializeObject()：表单转 json 对象

class="heading-2 ace-line old-record-id-YGSYfdixHdLMWYc37eknxyzNu19"

class="heading-3 ace-line old-record-id-BuBLfLR37dbftCcQTX8cbcqFiMN"

.box{
    background:var(--main-bg-color);
    color:var(--main-color);
    border:1px solid var(--main-border-color);
    border-radius:var(--main-radius);
}

class="heading-3 ace-line old-record-id-BuBLfLR37dbftCcQTX8cbcqFiMN"

class="heading-3 ace-line old-record-id-FDGPfX7cgdgmnCcEEPUo8htuowB"

• 卡片：zib-widget（侧边标准容器）、box-bg、muted-box
• 颜色：.c-theme/.c-red/.c-blue/.c-green文字色；.jb-blue/.jb-green渐变背景
• 布局：.flex .jc .ac .gap10弹性布局；.padding-10 .mt10 .mb15内外边距
• 圆角：.radius8、.radius4

class="heading-2 ace-line old-record-id-ZHVafcqrvdzMRVcY5kldmqFPq2d"

function zb_short($attr,$content=null){ $arg=shortcode_atts(['title'=>'默认'], $attr); return '<div class="zib-widget">'.esc_html($arg['title']).'</div>'; } add_shortcode('zb_demo','zb_short');

class="heading-2 ace-line old-record-id-ZHVafcqrvdzMRVcY5kldmqFPq2d"

class="heading-2 ace-line old-record-id-OQZ9fehrsdsDNNcW09ejfhinxzD"

class="heading-3 ace-line old-record-id-FRYcfcqzzdGNT8ceoovpEKW2z9f"

• zib_require_end：主题全加载完毕（CSF 必挂）
• zib_single_before/zib_single_after：文章首尾注入内容
• payment_order_success：订单支付成功回调
• zibll_update_notices：主题更新弹窗提示插件

class="heading-3 ace-line old-record-id-WJJMfM1dddknuwcHW59mjmvGyMO"

• zib_is_show_sidebar：控制侧边栏显示
• zib_theme_mode：拦截明暗主题
• zib_user_center_page_sidebar：用户中心侧栏追加内容

class="heading-2 ace-line old-record-id-IBNQfW9bhdqvBDcSXX6mgkuJoO2"