vr-shopxo-plugin/docs/09_SHOPXO_HOOKS_REFERENCE.md

ShopXO 钩子完整清单（v6.8.0）

从源码提取：app/service/*.php, app/index/controller/*.php, app/admin/controller/*.php 提取时间：2026-04-15 提取方式：grep "hook_name = \|'plugins_" /var/www/html/app/**/*.php

---

一、订单支付 — 票务插件最关键

来源：app/service/OrderService.php

钩子名称	触发时机	参数关键字段	票务用途
plugins_service_order_pay_launch_begin	发起支付前	business_ids, business_data, payment, params	支付前预处理
plugins_service_order_pay_launch_handle	支付方式处理	同上	扩展支付方式
plugins_service_order_pay_notify_handle	支付回调通知	business_ids, business_data	★ 支付成功，最佳入场点
plugins_service_order_pay_handle_begin	支付成功后开始	business_data, payment	支付成功业务处理开始
plugins_service_order_pay_success_handle_end	支付成功处理结束	business_data	★ 支付完全成功，生成票务记录
plugins_service_order_total_begin	订单总价计算前	goods, params	修改商品价格/附加费用
plugins_service_order_status_change_history_success_handle	订单状态变更历史	order_id, old_status, new_status	监听状态变化
plugins_service_order_delete_success	订单删除成功	order_id	清理关联票务数据

---

二、商品详情页（前端）— 票务 UI 注入点

来源：app/index/controller/Goods.php

钩子名称	位置描述	最佳注入
plugins_view_goods_detail_base_top	商品基础信息区顶部
plugins_view_goods_detail_base_sku_top	SKU/规格选择区顶部	★ 票务选座最佳注入点
plugins_view_goods_detail_base_inventory_top	库存显示区顶部
plugins_view_goods_detail_base_inventory_bottom	库存显示区底部
plugins_view_goods_detail_base_buy_nav_min_inside_begin	购买按钮区内部前
plugins_view_goods_detail_base_buy_nav_min_inside	购买按钮区内部后
plugins_view_goods_detail_base_bottom	商品基础信息区底部
plugins_view_goods_detail_panel_original_price_top	原价上方
plugins_view_goods_detail_panel_price_top	现价上方
plugins_view_goods_detail_panel_price_bottom	现价下方
plugins_view_goods_detail_panel_bottom	购买面板底部
plugins_view_goods_detail_photo_within	相册内部
plugins_view_goods_detail_photo_bottom	相册底部
plugins_view_goods_detail_buy_nav_top	购买导航顶部
plugins_view_goods_detail_right_content_top	右侧内容顶部
plugins_view_goods_detail_right_content_bottom	右侧内容底部
plugins_view_goods_detail_right_content_inside_top	右侧内容内部顶部
plugins_view_goods_detail_right_content_inside_bottom	右侧内容内部底部
plugins_view_goods_detail_tabs_top	标签页顶部
plugins_view_goods_detail_tabs_content	标签页内容
plugins_view_goods_detail_tabs_comments_top	评论区顶部
plugins_view_goods_detail_tabs_comments_bottom	评论区底部
plugins_view_goods_detail_tabs_guess_like_top	猜你喜欢顶部
plugins_view_goods_detail_tabs_guess_like_bottom	猜你喜欢底部
plugins_view_goods_detail_tabs_bottom	标签页底部
plugins_view_goods_detail_content_top	商品详情内容顶部
plugins_view_goods_detail_content_bottom	商品详情内容底部
plugins_view_goods_detail_left_top	左侧区域顶部
plugins_view_goods_detail_title	商品标题区

---

三、购物车/结算页（前端）

来源：app/index/controller/Buy.php

钩子名称	位置描述
plugins_view_buy_top	结算页顶部
plugins_view_buy_inside_top	结算内容区顶部
plugins_view_buy_address_bottom	收货地址下方
plugins_view_buy_payment_bottom	支付方式下方
plugins_view_buy_group_goods_bottom	商品分组下方
plugins_view_buy_user_note_bottom	用户备注下方
plugins_view_buy_base_confirm_top	确认信息顶部
plugins_view_buy_form_inside	表单内部
plugins_view_buy_inside_bottom	结算内容区底部
plugins_view_buy_bottom	结算页底部

---

四、用户中心（前端）

来源：app/index/controller/User.php

钩子名称	位置描述	票务用途
plugins_view_user_center_top	用户中心顶部
plugins_view_user_base_bottom	用户基础信息底部
plugins_view_user_various_top	聚合内容顶部
plugins_view_user_various_bottom	聚合内容底部
plugins_view_user_various_inside_top	聚合内容内部顶部	★ 票夹最佳注入点
plugins_view_user_various_inside_bottom	聚合内容内部底部

---

五、全局页面（前端）

来源：app/index/controller/Common.php

CSS/JS 加载钩子

钩子名称	用途
plugins_css	全局 CSS
plugins_js	全局 JS

全局视图钩子

