@ibiz-template/runtime 0.7.41-alpha.105 → 0.7.41-alpha.107

package/src/interface/api/controller/control/i-api-mob-md-ctrl.controller.ts

@@ -0,0 +1,32 @@
+/* eslint-disable prettier/prettier */
+import { IDEMobMDCtrl } from '@ibiz/model-core';
+import { IApiMobMdCtrlState } from '../../state';
+import { IApiMDControlController } from './i-api-md-control.controller';
+import { IApiExportParams } from '../../common';
+
+/**
+ * 移动端多数据部件
+ * @description 以列表形式展示内容，列表项整合图文、操作按钮等元素，呈现清晰的信息层级与视觉分隔。
+ * @ctrlparams {name:showgroupanchor,title:显示分组导航区域,parameterType:boolean,defaultvalue:false,description:当部件以分组形式展示内容时，用于控制是否显示分组锚点导航,effectPlatform:mob}
+ * @primary
+ * @export
+ * @interface IApiMobMDCtrlController
+ * @extends {IApiMDControlController<T, S>}
+ * @template T
+ * @template S
+ */
+export interface IApiMobMDCtrlController<
+  T extends IDEMobMDCtrl = IDEMobMDCtrl,
+  S extends IApiMobMdCtrlState = IApiMobMdCtrlState,
+> extends IApiMDControlController<T, S> {
+  /**
+   * @description 导出数据
+   * @param {{
+   *     event?: MouseEvent;
+   *     params?: IApiExportParams;
+   *   }} [args] 导出参数
+   * @returns {*}  {Promise<void>}
+   * @memberof IApiMobMDCtrlController
+   */
+  exportData(args?: {event?: MouseEvent; params?: IApiExportParams}): Promise<void>;
+}

package/src/interface/api/controller/control/i-api-panel.controller.ts

@@ -0,0 +1,66 @@
+import { IApiData } from '@ibiz-template/core';
+import { IPanel } from '@ibiz/model-core';
+import { IApiController } from '../common';
+import { IApiControlController } from './i-api-control.controller';
+import { IApiPanelState } from '../../state';
+import { IApiPanelItemController } from './panel-item';
+
+/**
+ * 面板
+ * @description 解析树型结构布局模型，按照层级关系逐级渲染面板内容，确保布局模型与渲染内容完全一致。
+ * @primary
+ * @export
+ * @interface IApiPanelController
+ * @extends {IApiControlController<T, S>}
+ * @template T
+ * @template S
+ */
+export interface IApiPanelController<
+  T extends IPanel = IPanel,
+  S extends IApiPanelState = IApiPanelState,
+> extends IApiControlController<T, S> {
+  /**
+   * @description 所有面板成员的控制器
+   * @type {{ [key: string]: IApiPanelItemController }}
+   * @memberof IApiPanelController
+   */
+  panelItems: { [key: string]: IApiPanelItemController };
+
+  /**
+   * @description 面板数据
+   * @type {IApiData}
+   * @memberof IApiPanelController
+   */
+  data: IApiData;
+
+  /**
+   * @description 容器控制器（可能是视图控制器，也可能是部件控制器）
+   * @type {IApiController}
+   * @memberof IApiPanelController
+   */
+  container?: IApiController;
+
+  /**
+   * @description 设置面板数据的值
+   * @param {string} name 要设置的数据的属性名称
+   * @param {unknown} value 要设置的值
+   * @returns {*}  {Promise<void>}
+   * @memberof IApiPanelController
+   */
+  setDataValue(name: string, value: unknown): Promise<void>;
+
+  /**
+   * @description 加载数据
+   * @returns {*}  {Promise<void>}
+   * @memberof IApiPanelController
+   */
+  load(): Promise<void>;
+
+  /**
+   * @description 获取面板成员控制器
+   * @param {string} name 面板成员名称
+   * @returns {*}  {(IApiPanelItemController | undefined)}
+   * @memberof IApiPanelController
+   */
+  findPanelItemByName(name: string): IApiPanelItemController | undefined;
+}

package/src/interface/api/controller/control/i-api-pickup-view-panel.controller.ts

