将输入文档转换为VECTOR向量格式后,通过对接智能媒体管理提供的前端渲染引擎,实现更易用、功能更强大、定制化的文档预览效果。文档预览时支持复制文档中的文字,缩放文档内容不失真,自定义广告等功能。

说明 如果将输入文档转换为JPG、PNG等格式时,您可以直接搭建一个在线文件预览系统进行文档预览。

预览原理

将输入文档转换为VECTOR向量格式后,通过对接智能媒体管理提供的前端渲染引擎实现文档预览。

a1

准备工作

  • 当访问的OSS Bucket域名与预览引擎的域名不同时,请通过OSS管理控制台将预览服务域名添加到存储转换后文档的OSS Bucket的跨域访问列表中。更多信息,请参见设置跨域访问
    设置跨域访问的具体操作步骤如下:
    1. 登录OSS管理控制台后,单击目标Bucket名称,选择权限管理 > 跨域设置
    2. 权限管理页面的跨域设置区域单击设置
    3. 单击创建规则,配置跨域规则。

      配置跨域规则时,来源需要配置为*.imm.aliyuncs.com允许 Methods选择GETHEAD,其他参数请根据需要填写。

      figimmcros1
    4. 单击确定
  • 为了数据安全性,预览引擎只支持从私有的OSS Bucket中读取文档。当OSS Bucket设置为私有时,此时需要通过OSS STS获取该文件临时的访问权限,获取临时访问凭证后传递给预览引擎,预览引擎通过凭证获取相关权限,实现文档预览。

    临时访问凭证包括临时访问密钥(AccessKey ID和AccessKey Secret)和安全令牌(SecurityToken),获取临时访问权限的具体操作,请参见STS临时授权访问OSS

    说明 由于预览引擎需要从用户的OSS Bucket读取转换后的文档,受用户OSS Bucket的读取权限影响。OSS权限的更多信息,请参见了解OSS读写权限控制

预览流程

  1. 上传原始文档到对象存储OSS中。具体操作,请参见上传文件
  2. 调用智能媒体管理的CreateOfficeConversionTask接口,将原始文档转换为VECTOR向量格式输出到指定的OSS目录。
  3. 将智能媒体管理提供的预览引擎preview.imm.aliyuncs.com/index.html?url=[TgtUri]通过HTML的<iframe>标签嵌入到页面或者Web App中进行文档预览。其中TgtUri为预览文件在OSS的http(s)路径,需要通过QueryString参数传入,如下图所示。

    智能媒体管理的预览引擎支持URL参数预览和JavaScript API预览两种方式,两种预览方式的对比如下,请根据应用场景选择合适的预览方式,推荐使用JavaScript API预览方式。

    预览引擎支持的浏览器包括Internet Explorer 10+、Microsoft Edge、Google Chrome、Firefox、Safari和Opera。

    预览方式 说明
    URL参数预览 通过URL QueryString将必要的参数传递给预览引擎,预览引擎获取相关参数后在页面中展示文档。

    此方式操作快捷方便,但是相关临时授权凭证会暴露在iframe的URL地址中。当用户的OSS Bucket为私有读并且签名有效期内时,只要把对应的URL从iframe src属性中复制出来即可分享给别人,对安全性要求较高的业务不建议使用此方式。

    JavaScript API预览 通过postMessage将必要参数发送给预览引擎页并完成初始化工作。

    JavaScript API预览具有更高的安全性,并且支持全屏预览、文字和演示页码跳转控制、文字和演示预览界面UI自定义等高级功能配置。更多信息,请参见文档预览JavaScript API

    此方式采用隐式传递参数,安全性较高,但是需要部分额外的前端编程工作。由于iframe的URL地址中不包含签名,因此即使复制了URL地址也无法预览。

    说明 postMessage浏览器兼容的更多信息,请参见postMessage浏览器兼容性
  4. 在线预览文档。

URL参数预览

