全部产品
云市场

文档预览JavaScript API

更新时间:2019-04-10 15:49:41

当使用 JavaScript API 时,您还可以实现诸如加密文档处理、签名刷新、重试、UI设置、全屏等功能,以及获取到预览文档渲染的相关信息,方便您查看相关数据。

预览高级配置

全屏预览支持

在嵌套预览引擎的父页面中,在 iframe 上添加 allowfullscreen 属性,即可实现全屏预览。

  1. <iframe id="preview" src=[PreviewURL] allowfullscreen frameborder="0" scrolling="no"></iframe>

文字演示跳转控制

  1. // 跳转到某一页
  2. sendMessage('logic.toPage', {
  3. pageIndex: 0 // 跳转页码,从0开始
  4. });
  5. // 跳转到上一页
  6. sendMessage('logic.prevPage');
  7. // 跳转到下一页
  8. sendMessage('logic.nextPage');

文字、演示预览界面 UI 自定义

  1. sendMessage('setConfig', {
  2. writerCustomStyle: function(isMobile) {
  3. if (!isMobile) {
  4. return {
  5. // 预览容器上边距
  6. containerMarginTop: 30,
  7. // 预览容器下边距
  8. containerMarginBottom: 30,
  9. // 容器背景色
  10. containerBackground: '#000000',
  11. // 页与页之间的距离
  12. pageSpacing: 20,
  13. // 每页的阴影样式
  14. pageShadow: '0px 0px 6px 0px rgba(0, 0, 0, 0.3)',
  15. // 每页的边框样式
  16. pageBorder: 'none',
  17. // 放大缩小按钮容器样式
  18. scale: {/* style 注意这里的样式写法跟 css 文件样式写法一样,比如 vertical-align:middle */},
  19. // 放大缩小按钮样式
  20. scaleBtn: {/* style 注意这里的样式写法跟 css 文件样式写法一样,比如 vertical-align:middle */},
  21. // 缩小按钮样式
  22. scaleShrink: {/ *style 注意这里的样式写法跟 css 文件样式写法一样,比如 vertical-align:middle */},
  23. // 缩小按钮字符
  24. scaleShrinkText: '',
  25. // 缩小按钮不可点击样式
  26. scaleShrinkDisable: {/* style 注意这里的样式写法跟 css 文件样式写法一样,比如vertical-align:middle */},
  27. // 放大按钮样式
  28. scaleMagnify: {/* style 注意这里的样式写法跟 css 文件样式写法一样,比如vertical-align:middle */},
  29. // 放大按钮字符
  30. scaleMagnifyText: '',
  31. // 放大按钮不可点击样式
  32. scaleMagnifyDisable: {/* style 注意这里的样式写法跟 css 文件样式写法一样,比如vertical-align:middle * /},
  33. // 缩放比例文字
  34. scaleText: {/* style 注意这里的样式写法跟 css 文件样式写法一样,比如 vertical-align:middle */},
  35. // 缩放组件元素排序
  36. scaleSort: ['shrink', 'text', 'magnify'] // 缩小 文字 放大
  37. }
  38. } else {
  39. return {
  40. pageBorder: '1px solid #d2d5d8'
  41. };
  42. }
  43. }
  44. });
  45. // 演示预览自定义样式
  46. sendMessage('setConfig', {
  47. powerpointCustomStyle: function(isMobile) {
  48. if (!isMobile) {
  49. return {
  50. // 隐藏翻页按钮
  51. paginationDisplay: false,
  52. // 隐藏全屏按钮
  53. fullScreenButtonDisplay: false,
  54. // 预览容器上边距
  55. containerMarginTop: 30,
  56. // 预览容器下边距
  57. containerMarginBottom: 30,
  58. // 容器背景色
  59. containerBackground: '#000000'
  60. };
  61. } else {
  62. return {};
  63. }
  64. }
  65. });

自定义错误提示界面

在 iframe 外框监听错误消息,自行处理报错的 UI 逻辑。

  1. sendMessage("setConfig", {
  2. enableMessageUI: false
  3. });
  4. window.addEventListener('message', function(e) {
  5. var res = JSON.parse(e.data);
  6. switch(res.action) {
  7. case 'message.error':
  8. toast(i18n(res.data.result));
  9. break;
  10. }
  11. }, false);

设置加密文件解密流程