@@ -0,0 +1,49 @@
+import { IDEPickupViewPanel } from '@ibiz/model-core';
+import { IApiData } from '@ibiz-template/core';
+import { IApiPickupViewPanelState } from '../../state';
+import { IApiControlController } from './i-api-control.controller';
+import { IApiViewController } from '../view';
+
+/**
+ * 选择视图面板
+ * @description 承载选择视图（部件视图），传递选中数据给选择视图，并监听内部视图的数据选择并规范化返回给外部调用组件。
+ * @primary
+ * @export
+ * @interface IApiPickupViewPanelController
+ * @extends {IApiControlController<T, S>}
+ * @template T
+ * @template S
+ */
+export interface IApiPickupViewPanelController<
+  T extends IDEPickupViewPanel = IDEPickupViewPanel,
+  S extends IApiPickupViewPanelState = IApiPickupViewPanelState,
+> extends IApiControlController<T, S> {
+  /**
+   * @description 选择视图嵌入视图控制器
+   * @type {IApiViewController}
+   * @memberof IApiPickupViewPanelController
+   */
+  embedView: IApiViewController;
+
+  /**
+   * @description 获取选中数据
+   * @returns {*}  {Promise<IApiData[]>}
+   * @memberof IApiPickupViewPanelController
+   */
+  getSelectedData(): Promise<IApiData[]>;
+
+  /**
+   * @description 设置选中数据
+   * @param {IApiData[]} items 数据集合
+   * @returns {*}  {Promise<void>}
+   * @memberof IApiPickupViewPanelController
+   */
+  setSelectedData(items: IApiData[]): Promise<void>;
+
+  /**
+   * @description 获取所有数据
+   * @returns {*}  {Promise<IApiData[]>}
+   * @memberof IApiPickupViewPanelController
+   */
+  getAllData(): Promise<IApiData[]>;
+}

package/src/interface/api/controller/control/i-api-report-panel.controller.ts

@@ -0,0 +1,50 @@
+import { IDEReportPanel } from '@ibiz/model-core';
+import { IApiData } from '@ibiz-template/core';
+import { IApiReportPanelState } from '../../state';
+import { IApiControlController } from './i-api-control.controller';
+import { IApiMDCtrlLoadParams } from './i-api-md-control.controller';
+import { IApiReportPanelGenerator } from './report-panel';
+
+/**
+ * 报表部件
+ * @description 构建智能报表引擎，支持多源数据融合、关键指标动态计算及可视化渲染，实现数据驱动的决策分析。
+ * @primary
+ * @export
+ * @interface IReportPanelController
+ * @extends {IApiControlController<T, S>}
+ * @template T
+ * @template S
+ */
+export interface IApiReportPanelController<
+  T extends IDEReportPanel = IDEReportPanel,
+  S extends IApiReportPanelState = IApiReportPanelState,
+> extends IApiControlController<T, S> {
+  /**
+   * @description 报表生成器对象
+   * @type {IApiData}
+   * @memberof IApiReportPanelController
+   */
+  generator: IApiReportPanelGenerator;
+
+  /**
+   * @description 加载数据
+   * @param {IApiMDCtrlLoadParams} [args] 加载参数
+   * @returns {*}  {Promise<IApiData>}
+   * @memberof IApiReportPanelController
+   */
+  load(args?: IApiMDCtrlLoadParams): Promise<IApiData>;
+
+  /**
+   * @description 获取报表数据
+   * @returns {*}  {IApiData[]}
+   * @memberof IApiReportPanelController
+   */
+  getData(): IApiData[];
+
+  /**
+   * @description 刷新
+   * @returns {*}  {Promise<void>}
+   * @memberof IApiReportPanelController
+   */
+  refresh(): Promise<void>;
+}

package/src/interface/api/controller/control/i-api-search-bar.controller.ts

