# custom.js

custom.js是SuccBI前端嵌入式脚本的约定文件名，当需要对某个页面（如一个仪表板、报表或SuperPage页面等）进行个性化前端开发的时候，通过custom.js可以向特定的页面注入前端js脚本代码，可以实现如“自定义按钮点击的执行逻辑”、“自定义某个组件的渲染逻辑”之类的个性化需求。

# 脚本位置

为了方便管理二次开发的代码，SuccBI将多个页面的个性化脚本代码集中到一个custom.js文件进行管理，也就是说可以通过在特定的位置编写一个custom.js文件，实现多个目标页面的个性化处理。custom.js可以位于如下几个位置：

/业务项目/fapp/xxx.fapp/custom.js - 表单应用内部页面加载
/业务项目/app/xxx.app/custom.js - 应用内嵌入的页面加载
/业务项目/public/hooks/custom.js - 项目内的报表、仪表板、应用、表单应用加载
/sysdata/public/hooks/custom.js - 系统内的报表、仪表板、应用、表单应用、元数据管理界面等所有页面都加载

说明：

在custom.js中可以通过文件的路径、名称、类型等限定具体的脚本代码或事件代码作用到哪个具体的页面。
可以直接编辑custom.js文件，也可以在SuccIDE或元数据项目设置中通过脚本编辑器直接编辑ts语法的脚本文件custom.ts，编辑器会自动编译并生成custom.js。
当存在多个脚本时，系统将以函数为粒度按以上顺序优先使用应用内的、其次使用项目全局的最后使用系统全局的进行调用（如onDidInitFileViewer在项目脚本和系统脚本都存在，那么将会只调用项目脚本的，但如果项目脚本文件存在但是并不包含onDidInitFileViewer函数，那么会继续调用系统脚本文件中的onDidInitFileViewer函数）。
未登录用户也可以访问这个文件，所以将它放在/sysdata/public下面，这样就不需要给它分配权限。

# 支持的事件

前端脚本支持大量的事件，不同的类型可能支持不同的事件，具体见前端脚本支持的事件。

# 自定义表达式脚本函数

前端表达式计算时，有时需要执行用户自定义逻辑，并在表达式中引用脚本函数执行结果（如：在表达式中引用数据库查询结果）。当产品内置表达式无法满足需求时，可以通过javascript脚本扩展表达式的执行能力。

在custom.js中的CustomExpFunctions定义个性化的脚本函数，然后通过表达式函数SCRIPT_STR调用脚本函数：

/**
 * 提供给表达式中执行的个性化脚本函数。
 * 1. 用户定义的个性化脚本函数,在表达式中调用`SCRIPT_STR`函数即可执行。
 * 2. context: 表达式计算上下文
 * 3. args: 脚本函数执行参数，参数类型只支持基本类型`string|number|boolean|Date`或者基本类型的数组形式`Array<string|number|boolean|Date>`
 */
CustomExpFunctions?: {
	[funcName: string]: (context: IExpEvalDataProvider, ...args) => string | Promise<string>;
}

脚本示例：

CustomExpFunctions: {
    queryUserData: (context: IExpEvalDataProvider, arg1,...,argN) => string | Promise<string> {
        // TODO something
        // 在此处实现个性化需求，并返回结果
        // let data = null;
        // return data;
    }
}

在表达式中如何引用:

SCRIPT_STR('queryUserData', 控件1, 控件2);

# 脚本模版

下面的钩子函数按需实现，需要实现哪个就把它的注释去掉即可，也可以添加新的事件，支持的事件见脚本前端脚本支持的事件。

/**
 * `custom.js`是SuccBI前端嵌入式脚本的约定文件名，当需要对某个页面（如一个仪表板、报表或SuperPage页面等）进
 * 行个性化前端开发的时候，通过`custom.js`可以向特定的页面注入前端js脚本代码，通过前端脚本开发可以实现如“自定
 * 义按钮点击的执行逻辑”、“自定义某个组件的渲染逻辑”之类的个性化需求。
 * 
 * 为了方便管理二次开发的代码，SuccBI将多个页面的个性化脚本代码集中到一个`custom.js`文件进行管理，也就是说可以
 * 通过在特定的位置编写一个`custom.js`文件，可以多个目标页面的个性化处理。
 * 
 * 更多信息见：<https://docs.succbi.com/develop/hooks/custom-js/>
 */

import {
	throwError,
	assign,
	message,
	rc,
	Component,
	showSuccessMessage,
	ajax,
	browser,
	rc1,
	showErrorMessage,
	IPageContainer,
	UrlInfo,
	encodeUrlInfo,
	ctx,
	showWaiting,
	showDialog,
	ctxIf,
	AjaxArgs,
} from "sys/sys";

import {
	IMetaFileViewer,
	MetaFileViewerArgs,
	IMetaFileCustomJS
} from "metadata/metadata";
import {
	IAppCustomJS,
	IFAppCustomJS
} from "metadata/metadata-script-api";

/**
 * 可以在此处通过路径、资源ID、文件名、类型指定脚本：
 * 优先级顺序为：id>路径>名称>类型>*。
 * id/路径/名称 匹配到的脚本之间不会合并，取优先级最高的，与类型、*匹配到的脚本按优先级进行合并。
 * 
 * 1. path或resID， 完整的路径或资源id。
 * 2. name，文件名（无路径，带扩展名）
 * 3. type，类型
 * 4. *，默认
 */
export const CustomJS: { [file_OR_type_OR_resid: string]: IMetaFileCustomJS } = {
	/**
	 * 用完整的路径设置脚本作用到哪个具体的仪表板、报表或spg等，路径以/开头，包含项目名称和文件扩展名
	 */
	"/path/to/file": {
		/**
		 * 在这里定义报表类型的元数据的个性化脚本，支持的函数见
		 * <https://docs.succbi.com/develop/hooks/customjs-events-api/>
		 */
	},
	/**
	 * 用文件名设置脚本作用到哪个具体的仪表板、报表或spg等，文件名包含文件扩展名
	 */
	"xxxxx.spg": {

	}
}

custom.css

filter.action

0条评论