amis2/office-viewer.md at 1a6a680020a1f229bc4f2967f768ef5e4c6f35b5

test/amis2

mirror of https://gitee.com/baidu/amis.git synced 2024-11-29 18:48:45 +08:00

* feat: Office viewer 支持 Excel

* 修复类型报错

* 修复类型报错

2024-03-20 11:08:43 +08:00

12 KiB

Raw Blame History

title	description	type	group	menuName	icon	order
Office Viewer		0	⚙ 组件	OfficeViewer 文档渲染		23

2.9.0 及以上版本

用于渲染 office 文档，目前只支持 docx 和 xlsx 格式，本文档只介绍 docx 的配置，xlsx 的配置请参考 office-viewer-excel

基本用法

{
  "type": "office-viewer",
  "src": "/examples/static/simple.docx",
  "wordOptions": {
    "padding": "8px",
    "ignoreWidth": false
  }
}

渲染配置项

目前只支持 Word 文档，所以只有 word 的配置项，放在 wordOptions 下

Word 渲染支持以下功能：

基础文本样式
表格及表格样式
内嵌图片
列表
注音
链接
文本框
形状
数学公式（依赖 MathML，需要比较新的浏览器，或者试试 polyfill）
分页渲染

不支持的功能：艺术字、域、对象、目录

word 渲染配置属性表

{
  "type": "office-viewer",
  "wordOptions": {
    "padding": "8px",
    "ignoreWidth": false
  }
}

属性名	类型	默认值	说明
classPrefix	`string`	'docx-viewer'	渲染的 class 类前缀
ignoreWidth	`boolean`	false	忽略文档里的宽度设置，用于更好嵌入到页面里，但会减低还原度
padding	`string`		设置页面间距，忽略文档中的设置
bulletUseFont	`boolean`	true	列表使用字体渲染，请参考下面的乱码说明
fontMapping	`object`		字体映射，是个键值对，用于替换文档中的字体
forceLineHeight	`string`		设置段落行高，忽略文档中的设置
enableVar	`boolean`	true	是否开启变量替换功能
printOptions	`object`		针对打印的特殊设置，可以覆盖其它所有设置项

分页渲染

2.10.0 及以上版本

默认情况下 word 文档渲染使用流式布局，这样能更好融入到已有页面中，但展现上会和原先的文档有较大差异，且不支持页眉页脚，如果希望能看起来更像桌面端的效果，可以通过 page 配置开启分页渲染

{
  "type": "office-viewer",
  "id": "office-viewer-page",
  "wordOptions": {
    "page": true
  },
  "src": "/examples/static/page.docx",
}

分页渲染的其它设置项

属性名	类型	默认值	说明
page	`boolean`	false	是否开启分页渲染
pageMarginBottom	`number`	20	页面上下间距
pageBackground	`string`	'#FFF'	页面内背景色
pageShadow	`boolean`	true	是否显示阴影
pageWrap	`boolean`	true	是否显示页面包裹
pageWrapBackground	`string`	'#ECECEC'	页面包裹的背景色
zoom	`number`		缩放比例，取值 0-1 之间
zoomFitWidth	`boolean`	false	自适应宽度缩放，如果设置了 zoom 将不会生效

关于渲染效果差异

目前的实现难以保证和本地 Word 渲染完全一致，会遇到以下问题：

字体大小不一致
单元格宽度不一致，表格完全依赖浏览器渲染

如果追求完整效果打印，目前只能使用下载文件的方式用本地 Word 进行打印。

列表符号出现乱码问题

默认情况下列表左侧的符号使用字体渲染，这样能做到最接近 Word 渲染效果，但如果用户的系统中没有这些字体就会显示乱码，为了解决这个问题需要手动在 amis 渲染的页面里导入对应的字体，比如

<style>
  @font-face {
    font-family: Wingdings;
    src: url(./static/font/wingding.ttf);
  }

  @font-face {
    font-family: Symbol;
    src: url(./static/font/symbol.ttf);
  }
</style>

目前已知会有 Wingdings 和 Symbol 两个字体，可能还有别的

如果不想嵌入这两个字体，就只能在前面的 wordOptions 里设置 bulletUseFont: false。

变量替换

文档可以预先定义变量，通过配置 enableVar 来开启这个功能，在实际渲染时根据上下文数据来渲染变量，比如