@@ -0,0 +1,109 @@
+import { ISearchBar } from '@ibiz/model-core';
+import { IApiParams } from '@ibiz-template/core';
+import { IApiControlController } from './i-api-control.controller';
+import { IApiSearchBarState } from '../../state';
+
+/**
+ * 搜索栏过滤项
+ */
+export interface IApiSearchBarFilterController {
+  /**
+   * @description 唯一标识
+   * @type {string}
+   * @memberof IApiSearchBarFilterController
+   */
+  key: string;
+
+  /**
+   * @description 过滤的属性名称
+   * @type {string}
+   * @memberof IApiSearchBarFilterController
+   */
+  fieldName: string;
+
+  /**
+   * @description 属性显示的标题
+   * @type {string}
+   * @memberof IApiSearchBarFilterController
+   */
+  label: string;
+
+  /**
+   * @description 配置的属性搜索模式对应的值操作
+   * @type {string}
+   * @memberof IApiSearchBarFilterController
+   */
+  valueOP?: string;
+}
+
+/**
+ * 搜索栏
+ * @description 默认提供输入框搜索功能，同时支持过滤项搜索、后台分组搜索及快速搜索。
+ * @primary
+ * @export
+ * @interface IApiSearchBarController
+ * @extends {IApiControlController<T, S>}
+ * @ctrlparams {name:enablejsonschema,title:是否启用JSONSchema,parameterType:boolean,defaultvalue:false,description:是否启用基于实体的 jsonschema 生成过滤项功能}
+ * @ctrlparams {"name":"jsonschemaparams","title":"jsonschema参数数据","parameterType":"string","defaultvalue":"'{}'","description":"当`enablejsonschema`值为true时生效。支持配置 JSON 字符串并转化为导航参数，该参数将被附加到获取实体的 jsonschema 数据的请求参数中，获取的数据用于生成搜索栏过滤项，示例格式：\\{\"test\":\"%test%\"\\}"}
+ * @ctrlparams {name:storage,title:是否启用缓存,parameterType:boolean,defaultvalue:false,description:该值true时，会将点击的搜索栏后台分组项名称缓存到 localStorage 中，用于组件初始化时默认选中后台分组项,effectPlatform:web}
+ * @ctrlparams {name:searchphseparator,title:快速搜索提示分隔符,parameterType:string,defaultvalue:'、',description:搜索栏输入框根据该值将所有输入项提示文本进行拼接展示}
+ * @ctrlparams {name:enablestoredquery,title:是否启用历史录,parameterType:boolean,defaultvalue:false,description:启用后每次的搜索记录都将存储到 localStorage 中，下次打开该页面并搜索时将显示所有历史记录,effectPlatform:mob}
+ * @template T
+ * @template S
+ */
+export interface IApiSearchBarController<
+  T extends ISearchBar = ISearchBar,
+  S extends IApiSearchBarState = IApiSearchBarState,
+> extends IApiControlController<T, S> {
+  /**
+   * @description 获取搜索栏当前的过滤条件参数
+   * @returns {*}  {IApiParams}
+   * @memberof IApiSearchBarController
+   */
+  getFilterParams(): IApiParams;
+
+  /**
+   * @description 执行搜索，触发关联表格/列表重新加载
+   * @memberof IApiSearchBarController
+   */
+  onSearch(): void;
+
+  /**
+   * @description 重置过滤条件为默认值并重新搜索
+   * @memberof IApiSearchBarController
+   */
+  resetFilter(): void;
+
+  /**
+   * @description 切换后台分组项
+   * @param {string} tabId 分组标识
+   * @memberof IApiSearchBarController
+   */
+  selectTab(tabId: string): void;
+
+  /**
+   * @description 处理快速搜索值输入
+   * @param {string} val
+   * @memberof IApiSearchBarController
+   */
+  handleInput(val: string): void;
+
+  /**
+   * @description 处理后台分组保存
+   * @returns {*}  {Promise<void>}
+   * @memberof IApiSearchBarController
+   */
+  handleSave(): Promise<void>;
+
+  /**
+   * @description 查找过滤项控制器
+   * @param {(string | null)} fieldName 过滤项名称
+   * @param {(string | null)} valueOP 值操作
+   * @returns {*}  {(IApiSearchBarFilterController | undefined)}
+   * @memberof IApiSearchBarController
+   */
+  findFilterController(
+    fieldName: string | null,
+    valueOP: string | null,
+  ): IApiSearchBarFilterController | undefined;
+}

package/src/interface/api/controller/control/i-api-search-form.controller.ts

