seblhaire/uploader

一个 Laravel 库，提供文件上传工具。一个 JavaScript 库构建了一个完整的文件上传组件，包括上传按钮、拖放区域、进度条和结果构建器。还有一个控制器用于管理上传的文件。

维护者

详细信息

github.com/seblhaire/uploader

主页

源代码

问题

安装: 56

依赖项: 0

建议者: 0

安全性: 0

星星: 0

关注者: 1

分支: 0

公开问题: 0

语言：JavaScript

4.3.0 2024-03-13 18:54 UTC

Requires

MIT 9d0a0647a813eb2867c99f17dd6de44a391c9869

This package is auto-updated.

Last update: 2024-09-13 20:04:58 UTC

README

由 Sébastien L'haire 编写

一个 Laravel 库，提供文件上传工具。一个 JavaScript 库构建了一个完整的文件上传组件，包括上传按钮、拖放区域、进度条和结果构建器。还有一个控制器用于管理上传的文件。

它使用

Uploader example image

演示网站可在此处找到。

安装

  1. composer require seblhaire/uploader

  2. Composer 将自动将包与 Laravel 连接起来。但您仍然可以在 config/app.php 中显式添加提供者和外观。

  'providers' => [
    ...
      Seblhaire\TableBuilder\UploaderServiceProvider::class,
      ...
   ],
   'aliases' => [
        ...
      "TableBuilderHelper" => Seblhaire\TableBuilder\UploaderHelper::class
   ]
  1. 发布包（可选）。
$ php artisan vendor:publish
  1. 设置存储链接（可选，请参阅 Laravel 文档）
$ php artisan storage:link
  1. 有关 JavaScript 和样式表的详细信息，请参阅下一节。

JavaScript 和样式表

在网页上，每个 JS 库和 CSS 样式表都可以单独链接。如果您选择这种方法，首先下载并安装上述提到的库。然后按照上述说明发布包文件，并在您的模板中放置以下标签

<script type="text/javascript" src="js/vendor/seblhaire/uploader/upload.js"></script>
<link rel="stylesheet" type="text/css" property="stylesheet" href="css/vendor/seblhaire/uploader/uploader.css"/>

但网站通常使用许多库和样式表，浏览器必须下载许多文件才能正确渲染网站。现代网站通常包含一个单独的压缩 JavaScript 文件，其中包含必要的脚本；样式表也有同样的原则。在 Laravel 中，您可以使用 Laravel Mix 来编译文件。

使用 NPM 包管理器： npm install bootstrap jquery clipboard @fortawesome/fontawesome-free

然后您的 JavaScript 源文件应该像这样

global.jQuery = require('jquery');
var $ = global.jQuery;
var jQuery = global.JQuery;
window.$ = $;
window.jQuery = jQuery;
require('bootstrap');
global.Clipboard = require('clipboard');
require('../../vendor/seblhaire/uploader/resources/js/uploader.js');
require('../../vendor/seblhaire/uploader/resources/js/UploadedFileContainerExt.js');

UploadedFileContainerExt 是可选的，因为您可以编写自己的结果处理器和自己的文件容器。

对于您的样式表

@import '~bootstrap/scss/bootstrap';
@import "~@fortawesome/fontawesome-free/scss/fontawesome";
@import "~@fortawesome/fontawesome-free/scss/regular";
@import "~@fortawesome/fontawesome-free/scss/solid";
@import "~@fortawesome/fontawesome-free/scss/brands";

@import "../../vendor/seblhaire/uploader/resources/css/uploader";

配置文件

上传库是可定制的。默认值可以在配置文件中更改，或者通过在 Facade 函数中传递选项（见下一节）。如果您想修改默认配置文件，发布包文件并访问 config/uploader.php。

用法

上传包附带一个简单的 Facade。

链接到 Facade

use Seblhaire\Uploader\UploaderHelper;

UploaderHelper::init

初始化一个可以传递给视图以正确设置上传器的 PHP 对象。

