tencent cloud

对象存储

动态与公告
产品动态
产品公告
产品简介
产品概述
功能概览
应用场景
产品优势
基本概念
地域和访问域名
规格与限制
产品计费
计费概述
计费方式
计费项
免费额度
计费示例
查看和下载账单
欠费说明
常见问题
快速入门
控制台快速入门
COSBrowser 快速入门
用户指南
创建请求
存储桶
对象
数据管理
批量处理
全球加速
监控与告警
运维中心
数据处理
内容审核
智能工具箱
数据工作流
应用集成
工具指南
工具概览
环境安装与配置
COSBrowser 工具
COSCLI 工具
COSCMD 工具
COS Migration 工具
FTP Server 工具
Hadoop 工具
COSDistCp 工具
HDFS TO COS 工具
GooseFS-Lite 工具
在线辅助工具
自助诊断工具
实践教程
概览
访问控制与权限管理
性能优化
使用 AWS S3 SDK 访问 COS
数据容灾备份
域名管理实践
图片处理实践
COS 音视频播放器实践
工作流实践
数据直传
内容审核实践
数据安全
数据校验
大数据实践
COS 成本优化解决方案
在第三方应用中使用 COS
迁移指南
本地数据迁移至 COS
第三方云存储数据迁移至 COS
以 URL 作为源地址的数据迁移至 COS
COS 之间数据迁移
Hadoop 文件系统与 COS 之间的数据迁移
数据湖存储
云原生数据湖
元数据加速
数据加速器 GooseFS
数据处理
数据处理概述
图片处理
媒体处理
内容审核
文件处理
文档处理
故障处理
获取 RequestId 操作指引
通过外网上传文件至 COS 缓慢
访问 COS 时返回403错误码
资源访问异常
POST Object 常见异常
API 文档
简介
公共请求头部
公共响应头部
错误码
请求签名
操作列表
Service 接口
Bucket 接口
Object 接口
批量处理接口
数据处理接口
任务与工作流
内容审核接口
云查毒接口
SDK 文档
SDK 概览
准备工作
Android SDK
C SDK
C++ SDK
.NET(C#) SDK
Flutter SDK
Go SDK
iOS SDK
Java SDK
JavaScript SDK
Node.js SDK
PHP SDK
Python SDK
React Native SDK
小程序 SDK
错误码
鸿蒙(Harmony) SDK
终端 SDK 质量优化
安全与合规
数据容灾
数据安全
访问管理
常见问题
热门问题
一般性问题
计费计量问题
域名合规问题
存储桶配置问题
域名和 CDN 问题
文件操作问题
日志监控问题
权限管理问题
数据处理问题
数据安全问题
预签名 URL 问题
SDK 类问题
工具类问题
API 类问题
服务协议
Service Level Agreement
隐私政策
数据处理和安全协议
联系我们
词汇表

自定义配置概述

PDF
聚焦模式
字号
最后更新时间: 2026-01-13 15:12:51

功能说明

通过使用 JS-SDK,网页开发者可以自定义界面显示、页面状态、监听事件等能力,为用户提供更优质的网页体验。

架构图





使用环境

平台
支持浏览器
iOS
Safari、QQ 内置浏览器、QQ 小程序、微信内置浏览器、微信小程序
Android
QQ 内置浏览器、QQ 小程序、微信内置浏览器、微信小程序
Windows
Chrome、QQ 浏览器(非兼容模式)、EDGE、火狐、IE11
Mac OS X
Chrome、Safari、QQ 浏览器、EDGE、火狐

使用说明

1. 下载

请下载最新版本的 JS-SDK 包。历史版本前往 更新日志

2. 引入 JS-SDK

在需要调用的页面引入如下 JS-SDK。示例中${version}表示版本号,请根据下载的实际版本号填写。
<script src="sdk-${version}.js"></script>

3. 获取在线文档预览地址

方法一:使用 JS-SDK 获取(支持 sdk-v0.1.1及以上版本)

通过 JS-SDK(v0.1.1及以上版本)获取在线文档预览地址,示例如下:
var url = await COSDocPreviewSDK.getPreviewUrl( {
objectUrl: 'https://examplebucket-1250000000.cos.ap-shanghai.myqcloud.com/test.pptx',
credentials: { // 如果预览文件是私有的,则需要携带访问凭证。
secretId: '',
secretKey: '',
authorization: 'q-sign-algorithmxxxxxxxxxxxxxxx',
},
copyable: 0, // 是否可以复制文件内容
htmlwaterword: '' // 水印内容
})
console.log(url)
配置项说明如下:
配置项
说明
是否必选
objectUrl
需要预览的对象地址,例如:https://examplebucket-1250000000.cos.ap-shanghai.myqcloud.com/test.pptx
credentials
如果预览的对象是私有,则需要传入 credentials 作为访问凭证。可以传入计算好的 请求签名 authorization,也可以传入用户的 secretId 和 secretKey(固定密钥放在前端会有安全风险,不推荐此方式)
credentials.authorization
对象下载签名,详情请参见 请求签名 文档
credentials.secretId
用户的 secretId,可前往访问管理控制台中的 API 密钥管理 页面获取
credentials.secretKey
用户的 secretKey,可前往访问管理控制台中的 API 密钥管理 页面获取
copyable
是否可复制。默认为可复制,填入值为1;不可复制,填入值为0
htmlwaterword
水印文字,需要经过 URL 安全 的 Base64 编码,默认为空
htmlfillstyle
水印 RGBA(颜色和透明度),需要经过 URL 安全 的 Base64 编码,默认为:rgba(192,192,192,0.6)
htmlfront
水印文字样式,需要经过 URL 安全 的 Base64 编码,默认为:bold 20px Serif
htmlrotate
旋转角度,0 - 360,默认315度
htmlhorizontal
水印文字水平间距,单位 px,默认为50
htmlvertical
水印文字垂直间距,单位 px,默认为100

方法二:直接请求获取

请求示例
GET /<ObjectKey>?ci-process=doc-preview&dstType=html&weboffice_url=1&sign=AuthString HTTP/1.1 HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
请求参数
参数名称
描述
是否必选
ci-process
预览固定参数,值为 doc-preview
dstType
预览类型,如需预览生成类型为 html 则填入 html
weboffice_url
是否获取预览链接。填入值为1会返回预览链接和Token信息;填入值为2只返回Token信息;不传会直接预览
tokenuid
是否获取token。根据传入的tokenuid、文件信息等生成Token,返回Token和有效期;如果不传则不会返回Token信息
sign
对象下载签名,如果预览的对象为私有读时,需要传入签名,详情请参见 请求签名 文档
注意:需要进行 urlencode
copyable
是否可复制。默认为可复制,填入值为1;不可复制,填入值为0
htmlwaterword
水印文字,需要经过 URL 安全 的 Base64 编码,默认为空
htmlfillstyle
水印 RGBA(颜色和透明度),需要经过 URL 安全 的 Base64 编码,默认为:rgba(192,192,192,0.6)
htmlfront
水印文字样式,需要经过 URL 安全 的 Base64 编码,默认为:bold 20px Serif
htmlrotate
旋转角度,0 - 360,默认315度
htmlhorizontal
水印文字水平间距,单位 px,默认为50
htmlvertical
水印文字垂直间距,单位 px,默认为100
响应示例
HTTP/1.1 200 OK
Content-Type: text/html
Content-Length: 478
Date: Thu, 25 Feb 2021 07:44:37 GMT
Status: 200 OK
x-cos-request-id: NjAzNzU1NjVfY2MxZTIzMDlfNzc5NF8yMDQ5****



{
"PreviewUrl": "https://prvsh.myqcloud.com/office/p/xxxx?_w_provider=XXX"
}

4. 初始化

通过初始化配置,JS-SDK 会在配置的 mount 节点下创建一个 iframe,并自动初始化相关数据和事件。
var demo = COSDocPreviewSDK.config({
url: '在线文档预览地址', // 步骤3中获取到的在线文档预览地址
})
// 如果需要对 iframe 进行特殊的处理,可以通过以下方式拿到 iframe 的 dom 对象
console.log(demo.iframe)
// 打开文档结果
demo.on('fileOpen', function(data) {
console.log(data.success)
})

5. 挂载节点

挂载节点指 JS-SDK 插入 iframe 时挂载的节点。在初始化时,JS-SDK 挂载节点为可配置项。
<div class="custom-mount"></div>
var demo = COSDocPreviewSDK.config({
url: '在线文档预览地址', // 步骤3中获取到的在线文档预览地址
mount: document.querySelector('.custom-mount') // 挂载节点,默认会挂载到 body 下,可根据需要自定义加载节点
})
JS-SDK 初始化完成后会自动在挂载节点下面插入一个 iframe。
<div class="custom-mount">
<iframe src="..."></iframe>
</div>

6. Token 鉴权

不使用 Token 时,默认使用文档的签名有效期鉴权,过期则无法预览文件。 使用 Token 鉴权可以在预览期间持续进行 Token 鉴权和 Token 续期,由业务侧自主控制预览授权。



Token 鉴权与续期分为以下三个步骤,详情请参见 demo 示例
1. 获取 Token 请求示例
GET /<ObjectKey>?ci-process=doc-preview&dstType=html&weboffice_url=2&tokenuid=test&sign=AuthString HTTP/1.1 HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
响应示例
HTTP/1.1 200 OK
Content-Type: text/html
Content-Length: 108
Date: Tue, 21 Jun 2022 10:41:10 GMT
Status: 200 OK
x-cos-request-id: NjJiMWEwNDZfMTgyMjYyNjRfYmRlYl9iNTAw****



{
Token: "ChAJj2vNRiHTc8reToMmJ7T2EJ7FxpUGGhS1mPJanpN03u8PSB17/YKBA/Vo****"
TokenExpireTime: "1655808670"
}
2. 设置 Token
说明:
避免 Token 刷新过于频繁,推荐设置的超时时间(timeout)为 10 分钟以上。为避免 refresh 请求超时,JS-SDK 会提前几分钟去更新 Token。
var demo = COSDocPreviewSDK.config({
url: '在线文档预览地址', // 步骤3中获取到的在线文档预览地址
})

// 设置Token
demo.setToken({
token: 'yourToken', // 填入获取到的token
timeout: 10 * 60 * 1000, // token超时时间,单位为毫秒,避免频繁续期,建议设置 10 分钟及以上,JS-SDK将在超时前调用更新Token的方法(refreshToken)
});
3. 配置 refreshToken 方法,超时自动续期 Token refreshToken 方法需要请求您的服务端封装的更新 Token 的方法,服务端可以封装上述的获取 Token 的方法(参考 获取 Token)。
4. 以服务端方法http://your.server.com/refreshToken为例,配置 refreshToken 函数如下:
// 获取 Token 函数
const refreshToken = () => {
// 调用服务端封装的方法,获取token信息
const tokenInfo = await $.get('http://your.server.com/refreshToken')

// 可以返回 Promise 或者 return { token, timeout }
return {
token: tokenInfo.token, // 必需:你需要设置的 Token
timeout: 10 * 60 * 1000, // 必需:Token 超时时间,单位毫秒
};
};

var demo = COSDocPreviewSDK.config({
url: '在线文档预览地址',
refreshToken // Token自动更新方法
})

// 设置Token
demo.setToken({
token: 'yourToken', // 填入获取到的token
timeout: 10 * 60 * 1000 // token超时时间,单位为毫秒
});


实际案例

文字文件在线预览案例,参考 DOC 预览案例
演示文件在线预览案例,参考 PPT 预览案例
表格文件在线预览案例,参考 Excel 预览案例
PDF 文件在线预览案例,参考 PDF 预览案例
Token 鉴权与续期案例,参考 Token 鉴权与续期案例

帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