@@ -0,0 +1,77 @@
+import { IDESearchForm } from '@ibiz/model-core';
+import { IApiData, IApiParams } from '@ibiz-template/core';
+import { IApiFormController } from './i-api-form.controller';
+import { IApiSearchFormState } from '../../state';
+
+/**
+ * 搜索表单
+ * @primary
+ * @description 搜索表单包含输入框、单选框、下拉选择、多选框等用户输入组件，用于收集数据并执行过滤搜索。
+ * @export
+ * @interface IApiSearchFormController
+ * @extends {IApiFormController<T, S>}
+ * @ctrlparams {name:emptyhiddenunit,title:无值是否隐藏,parameterType:boolean,defaultvalue:false,description:表单项无值时，其对应的值单位（如'天'、'%'等）是否隐藏,effectPlatform:web}
+ * @ctrlparams {name:enablestoredfilters,title:启用存储过滤条件,parameterType:boolean,defaultvalue:true,description:设置为true的时候初始化时就会去加载保存的过滤条件，并将过滤条件附加在后续搜索行为的查询参数中,effectPlatform:web}
+ * @ctrlparams {"name":"validatemode","title":"校验模式","parameterType":"'default' | 'notification'","defaultvalue":"'default'","description":"default:默认模式,错误信息显示在表单项下方；notification:通知模式，错误信息显示在页面右上角弹框中","effectPlatform":"web"}
+ * @ctrlparams {"name":"convertparammode","title":"搜索过滤参数转换模式","parameterType":"'default' | 'searchconds'","defaultvalue":"'default'","description":"default：默认模式，过滤参数保持键值对格式（如 \\{\"n_name_like\":\"名称\"\\}）；searchconds：搜索条件模式，将对象格式的查询参数转换为结构化的搜索条件数组，并将其作为新的过滤参数（如 \\{\"searchconds\": [{\"condop\": \"AND\",\"condtype\": \"GROUP\",\"searchconds\": [{\"condtype\": \"DEFIELD\",\"fieldname\": \"name\",\"value\": \"名称\",\"condop\": \"LIKE\"}]}]\\}"}
+ * @ctrlparams {"name":"enablejsonschema","title":"是否启用jsonschema","parameterType":"boolean","defaultvalue":"false","description":"是否启用jsonschema。参数为true时，会请求服务获取jsonschema对象，并根据该对象的enumOptions属性值计算生成表单项编辑器的代码表数据集合"}
+ * @ctrlparams {"name":"jsonschemaparams","title":"请求jsonschema查询参数","parameterType":"string","defaultvalue":"","description":"启用jsonschema才生效，查询实体jsonschema附加额外业务查询参数"}
+ * @ctrlparams {"name":"showtipsicon","title":"是否显示属性标签提示图标","parameterType":"boolean","defaultvalue":"","description":"用于设置当前表单所有表单项标签是否显示提示图标，优先级大于全局显示属性提示图标配置","effectPlatform":"web"}
+ * @template T
+ * @template S
+ */
+export interface IApiSearchFormController<
+  T extends IDESearchForm = IDESearchForm,
+  S extends IApiSearchFormState = IApiSearchFormState,
+> extends IApiFormController<T, S> {
+  /**
+   * @description 加载数据
+   * @returns {*}  {Promise<IApiData>}
+   * @memberof IApiSearchFormController
+   */
+  load(): Promise<IApiData>;
+
+  /**
+   * @description 获取搜索表单当前的过滤条件参数
+   * @returns {*}  {IApiParams}
+   * @memberof IApiSearchFormController
+   */
+  getFilterParams(): IApiParams;
+
+  /**
+   * @description 执行搜索，触发关联表格/列表重新加载
+   * @returns {*}  {Promise<void>}
+   * @memberof IApiSearchFormController
+   */
+  search(): Promise<void>;
+
+  /**
+   * @description 重置搜索条件为默认值并重新搜索
+   * @returns {*}  {Promise<void>}
+   * @memberof IApiSearchFormController
+   */
+  reset(): Promise<void>;
+
+  /**
+   * @description 存储搜索条件
+   * @param {string} name 存储的名称
+   * @returns {*}  {Promise<void>}
+   * @memberof IApiSearchFormController
+   */
+  storeFilter(name: string): Promise<void>;
+
+  /**
+   * @description 应用保存的过滤条件
+   * @param {number} index 存储的过滤条件集合索引下标
+   * @memberof IApiSearchFormController
+   */
+  applyStoredFilter(index: number): void;
+
+  /**
+   * @description 删除保存的过滤条件
+   * @param {number} index 存储的过滤条件集合索引下标
+   * @returns {*}  {Promise<void>}
+   * @memberof IApiSearchFormController
+   */
+  removeStoredFilter(index: number): Promise<void>;
+}

package/src/interface/api/controller/control/i-api-tab-exp-panel.controller.ts