UploaderHelper::init($uploaderElement, $label, $url, $options = array(), $additionalParams = array())

其中

  • $uploaderElement: 必须插入上传器的 <div> 标签的 id。
  • $label: 上传器的字段标签
  • $url: 必须用于上传文件的路由。参见 下面。
  • $options: 选项数组。
    • 'multiple' : 用户可以上传多个文件。默认 false。
    • 'maindiv' ; 主 div 的类。默认: 'mb-3'。
    • 'draggable': 设置拖放选项。默认 true。
    • 'hidden': 在开始时隐藏整个上传器。默认 false。
    • 'hiddenuploader': 在开始时隐藏上传器但仍然显示标签。默认 false。
    • 'uploadzoneclass': 主要上传器 div 的类。默认 'uploadzone'。
    • 'acceptable_mimes'：允许的文件扩展名列表，用逗号分隔。
    • 'droptext'：显示在拖拽区域的文本。文本可以是字符串或翻译键。参见以下内容。
    • 'droptextclass'：拖拽区域文本的类。默认：'form-text'。
    • 'labelclass'：标签的类。默认：'col-form-label'。
    • 'buttondivclass'：按钮div的类。默认：'col-auto'
    • 'buttonclass'：上传按钮的类。默认：'btn btn-dark'。
    • 'uploadicon'：定义按钮图标的FontAwesome类。默认："fas fa-upload"。
    • 'uploadtext'：上传按钮的文本。文本可以是字符串或翻译键。参见以下内容。
    • 'progbarmainclass'：主要进度条div的类。默认："progress"。
    • 'progressbarwidth'：进度条的宽度。可以是固定值或百分比。默认：'40%'。
    • 'progressbar'：进度条的类。默认："progress-bar progress-bar-striped progress-bar-animated"。
    • 'failmessage'：上传失败时显示的消息。文本可以是字符串或翻译键。参见以下内容。
    • 'alerterrorclass'：失败时显示的alert div的类。默认：'alert alert-danger'。
    • 'alertsuccessclass'：成功时显示的alert div的类。默认：'alert alert-success'。
    • 'alerttimeout'：alert div隐藏前的时间（毫秒）。默认：10000。
    • 'path'：上传文件的默认路径。参见以下内容。默认："/"。
    • 'filepattern'：替换原始文件名的名称模式。默认：''。
    • 'storagename'：存储名称，参见以下setstoragename函数。
    • 'rename'：如果存在同名文件，当前文件将被重命名。默认：false。
    • 'maxfilesizek'：最大文件大小（千字节）。默认：null。
    • 'resultprocessor'：上传结果处理器类。参见以下内容，默认：'UploadresultProcessor'。
    • 'filecontainer'：文件容器类。参见以下内容，默认：'UploadedFileContainer'。
    • 'filecontainerclass'：文件容器类。默认：'d-flex uploadres'。
    • 'errorfn'：如果不使用默认的错误处理函数，则处理文件上传错误的函数。函数名称或null。默认：null。
    • 'resultdivclass'：文件列表容器的类。默认：'uploadresdiv'。
    • 'delurl'：可以调用文件结果中的文件删除控制器函数的路由。默认：null。
    • 'resultbaseurl'：用于构建URL的基础URL。默认：null。
    • 'additionalparamsfn'：添加参数到上传函数的函数。默认：null。
    • 'delete'：文件删除确认的文本。文本可以是字符串或翻译键。参见以下内容。
    • 'afteruploadfn'：文件上传后调用的回调函数：默认：null。
  • $additionalParams：要发送到路由的参数数组。

上传器将数据发送到控制器（参见以下内容），该控制器接受参数来设置文件名、文件系统存储名称和文件路径。由于这些值通常动态设置，上传器JavaScript对象提供设置它们的方法；我们构建的PHP对象通过我们的外观提供插入JavaScript代码的方法，例如在Ajax脚本中。

获取上传器

getUploader()

