07 File Workflows

07 文件上传下载

WebNativeBrowser 支持网页常见的文件工作流。平台交互有所不同，但网页仍使用标准 HTML 能力。

---

1. 文件选择与上传

网页示例：

<input id="file" type="file" accept=".json,.csv,image/*">

document.getElementById("file").addEventListener("change", (event) => {
  const file = event.target.files?.[0];
  if (!file) return;

  console.log(file.name, file.size, file.type);
});

平台差异

平台	文件选择体验
Windows	系统原生文件选择窗口
Linux Runtime	插件提供的运行时文件选择窗口

---

2. 下载

网页可使用普通链接、download 属性、Blob 或 HTTP 下载。插件提供保存流程，并广播以下 JS 事件：

事件名	字段	说明
webNativeDownloadProgress	filename / received / total / percent	下载进度
webNativeDownloadComplete	filename / path / size	下载完成
webNativeDownloadFailed	filename / reason / canceled / interrupted	下载失败

监听示例：

WebNative.on("webNativeDownloadProgress", (messageBody) => {
  const state = JSON.parse(messageBody);
  console.log(state.filename, state.percent);
});

WebNative.on("webNativeDownloadComplete", (messageBody) => {
  const result = JSON.parse(messageBody);
  console.log("下载完成", result.filename, result.path);
});

WebNative.on("webNativeDownloadFailed", (messageBody) => {
  const error = JSON.parse(messageBody);
  console.error("下载失败", error.filename, error.reason);
});

webNative 前缀为插件保留命名空间，用户业务事件不要使用此前缀。

---

3. 内置下载提示

配置项（见 06-CEF 参数配置）：

[WebNative]
show_download_notification=true

• true：显示插件内置下载进度/结果提示，同时继续广播 JS 事件。
• false：不显示内置提示，仅广播事件，由网页或 UE 自行绘制 UI。

---

4. 无桌面与像素流送

需要区分三个概念：

1. Linux 应用所在机器的文件选择：选择渲染机器上的文件。
2. 纯无桌面部署：没有可交互桌面时，不应依赖本机弹窗完成工作流。
3. 像素流送远端用户选文件：应在远端用户浏览器中选取并上传，再由项目服务器接收；这不是渲染机器本地文件选择。

如果产品面向像素流送，建议单独设计 Web 上传服务和权限策略。详见 09-云渲染支持。

---

5. 安全建议

• 使用 accept 限制预期类型，但不要只依赖扩展名。
• UE/服务器端再次校验文件类型、大小和内容。
• 下载文件名需要过滤非法字符。
• 不自动执行下载后的文件。
• 对敏感目录设置明确访问策略。
• 客户数据上传前确认隐私与合规要求。

---

下一步

• 下载提示与权限配置：06-CEF 参数配置
• 远端上传与像素流送：09-云渲染支持
• 平台差异与发布测试：08-平台兼容性