监听 message.error 事件, 处理展示密码输入相关 UI 逻辑,然后用户输入密码后,携带密码再次提交转换任务,服务端根据提交的密码执行解密流程,生成一个新的预览地址,浏览器重新设置 iframe 的 src 属性为新的预览地址。如果解密失败,子页面会重新抛出 aliyunPasswordInvalid 错误,重新输入密码即重复以上流程即可。

  1. sendMessage("setConfig", {
  2. enableCheckPasswordLogic: false
  3. });
  1. var isFirstTime = false;
  2. window.addEventListener('message', function(e) {
  3. var res = JSON.parse(e.data);
  4. switch(res.action) {
  5. case 'message.error':
  6. if (res.data.result === 'aliyunPasswordInvalid') {
  7. if (isFirstTime) {
  8. // 显示密码框
  9. // your code
  10. isFirstTime = false;
  11. } else {
  12. // 提示密码错误
  13. // your code
  14. }
  15. }
  16. break;
  17. }
  18. }, false);

刷新签名

当用户本地临时访问凭证过期时,无法继续预览文档,此时需要刷新签名。首先监听子页面抛出的 logic.refreshToken 事件,然后获取相关 token 信息后通过发送 logic.setToken 消息设置相关token信息,刷新iframe页面签名。

  1. window.addEventListener('message', function(e) {
  2. var res = JSON.parse(e.data);
  3. switch(res.action) {
  4. case 'logic.refreshToken':
  5. // 重新获取 token 的逻辑请自行实现
  6. $.ajax(...).then(function(data){
  7. sendMessage('logic.setToken', {
  8. region: data.region,
  9. accessKeyId: data.accessKeyId,
  10. accessKeySecret: data.accessKeySecret,
  11. stsToken: data.stsToken,
  12. bucket: data.bucket
  13. });
  14. });
  15. break;
  16. ...
  17. }
  18. }, false);

重试机制

如果浏览器预览出错,可以设置重试逻辑,尝试重新获取 OSS 预览文档信息,提高用户可以预览的成功率。

  1. sendMessage('setConfig', {
  2. couldRetry: function(tryCount) {
  3. //tryCount 当前已经重试的次数
  4. return new Promise(function(resolve) {
  5. if (tryCount > 35) {
  6. // 最多重试次数
  7. resolve(false);
  8. } else {
  9. var tryDelay = 0;
  10. if (tryCount < 2) {
  11. // 0 - 1
  12. tryDelay = 250;
  13. } else if (tryCount <= 11) {
  14. // 2 - 11
  15. tryDelay = 500;
  16. } else {
  17. // 12 - 35
  18. tryDelay = 1000;
  19. }
  20. setTimeout(function () {
  21. resolve(true); // 执行重试
  22. }, tryDelay);
  23. }
  24. });
  25. }
  26. });

广告配置

  1. //文字 Word (演示移动端)
  2. sendMessage('setConfig', {
  3. wordAd: function(pageIndex, total) {
  4. //pageIndex 当前页数 total 总页数,接入方可以通过这些参数设计广告显示逻辑
  5. return {
  6. type: 'iframe', // iframe 或者 img
  7. src: iframeData.xxx, //函数中所有变量必须通过 setData 传递,并通过 iframeData 来使用
  8. href: iframeData.xxx, //跳转地址
  9. width: 1090, //宽度
  10. height: 200, //高度
  11. closeBtn: true //是否显示关闭广告按键
  12. };
  13. }
  14. });
  15. //表格 Excel
  16. sendMessage('setConfig', {
  17. etAd: function() {
  18. return {
  19. type: 'iframe',
  20. src: 'http://xxxx',
  21. href: '',
  22. width: 1090,
  23. height: 200,
  24. closeBtn: true
  25. }
  26. }
  27. });
  28. //演示 PowerPonit(web 端)
  29. sendMessage('setConfig', {
  30. wppAd: function() {
  31. return {
  32. type: 'iframe',
  33. src: 'http://xxxx',
  34. href: '',
  35. width: 1090,
  36. height: 200,
  37. closeBtn: true
  38. }
  39. }
  40. });

注意:若 data 为 function,则函数中引用的变量必须在此之前通过 setData 来传递到子页面

本地签名时间校准

