Integration Guide

5 分钟把 kkFileView 接进你的业务项目。

这里按常见接入场景提供示例，方便你直接按需选用。默认假设服务地址为 https://preview.hnyuyuan.com/。

HTTP / HTTPS FTP AES 附加参数

URL 所有预览能力统一汇总到 `onlinePreview` 入口。

Base64 普通接入默认对原始文件地址做 Base64 编码后再传入。

参数扩展 支持页码、高亮、水印、密码、跨域、AES 和秘钥等控制项。

Quick Start

接入思路

推荐入口

前端只需要拿到可访问的文件 URL，然后把它编码后拼到 `https://preview.hnyuyuan.com/onlinePreview` 上即可。对于大多数业务系统，这是最快的落地路径。

普通 HTTP/HTTPS 文件地址：直接 Base64 编码后传入。
下载流接口没有后缀名：补充 `fullfilename=xxx.xxx`。
鉴权或加密场景：附加 Basic、FTP、AES 等参数。

HTTP / HTTPS

普通文件地址预览

适用于系统已经直接暴露出可下载文件地址的情况。前端只需要编码后打开新窗口。

                        var url = 'http://127.0.0.1:8080/file/test.txt';
window.open('https://preview.hnyuyuan.com/onlinePreview?url=' + encodeURIComponent(base64Encode(url)));
                    

Streaming

流式接口预览

很多业务系统通过 `fileId`、`code` 等参数走统一下载接口，此时原始 URL 没有后缀名，需要额外指定完整文件名。

                        var originUrl = 'http://127.0.0.1:8080/filedownload?fileId=1';
var previewUrl = originUrl + '&fullfilename=test.txt';
window.open('https://preview.hnyuyuan.com/onlinePreview?url=' + encodeURIComponent(Base64.encode(previewUrl)));
                    

FTP

FTP 资源预览

FTP 如果允许匿名访问，可以直接预览；如果需要认证，则把连接参数拼到 URL 后面传入。

                        // 匿名 FTP
var url = 'ftp://127.0.0.1/file/test.txt';
window.open('https://preview.hnyuyuan.com/onlinePreview?url=' + encodeURIComponent(Base64.encode(url)));

// 认证 FTP
var originUrl = 'ftp://127.0.0.1/file/test.txt';
var previewUrl = originUrl + '?ftp.control.port=21&ftp.username=admin&ftp.password=123456&ftp.control.encoding=utf8';
window.open('https://preview.hnyuyuan.com/onlinePreview?url=' + encodeURIComponent(Base64.encode(previewUrl)));
                    

Basic Auth

带 Basic 鉴权的 HTTP 资源

如果文件源本身需要用户名和密码，可以直接把 Basic 鉴权参数拼到地址中，再交给 kkFileView。

                        var originUrl = 'http://127.0.0.1/file/test.txt';
var previewUrl = originUrl + '?basic.name=admin&basic.pass=123456';
window.open('https://preview.hnyuyuan.com/onlinePreview?url=' + encodeURIComponent(Base64.encode(previewUrl)));
                    

AES

前后端同秘钥加密接入

如果不希望明文传递原始文件地址，可以在前端先做 AES 加密，再通过 `encryption=aes` 告知服务端按 AES 方式解密。

                        <script src="https://preview.hnyuyuan.com/js/crypto-js.js"></script>
<script src="https://preview.hnyuyuan.com/js/aes.js"></script>

function aesEncrypt(encryptString, key) {
  var keyBytes = CryptoJS.enc.Utf8.parse(key);
  var srcs = CryptoJS.enc.Utf8.parse(encryptString);
  var encrypted = CryptoJS.AES.encrypt(srcs, keyBytes, {
    mode: CryptoJS.mode.ECB,
    padding: CryptoJS.pad.Pkcs7
  });
  return encrypted.toString();
}

var key = '1234567890123456';
var url = 'http://127.0.0.1/file/test.txt';
window.open('https://preview.hnyuyuan.com/onlinePreview?url=' + encodeURIComponent(aesEncrypt(url, key)) + '&encryption=aes');
                    

Parameters

常用附加参数

这些参数都应该在原始 URL 编码完成之后，再附加到预览地址后面。

`filePassword`：加密文件的密码。
`page`：指定预览页码。
`highlightall`：关键字高亮。
`watermarkTxt`：动态水印文本。
`forceUpdatedCache=true`：强制刷新缓存。
`kkagent=true`：需要 kkFileView 代理跨域时启用。
`usePasswordCache=true`：开启密码缓存。
`key`：实例启用秘钥后传入访问秘钥。

                        var url = 'http://127.0.0.1:8080/file/test.txt';
window.open(
  'https://preview.hnyuyuan.com/onlinePreview?url=' +
  encodeURIComponent(base64Encode(url)) +
  '&filePassword=123' +
  '&page=1' +
  '&highlightall=kkfileview' +
  '&watermarkTxt=kkfileview' +
  '&kkagent=false' +
  '&key=123'
);
                    