本页内容
直链与 iframe
直接拼接文件 URL 和 API Key 打开预览，适合可信内网和低改造成本场景。
请求格式
http
GET https://preview.example.com/view?url={encoded_file_url}&key={api_key}参数
| 参数 | 类型 | 默认/必填 | 说明 |
|---|---|---|---|
url | string | 必填 | 经过 URL 编码的 HTTP/HTTPS 文件地址 |
key | string | 必填 | API Key |
title | string | 文件名 | 预览标题 |
watermark | string | 无 | 文字水印 |
watermark_image | string | 无 | 水印图片 URL |
toolbar | 0/1 | 1 | 是否显示工具栏 |
toolbar_color | #RRGGBB | 服务默认 | 工具栏颜色 |
background_color | #RRGGBB | 服务默认 | 工作区背景颜色 |
saveable | 0/1 | 1 | 是否允许下载 |
printable | 0/1 | 1 | 是否允许打印 |
copyable | 0/1 | 1 | 是否允许复制 |
mtime | number | 无 | 文件修改时间戳，用于刷新缓存 |
iframe 嵌入
iframe 只是承载 /view 地址，不增加新的认证协议；建议根据业务页面设置 640–800px 高度。
html
<iframe src="https://preview.example.com/view?token={token}" width="100%" height="720" title="文档预览"></iframe>编码与来源限制
url、水印和标题应分别进行 URL 编码，颜色中的 # 必须编码为 %23。建议使用 URL 与 URLSearchParams 构建链接，避免文件 URL 内部的 & 被解析为预览参数。
javascript
const preview = new URL('/view', 'https://preview.example.com');
preview.searchParams.set('url', fileURL);
preview.searchParams.set('key', apiKey);
preview.searchParams.set('watermark', '内部资料');
// 仅在可信环境使用 preview.href；公网优先使用 Token API。iframe 使用接口返回的完整 view_url。跨域嵌入时将业务页面来源配置到来源白名单，并确保业务站点的 CSP frame-src 允许预览域名。不要在 iframe 上盲目添加会禁止脚本的 sandbox 配置。