打印获取上传器类的JavaScript代码。

设置路径名称

setPath($path, $is_string = true)

  • $path可以是字符串或变量名
  • $is_string 表示 $path 是否为字符串（true）或变量（false）。

更多解释请参阅这里，用法示例请参阅这里。

设置文件模式

setfilepattern($filename)

定义一个模式来构建上传文件的文件名，该模式将替换原始文件名。更多解释请参阅这里，用法示例请参阅这里。

设置文件系统存储名称

setstoragename($storagename)

上传器使用Laravel 文件系统。 $storagename 必须是您的应用程序 config/filesystems.php 中存储的存储名称之一。更多解释请参阅这里，用法示例请参阅这里。

设置最大文件大小

setmaxsize($size)

定义最大文件大小（单位为KB）。

设置接受文件类型

setmimes($mimes)

接受一个由逗号分隔的文件扩展名字符串。

设置重命名权限

setrename($val)

定义如果上传目录中已存在同名文件，是否重命名当前文件。接受布尔变量或字符串 'true' 或 'false'。

重置上传器

reset()

清空文件列表。

获取结果处理器

getresultprocessor()

上传成功后，Uploader 返回一个结果处理器，它是一个 JavaScript 对象。更多详情请参阅这里。您可能需要访问附加到您的 Uploader 的结果处理器，例如添加之前过程中已上传的文件。在这种情况下，请在您的视图中插入以下内容

var proc = {!! $uploader->getresultprocessor() !!};

显示上传器

showall()

如果部分或全部已隐藏，则完全显示上传器。

showuploader()

如果已隐藏，则显示上传器按钮和区域。

完全隐藏上传器

hideall()

隐藏上传器区域和标签。

hideuploader()

隐藏上传器区域。

切换显示

toggleall()

如果整个上传器可见，则隐藏它，如果隐藏，则显示它。

toggleuploader()

如果上传器区域可见，则隐藏它，如果隐藏，则显示它。

摘要

总结，在您的控制器中插入

$uploader = UploaderHelper::init(
  'uploaderdiv',
  'Uploader',
  route('fileupload'),
  [
    'filecontainer' => 'UploadedFileContainerExt'
  ], [ // additional parameters transmitted to second script
    'article_title' => "l'ami",
    'article_id' => 40
]);
...
return view('uploader', ['uploader' => $uploader]);

在您的 blade 模板中，将以下内容插入到您希望上传器出现的位置

{!! $uploader !!}

如果您需要设置表单参数或在结果列表中添加文件，可以使用上述方法。在这种情况下，我们将在文档就绪子句中插入它们，但您通常会在 Ajax 函数中使用它

jQuery(document).ready(function(){
  // set uploaders after page is completely loaded
  {!! $uploader->setpath('/uploads') .
  $uploader->setstoragename('public'); !!}
  var proc = {!! $uploader4->getresultprocessor() !!}
  proc.preparedisplay({filename: 'seb.jpg', ext: 'jpg'}, 1);
});

上传器结果类

文件处理很大程度上取决于您的网络应用程序目的。因此，不可能提供一个满足所有需求的完整上传器包。我们提供有用的函数。

上传器使用一个结果类来处理控制器返回的上传结果。包中包含一个名为 UploadresultProcessor 的结果类，存储在 resources/js/upload.js 中，可以替换或扩展。

必需的类属性和函数

  • 属性 uploader。这将结果类实例与其相应的上传器实例链接。
  • 属性 filelist。包含上传文件。
  • 方法 init(uploader)。它在上传器实例创建后由上传器调用，以设置 uploader 属性。
  • 方法 process(res)：此函数用于处理上传结果。对于每个上传的文件，它创建一个文件容器类实例（请参见下文）并将文件添加到 filelist 属性。如果结果包含错误，错误将在一个 alert <div> 中显示。
  • 方法 buildresdiv(id, myclass) 构建 <div> 来包含文件列表。