钩子名称	位置描述
plugins_common_header	全局头部
plugins_common_header_css	头部 CSS
plugins_common_header_javascript	头部 JS
plugins_common_page_bottom	全局页面底部
plugins_view_common_top	全局页面顶部
plugins_view_common_bottom	全局页面底部
plugins_view_common_top_header	头部内顶部
plugins_view_common_bottom_footer	底部内

头部导航钩子

钩子名称	位置描述
plugins_view_header_navigation_top_left_begin	导航左上起始
plugins_view_header_navigation_top_left_end	导航左上结束
plugins_view_header_navigation_top_right_begin	导航右上起始
plugins_view_header_navigation_top_right_end	导航右上结束
plugins_view_common_header_nav_left	导航左侧
plugins_view_common_header_nav_search_inside	搜索框内部
plugins_view_common_header_nav_content_inside_top	导航内容顶部
plugins_view_common_header_nav_content_inside_bottom	导航内容底部
plugins_view_common_header_nav_right	导航右侧
plugins_view_common_logo_right	Logo 右侧
plugins_view_common_search_right	搜索框右侧
plugins_view_common_search_inside_left	搜索框内部左侧
plugins_view_common_search_inside_right	搜索框内部右侧

登录/注册页钩子

钩子名称	位置描述
plugins_view_user_login_content_inside_top	登录内容内部顶部
plugins_view_user_login_content_inside_bottom	登录内容内部底部
plugins_view_user_login_info_top	登录信息区域顶部
plugins_view_user_login_inside_bottom	登录区域内部底部
plugins_view_user_login_inside_reg_bottom	注册登录区域底部
plugins_view_user_login_content_bottom	登录内容底部
plugins_view_user_reg_info	注册信息区域
plugins_view_user_reg_info_top	注册信息顶部
plugins_view_user_reg_info_inside_bottom	注册信息内部底部
plugins_view_user_reg_info_inside_login_bottom	注册内登录底部
plugins_view_user_reg_info_bottom	注册信息底部

底部钩子

钩子名称	位置描述
plugins_view_common_footer_top	页脚顶部

---

六、首页楼层（前端）

来源：app/index/controller/Index.php

钩子名称	位置描述
plugins_view_home_floor_top	首页楼层顶部
plugins_view_home_floor_bottom	首页楼层底部
plugins_view_home_banner_mixed_bottom	混合 Banner 底部

---

七、搜索页（前端）

来源：app/index/controller/Search.php

钩子名称	位置描述
plugins_view_search_top	搜索页顶部
plugins_view_search_bottom	搜索页底部
plugins_view_search_inside_top	搜索结果区顶部
plugins_view_search_inside_bottom	搜索结果区底部
plugins_view_search_data_top	商品列表顶部
plugins_view_search_data_bottom	商品列表底部
plugins_view_search_map_top	地图区域顶部
plugins_view_search_nav_top	筛选导航顶部
plugins_view_search_nav_inside_begin	筛选导航内部起始
plugins_view_search_nav_inside_end	筛选导航内部结束
plugins_view_search_map_inside_begin	地图内部起始
plugins_view_search_map_inside_base_bottom	地图基础内容底部
plugins_view_search_map_inside_end	地图内部结束

---

八、服务层钩子（业务逻辑）

来源：app/service/GoodsService.php

钩子名称	触发时机	票务用途
plugins_service_goods_data	商品数据读取
plugins_service_goods_spec_data	商品规格数据	★ 票务座位规格注入
plugins_service_goods_parameters_data	商品参数数据
plugins_service_goods_content_app_data	商品详情 APP 数据
plugins_service_home_floor_data_begin	首页楼层数据前
plugins_service_category_goods_total_begin	分类商品总数前
plugins_service_category_goods_list_begin	分类商品列表前
plugins_service_goods_list_begin	商品列表前
plugins_service_goods_total_begin	商品总数前
plugins_service_goods_list_handle_begin	商品列表处理开始
plugins_service_goods_handle_begin	商品处理开始
plugins_service_goods_handle_end	商品处理结束
plugins_service_goods_list_handle_end	商品列表处理结束
plugins_service_goods_save_handle	商品保存处理
plugins_service_goods_save_thing_begin	商品保存项目开始
plugins_service_goods_save_thing_end	商品保存项目结束
plugins_service_goods_save_end	商品保存结束
plugins_service_goods_base_update	商品基础更新
plugins_service_goods_delete	商品删除
plugins_service_goods_field_status_update	商品字段状态更新
plugins_service_goods_spec_base	商品规格基础
plugins_service_goods_spec_type	商品规格类型
plugins_service_goods_spec_extends_handle	商品规格扩展处理
plugins_service_goods_buy_left_nav_handle	购买左侧导航处理
plugins_service_goods_buy_nav_button_handle	购买导航按钮处理
plugins_service_goods_detail_middle_tabs_nav_handle	详情页标签导航处理
plugins_service_goods_search_list_begin	商品搜索列表开始
plugins_service_goods_base_forbid_operate_data	商品禁止操作数据
plugins_service_goods_params_operate_data	商品参数操作数据
plugins_service_goods_spec_operate_data	商品规格操作数据

---

九、服务层钩子（订单）

来源：app/service/OrderService.php

