PandaJS 使用说明 (1.3)： 文件下传与上载

PandaJS 使用说明 (1.3)： 文件上传与下载

PandaJS 使用说明 (1.3)： 文件上传与下载

　　PanadaJS 为文件上传与下载提供了服务器端和客户端的组件，客户端 JS 可以根据浏览器的支持情况，自动选择 HTML5，Flash 和传统（隐藏）表单上传；服务器端兼容 HTML5 Streaming 方式上传和 Multipart 方式上传。
　　接下来，就让我们在上一篇文章编写的 hello.html 上直接添加增加一个文件上传按钮吧。

运行效果

　　三种上传方式外观相似，如下图所示：


　　直接在前一篇文章中使用的 hello.html 中增加了上传按钮。点击上传按钮弹出文件选择框（HTML 或 Flash 方式支持文件多选），选择完成后立即开始上传。上传过程中显示上传进度，期间可以取消；完成后添加到下方的完成列表中，可以移除已经上传完成的文件。
　　HTML5 和 表单上传的样式通过 CSS 样式进行设置，Flash 按钮需要加载一张图片（如附件中的 panda.button.png），可以在创建组件的参数中设置样式。

　　同时，对于支持 HTML5 的浏览器，还支持拖拽文件进行上传。
　　拖拽效果如下：


　　只有支持 HTML5 方式的浏览器才提供拖拽功能，如较新版本的 Chrome，FireFox 等；
　　Safari 上的拖拽区域不会显示出来（因为没法 drop 到一个 div 上，谁有解决的办法吗？），需要拖拽到上传按钮上，并且同时拖拽多个文件到上传按钮时，也只上传一个文件（这是 Safari 的一个 Bug，有办法解决吗？）。
　　点击文件名称进行下载：

HTML 页面修改

　　首先，需要在这句代码：

<div id="message" /></div>

　　的后面添加一个文件上传按钮：

<div id="file-uploader"></div>

　　然后，增加显示已上传的附件的名称的 div：

<div id="attachment_names"></div>

	<script id="attachment_names_tmpl" type="tmpl">
		<span id="attachment_${file.id}" class="attachment_name">
			<a href="##" name="${data.name}">${panda.shorten(file.name, 11)}</a> (${panda.formatSize(file.size)})
			<a href="##" class="remove" title="Remove">&nbsp;</a>
		</span>
	</script>

　　最后，需要在以下代码：

<script src="js/lib/panda.js"></script>

　　的后面增加对 panda.uploader.js 的引用。

<script src="js/lib/panda.uploader.js"></script>

　　HTML 页面的修改就这些了，接着让我们看看 JS 代码的修改。

客户端 JS 修改

　　在 webapp/js/hello.js 中，需要增加如下代码，以初始化一个文件上传按钮：

	panda.uploader({
		// 指定文件上传按钮所在的div
		element: $("#file-uploader")[0],
		// 指定处理请求的方法
		params: { action: "hello.upload" },
		// 文件大小限制
		sizeLimit: 1000 * 1024 * 1024,
		// 上传结束的处理
		onComplete: function(file, data){
			// 上传结束，显示文件名称
			$("#attachment_names").append($("#attachment_names_tmpl").tmpl({
				file: file, data: data
			}));

			// 增加文件名称的点击事件
			var $attachment = $("#attachment_" + file.id);
			var $a = $attachment.find("a");

			// 点击文件名称，开始下载文件
			$a.eq(0).click(function() {
				panda.open({
					action: "hello.download",
					params: { name: $(this).attr("name") }
				});
			});

			// 点击 Remove 按钮，删除已上传的附件
			$a.eq(1).click(function(){ $attachment.remove(); });
		}
	});

服务器端 JS 修改