文件容器是一个类，它会在文件列表 <div> 内部构建一个 <div>。类名在上传器参数 filecontainer 中定义。它必须具有以下方法：

  • 方法 init(processor) 初始化类。它将其链接到文件处理器（因此也链接到上传器），并初始化一个属性 idx，该属性包含文件处理器 filelist 中的文件索引。
  • 方法 build(file, info) 构建一个 <div> 并添加来自 file 参数的信息。 info 包含一般信息，例如基础 URL。

在 resources/js/upload.js 中，您可以找到默认由我们的上传器使用的文件容器 UploadedFileContainer。它构建一个非常简单的容器，包含基本文件信息。我们还添加了一个 URL 构建工具 buildurl(file, info)，您可以在自己的类扩展中使用它。文件 URL 的构建遵循以下规则：

  • 如果文件上传路由返回的文件对象包含参数 url，我们返回此值。
  • 如果参数 info 中的通用信息包含 baseurl 值，我们使用此值构建文件 URL。
  • 如果文件处理器实例中定义了属性 baseurl，我们使用此值构建文件 URL。
  • 如果上传器参数中定义了选项 baseurl，我们使用此值构建文件 URL。

在 resources/js/UploadedFileContainerExt.js 中，我们定义了一个名为 UploadedFileContainerExt 的类，它扩展了 UploadedFileContainer，构建了一个带有图像缩略图的良好文件容器，并提供了其他功能，例如文件 URL 复制和文件删除处理器，该处理器调用上传器参数 delurl 定义的路线，从文件结果容器 filelist 中删除文件。

控制器

上传器包包含一些辅助工具，可以帮助您轻松构建控制器方法。我们使用 Laravel 文件存储系统。例如，文件可以存储在公共文件夹中，用于网站，或在存储系统中用于其他目的。

更多示例可以在这里找到。

验证规则

我们为我们的上传器构建了两个 Laravel 验证规则，这些规则非常有用。

  • FiletypeRule 验证上传文件属于允许的文件类型。
  • FilesizeRule 验证上传文件的大小不超过为我们上传器定义的最大文件大小。

FileuploadRequest 是一个自定义请求验证规则，用于验证我们的上传器字段。如果需要验证其他参数，它可以被扩展。

namespace App\Http\Requests;

use Seblhaire\Uploader\FileuploadRequest;

class Fileupload2Request extends FileuploadRequest
{

    public function rules()
    {
        return array_merge(parent::rules(), [
          'article_title' => "required|string",
          'article_id' => "required|numeric"
        ]);
    }
}

受保护的特质函数

我们在 UploaderTrait 中定义了受保护的方法，可以在以下方式在控制器中使用。

use Seblhaire\Uploader\UploaderTrait;

class FileUploadController extends Controller
{
  use UploaderTrait;
  ...

buildFileObj($filename)

从文件名构建一个简单的 stdClass 对象，包含字段 name 和 ext，这些字段将被特质中的其他函数使用。

buildUniqueFileName($disk, $path, $fileobj, $separator = '-')

此函数在上传目录中构建一个唯一的文件名。

cleanFileName($filename)

从文件名中移除重音符号和空白字符。

getPath($request)

返回默认配置文件中定义的或从上传器参数中定义的文件路径。

getDisk($request, $path)

返回默认配置文件中或上传器参数中定义的存储名称，并从路径创建目录。

翻译键

Laravel在进程早期就加载配置文件。因此，配置文件不能包含__('translation.key')。为了解决这个问题，我们创建了一个助手，可以直接打印字符串或将翻译键发送到翻译助手。翻译键可以用字符#分隔。例如："uploader::messages.uploadtext"。原始翻译存储在vendor/seblhaire/uploader/resources/lang下。如果你发布包文件，你可以在resources/lang/vendor/uploader/中找到翻译。

请随意用你的语言翻译键，并将其发送给作者或提交一个GitHub上的merge请求。

有问题？想贡献？

请随意发送功能请求或merge请求给作者，或者简单地提问。