@@ -0,0 +1,32 @@
+import { ITabExpPanel } from '@ibiz/model-core';
+import { IApiTabExpPanelState } from '../../state';
+import { IApiControlController } from './i-api-control.controller';
+
+/**
+ * 分页导航面板
+ * @description 采用 Tab 分页导航组件，支持动态路由加载、页面缓存及状态保持，实现高效的多视图切换与管理。
+ * @primary
+ * @export
+ * @interface IApiTabExpPanelController
+ * @extends {IApiControlController<T, S>}
+ * @ctrlparams {"name":"expcache","title":"是否启用缓存","defaultvalue":"'DEFAULT'","parameterType":"'DEFAULT' | 'CACHE' | 'NO_CACHE'","description":"用于判断导航区占位中显示的导航视图是否缓存。有三种情况，'CACHE' 为缓存；'NO_CACHE' 为不缓存；'DEFAULT' 时匹配当前部件类型是否存在于全局配置参数`expCacheMode`中，存在则缓存，否则不缓存"}
+ * @template T
+ * @template S
+ */
+export interface IApiTabExpPanelController<
+  T extends ITabExpPanel = ITabExpPanel,
+  S extends IApiTabExpPanelState = IApiTabExpPanelState,
+> extends IApiControlController<T, S> {
+  /**
+   * @description 刷新当前页面（会重新计算相关视图参数和上下文）
+   * @memberof IApiTabExpPanelController
+   */
+  refresh(): void;
+
+  /**
+   * @description 设置激活项（name 传入目标分页的 tabTag 标识）
+   * @param {string} name 分页标识
+   * @memberof IApiTabExpPanelController
+   */
+  setActive(name: string): void;
+}

package/src/interface/api/controller/control/i-api-toolbar.controller.ts

@@ -0,0 +1,62 @@
+import { IDEToolbar, IDEToolbarItem } from '@ibiz/model-core';
+import { IApiData } from '@ibiz-template/core';
+import { IApiControlController } from './i-api-control.controller';
+import { IApiExtraButton, IApiToolbarState } from '../../state';
+
+/**
+ * 工具栏
+ * @description 工具栏集中了页面常用操作按钮，点击按钮即可执行相应操作，实现页面多样化业务功能。
+ * @ctrlparams {"name":"placement","title":"移动端自定义工具栏显示位置","defaultvalue":"'RIGHTEND'","parameterType":"'LEFTSTART' | 'LEFT' | 'LEFTEND' | 'RIGHT' | 'RIGHTSTART' | 'RIGHTEND'","description":"该参数可将工具栏固定在屏幕左侧或右侧的顶部、中部、底部位置，可选值包含左上（LEFTSTART）、左侧居中（LEFT）、左下（LEFTEND）、右上（RIGHTSTART）、右侧居中（RIGHT）、右下（RIGHTEND）。仅工具栏样式设为自定义时生效","effectPlatform":"mob"}
+ * @ctrlparams {"name":"direction","title":"移动端自定义工具栏项的排列方向","defaultvalue":"'HORIZONTAL'","parameterType":"'VERTICAL' | 'HORIZONTAL'","description":"定义移动端工具栏项的排列方向，可选值包含水平排列（HORIZONTAL）、垂直排列（VERTICAL）。仅工具栏样式设为自定义时生效。","effectPlatform":"mob"}
+ * @ctrlparams {"name":"showmode","title":"移动端工具栏的显示模式","defaultvalue":"'IMMEDIATE'","parameterType":"'IMMEDIATE' | 'COLLAPSIBLE'","description":"定义移动端工具栏的显示模式，可选值包含即时渲染模式（IMMEDIATE）、可折叠模式（COLLAPSIBLE）。","effectPlatform":"mob"}
+ * @ctrlparams {"name":"groupshowmode","title":"移动端工具栏分组与行为组的展示模式","defaultvalue":"'ACTIONSHEET'","parameterType":"'DEFAULT' | 'ACTIONSHEET'","description":"定义移动端工具栏分组与行为组的展示模式，可选值包含DEFAULT（气泡模式，组内容以悬浮气泡形式展示）、ACTIONSHEET（行为列表模式，组内容以下拉抽屉形式展示）。","effectPlatform":"mob"}
+ * @primary
+ * @export
+ * @interface IApiToolbarController
+ * @extends {IApiControlController<T, S>}
+ * @template T
+ * @template S
+ */
+export interface IApiToolbarController<
+  T extends IDEToolbar = IDEToolbar,
+  S extends IApiToolbarState = IApiToolbarState,
+> extends IApiControlController<T, S> {
+  /**
+   * @description 所有工具栏项
+   * @type {IDEToolbarItem[]}
+   * @memberof IApiToolbarController
+   */
+  allToolbarItems: IDEToolbarItem[];
+
+  /**
+   * @description 设置额外的按钮（可多次调用，会累加）
+   * @param {('before' | 'after' | number)} position 按钮位置
+   * @param {IExtraButton[]} buttons 按钮集合
+   * @memberof IApiToolbarController
+   */
+  setExtraButtons(
+    position: 'before' | 'after' | number,
+    buttons: IApiExtraButton[],
+  ): void;
+
+  /**
+   * @description 清除所有设置的额外按钮
+   * @param {('before' | 'after' | number)} [position] 按钮位置
+   * @memberof IApiToolbarController
+   */
+  clearExtraButtons(position?: 'before' | 'after' | number): void;
+
+  /**
+   * @description 执行工具栏按钮点击
+   * @param {(IDEToolbarItem | IApiExtraButton)} item 工具栏项
+   * @param {MouseEvent} event 鼠标事件
+   * @param {IApiData} [params] 界面行为参数（界面行为点击自定义按钮可能需要传参数到行为去，标准行为忽略此参数）
+   * @returns {*}  {Promise<void>}
+   * @memberof IApiToolbarController
+   */
+  onItemClick(
+    item: IDEToolbarItem | IApiExtraButton,
+    event: MouseEvent,
+    params?: IApiData,
+  ): Promise<void>;
+}