钩子名称	触发时机
plugins_service_order_pay_launch_begin	发起支付前
plugins_service_order_pay_launch_handle	支付方式处理
plugins_service_order_pay_notify_handle	支付通知处理
plugins_service_order_pay_handle_begin	支付成功开始处理
plugins_service_order_pay_success_handle_end	支付成功处理结束
plugins_service_order_total_begin	订单总价计算前
plugins_service_order_status_group_total_begin	订单状态分组统计前
plugins_service_order_list_begin	订单列表前
plugins_service_order_list_handle_begin	订单列表处理开始
plugins_service_order_handle_begin	订单处理开始
plugins_service_order_handle_end	订单处理结束
plugins_service_order_list_handle_end	订单列表处理结束
plugins_service_order_detail_data	订单详情数据
plugins_service_order_extraction_data	订单提取数据（取货码）
plugins_service_order_trace_source_data	订单溯源数据
plugins_service_order_service_data	订单服务数据
plugins_service_order_express_data	订单快递数据
plugins_service_order_address_data	订单地址数据
plugins_service_order_status_change_history_success_handle	订单状态变更历史
plugins_service_order_delete_success	订单删除成功

---

十、服务层钩子（其他）

来源：app/service/AppHomeNavService.php, app/service/DiyService.php

钩子名称	来源	触发时机
plugins_service_app_home_navigation_{client_type}	AppHomeNavService	首页导航（client_type=pc/h5/weixin_mp等）
plugins_module_diy_view_data_handle	DiyModule	DIY 视图数据处理
plugins_module_diy_save_data_handle	DiyModule	DIY 保存数据处理
plugins_layout_service_url_value_begin	LayoutModule	布局服务 URL 值前
plugins_layout_service_url_value_handle	LayoutModule	布局服务 URL 值处理
plugins_layout_service_search_goods_begin	LayoutModule	布局搜索商品前
plugins_layout_service_goods_data_begin	LayoutModule	布局商品数据前
plugins_layout_service_pages_list	LayoutModule	布局页面列表

---

十一、后台管理钩子

来源：app/admin/controller/Common.php

全局 CSS/JS 钩子

钩子名称	用途
plugins_admin_css	后台全局 CSS
plugins_admin_js	后台全局 JS
plugins_admin_common_header	后台头部
plugins_admin_common_header_css	后台头部 CSS
plugins_admin_common_header_javascript	后台头部 JS
plugins_admin_common_page_bottom	后台页面底部
plugins_admin_view_common_top	后台页面顶部
plugins_admin_view_common_bottom	后台页面底部

后台表单钩子

钩子名称	来源控制器
plugins_view_admin_goods_save	Goods.php — 商品保存
plugins_view_admin_user_save	User.php — 用户保存
plugins_view_admin_admin_save	Admin.php — 管理员保存
plugins_view_admin_login_info	Admin.php — 登录页
plugins_view_admin_role_save	Role.php — 角色保存

---

十二、VR 票务插件 — 推荐钩子使用方案

方案 A：支付成功立即生成票（最可靠）

使用钩子: plugins_service_order_pay_notify_handle 或 plugins_service_order_pay_success_handle_end

// Event.php
public function PayNotifyHandle($params = [])
{
    // $params['business_data'] 包含订单数据
    // $params['business_ids'] 包含订单ID列表
    $order_id = $params['business_ids'][0] ?? 0;
    $order = Db::name('order')->find($order_id);
    
    if ($order['pay_status'] == 1) {
        // 1. 原子扣 vr_sessions 库存
        // 2. 生成 vr_tickets（AES QR）
        // 3. 写入 vr_attendees
    }
}

方案 B：商品详情页注入票务选座 UI

使用钩子: plugins_view_goods_detail_base_sku_top

// view/Goods.php
public static function PluginsViewGoodsDetailBaseSkuTop($params)
{
    $goods = $params['goods'];
    if (empty($goods['item_type']) || $goods['item_type'] != 'ticket') {
        return '';
    }
    return '<div id="ticket-seat-map" data-goods-id="'.$goods['id'].'"></div>';
}

方案 C：用户中心票夹

使用钩子: plugins_view_user_various_inside_top

// view/User.php
public static function PluginsViewUserVariousInsideTop($params)
{
    return '<div id="ticket-wallet"></div>';
}

---

十三、钩子注册方式（config.json）

{
  "base": {
    "name": "VR票务",
    "plugins": "vr_ticket"
  },
  "hook": {
    "plugins_service_order_pay_success_handle_end": [
      "\\app\\plugins\\vr_ticket\\Event::PaySuccess"
    ],
    "plugins_view_goods_detail_base_sku_top": [
      "\\app\\plugins\\vr_ticket\\view\\Goods::PluginsViewGoodsDetailBaseSkuTop"
    ],
    "plugins_view_user_various_inside_top": [
      "\\app\\plugins\\vr_ticket\\view\\User::PluginsViewUserVariousInsideTop"
    ]
  },
  "backend_hook": {
    "plugins_view_admin_goods_save": [
      "\\app\\plugins\\vr_ticket\\hook\\AdminGoodsSave"
    ]
  }
}