laravel-admin-ext-cos

腾讯云 COS 浏览器分片直传组件，适用于 encore/laravel-admin。

安装

composer require themismin/laravel-admin-ext-cos:^1.1
php artisan vendor:publish --provider="ThemisMin\\LaravelAdminExtCos\\CosJsUploadServiceProvider" --tag=cos-js-upload
php artisan vendor:publish --provider="ThemisMin\\LaravelAdminExtCos\\CosJsUploadServiceProvider" --tag=cos-js-upload-config

扩展会自动注册 cosupload 表单字段。旧项目也可以在 app/Admin/bootstrap.php 中显式注册：

Encore\Admin\Form::extend(
    'cosupload',
    \ThemisMin\LaravelAdminExtCos\CosJsUploadField::class
);

环境变量

APP_NAME=example
COS_SECRET_ID=
COS_SECRET_KEY=
COS_BUCKET=
COS_REGION=ap-shanghai
COS_URL=https://example-123456.cos.ap-shanghai.myqcloud.com/

字段类型

$form->cosupload('cover', '封面')
    ->image()
    ->storeFullUrl();

$form->cosupload('video', '视频')->video();
$form->cosupload('attachment', '附件')->file();

默认规则：

• 图片：jpg、jpeg、png、webp、gif、bmp、svg，最大 20 MB。
• 视频：mp4、mov、webm、avi、mkv、m4v，最大 2 GB。
• 文件：PDF、Office、文本、CSV 和常见压缩包，最大 500 MB。

字段可覆盖默认限制：

$form->cosupload('cover', '封面')
    ->image()
    ->extensions(['jpg', 'png'])
    ->mimeTypes(['image/jpeg', 'image/png'])
    ->maxSize(5)
    ->storeFullUrl();

未调用 image()、video() 或 file() 的旧字段保持无限制。

上传安全

• 浏览器在申请上传授权前校验扩展名、MIME 和大小。
• 上传策略使用 Laravel 加密令牌，客户端无法放宽规则。
• 授权接口由 laravel-admin 的 web 和 admin 中间件保护，并使用 CSRF。
• STS 临时凭证只允许写入本次生成的对象 Key。
• 对象 Key 格式为 {APP_NAME}/{type}/YYYY/MM/DD/UUID.ext。

PJAX 导航兼容

从 v1.2.0 开始，扩展已原生支持 PJAX 导航后的组件重新初始化。

Laravel-admin 使用 PJAX 实现无刷新页面导航。在列表页点击编辑按钮进入编辑页时， 页面内容通过 AJAX 加载，但依赖 $(document).ready() 初始化的组件（如 COS 上传按钮） 不会自动重新初始化，导致组件不渲染。

工作原理

1. 扩展自动加载 field-init.js，提供全局初始化函数 window.initCosUploadField()
2. 字段配置数据存储在 HTML 元素的 data-cos-config 属性中
3. 在 PJAX 完成事件 (pjax:complete) 后，可以从 data-cos-config 读取配置并重新初始化

PJAX 重新初始化示例

在自定义的 pjax-reinit.js 中：

$(document).on('pjax:complete', function (event) {
    var $target = $(event.target);
    
    // 重新初始化 COS 上传组件
    $target.find('[id^="cos-js-upload-wrapper-"]').each(function () {
        var wrapperId = $(this).attr('id');
        var name = wrapperId.replace('cos-js-upload-wrapper-', '');
        var configData = $('#' + name + '-resource').data('cos-config');
        if (configData && typeof window.initCosUploadField === 'function') {
            window.initCosUploadField(name, configData);
        }
    });
});

这样从列表页点击编辑按钮进入页面时，COS 上传组件能正常渲染，无需手动刷新页面。