完整的预览URL格式如下所示:
https://preview.imm.aliyuncs.com/index.html?url=[url]&accessKeyId=[accessKeyId]&accessKeySecret=[accessKeySecret]&stsToken=[stsToken]&bucket=[bucket]&region=[region]           
其中https://preview.imm.aliyuncs.com/index.html是智能媒体管理服务提供的预览引擎地址,问号(?)后的参数为预览文档的信息,如果未提供必填参数,则会预览失败。
  • 参数
    参数 类型 是否必填 说明
    url String 文档转换后的向量文件所在OSS目录。

    如果提交文档转换任务的TgtUri为oss://your-bucket/paxos.pptx/output,则url的格式为https://your-bucket.oss-{region}.aliyuncs.com/paxos.pptx/output。

    注意 填写时无需在OSS目录结尾加/。
    accessKeyId String 从STS获取的访问OSS的访问密钥标识(AccessKeyId)。
    accessKeySecret String 从STS获取的访问OSS的访问密钥(AccessKeySecret)。
    stsToken String 从STS获取访问OSS的安全令牌(SecurityToken)后,对SecurityToken进行编码得到的结果。编码的具体操作,请参见签名机制
    region String OSS Bucket所在地域,例如oss-cn-shanghai。
    注意 请注意添加oss前缀。
    bucket String 文档转换后的向量文件所在OSS Bucket的名称,例如your-bucket。
    endpoint String 使用与OSS Bucket绑定的用户域名进行预览,使用此参数时无需传递bucket和region参数。
    pageIndex Int 从指定的页码开始预览。
    serverTime Int 服务器当前时间,用于校准本地OSS签名时的时间,避免本地与服务器时差大于15分钟导致签名失败。单位为秒。
    expires Int 文档预览的有效时间。默认值为1800,单位为秒。
  • 示例
    https://preview.imm.aliyuncs.com/index.html
    ?url=https://yourid-dev-imm.oss-cn-shanghai.aliyuncs.com/paxos.pptx/output   //文档转换后的向量文件所在OSS目录。请注意无需在output后加/。
    &accessKeyId=STS.AAAA    //从STS获取的AccessKey ID。请注意参数的access小写。
    &accessKeySecret=BBBB    //从STS获取的AccessKey Secret。请注意参数的access小写。
    &stsToken=CCCC    //CCCC是编码从STS获取的SecurityToken后得到的结果,从STS获取的SecurityToken不能直接使用。
    &region=oss-cn-shanghai    //OSS Bucket所在地域,请注意添加oss前缀。
    &bucket=bucket-name    //文档转换后的向量文件所在OSS Bucket的名称。
    &...
                        

JavaScript API预览

