自訂函式

1.1 應用場景

FineReport 已經提供了大量的自帶函式，在正常情況下足夠滿足使用者的報表製作需求，但是在一些特殊領域，可能需要一些特殊的函式，在這種情況下，FineReport 提供了自訂函式機制，可以由使用者根據業務需要自己來定義一些函式，但這些函式必須滿足FineReport函式定義規則。

1.2 函式定義規則

FineReport 函式定義規則：Functionname(Para,Para,...)，其中Functionname為函式名，Para 為參數。

在 FineReport中，每一個函式都被定義成一個類，這個類必須要實現 Function 這個API，在運算的時候首先透過函式名反射取得這個類，然後呼叫它的 run(Object[] agrs)方法。下面以 SUM 這個函式為例。

由程式可以看到，SUM 類用來運算 SUM 函式，他繼承了 AbstractFunction 類，而 AbstractFunction 實現了 Function 這個API。

當函式運算的時候，先根據函式名取得運算該函式的類，如 SUM(2,4,true) 這個函式先根據函式名取得 SUM 這個類，然後呼叫 SUM 類的run(Object[] args) 方法，args 中存放的是 SUM 函式的參數，運算的時候可以從 args 中取得參數進行運算。如執行結果為SUM(2,4,true)=2+4+1=7。

SUM 函式所使用程式碼：

package com.fr.report.script;
import com.fr.general.FArray;
import com.fr.script.AbstractFunction;
public class CSUM extends AbstractFunction {
	public Object run(Object[] args) {
		double result = 0;
		for (int i = 0; i < args.length; i++) {
			if (args[i] == null) {
				continue;
			}
			result += parseObject(args[i]);
		}
		return result;
	}
	private double parseObject(Object obj) {
		if (obj instanceof Number) {
			return ((Number) obj).doubleValue();
		} else if (obj instanceof Boolean) {
			return ((Boolean) obj).booleanValue() ? 1 : 0;
		} else if (obj instanceof FArray) {
			FArray array = (FArray) obj;
			double sum = 0;
			for (int i = 0; i < array.length(); i++) {
				sum += parseObject(array.elementAt(i));
			}
			return sum;
		} else if (obj != null) {
			try {
				return Double.parseDouble(obj.toString());
			} catch (NumberFormatException exp) {
				return 0;
			}
		}
		return 0;
	}
}

1.3 編譯環境準備

詳情參見：編譯Java程式

下面以一個簡單的自訂函式例子來說明使用自訂函式。我們定義一個函式 StringCat，它的作用是把所有的參數以字串的形式連結起來。

StringCat 函式使用規則為StringCat(Para,Para,Para…….)；

其中 Para 為該函式的參數，個數不限。

由概述可知 AbstractFunction 實現了 Function 這個API，因此 StringCat 可以直接繼承 AbstractFunction 類。

2.1 編寫 Java 檔案

編寫StringCat.java， 函式程式碼如下：

package com.fr.function;
import com.fr.script.AbstractFunction;
public class StringCat extends AbstractFunction {
	public Object run(Object[] args) {
		String result = "";
		Object para;
		for (int i = 0; i < args.length; i++) {
			para = args[i];
			result += para.toString();
		}
		return result;
	}
}

程式碼查看：https://code.fanruan.com/demo/example/src/branch/persist/10.0/src/main/java/com/fr/function/StringCat.java

說明： 使用函式 StringCat(Para,Para,Para…..)時，根據函式名取得運算該函式的類 StringCat，並將參數傳入類中的 args 物件陣列中，執行該類的run 函式。

而在 run 函式中即實現了將傳入的參數以字串的形式連結起來。並傳回最終形成的字串。

2.2 編譯 class 檔案

2.2.1 編譯環境準備

詳情參見：編譯Java程式

2.2.2 生成 class 檔案

編譯 StringCat.java，生成類 StringCat.class 。

2.3 匯入 class 檔案

1）將編譯後的StringCat.class放到 FineReport 的安裝目錄%FR_HOME%\webapps\webroot\WEB-INF\classes\com\fr\function目錄下。

2）重啟設計器。

注：遠端設計環境下，工程和設計器本地都需要存放該class檔案。遠端工程和設計器都需要重啟才能生效。

2.4 註冊自訂函式

重啟工程/設計器後便可直接使用，使用方法與內建函式是相同的。

生成該函式的類後需要在設計器中進行註冊，才可以使用該函式。開啟「伺服器>函式管理器」，選擇剛剛定義好的 StringCat 類，如下圖所示： 

修改函式名稱和函式描述，如下圖所示：

2.5 使用自訂函式

註冊好自訂函式後，製作報表時便可直接使用了，使用方法與內建函式是相同的。

1）範本設計
建立報表，定義兩個報表參數 para1、para2，類型分別為字串型與整形，預設值分別為空字串與 0，如下圖所示：

新增參數到參數面板，在空白報表的任意儲存格里寫入公式：=StringCat($para1,$para2)，如下圖所示：

注：寫入公式的時候在參數名前加 $，表明這是使用的參數。

2）範本預覽
點選分頁預覽在參數元件中，寫入參數值如 para1 為：FineReport，para2 為：123。

點選查詢可以看到結果：

時間類型計算

自訂函式開發程式

內部收益率公式 IRR

儲存格內容數字，字母或者中文顯示不同的顏色

自定义函数生成 UPC 条形码

自定义函数 Unicode 编码转化为中文

自定义函数实现表间校验

图片在下文字在上

引入 JFreeChart 图表

自定义函数中获取公式所在单元格

自定义函数把阳历转换成阴历

函式管理器中配置的自訂函式資訊都會儲存在 FineDB 的 fine_conf_entity 表中，欄位都是以 FunctionConfig.functionDefList 開頭。

每個自訂函式會被隨機分配一個 8 位的 UUID

在資料庫中儲存格式為：