Load

<br/> >i 本文档的最新修订日期是: > **2021-05-20** # Load ## 模块简述 将浏览器上传的文件存储至服务器以及将远程的文件下载至服务器。 ## :: Up()方法 ### 语法 **<font color="#0099ff"><font color="#ff6600">Load</font> :: <font color="#ff6600">Up</font> ( <kbd>传参数组</kbd> )</font>** ### 说明 将浏览器上传的文件存储至服务器,并返回已上传文件的信息。 此方法 <font color="#c7254e">`支持`</font> 中文参数名。 ### 参数 * **<font color="#ff6600">`field(字段)`</font>** <font color="#0099ff">`(Array)`</font> <font color="#BBBBBB">`<必须>`</font>: 检测表单中的文件域字段(也就是HTML表单里文件域 <font color="#c7254e">`name`</font> 属性的值)是否存在、是否上传了文件。 此参数为一个一维数组,数组的键无需定义,值为 <font color="#c7254e">`字段名[,非空检查]`</font> 的字符串。 其中,<font color="#c7254e">`字段名`</font> 为需要检查的字段,<font color="#c7254e">`非空检查`</font> 为检查对应的字段是否有文件上传(值为 <font color="#c7254e">`TRUE`</font> 或 <font color="#c7254e">`FALSE`</font> ,未被定义时默认值为FALSE)。 * **<font color="#ff6600">`path(路径)`</font>** <font color="#0099ff">`(String | Array)`</font> <font color="#BBBBBB">`<必须>`</font>: 用以指定将上传的文件存储到何处。 当传入的值的类型为 <font color="#c7254e">`String`</font> 时,对所有字段生效。 当传入的值的类型为 <font color="#c7254e">`Array`</font> 时,此参数为一个一维数组,数组的键为字段名,值为文件存储的路径。如果一个字段在 <font color="#c7254e">`field`</font> 参数中存在,而在此参数中没有,则会引发报错。 路径是相对于 <font color="#c7254e">`应用根目录`</font> (即Core、Source文件夹所在的目录,通常是站点根目录)的路径,以 <font color="#c7254e">`/`</font> 开始。 * **<font color="#ff6600">`type(类型)`</font>** <font color="#0099ff">`(String | Array)`</font> <font color="#BBBBBB">`<必须>`</font>: 用以指定所允许的文件上传类型。 所有允许上传的文件 <font color="#c7254e">`后缀名`</font> 用 <font color="#c7254e">`,`</font> 分隔,组成那个一个字符串。 当传入的值的类型为 <font color="#c7254e">`String`</font> 时,对所有字段生效。 当传入的值的类型为 <font color="#c7254e">`Array`</font> 时,此参数为一个一维数组,数组的键为字段名,值为允许的文件类型。如果一个字段在 <font color="#c7254e">`field`</font> 参数中存在,而在此参数中没有,则会引发报错。 * **<font color="#ff6600">`save_name(保存名称)`</font>** <font color="#0099ff">`(Array)`</font> <font color="#BBBBBB">`NULL`</font>: 用以指定新文件的文件名 <font color="#c7254e">`前缀`</font> 。 默认采用 <font color="#c7254e">`32位随机MD5值`</font> 作为文件名的前缀。 此参数为一个一维数组,数组的键为字段名,值为文件的前缀。如果一个字段在 <font color="#c7254e">`field`</font> 参数中存在,而在此参数中没有,则会使用默认值。 >w 如果一个字段中上传了多个文件,则此参数不会生效。 * **<font color="#ff6600">`size(大小)`</font>** <font color="#0099ff">`(Int | Array)`</font> <font color="#BBBBBB">`10240`</font>: 用以指定所上传文件的最大大小。 单位是 <font color="#c7254e">`KB`</font> ,默认值为10240(即10MB)。 当传入的值的类型为 <font color="#c7254e">`Int`</font> 时,对所有字段生效。 当传入的值的类型为 <font color="#c7254e">`Array`</font> 时,此参数为一个一维数组,数组的键为字段名,值为允许的文件类型。如果一个字段在 <font color="#c7254e">`field`</font> 参数中存在,而在此参数中没有,则会使用默认值。 * **<font color="#ff6600">`number(数量)`</font>** <font color="#0099ff">`(Int | Array)`</font> <font color="#BBBBBB">`NULL`</font>: 用以指定单个字段内所能上传的文件数量。 默认单个字段最多能够上传 <font color="#c7254e">`1`</font> 个文件。 当传入的值的类型为 <font color="#c7254e">`Int`</font> 时,对所有字段生效。 当传入的值的类型为 <font color="#c7254e">`Array`</font> 时,此参数为一个一维数组,数组的键为字段名,值为允许上传的文件数量。如果一个字段在 <font color="#c7254e">`field`</font> 参数中存在,而在此参数中没有,则会使用默认值。 * **<font color="#ff6600">`ignore_error(忽略错误)`</font>** <font color="#0099ff">`(Bool)`</font> <font color="#BBBBBB">`FALSE`</font>: 用以指定是否忽略上传过程中遇到的错误。 当值为 <font color="#c7254e">`FALSE`</font> 时,如果上传过程中遇到错误,将会中断程序运行,并进行报错。 当值为 <font color="#c7254e">`TRUE`</font> 时,如果上传过程中遇到错误,不会中断程序运行,但返回的文件名将变为 <font color="#c7254e">`NULL`</font> 。 ### 返回 <font color="#0099ff">`(Array)`</font> 类型。 返回的值为 <font color="#c7254e">`Array`</font> 类型,其中键为 <font color="#c7254e">`field`</font> 参数中定义的字段名,值为已上传文件的文件名的字符串。当一个字段中上传了多个文件时,值将变为一个由所有已上传文件的文件名组成的数组。 >d 务必注意在服务器中设置 <font color="#c7254e">`资源的响应方式`</font> (例如访问一个PDF文档时,服务器是直接展示还是提供下载),这关系到服务器的安全。 >d 如果要将保存时的文件名设定为上传文件原本的文件名,务必对文件名进行安全过滤。 >w 务必在前端页面中,即表单页通过HTML代码和JS来限制文件的 <font color="#c7254e">`上传类型`</font> 和 <font color="#c7254e">`大小`</font> ,这样用户体验更加友好,也可以拦截大部分使用者 <font color="#c7254e">`无心的非法操作`</font> 。 ## :: Down()方法 ### 语法 **<font color="#0099ff"><font color="#ff6600">Load</font> :: <font color="#ff6600">Down</font> ( <kbd>传参数组</kbd> )</font>** ### 说明 从远程下载文件至服务器。 此方法 <font color="#c7254e">`支持`</font> 中文参数名。 ### 参数 * **<font color="#ff6600">`url(地址)`</font>** <font color="#0099ff">`(String)`</font> <font color="#BBBBBB">`<必须>`</font>: 用以指定需要下载的URL。 * **<font color="#ff6600">`path(路径)`</font>** <font color="#0099ff">`(String)`</font> <font color="#BBBBBB">`<必须>`</font>: 用以指定将下载的文件存储到何处。 值为相对于 <font color="#c7254e">`应用根目录`</font> (即Core、Source文件夹所在的目录,通常是站点根目录)的路径,以 <font color="#c7254e">`/`</font> 开始。 * **<font color="#ff6600">`timeout(超时时间)`</font>** <font color="#0099ff">`(Int)`</font> <font color="#BBBBBB">`86400`</font>: 用以指定超时时间。 值的单位为秒(s)。 ### 返回 <font color="#0099ff">`(String)`</font> 类型。 返回的字符串为新文件相对于 <font color="#c7254e">`应用根目录`</font> (即Core、Source文件夹所在的目录,通常是站点根目录)的路径。 >w 出于安全因素考虑,新的文件的文件名由框架自动指定,采用 <font color="#c7254e">`时间戳+3位随机数`</font> 作为文件名的前缀。请手动修改文件名。 >w 当服务器网络不畅,或目标地址超时响应时,框架将 <font color="#c7254e">`报错`</font> 。