README

安装

通过 Composer

$ composer require nepada/file-upload-control

注册并配置容器扩展

唯一必需的配置选项是 uploadDirectory，它决定了上传文件临时存储的位置。

extensions:
    fileUploadControl: Nepada\Bridges\FileUploadControlDI\FileUploadControlExtension
fileUploadControl:
    uploadDirectory: %appDir%/../files/uploads

将工厂方法添加到您的表单中

选项 A：通过 DI 扩展安装表单容器扩展方法

fileUploadControl:
    registerExtensionMethod: true # defaults to false

这将注册扩展方法 addFileUpload($name, $label = null): FileUploadControl 到 Nette\Forms\Container。

选项 B：在您的基表单/容器类中使用 trait

您也可以在您的基表单/容器类中使用 FileUploadControlMixin trait 来添加方法 addFileUpload($name, $label = null): FileUploadControl。您需要将 FileUploadControlFactory 注入到您创建的每个表单/容器中，例如通过组合通用表单工厂服务和装饰器配置来启用注入。

示例

services:
    - FormFactory
decorator:
    Form:
        inject: true

trait FormControls
{

    use \Nepada\Bridges\FileUploadControlForms\FileUploadControlMixin;

    public function addContainer($name)
    {
        $control = new Container;
        $control->injectFileUploadFactory($this->fileUploadControlFactory);
        $control->setCurrentGroup($this->getCurrentGroup());
        if ($this->currentGroup !== null) {
            $this->currentGroup->add($control);
        }
        return $this[$name] = $control;
    }

}

class Container extends \Nette\Forms\Container
{

    use FormControls;

}

class Form extends \Nette\Application\UI\Form
{

    use FormControls;

}

interface FormFactory
{

    public function create(): Form;

}

用法

FileUploadControl 提供了一种类似于标准 Nette\Forms\Controls\UploadControl 的文件上传方式。主要区别在于文件通过 AJAX 请求分块上传到临时存储。这意味着您可以上传多个大文件而不用担心遇到服务器端文件/POST 大小限制。在提交表单后，表单控件的值将被设置为在临时存储中先前上传的文件 FileUpload 实例的列表。

配置

DI 扩展支持以下配置选项

fileUpload:
    uploadDirectory: path/to/temp/storage # required, no default value
    registerExtensionMethod: true # defaults to false
    templateFile: path/to/alternative/control-template.latte # defaults to the bundled Bootstrap 4 template
    thumbnails: # image thumbnail settings
        enable: true
        width: 200
        height: 150

该软件包包括为 Bootstrap 版本 4 和 版本 5 构建的模板和样式。默认情况下，使用版本 4，但为了提高向前兼容性，您应始终明确指定您希望使用的版本。

fileUpload:
    templateFile: Nepada\FileUploadControl\FileUploadControl::TEMPLATE_FILE_BOOTSTRAP4
    # or for Bootstrap 5
    # templateFile: Nepada\FileUploadControl\FileUploadControl::TEMPLATE_FILE_BOOTSTRAP5

验证

所有标准 Nette 文件上传相关验证都按预期工作。此外，您可以通过 "length" 规则限制允许上传的文件数量。

客户端

此软件包包含基于 blueimp-file-upload 的客户端。它作为 npm 软件包 @nepada/file-upload-control 发布。

使用预编译的包

使用预编译的包是让客户端工作起来最快的方法。

<link rel="stylesheet" href="https://unpkg.com/@nepada/file-upload-control@%5E1.7/dist/css/file-upload-control-bootstrap4.min.css">
<!-- or for Bootstrap 5
<link rel="stylesheet" href="https://unpkg.com/@nepada/file-upload-control@%5E1.7/dist/css/file-upload-control-bootstrap5.min.css">
-->
<script src="https://unpkg.com/jquery@%5E3.5.0/dist/jquery.min.js"></script>
<script src="https://unpkg.com/blueimp-file-upload@%5E10.10.0/js/vendor/jquery.ui.widget.js"></script>
<script src="https://unpkg.com/blueimp-file-upload@%5E10.10.0/js/jquery.fileupload.js"></script>
<script src="https://unpkg.com/nette-forms@%5E3.0.3/src/assets/netteForms.min.js"></script>
<script src="https://unpkg.com/@nepada/file-upload-control@%5E1.7/dist/js/file-upload-control.min.js"></script>

构建自己的包

强烈建议您通过 npm 安装客户端软件包并编译自己的包。

以下是一个初始化文件上传控件和 Nette 表单的示例脚本。

import Nette from 'nette-forms';
import initializeFileUploadControl from '@nepada/file-upload-control';

initializeFileUploadControl(Nette);

Nette.initOnLoad();

如果您使用 Bootstrap 4 或 5，您可以通过将源 SCSS 文件导入到 Sass 样式中轻松自定义默认外观

• _file-upload-control-module-bootstrap4.scss，有关覆盖，请参阅可用的 变量
• _file-upload-control-module-bootstrap5.scss，有关覆盖，请参阅可用的 变量