[TOC]

設(shè)計器產(chǎn)品界面

用戶界面.png

上圖所示能岩，設(shè)計器界面主要有下面幾個部分：

頂部狀態(tài)欄

頂部狀態(tài)欄主要有保存济舆，預(yù)覽肪康，退出按鈕，顯示當前正在編輯的模板文件的名稱盅视，以及設(shè)計器語言選擇下拉框巫湘。

status-bar.gif

工具欄

工具欄包含了一系列編輯功能的按鈕沸版，用戶可以在上面設(shè)置控件的位置琢唾，大小，樣式以及數(shù)據(jù)綁定腳本等和敬。

控件工具箱

控件工具箱上顯示有當前設(shè)計器支持的控件類型凹炸，其中指針樣式的按鈕表達進入控件編輯模板，選中其它控件按鈕進表示進入此類型控件的創(chuàng)建模板昼弟。用戶可以通過下面的步驟在模板上創(chuàng)建一個控件：

在工具箱上點擊需要創(chuàng)建的控件还惠，比如文本框。
在界面上點擊，拖拉出一個框蚕键。
松開鼠標救欧，一個文本框控件就創(chuàng)建出來了。

create-widget.gif

字體樣式選擇框

用戶可以在字體樣式選擇框中對控件的字體進行調(diào)整（如果控件支持字體樣式的話）锣光。后面我們看到笆怠，這些按鈕是從字體屬性面板中部分抽取出來的。

font.gif

控件位置誊爹，大小

顯示和輸入當前選中控件的位置蹬刷，大小的數(shù)值信息。

X, Y 分別表示控件距父容器的左邊界和上邊界的距離频丘，單位是0.1mm
W, H分別表示控件的寬办成，高，單位是0.1mm
Z表示控件的疊加層次搂漠，它跟CSS中的z-index類似迂卢，多個控件重疊的時候，Z數(shù)值越大的控件將會顯示在越上面桐汤。
橫向充滿而克，表示將當前控件的寬度設(shè)置成跟父容器的寬度一樣。
縱向充滿怔毛，表示將當前控件的高度設(shè)置成跟父容器的高度一樣员萍。
自適應(yīng)高度，表示控件高度在打印輸出時根據(jù)控件的內(nèi)容自動調(diào)整高度（注意在高度自適應(yīng)選中的情況下拣度，H表示的是控件的最小高度）
吸附碎绎，這是一個與控件無關(guān)的設(shè)置按鈕，用于開啟/關(guān)閉模板編輯器的吸附輔助功能抗果，吸附功能用于幫助用戶設(shè)計精確對齊的模板混卵。
打印/不打印，表示控件是否在輸出打印時不顯示窖张，比如一些預(yù)置好的紙張上面可以已經(jīng)有公司的Logo了，那么Logo圖片可以設(shè)置成不顯示蚁滋。
每頁出現(xiàn) 宿接，表示控件將會在每頁打印輸出，比如一些水印辕录，Logo睦霎，表頭位置等。
允許跨頁走诞，表示允許控件在內(nèi)容過長時副女，截斷內(nèi)容并在多頁上顯示

bound.gif

控件編輯區(qū)

控件編輯器主要是控件的ID，控件的復(fù)制剪切粘貼蚣旱，操作的撤消與回退碑幅，以及文本的橫向與縱向?qū)R樣式戴陡。

控件ID

控件的唯一標識，這個ID在模板中是唯一的沟涨。它主要用于腳本恤批，以及一些依賴控件的屬性配置上面。

復(fù)制剪切粘貼裹赴，操作的撤消與回退

對應(yīng)剪切板的復(fù)制剪切粘貼喜庞，另外，撤消與回退可以回退上一步的操作/重做下一步的操作棋返，

屬性面板

屬性面板上包含一系列公共的樣式延都，以及控件自有的屬性面板按鈕，點擊它們將會彈出相應(yīng)的面板設(shè)置對話框睛竣。

operation.gif

頁面編輯區(qū)域

XMReport在頁面編譯區(qū)域預(yù)覽模板的效果晰房，用戶也可以在這里對模板的控件通過拖拽的方式進行定位，調(diào)整大小酵颁，選擇嫉你，復(fù)制剪貼刪除等操作。

單擊控件：選中對應(yīng)的控件躏惋，如未選中控件幽污，則取消現(xiàn)選中的。
拖拽：移動選中的控件的位置簿姨。
雙擊：如果選中的控件是一個容器（如頁眉距误，頁腳，正文扁位，單元格等）准潭，那么將進入容器編輯狀態(tài)，點擊容器外則退出窗口編輯狀態(tài)域仇。
拖動選中控件上的錨點：可以調(diào)節(jié)控件大小刑然，旋轉(zhuǎn)角度，位置暇务。
右鍵單擊：彈出控件的編輯功能菜單泼掠，包含剪貼，復(fù)制垦细，刪除等功能择镇。

canvas.gif

組件結(jié)構(gòu)

