BeikeShop官方开发文档 | 安装教程 使用开发教程

# beikeshop 2.0 升级改动说明

为了保证 BeikeShop 的安全性与性能，核心框架已完成如下升级：

  • Laravel: 10 → 12
  • PHP: 8.2 → 8.4

插件开发者需要对现有插件进行适配与验证，确保在 Laravel 12 与 PHP 8.4 环境下的兼容性。

# 可能受影响的范围

  1. Laravel 内部 API

    • 部分方法在 Laravel 12 中已调整或弃用（如路由、服务容器、事件、Eloquent 等）。
    • 插件内如直接调用 Illuminate/* 类库，请检查兼容性。

  2. PHP 语法与函数

    • PHP 8.4 引入了新特性（只读属性增强、真实类型检查等）。
    • 部分函数/语法在 8.4 中已废弃，请避免继续使用。

  3. Blade & 中间件

    • Blade 组件注册方式、loadViewComponentsAs 相关逻辑需检查。
    • 中间件的签名、请求/响应处理在高版本可能有微调。

# 参考文档（官方升级指南）

# BeikeShop 自身调整说明（需插件适配）

在 BeikeShop 2.0 中，后台 UI 和系统设置进行了较大调整，插件开发者需要注意以下几点，确保插件功能兼容。

# 后台列表

  • 调整内容

    • 原先最右侧的 “编辑”按钮 已删除。
    • 现在改为 整行可点击，通过统一的 .row-link 类与 data-to-url 属性实现跳转
    • 支持通过 data-target="_blank" 控制在新窗口打开

  • 使用方式

    <tr class="cursor-pointer row-link" data-to-url="{{ admin_route('xxx') }}">
  <td>xxx</td>
  <td>xxx</td>
  <td>xxx</td>
</tr>
    • .row-link：表示当前行可点击。
    • data-to-url：指定跳转的目标地址。
    • （可选）data-target="_blank"：在新窗口打开。

  • 实现代码 以下逻辑已在 resources/beike/admin/js/common.js 中统一处理

    $(document).on('click', '.row-link', function(e) {
  const url = $(this).data('to-url');
  const target = $(this).data('target');
  if (url) {
    if (target === '_blank') {
      window.open(url);
    } else {
      window.location.href = url;
    }
  }
});

// 开发者若是在行内添加了按钮，需要阻止事件冒泡，否则点击按钮会触发整行点击事件
$(document).on('click', '.btn-approved', function(e) {
  e.stopPropagation();
});

  • 影响说明

    • 如果插件或主题在列表中添加了交互性元素（如按钮、下拉菜单、开关等），需要阻止事件冒泡，否则点击这些元素仍会触发行点击事件导致跳转。

  • 解决方案

    在 Vue 中：

    <button @click.stop="xxxx">按钮文本</button>

    在 a 链接中：

    <a href="xxxxx" onclick="event.stopPropagation();">按钮文本</a>

    在普通 JS 中：

    $(document).on('click', '.btn-approved', function(e) {
  e.stopPropagation(); // 阻止事件冒泡
  // 业务逻辑
});

# 后台表单

  • 调整内容

    • 所有表单调整为 平铺模式（card 卡片式平铺）。
    • 之前的 tab 选项卡 已移除，对应的 tab 相关 hook 也被移除。

  • 影响说明

    • 插件如依赖原有的 tab hook，需要重新适配到新的平铺卡片 hook 或布局中。
    • 请下载并参考最新的 2.0 代码结构，选择合适的 hook 进行挂载。

  • 示例对比

    2.0 之前：tab 选项卡切换 表单 Tab 模式

    2.0 之后：card 卡片平铺 表单 Card 模式

# 系统设置

  • 调整内容

    • 原先系统设置 admin/settings 的 6 个 tab 已拆分为 6 个独立页面。

  • 影响说明

    • 如果插件对系统设置 tab 做了扩展，需要将扩展点调整为独立页面的扩展方式（或在相应页面注册扩展项）。

  • 示例对比

    2.0 之前：系统设置 tab 模式 系统设置 Tab 模式

    2.0 之后：系统设置独立页面 系统设置 独立页面

    • 示例：点击「基础设置」，进入详情页只包含基础设置配置 系统设置详情页

# 文件路径调整

  • 词条文件路径 从 resources/lang 调整为 lang

  • 图片文件路径 从 public/catalog 调整为 public/image/catalog

插件开发者请注意修改插件中涉及文件路径的引用，以确保在 BeikeShop 2.0 中正常运行。

# 前台静态资源引用

在 BeikeShop 2.0 之前，我们通常通过以下方式向页面 <head> 标签中注入 JS/CSS 资源：

@push('header')
  <script src="{{ asset('vendor/vue/Sortable.min.js') }}"></script>
  <script src="{{ asset('vendor/vue/vuedraggable.js') }}"></script>
  <script src="{{ asset('vendor/tinymce/5.9.1/tinymce.min.js') }}"></script>
@endpush

对应的 layout/master 文件会在 <head> 中定义：

<head>
  @stack('header')
</head>

这样虽然能正常加载，但存在 多个插件重复引入相同资源 的问题，容易导致 资源浪费和加载阻塞。

2.0 之后的改进

在 BeikeShop 2.0 中，新增了 AssetService 服务类，用于集中管理前台资源加载。 在 beike/Shop/Providers/DocumentServiceProvider.php 中注册了 Blade 指令：

@addStyle(path) → 添加 CSS（自动去重）
@addScript(path, [attrs]) → 添加 JS，可附加 defer、async 等属性（自动去重）

对应的 layout/master 文件会在 <head> 中定义：

<head>
  @renderStyles
  @renderScripts
</head>

所以你的插件如果在前台使用了 @push('header') 加载资源，建议修改为 @addStyle() 和 @addScript()。

示例代码(适配 2.0 和兼容老版本)：

@if (version_compare(config('beike.version'), '2.0') >= 0)
  @addStyle(asset('vendor/swiper/swiper-bundle.min.css'))
  @addScript(asset('vendor/swiper/swiper-bundle.min.js'))
@else
  @push('header')
    <script src="{{ asset('vendor/swiper/swiper-bundle.min.js') }}"></script>
    <link rel="stylesheet" href="{{ asset('vendor/swiper/swiper-bundle.min.css') }}">
  @endpush
@endif

# 前台商品详情页 Vue 挂载点调整

在 BeikeShop 2.0 之前，商品详情页整体由一个 Vue 实例接管，挂载点为 #product-app。

在 BeikeShop 2.0 中，详情页整体已不再由 Vue 控制，#product-app 仅用于右侧的 商品信息与多规格区域。

因此，插件开发者需要注意：

  • 插件不能再依赖外层的全局 app 实例；
  • 需要在插件内部 自行创建 Vue 实例，并将逻辑放入该实例中。

新的 Vue 挂载区域如下图所示： vue 挂载点

# 兼容写法示例

如果需要兼容 2.0 之前 和 2.0 之后 的结构，可以使用版本判断：

@if (version_compare(config('beike.version'), '2.0') >= 0)
<script>
  const app = new Vue({
    el: '#product-comment',
    data: {
      // 插件内部逻辑
    },
    methods: {
      // 插件方法
    }
  });
</script>
@else
<script>
  // 旧版本中可直接依赖全局 app
  app.$set(app, 'pluginData', {
    // 插件逻辑
  });
</script>
@endif

# 版本兼容处理

插件需要同时兼容 2.0 与 2.0 之前的版本，可通过版本号判断进行区分：

在 PHP 中：

if (version_compare(config('beike.version'), '2.0') >= 0) {
    // 2.0 及之后的代码
} else {
    // 2.0 之前的代码
}

在 Blade 中：

@if (version_compare(config('beike.version'), '2.0') >= 0)
    {{-- 2.0 及之后的代码 --}}
@else
    {{-- 2.0 之前的代码 --}}
@endif

# 提醒

  • 建议优先在 Laravel 12 + PHP 8.4 的本地开发环境中进行测试与验证。

← 模板开发 →