文档

快速入门

更新时间:

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

重要

此文档已不再维护,建议您使用新版智能媒体管理。

  • 关于智能媒体管理新版与旧版的对比,请参见新旧版本使用指引

  • 关于如何快速使用新版智能媒体管理文档处理功能,请参见快速入门

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

预览原理

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

a1

准备工作

  1. 设置跨域访问规则。

    由于访问的OSS Bucket域名与预览引擎的域名不同,因此请通过OSS管理控制台将预览引擎域名添加到存储转换后文档的OSS Bucket的跨域访问列表中。更多信息,请参见设置跨域资源共享。设置跨域访问规则的具体操作步骤如下:

    1. 登录OSS管理控制台后,单击目标Bucket名称,选择权限管理 > 跨域设置

    2. 跨域设置区域单击设置

    3. 单击创建规则,配置跨域规则。

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

      figimmcros1
    4. 单击确定

  2. 获取预览文件的临时访问权限。

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

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

    说明

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

  3. 上传原始文档到对象存储OSS中。具体操作,请参见控制台上传文件

  4. 调用智能媒体管理的CreateOfficeConversionTask接口,将原始文档转换为VECTOR向量格式输出到指定的OSS目录。

预览方式对比

智能媒体管理的预览引擎支持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浏览器兼容性

URL参数预览

您可以通过完整的URL在浏览器中直接预览文档,也可以将智能媒体管理提供的预览引擎嵌入到页面或者Web App中进行文档预览。

  • 通过完整的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进行编码得到的结果。编码的具体操作,请参见RPC 调用机制

      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的名称。
      &...
  • 将预览引擎嵌入到页面或者Web App中预览文档

    将智能媒体管理提供的预览引擎preview.imm.aliyuncs.com/index.html?url=[TgtUri]通过HTML的<iframe>标签嵌入到页面或者Web App中进行文档预览。其中TgtUri为预览文件在OSS的http(s)路径,需要通过QueryString参数传入,如下图所示。iframe

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的访问密钥标识(AccessKey ID)。

    accessKeySecret

    String

    从STS获取的访问OSS的访问密钥(AccessKey Secret)。

    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

无效的STS Token。

-1005

STS Token已过期。

-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&...即可解决,推荐使用此方式。

  • 本页导读 (1)
文档反馈