組件結(jié)構(gòu)面板中用于顯示模板的組件大綱，它是一顆樹括改，我們可以一層層展開腻豌，找到任意任意控件并選中，另外我們可以在控件上點擊右鍵，呼出組件的編輯菜單吝梅，我們還可以通過上面的搜索框虱疏，搜索相應(yīng)的控件。

outline.gif

數(shù)據(jù)源

包含了系統(tǒng)中的數(shù)據(jù)源模板列表憔涉，數(shù)據(jù)源是一種輔助設(shè)計的手段订框，它并不包含具體數(shù)據(jù)，也不包含數(shù)據(jù)庫的連接信息兜叨，它僅僅是描述生成報告時穿扳，用戶程序傳遞進來的數(shù)據(jù)有那些字段，以及字段的表達式国旷。
用戶可以拖拽矛物，或者雙擊的方式將字段綁定到控件上面，方便實施人員對模板進行設(shè)計/修改跪但。

datasource.gif

模板管理

對系統(tǒng)中的模板進行管理履羞，包含了常見的復(fù)制，剪切屡久，粘貼忆首，刪除等功能。

雙擊模板被环，對該模板進行編輯糙及，編輯區(qū)域會刷新并顯示此模板。
右鍵筛欢，可以呼出模板的編輯按鈕浸锨。

templateManager.gif

公共腳本

用戶在這里可以添加自定義的腳本，然后在 “數(shù)據(jù)源/腳本” 屬性面板中使用load函數(shù)加載腳本版姑，比如 load('/xxx.js')柱搜，然后下來就可以使用腳本里面定義的函數(shù)/變量了。

sharescript.gif

數(shù)據(jù)與腳本

數(shù)據(jù)與腳本是XMReport的核心概念之一剥险，每個控件都可以綁定一個數(shù)據(jù)對象聪蘸，在生成報表的時候，數(shù)據(jù)腳本將被執(zhí)行表制，腳本的最后一行的執(zhí)行結(jié)果將被作為結(jié)果綁定到控件上健爬。

腳本

在XMReport中，腳本采用JavaScript ES5語法編寫夫凸，腳本將會通過解釋執(zhí)行的方式在JVM中運行。

數(shù)據(jù)腳本

默認情況下阱持，"數(shù)據(jù)源/腳本" 屬性面板中夭拌，"數(shù)據(jù)"輸入框中的內(nèi)容是直接被當作一個字符串對象綁定到控件上面的，如果需要把它當作一段腳本來執(zhí)行，有以下幾種方式：

第一行加上//javascript注釋前綴（斜線和javascript之間沒有空格）鸽扁，腳本的最后一行將作為結(jié)果綁定到控件上面蒜绽。
為了方便用戶的使用，你也可以采用等于號開頭的寫法桶现，等于號后面的寫法將會作為結(jié)果綁定到控件上面躲雅。
使用類似于 ${variableName}這樣的占位符的方式，點位標記$ {}中的內(nèi)容將會被當作腳本來執(zhí)行骡和，腳本執(zhí)行的最后一行的結(jié)果會替換對應(yīng)的占位符相赁。

另外，子控件的腳本中可以訪問到父控件綁定的數(shù)據(jù)中的屬性慰于，比如下面的例子钮科，子控件可以訪問到父控件綁定的數(shù)據(jù)中屬性a和b，result的結(jié)果為25婆赠。腳本中訪問一個變量時绵脯，如果腳本當前的作用域（scope）沒有定義該變量時，它將一層一層往父級控件找到休里，直到根數(shù)據(jù)（生成報表時應(yīng)用傳遞進來的數(shù)據(jù)）蛆挫，如果仍然查找不到，那么返回null妙黍。

//javascript Body's data script
var data={
    a: 12,
    b: 13
};
data;

//javascript Child's data script
var result=a+b;
result;

前置腳本

前置腳本是XMReport引擎在執(zhí)行控件前運行的一段腳本悴侵，用戶可以在前置腳本中做一些自定義操作，比如設(shè)置一些控件執(zhí)行行為的一些屬性废境。

后置腳本

后置腳本是XMReport引擎在執(zhí)行控件后運行的一段腳本畜挨，用戶可以在后置腳本中做針對執(zhí)行結(jié)果做一些自定義的修改，比如修改文本控件的內(nèi)容噩凹，寬高等巴元。

結(jié)束腳本

結(jié)束腳本是整個模板執(zhí)行完成之后回調(diào)運行的一段腳本，一些信息驮宴，比如總頁數(shù)逮刨，匯總等，在整個模板輸出完才能獲取到的堵泽，可以在結(jié)束腳本中獲取修己，并相應(yīng)對控件的內(nèi)容做一些修改。

可循環(huán)擴展的對象

XMReport中迎罗，有多種控件可以循環(huán)擴展的對象睬愤，比較常用的有Template，Page和Row纹安，比如給表格的行綁定一個"數(shù)組/List"對象時尤辱，它將根據(jù)所綁定的數(shù)組/List對象的大小砂豌，擴展成多行。給Page綁定一個數(shù)組/List對象時光督，它將擴展成多頁阳距，Template同理。

extendable-widgets.gif

集成示例工程