package/src/interface/api/controller/control/i-api-tree-exp-bar.controller.ts

@@ -0,0 +1,18 @@
+import { ITreeExpBar } from '@ibiz/model-core';
+import { IApiExpBarControlController } from './i-api-exp-bar-control.controller';
+import { IApiTreeExpBarState } from '../../state';
+
+/**
+ * 树导航栏
+ * @description 点击树结构节点可快速切换视图，通过层级清晰的页面导航，方便用户在导航视图中直观查看业务形态。
+ * @primary
+ * @export
+ * @interface IApiTreeExpBarController
+ * @ctrlparams {"name":"expcache","title":"是否启用缓存","defaultvalue":"'DEFAULT'","parameterType":"'DEFAULT' | 'CACHE' | 'NO_CACHE'","description":"用于判断导航区占位中显示的导航视图是否缓存。有三种情况，'CACHE' 为缓存；'NO_CACHE' 为不缓存；'DEFAULT' 时匹配当前部件类型是否存在于全局配置参数`expCacheMode`中，存在则缓存，否则不缓存"}
+ * @ctrlparams {name:searchphseparator,title:快速搜索提示分隔符,parameterType:string,defaultvalue:'、',description:搜索栏输入框根据该值将所有输入项提示文本进行拼接展示}
+ * @extends {IApiExpBarControlController}
+ */
+export interface IApiTreeExpBarController<
+  T extends ITreeExpBar = ITreeExpBar,
+  S extends IApiTreeExpBarState = IApiTreeExpBarState,
+> extends IApiExpBarControlController<T, S> {}

package/src/interface/api/controller/control/i-api-tree-grid-ex.controller.ts