{
  "type": "form",
  "title": "",
  "mode": "inline",
  "wrapWithPanel": false,
  "body": [
    {
      "type": "input-text",
      "name": "name",
      "value": "amis",
      "label": "姓名"
    },
    {
      "type": "input-email",
      "name": "email",
      "label": "邮箱"
    },
    {
      "type": "input-text",
      "name": "phone",
      "label": "手机号"
    },
    {
      "type": "office-viewer",
      "id": "office-viewer",
      "src": "/examples/static/info.docx",
      "wordOptions": {
        "enableVar": true,
        "padding": "8px"
      }
    }
  ]
}

如果关闭将显示原始文档

{
  "type": "office-viewer",
  "id": "office-viewer",
  "src": "/examples/static/info.docx",
  "wordOptions": {
    "padding": "8px"
  }
}

变量说明

目前变量使用的写法是 {{name}}，其中 name 代表变量名，另外这里可以是 amis 表达式，比如前面示例的 {{DATETOSTR(TODAY(), 'YYYY-MM-DD')}}

Word 经常会自作主张进行语法检查，生成无关的标签导致变量替换出错，解决办法是参考这个文档，将所有语法检查都忽略掉，也就是文档里不再有飘红的文字

表格行循环

目前针对表格支持循环语法，下面例子中第一个是模板里的变量写法，循环以 {{#xxx}} 开头，{{/}} 结束（不过目前还不支持嵌套语法，所以这个结束符合可以省略）

{
  "type": "page",
  "body": [
    {
      "type": "office-viewer",
      "id": "office-viewer-table-list",
      "src": "/examples/static/table-list.docx",
      "wordOptions": {
        "padding": "8px"
      }
    },
    {
      "type": "service",
      "api": "/api/mock2/sample/mirror?json=%7B%22users%22%3A%5B%7B%22name%22%3A%22u1%22%2C%22age%22%3A10%2C%22img%22%3A%22https%3A%2F%2Fsuda.cdn.bcebos.com%2Fimages%2Famis%2Fai-fake-face.jpg%22%7D%2C%7B%22name%22%3A%22u2%22%2C%22age%22%3A11%7D%5D%7D",
      "body": [{
        "type": "office-viewer",
        "src": "/examples/static/table-list.docx",
        "wordOptions": {
          "padding": "8px",
          "enableVar": true,
          "ignoreWidth": true
        },
        "trackExpression": "${users}"
      }]
    },
    {
      "type": "action",
      "label": "下载文档",
      "onEvent": {
          "click": {
            "actions": [
              {
                "actionType": "saveAs",
                "componentId": "office-viewer-table-list"
              }
            ]
          }
        }
    },

  ]
}

循环的语法是以 {{#name}} 开始，{{/}} 结束，在这期间的变量会取循环内的值。

注意上面的例子用到了 trackExpression，默认情况下如果设置了 enableVar，每次上层数据变化都会重新渲染文档，如果文档较大可能会有性能问题，这时可以通过配置 trackExpression 来限制只有某个数据变化时才重新渲染。

图片中的变量

2.10 及以上版本

如果要将文档中的图片设置为变量，需要右键对应的图片，选择「查看可选文字」，然后填入类似 {{img}} 变量标识，在渲染时图片将替换为这个 img 变量的 url 地址

下面是示例

{
  "type": "form",
  "title": "",
  "wrapWithPanel": false,
  "body": [
    {
      "type": "input-text",
      "name": "img",
      "value": "https://suda.cdn.bcebos.com/amis/images/alice-macaw.jpg",
      "label": "图片地址"
    },
    {
      "type": "office-viewer",
      "id": "office-viewer",
      "src": "/examples/static/image-alt-var.docx",
      "wordOptions": {
        "enableVar": true,
        "padding": "8px"
      }
    }
  ]
}

不渲染模式

通过配置 display: false 可以让文档不渲染，虽然不渲染，但还是可以使用后面的下载及打印功能

下载文档

基于事件动作实现

[
  {
    "type": "action",
    "label": "下载文档",
    "onEvent": {
        "click": {
          "actions": [
            {
              "actionType": "saveAs",
              "componentId": "office-viewer-download"
            }
          ]
        }
      }
  },
  {
    "type": "office-viewer",
    "id": "office-viewer-download",
    "display": false,
    "src": "/examples/static/simple.docx"
  }
]

打印文档