集成的示例工程為前端設(shè)計器提供了預(yù)覽结借，以及/數(shù)據(jù)源/模板/公共腳本的增刪改查管理接口筐摘。用戶可以根據(jù)自己的需要在自己的項目中實現(xiàn)對應(yīng)的接口。

集成示例工程采用了SpringBoot + JPA的技術(shù)框架來實現(xiàn)船老，數(shù)據(jù)庫方面采用了內(nèi)嵌的Derby咖熟，用戶可以根據(jù)自己的需求進行相應(yīng)的修改，或者改成自己熟悉的技術(shù)來實現(xiàn)相應(yīng)的接口努隙。

編譯示例工程前球恤，需要使用以下命令將XMReport引擎包安裝到本地maven庫中：

mvn install:install-file -Dfile=web-report-engine-1.1.jar -DgroupId=org.mosmith -DartifactId=web-report-engine -Dversion=1.1 -Dpackaging=jar

如果客戶操作系統(tǒng)為Linux/Unix/Mac OS X，那么需要在系統(tǒng)中安裝SimSun.ttc字體（可以從Windows操作系統(tǒng)中復(fù)制）荸镊，或者通過系統(tǒng)屬性設(shè)置默認的字體：

System.setProperty("org.mosmith.tools.report.engine.output.pdf.PdfFontMapper.default", "simsun");

src/main/resources/static XMReport報表設(shè)計器前端靜態(tài)資源文件咽斧。

src/main/resources/META-INF/persistence.xml 示例工程JPA配置文件（包含數(shù)據(jù)庫連接配置），如下躬存，用戶可以根據(jù)需求修改數(shù)據(jù)源的連接信息：

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.1" xmlns="http://xmlns.jcp.org/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd">
  <persistence-unit name="TemplateStorage" transaction-type="RESOURCE_LOCAL">
    <provider>org.hibernate.jpa.HibernatePersistenceProvider</provider>
    <properties>
      <property name="javax.persistence.jdbc.url" value="jdbc:derby:testdb;create=true"/>
      <property name="javax.persistence.jdbc.driver" value="org.apache.derby.jdbc.EmbeddedDriver"/>
      <property name="javax.persistence.jdbc.user" value="admin"/>
      <property name="javax.persistence.jdbc.password" value="admin"/>
      <property name="javax.persistence.schema-generation.database.action" value="create"/>
      <property name="hibernate.cache.provider_class" value="org.hibernate.cache.NoCacheProvider"/>
      <property name="hibernate.dialect" value="org.hibernate.dialect.DerbyDialect" />
    </properties>
  </persistence-unit>
</persistence>

ReportController 設(shè)計器預(yù)覽接口张惹，同時它是一個調(diào)用引擎生成報表文件的接口，如下岭洲，將模板宛逗，填充的數(shù)據(jù)，和選項傳遞進ReportHelper相應(yīng)的接口盾剩，即可生成相應(yīng)的PDF文件雷激。

File file=new ReportHelper().toPdf(templateDataReader, previewData, previewOptions);

TemplateManagerController 設(shè)計器使用的模板增刪改查接口。

ShareScriptManagerController 公共腳本的增刪改查接口（可選集成）告私。

DataSourceTemplateController 數(shù)據(jù)源模板的增刪改查接口（可選集成）屎暇。

內(nèi)置函數(shù)

用戶可以添加自定義的函數(shù)，如下代碼驻粟，控件的腳本中可以直接訪問到對象的方法根悼。由此用戶可以集成自己的數(shù)據(jù)查詢方法等。

        // 生成報表文件前通過ReportHelper.setBuiltIn方法設(shè)置內(nèi)置方法對象蜀撑，可以設(shè)置多個挤巡。
        ...
        ReportHelper reportHelper=new ReportHelper();
        reportHelper.setBuiltIn("testBuiltInMethods", new TestBuiltInMethods());
        reportHelper.toPdf(xxx)
        ...
        
        class TestBuiltInMethods {
            public String sayHello(String name) {
                return "Hello " + name;
            }
        }
        
        
        // 控件的腳本上可以直接調(diào)用TestBuiltIn里面的方法
        ...
        var message=sayHello('Mosmith');
        ...

內(nèi)置變量

同樣，用戶也可以添加自定義的內(nèi)置蠻一酷麦，如下代碼矿卑，控件的腳本中可以通過內(nèi)置變量名訪問到對象，并可以調(diào)用對象上面的方法或者獲取對象的字段：

        // 生成報表文件前通過ReportHelper.setProperty方法設(shè)置內(nèi)置變量沃饶，可以設(shè)置多個母廷。
        ...
        ReportHelper reportHelper=new ReportHelper();
        reportHelper.setBuiltIn("testBuiltIn", new TestBuiltIn());
        reportHelper.toPdf(xxx)
        ...
        
        class TestBuiltIn {
            public String field;

            public String sayHello(String name) {
                return "Hello " + name;
            }
        }
        
        
        // 控件的腳本上可以通過內(nèi)置變量名訪問到內(nèi)置變量的方法和字段 
        ...
        var message=testBuiltIn.sayHello('Mosmith');
        var field=testBuiltIn.field;
        ...

XMReport快速開始