OSS SDK 签名时默认会使用本地时间,如果用户本地时间与服务器时间相差超过 15min 则会导致签名验证失败,此时可手动设置强制本地使用服务器时间签名,而获取服务器时间的逻辑则由用户自行处理。

  1. sendMessage("setConfig", {
  2. timestamp: {
  3. serverTime: 1540881763, // 服务器当前时间,单位:秒
  4. expires: 3600 // 签名有效期,单位:秒,默认:1800
  5. }
  6. });

预览信息获取

记录当前浏览页码

监听 page.readPage 事件会返回当前浏览页数 pageIndex,接入方自行存储该值后,下次打开相同页面只需将其赋值于 iframe url 中的 pageIndex 参数即可跳转到上次浏览的页码,以实现从历史记录继续浏览。

  1. {
  2. "action": "page.readPage",
  3. "data": {
  4. "pageIndex": 0
  5. }
  6. }

获取 meta.json信息

  1. {
  2. action: "preview.meta", //当前页面执行状态
  3. data: {
  4. version: "xxx", //数据版本号
  5. epc: "xxx", //预览渲染的页数
  6. pc: "xxx", //文档实际的页数
  7. pro: "xxx", //文件类型
  8. ...
  9. }
  10. }

错误事件说明

当发生错误时,父级窗口会接收到以下数据结构 JSON 字符串消息:

  1. {
  2. action: 'message.error',
  3. data: {
  4. result: 'aliyunOpenFileFail',
  5. data: {
  6. // 错误细节
  7. }
  8. }
  9. }

其中 action 字段为 message.error,是固定值result 字段为具体错误类型的说明,如下所示:

  • aliyunOpenFileFail: 打开文档失败
  • aliyunUnsupportFile: 不支持的文件类型
  • aliyunRequstFail: 前端请求静态资源失败,包括签名错误等,具体信息会有data数据返回
  • aliyunQueryParamInvalid: 页面必传参数缺失
  • aliyunRequestTimeout: 资源加载超时
  • aliyunRenderEngineTooOld: js渲染引擎版本过旧
  • aliyunPasswordInvalid: 密码错误,需要处理密码重试的逻辑

获取渲染页面关键信息

首先父级窗口会接收到以下数据结构JSON字符串消息:

  1. {
  2. action: 'page.getBaseInfoFromServerDone', //当前页面执行状态
  3. data: {
  4. startTime: 1111,//开始时间
  5. endTime: 1111, //结束时间
  6. useTime: 1111, //花费时间
  7. pageStartTime: 1111 //预览页面开始时间
  8. }
  9. }
事件 说明
getBaseInfoFromServerDone 获取页面基本信息
getSheetInfoFromServerDone 获取表格基础信息
getPageInfoFromServerDone 获取单页信息, {pageIndex: 0, …..}
firstRendered 首屏渲染完成 {startTime, pageStartTime}
timing 下面单独说明

所有 page.*Done 格式的事件 data 都有以下参数, {startTime: 开始时间, endTime: 结束时间, useTime: 花费时间, pageStartTime: 页面开始时间} , 时间都是毫秒为单位, 上面表格描述的事件中,page.xxxDone 就会有 page.xxx事件,page.xxx 为 page.xxxDone 开始执行的事件, page.xxx 少了 endTime,useTime 字段。

timing格式如下所示:

  1. // t为performance.timing
  2. {
  3. // 页面加载完成的时间
  4. loadPage : t.loadEventEnd - t.navigationStart,
  5. // dom解析事件
  6. domReady : t.domComplete - t.responseEnd,
  7. // 重定向的时间
  8. redirect : t.redirectEnd - t.redirectStart,
  9. // DNS 查询时间
  10. lookupDomain : t.domainLookupEnd - t.domainLookupStart,
  11. // TTFB 即 Time To First Byte 的意思
  12. ttfb : t.responseStart - t.navigationStart,
  13. // 内容加载完成的时间
  14. request : t.responseEnd - t.requestStart,
  15. // 执行 onload 回调函数的时间
  16. loadEvent : t.loadEventEnd - t.loadEventStart,
  17. // DNS 缓存时间
  18. appcache : t.domainLookupStart - t.fetchStart,
  19. // 卸载页面的时间
  20. unloadEvent : t.unloadEventEnd - t.unloadEventStart,
  21. // TCP 建立连接完成握手的时间
  22. connect : t.connectEnd - t.connectStart,
  23. timing: t
  24. }