@@ -0,0 +1,97 @@
+import { IDETreeGridEx } from '@ibiz/model-core';
+import { IApiData } from '@ibiz-template/core';
+import {
+  IApiTreeNodeData,
+  IApiTreeGridExState,
+  IApiTreeGridExRowState,
+} from '../../state';
+import { IApiTreeController } from './i-api-tree.controller';
+import { IApiTreeGridExColumnController } from './tree-grid-ex-column';
+
+/**
+ * 树表格(增强)
+ * @description 实现可折叠树形表格组件，支持节点数据懒加载、列宽拖拽调整、行双击事件触发、多条件排序及行选中高亮，提升数据浏览与操作效率。
+ * @primary
+ * @export
+ * @interface IApiTreeGridEXController
+ * @extends {IApiGridController<T, S>}
+ * @ctrlparams {"name":"overflowmode","title":"超出呈现模式","parameterType":"'ellipsis' | 'wrap'","defaultvalue":"'wrap'","description":"单元格内容超出单元格宽度时的呈现模式，包含超出省略 'ellipsis'，换行 'wrap' 两种模式"}
+ * @ctrlparams {name:emptyhiddenunit,title:无值隐藏,parameterType:boolean,defaultvalue:true,description:单元格无值时，其对应的值单位（如'天'、'%'等）是否隐藏}
+ * @ctrlparams {"name":"editshowmode","title":"行编辑显示模式","parameterType":"'row' | 'cell' | 'all'","defaultvalue":"'row'","description":"表格进行行编辑时的呈现模式，包含单行编辑模式 'row'，单元格编辑 'cell' 模式，整个表格编辑模式 'all' 三种模式"}
+ * @ctrlparams {"name":"editsavemode","title":"行编辑保存模式","parameterType":"'cell-blur' | 'auto' | 'manual'","defaultvalue":"'cell-blur'","description":"处理表格进行行编辑时的保存模式，包含单元格失焦 'cell-blur' 时保存，自动保存 'auto'，手动确认 'manual' 三种模式"}
+ * @template T
+ * @template S
+ */
+export interface IApiTreeGridEXController<
+  T extends IDETreeGridEx = IDETreeGridEx,
+  S extends IApiTreeGridExState = IApiTreeGridExState,
+> extends IApiTreeController<T, S> {
+  /**
+   * @description 树表格列控制器，包含表格列相关能力,key为表格列代码名称，可通过ctrl.columns['树表格列codeName']
+   * @type {{ [key: string]: IApiTreeGridExColumnController }}
+   * @memberof IApiTreeGridEXController
+   */
+  columns: { [key: string]: IApiTreeGridExColumnController };
+  /**
+   * @description 保存数据
+   * @param {IApiTreeNodeData} data 树节点数据
+   * @returns {*}  {Promise<void>}
+   * @memberof IApiTreeGridEXController
+   */
+  save(data: IApiTreeNodeData): Promise<void>;
+  /**
+   * @description 保存所有变更数据
+   * @returns {*}  {Promise<void>}
+   * @memberof IApiTreeGridEXController
+   */
+  saveAll(): Promise<void>;
+  /**
+   * @description 切换行编辑状态
+   * @returns {*}  {Promise<void>}
+   * @memberof IApiTreeGridEXController
+   */
+  toggleRowEdit(): Promise<void>;
+  /**
+   * @description 切换行编辑状态，editable表示行编辑目标状态，isSave=true表示关闭编辑时自动保存（默认true）
+   * @param {IApiTreeGridExRowState} row 行状态
+   * @param {boolean} [editable] 是否为编辑状态
+   * @param {boolean} [isSave] 是否保存数据
+   * @returns {*}  {Promise<void>}
+   * @memberof IApiTreeGridEXController
+   */
+  switchRowEdit(
+    row: IApiTreeGridExRowState,
+    editable?: boolean,
+    isSave?: boolean,
+  ): Promise<void>;
+  /**
+   * @description 获取行状态（key 为 IApiGanttNodeData._id（节点唯一标识））
+   * @param {string} key 行数据标识
+   * @returns {*}  {(IApiTreeGridExRowState | undefined)}
+   * @memberof IApiTreeGridEXController
+   */
+  getRowState(key: string): IApiTreeGridExRowState | undefined;
+  /**
+   * @description 设置行属性值，其中ignore=是否忽略脏值检查（true=不提示用户数据变更，默认false）
+   * @param {IApiTreeGridExRowState} row 行状态对象
+   * @param {string} name 属性名称
+   * @param {unknown} value 属性值
+   * @param {boolean} [ignore] 忽略脏值检查
+   * @returns {*}  {Promise<void>}
+   * @memberof IApiTreeGridEXController
+   */
+  setRowValue(
+    row: IApiTreeGridExRowState,
+    name: string,
+    value: unknown,
+    ignore?: boolean,
+  ): Promise<void>;
+  /**
+   * @description 计算默认值
+   * @param {IApiTreeNodeData} data 树节点数据
+   * @param {boolean} isCreate 是否为新建数据
+   * @returns {*}  {IApiData}
+   * @memberof IApiTreeGridEXController
+   */
+  calcDefaultValue(data: IApiTreeNodeData, isCreate: boolean): IApiData;
+}

package/src/interface/api/controller/control/i-api-tree-grid.controller.ts