为便于描述,以下称阿里云的iframe页面为子页面,嵌入该iframe的接入方页面称为父页面。
  1. 子页面发送preview.ready事件。
  2. 父页面接收preview.ready事件后,发送preview.init事件以及传递初始化参数。
    父页面向子页面发送消息,通过sendMessage完成,调用格式为sendMessage(action, data)
    参数 类型 是否必填 说明
    action String 事件名称,包括preview.init和setConfig。
    • preview.init:父页面传递初始化子页面参数。
    • setConfig:父页面设置子页面相关的渲染参数。
    data Object 事件参数。
    • preview.init事件中的参数说明请参见参数说明
    • setConfig事件使用setData传递参数变量,函数中的变量以window.iframeData形式在子页面中访问,可多次调用。支持功能的更多信息请参见文档预览JavaScript API
      sendMessage("setData", {
        //需要在子页面中用到的数据。
      });
      
        //注意sendMessage封装了postMessage,详细操作请参见示例代码。                    
  3. 子页面接收preview.init事件及其参数,并根据参数初始化渲染引擎。
  • 参数
    preview.init事件中父页面传递初始化子页面参数,详细参数说明请参见下表。
    参数 类型 是否必填 说明
    url String 文档转换后的向量文件所在OSS目录。

    如果提交文档转换任务的TgtUri为oss://your-bucket/paxos.pptx/output,则url的格式为https://your-bucket.oss-{region}.aliyuncs.com/paxos.pptx/output。

    注意 填写时无需在OSS目录结尾加/。
    region String OSS Bucket所在地域,例如oss-cn-shanghai。
    注意 请注意添加oss前缀。
    bucket String 文档转换后的向量文件所在OSS Bucket的名称,例如your-bucket。
    accessKeyId String 从STS获取的访问OSS的访问密钥标识(AccessKeyId)。
    accessKeySecret String 从STS获取的访问OSS的访问密钥(AccessKeySecret)。
    stsToken String 从STS获取的访问OSS的安全令牌(SecurityToken)。
    endpoint String 使用与OSS Bucket绑定的用户域名进行预览,使用此参数时无需传递bucket和region参数。
    copy Int 是否允许文字拷贝,可选值如下:
    • 0(默认值):禁止文字拷贝。
    • 1:允许文字拷贝。
    wmType Int 水印类型,可选值如下:
    • 0(默认值):关闭水印。
    • 1:文字水印。
    • 2:图片水印。
    wmValue String 水印值。
    • 当wmType设置为1时,填写水印内容。
    • 当wmType设置为2时,填写图片水印地址。
    wmColor String 水印颜色的RGBA值。默认值为rgba(192, 192, 192, 0.6)。
    wmRotate Float 水印角度。默认值为-Math.PI/4。
    wmFont String 水印字体。默认值为bold 20px Serif。
    wmHeight Int 水印高度。默认值为170,单位为px。
    wmWidth Int 水印宽度。默认值为195,单位为px。
  • 示例
    <html>
      <head>
        <meta charset="UTF-8">
        <!-- 建议禁用外框浏览器自带的缩放 -->
        <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0,user-scalable=no">
        <meta http-equiv="X-UA-Compatible" content="ie=edge">
        <title></title>
        <style>
          * {
            box-sizing: border-box;
          }
          html, body {
            padding: 0;
            margin: 0;
            height: 100%;
            /* 防止双击缩放 */
            touch-action: manipulation;
          }
          .main {
            display: flex;
            flex-direction: column;
            height: 100%;
          }
          #aliyunPreview {
            flex: 1;
          }
        </style>
        <script type="text/javascript" charset="utf-8">
          function json2str(obj) {
            return JSON.stringify(obj, function(key, val) {
              if (typeof val === 'function') {
                val = val.toString();
              }
              return val;
            });
          };
    
          window.sendMessage = function(action, data) {
            var iframe = document.getElementById('aliyunPreview');
            iframe.contentWindow.postMessage(json2str({ action: action, data: data }), '*');
          };
    
          window.addEventListener('message', function(e) {
            try {
              var res = JSON.parse(e.data);
            } catch(err) {
              return;
            }
    
            switch (res.action) {
              case 'preview.ready':
                window.sendMessage('preview.init', {
                  url: '',
                  region: '',
                  bucket: '',
                  accessKeyId: '',
                  accessKeySecret: '',
                  stsToken: ''
                });
                break;
            }
          }, false);
    
          //禁止双指缩放手势。
          document.addEventListener('gesturestart', function (e) {
            e.preventDefault();
          });
        </script>
      </head>
      <body>
        <iframe
          allowfullscreen
          id="aliyunPreview"
          frameborder="0"
          src="https://preview.imm.aliyuncs.com/index.html"
        ></iframe>
      </body>
    </html>
                

错误码参考

错误码 说明
-1002 无效的AccessKey ID。
-1003 无权限访问该文档。
-1004 无效的STSToken。
-1005 STSToken已过期。
-1006 签名错误。
-1007 OSS Bucket未配置跨域。
-1008 Refers配置错误。
-1100 其他原因造成的错误。

常见问题处理

如下方案仅为建议的通用解决方案,不同的应用场景请根据实际分析和处理问题。

常见问题 解决方案
iframe内部预览界面被遮挡问题
  • 禁止iframe滚动,设置iframe属性scrolling="no"(预览界面实现了局部滚动,可以放心把该属性设置为no)。
  • 通过flex布局来给iframe弹性高度或者通过js计算设置iframe一个具体高度值,不能用百分比。
父级窗口缩放导致预览界面变形问题 遇到此问题则需要父级窗口禁用浏览器自带的缩放功能。
  • Android平台
    通过设置viewport的user-scalable属性来禁止父级窗口缩放,示例代码如下:
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0,minimum-scale=1.0,user-scalable=no">                            
  • iOS平台
    禁用双击缩放手势,示例代码如下:
    body {
     touch-action: manipulation;
    }                            
    禁止双指缩放手势,示例代码如下:
    document.addEventListener('gesturestart', function(e) {
     e.preventDefault();
    });                           
PPT预览全屏按钮在某些浏览器中消失 只需在iframe上添加allowfullscreen属性即可修复,添加此属性后PPT文件可支持全屏预览。
IE下通过location.href | window.open打开预览URL时,如果URL中包含复制功能参数&copy=1,则会被当做HTML字符实体解析为版权符号©=1,导致预览不成功

由于IE的经典bug导致此问题,此时有如下两种解决方案:

  • 方式一:使用IE浏览器时在跳转前把&转义为HTML字符实体&amp;
  • 方式二:将&copy=1的位置调整为紧跟url的第一个参数,例如?copy=1&...即可解决,推荐使用此方式。