　　在 scripts/api/hello.js 中增加如下代码，以处理文件上传与下载的请求：

	// 文件上传
	upload: function(params, req) {
		// 检查文件大小
		var size = parseFloat(req.getHeader("Content-Length"));
		
		if (!size || size <= 0 ) {
			throw "Invalid Content-Length";
		} else if (size > 1000 * 1024 * 1024) {
			throw "File too large.";
		}

		// 生成文件名称
		var prefix = new Date().getTime() + "-";
		var name = prefix + panda.fileName(req, "Filedata");

		// 上传文件
		var target = "upload/" + name;
		var size = panda.upload(req, "Filedata", target);

		// 返回上传结果
		return { name: name, size: size };
	},

	// 文件下载
	download: function(params, req, res) {
		// 提取文件的原始名称
		var name = "" + params.name;
		name = name.substr(name.indexOf("-") + 1);

		// 下载文件
		var source = "upload/" + params.name;
		panda.download(req, res, name, source);

		// 返回 null，表示不需要返回 JSON 结果
		return null;
	}

panda.uploader 的其他配置项

　　panda.uploader(...) 还支持更多的配置项：

　　【基本配置项】
　　element： 上传组件的容器，可以是 div 或 span
　　action： 上传 URL ，一般为 "api"
　　params： object，表示发送到服务器端的额外参数
　　sizeLimit： 上传总大小限制
　　template： HTML 片段，作为上传组件的模板，其中 {tip} 表示提示信息
　　fileTemplate： HTML 片段，作为正在上传的文件条目的模板
　　allowedExtensions： 表示允许的扩展名

　　【回调函数】
　　onSubmit(id, fileName)： 开始上传的回调函数
　　onComplete(file, data)： 上传完成时的回调函数
　　showMessage： 显示信息的方式，默认为 alert(message)


　　【消息配置】

　　用 messages 属性（object类型）进行消息配置。
　　可配置的消息包括：

　　typeError： 文件类型错误，默认为 '{file} has invalid extension. Only {extensions} are allowed.'
　　sizeError： 文件大小错误，默认为 'Total size is too large, maximum size is {sizeLimit}.'
　　emptyError： 文件为空时的错误，默认为 '{file} is empty, please select files again without it.'
　　onLeave： 文件正在上传时离开页面的提示，默认为 'The files are being uploaded, if you leave now the upload will be cancelled.'
　　sizeTip： 文件大小限制提示信息，默认为  'Maximum total size is {sizeLimit}. '
　　ddTip： 拖拽支持提示，默认为 'Drag and Drop is Supported.'



　　【CSS Class 配置】

　　用 classes 属性（object类型） 配置上传组件对应的各部件的 CSS Class。

　　button： 上传按钮，默认为 'pure-upload-button'
　　drop： 拖拽区域，默认为 'pure-upload-drop-area'
　　dropActive： 鼠标滑入时的拖拽区域，默认为 'pure-upload-drop-area-active'
　　list： 上传中的文件列表，默认为 'pure-upload-list'
　　file： 上传中的文件名称，默认为 'pure-upload-file'
　　spinner： 上传中的文件的进度条，默认为 'pure-upload-spinner'
　　size： 上传中的文件大小，默认为 'pure-upload-size'
　　cancel： 取消上传的链接，默认为 'pure-upload-cancel'
　　buttonFocus： 焦点位于上传按钮时的样式，默认为 'pure-upload-button-focus'
　　buttonHover： 鼠标滑过上传按钮时的样式，默认为 'pure-upload-button-hover'


　　【Flash 属性配置】

　　用 flashSettings 属性（object类型） 配置 flash 上传按钮

　　swfPath： swf 文件路径，默认为 'swf/pure.upload.swf',
　　url： 上传 url，默认为 options.action + '?' + $.param(options.params),
　　image： flash 按钮图片路径，默认为 'images/pure.upload.png',
　　width： 按钮宽度，默认为 107
　　height： 按钮高度，默认为 31
　　text： 文字，默认为 'Upload a file',
　　textStyle： 文字样式，默认为 'font-family: Arial; font-size: 12px',
　　textTop： 文字上方开始位置，默认为 6
　　textLeft： 文字左边开始位置，默认为 17

　　【返回对象支持的方法】

　　通过pure.uploader(...)方法返回的对象支持以下方法：

　　reset()：  重置uploader
　　uploading()： 检查是否有文件还在上传中