@@ -0,0 +1,45 @@
+/* eslint-disable prettier/prettier */
+import { IDETreeGrid } from '@ibiz/model-core';
+import { IApiTreeGridState } from '../../state';
+import { IApiGridController } from './i-api-grid.controller';
+import { IApiExportParams } from '../../common';
+
+/**
+ * 树表格
+ * @description 采用树形表格组件，支持行级懒加载与动态伸缩交互，实现高效层级数据展示与操作。
+ * @primary
+ * @export
+ * @interface IApiTreeGridController
+ * @extends {IApiGridController<T, S>}
+ * @ctrlparams {"name":"overflowmode","title":"超出呈现模式","parameterType":"'ellipsis' | 'wrap'","defaultvalue":"'wrap'","description":"单元格内容超出单元格宽度时的呈现模式，包含超出省略 'ellipsis'，换行 'wrap' 两种模式"}
+ * @ctrlparams {name:emptyhiddenunit,title:无值隐藏,parameterType:boolean,defaultvalue:true,description:单元格无值时，其对应的值单位（如'天'、'%'等）是否隐藏}
+ * @ctrlparams {"name":"editshowmode","title":"行编辑显示模式","parameterType":"'row' | 'cell' | 'all'","defaultvalue":"'row'","description":"表格进行行编辑时的呈现模式，包含单行编辑模式 'row'，单元格编辑 'cell' 模式，整个表格编辑模式 'all' 三种模式"}
+ * @ctrlparams {"name":"editsavemode","title":"行编辑保存模式","parameterType":"'cell-blur' | 'auto' | 'manual'","defaultvalue":"'cell-blur'","description":"处理表格进行行编辑时的保存模式，包含单元格失焦 'cell-blur' 时保存，自动保存 'auto'，手动确认 'manual' 三种模式"}
+ * @ctrlparams {"name":"saveerrorhandlemode","title":"行编辑保存错误处理模式","parameterType":"'default' | 'reset'","defaultvalue":"'default'","description":"表格保存错误时的处理模式，包含提示错误信息 'default' 和重置表格行数据 'reset' 两种模式"}
+ * @ctrlparams {name:enablejsonschema,title:是否允许使用jsonschema模式,parameterType:boolean,defaultvalue:false,description:是否启用自定义添加表格列功能，当参数为true且后台返回 jsonschema 格式的表格列数据时执行添加操作}
+ * @ctrlparams {"name":"jsonschemaparams","title":"jsonschema参数数据","parameterType":"string","defaultvalue":"'{}'","description":"当`enablejsonschema`值为true时生效。支持配置 JSON 字符串并将其转化为导航参数，该参数将被附加到获取实体的 jsonschema 数据的请求参数中，获取的数据解析后用于自定义添加表格列功能，示例格式：\\{\"test\":\"%test%\"\\}"}
+ * @ctrlparams {"name":"triggermode","title":"编辑器值变更模式","parameterType":"'blur' | 'input'","defaultvalue":"'blur'","description":"该配置项用于指定编辑器触发 `emit` 事件的模式。若值为 'input'，则在输入框值变更时触发 change 事件；若值为 'blur'，则在输入框失去焦点时触发 change 事件"}
+ * @ctrlparams {"name":"mdctrlrefreshmode","title":"刷新模式","defaultvalue":"'cache'","parameterType":"'nocache' | 'cache'","description":"多数据部件刷新模式，当值为 'cache'，部件刷新时保留选中数据；当值为 'nocache'，部件刷新时清空选中数据","effectPlatform":"web"}
+ * @ctrlparams {"name":"batchtoolbarmode","title":"批操作工具栏显示模式","parameterType":"'default' | 'multiple'","defaultvalue":"'default'","description":"批操作工具栏显示模式，值为 'default' 时表示存在选择数据就显示批操作工具栏，值为 'multiple' 时表示选择至少2条数据才显示批操作工具栏","effectPlatform":"web"}
+ * @ctrlparams {"name":"paginationmode","title":"分页显示模式","defaultvalue":"'default'","parameterType":"'default'|'simple'","description":"表格分页显示模式，当值为 default 时，显示完整的分页组件，值为 simple 时，显示简略版的分页组件，仅包含总条数，当前页，上一页和下一页","effectPlatform":"web"}
+ * @template T
+ * @template S
+ */
+export interface IApiTreeGridController<
+  T extends IDETreeGrid = IDETreeGrid,
+  S extends IApiTreeGridState = IApiTreeGridState,
+> extends IApiGridController<T, S> {
+  /**
+   * @description 切换树表格显示
+   * @memberof IApiTreeGridController
+   */
+  switchTreeGridShow(): void;
+
+  /**
+   * @description 数据导出
+   * @param {{ event: MouseEvent; params: IApiExportParams }} _args 导出参数
+   * @returns {*}  {Promise<void>}
+   * @memberof IApiTreeGridController
+   */
+  exportData(_args: {event: MouseEvent;params: IApiExportParams}): Promise<void>;
+}