@ticatec/uniface-element 5.0.1 → 5.0.2

package/docs/components/columns-layout/README.md

@@ -0,0 +1,70 @@
+# ColumnsLayout
+
+应用布局组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+以多列方式组织可调整区域的应用布局。
+
+## 适用场景
+
+- 主从视图和多面板工作台
+- 左右或多列区域需要独立宽度配置
+
+## 导入
+
+```ts
+import ColumnsLayout from '@ticatec/uniface-element/app-layout/ColumnsLayout';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `width` | 否 | `string` | 否 | `'100%'` | 否 | 宽度配置；字符串可以使用 px、rem、% 等 CSS 单位。 |
+| `height` | 否 | `string` | 否 | `'100%'` | 否 | 高度配置；字符串可以使用 px、rem、% 等 CSS 单位。 |
+| `leftWidth` | 否 | `string \| null` | 否 | `null` | 否 | 宽度配置；字符串可以使用 px、rem、% 等 CSS 单位。 |
+| `rightWidth` | 否 | `string \| null` | 否 | `null` | 否 | 宽度配置；字符串可以使用 px、rem、% 等 CSS 单位。 |
+| `leftMin` | 否 | `string \| null` | 否 | `null` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `leftMax` | 否 | `string \| null` | 否 | `null` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `rightMin` | 否 | `string \| null` | 否 | `null` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `rightMax` | 否 | `string \| null` | 否 | `null` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `leftResize` | 否 | `boolean` | 否 | `false` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `rightResize` | 否 | `boolean` | 否 | `false` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `left` | 否 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 渲染入口，用于替换或补充默认内容。 |
+| `children` | 是 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 子内容，用于自定义组件主体。 |
+| `right` | 否 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 渲染入口，用于替换或补充默认内容。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `children`
+
+Svelte Snippet 子内容，用于自定义组件主体。
+
+- 类型：`Snippet`
+- 默认值：`undefined`
+- 示例写法：`children={children}`
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import ColumnsLayout from '@ticatec/uniface-element/app-layout/ColumnsLayout';
+</script>
+
+<ColumnsLayout
+  width="240px"
+  height="48px"
+  leftWidth="240px"
+  rightWidth="240px"
+>
+  <div>在这里放置子内容</div>
+</ColumnsLayout>
+```
+
+## 源码
+
+- `src/lib/app_layout/ColumnsLayout.svelte`

package/docs/components/columns-layout/example.svelte

@@ -0,0 +1,12 @@
+<script lang="ts">
+  import ColumnsLayout from '@ticatec/uniface-element/app-layout/ColumnsLayout';
+</script>
+
+<ColumnsLayout
+  width="240px"
+  height="48px"
+  leftWidth="240px"
+  rightWidth="240px"
+>
+  <div>在这里放置子内容</div>
+</ColumnsLayout>

package/docs/components/common-dialog/README.md

@@ -0,0 +1,109 @@
+# CommonDialog
+
+浮层与弹窗组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+带标准标题、内容和操作区的通用对话框壳。
+
+## 适用场景
+
+- 编辑表单和详情确认弹窗
+- 需要统一对话框结构的业务组件
+
+## 导入
+
+```ts
+import CommonDialog from '@ticatec/uniface-element/CommonDialog';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `title` | 是 | `string` | 是 | `—` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `width` | 否 | `string` | 否 | `'unset'` | 否 | 宽度配置；字符串可以使用 px、rem、% 等 CSS 单位。 |
+| `height` | 否 | `string` | 否 | `'unset'` | 否 | 高度配置；字符串可以使用 px、rem、% 等 CSS 单位。 |
+| `closeConfirm` | 否 | `DialogCloseConfirm \| null` | 否 | `null` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `content$style` | 否 | `string` | 否 | `''` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `enableConfirm` | 否 | `boolean` | 否 | `true` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `confirmHandler` | 否 | `(() => Promise<any>) \| null` | 否 | `null` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `confirmText` | 否 | `string \| null` | 否 | `null` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `onClose` | 是 | `OnClose \| null` | 否 | `null` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
+| `children` | 是 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 子内容，用于自定义组件主体。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `title`
+
+可选配置，具体取值范围和数据结构见类型列。
+
+- 类型：`string`
+- 默认值：`—`
+- 示例写法：`title="示例标题"`
+
+### `onClose`
+
+事件或行为回调；参数与返回值以类型签名为准。
+
+- 类型：`OnClose | null`
+- 默认值：`null`
+- 示例写法：`onClose={async (...args: any[]) => { console.log('onClose', ...args); return true; }}`
+
+### `children`
+
+Svelte Snippet 子内容，用于自定义组件主体。
+
+- 类型：`Snippet`
+- 默认值：`undefined`
+- 示例写法：`children={children}`
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `DialogCloseConfirm`
+
+```ts
+export type DialogCloseConfirm = () => Promise<boolean>;
+```
+
+### `OnClose`
+
+```ts
+export type OnClose = (result: ModalResult) => void;
+```
+
+### `ModalResult`
+
+```ts
+export enum ModalResult {
+    MR_OK = 1,
+    MR_CANCEL = 2,
+    MR_CLOSE = 3
+}
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import CommonDialog from '@ticatec/uniface-element/CommonDialog';
+</script>
+
+<CommonDialog
+  title="示例标题"
+  onClose={async (...args: any[]) => { console.log('onClose', ...args); return true; }}
+  width="240px"
+  height="48px"
+>
+  <div>在这里放置子内容</div>
+</CommonDialog>
+```
+
+## 源码
+
+- `src/lib/overlay/dialog/CommonDialog.svelte`

package/docs/components/common-dialog/example.svelte

@@ -0,0 +1,12 @@
+<script lang="ts">
+  import CommonDialog from '@ticatec/uniface-element/CommonDialog';
+</script>
+
+<CommonDialog
+  title="示例标题"
+  onClose={async (...args: any[]) => { console.log('onClose', ...args); return true; }}
+  width="240px"
+  height="48px"
+>
+  <div>在这里放置子内容</div>
+</CommonDialog>

package/docs/components/concise-data-table/README.md

@@ -0,0 +1,307 @@
+# ConciseDataTable
+
+数据展示组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+轻量紧凑的数据表格，适合快速展示较少列。
+
+## 适用场景
+
+- 弹窗内列表和摘要数据
+- 不需要复杂冻结列与行操作的表格
+
+## 导入
+
+```ts
+import ConciseDataTable from '@ticatec/uniface-element/ConciseDataTable';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `list` | 是 | `Array<any>` | 是 | `—` | 否 | 组件展示的数据集合。数据项结构由相关列、字段映射或渲染器决定。 |
+| `columns` | 是 | `Array<Column>` | 是 | `—` | 否 | 表格列定义，控制字段、标题、宽度、格式化、链接和自定义渲染。 |
+| `autoScroll` | 否 | `boolean` | 否 | `false` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `scrollInterval` | 否 | `number` | 否 | `2000` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `rowClickHandler` | 否 | `RowClickHandler \| null` | 否 | `null` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `options` | 是 | `TableOptions` | 否 | `{}` | 否 | 可选项数据源；通常配合 `keyField` 与 `textField` 指定值字段和显示字段。 |
+| `style` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的内联样式。 |
+| `class` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的 CSS class。 |
+| `onfocus` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 组件获得焦点时调用。 |
+| `onblur` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 组件失去焦点时调用。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `list`
+
+组件展示的数据集合。数据项结构由相关列、字段映射或渲染器决定。
+
+- 类型：`Array<any>`
+- 默认值：`—`
+- 示例写法：`list={[
+    {id: 1, name: '张三', department: '研发部'},
+    {id: 2, name: '李四', department: '产品部'}
+  ]}`
+
+### `columns`
+
+表格列定义，控制字段、标题、宽度、格式化、链接和自定义渲染。
+
+- 类型：`Array<Column>`
+- 默认值：`—`
+- 示例写法：`columns={[
+    {field: 'name', title: '姓名', width: 160},
+    {field: 'department', title: '部门', width: 180}
+  ]}`
+
+### `options`
+
+可选项数据源；通常配合 `keyField` 与 `textField` 指定值字段和显示字段。
+
+- 类型：`TableOptions`
+- 默认值：`{}`
+- 示例写法：参见下方完整示例中的类型化实现。
+
+## 组件实例方法
+
+通过 `bind:this` 获取组件实例后调用。
+
+| 方法 | 类型 | 说明 |
+| --- | --- | --- |
+| `setFocus()` | `() => void` | 组件实例方法。 |
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `Column`
+
+```ts
+export default interface Column {
+    // Display title for column header
+    title: string;
+    // Field name in data object
+    field: string;
+    // Width in pixels
+    width: number;
+    // Alignment: "left", "center", "right"
+    align?: "left" | "center" | "right",
+    // Flex weight: 0 = fixed width, >0 = proportional scaling
+    weight?: number;
+    // Optional formatter function
+    formatter?: (value: any) => string
+    // When true, the cell's (formatted) value is rendered as raw HTML ({@html}).
+    // Defaults to false/unset (safe, escaped plain text). Only set true when the
+    // field/formatter output is trusted markup — this is the same opt-in semantic as
+    // DataColumn#renderHTML in the data_table component.
+    renderHTML?: boolean;
+
+    /**
+     * @deprecated Use renderHTML instead; "escapeHTML" reads as "this escapes HTML"
+     * when it actually means the opposite — true renders raw, trusted HTML. Still
+     * honored as a fallback for existing callers.
+     */
+    escapeHTML?: boolean;
+}
+```
+
+### `RowClickHandler`
+
+```ts
+export type RowClickHandler = (row:any) => void;
+```
+
+### `TableOptions`
+
+```ts
+export interface TableOptions {
+    //表格的背景色
+    backgroundColor?: string;
+    //表格的文字颜色
+    color?: string;
+    //标题行高
+    headerHeight?: number;
+    //标题行的背景色
+    headerBackgroundColor?: string;
+    //标题行文字颜色
+    headerColor?: string;
+    //间隔行背景色
+    alternativeBackgroundColor?: string;
+    //间隔行颜色
+    alternativeColor?: string;
+    //数据行高度
+    rowHeight?: number;
+}
+```
+
+### `DataColumn`
+
+```ts
+export default interface DataColumn {
+
+    /**
+     * 列头文字
+     */
+    text: string;
+
+    /**
+     * 对应的字段/属性名
+     */
+    field?: string;
+
+    /**
+     * 是否冻结在数据表中，如果前面的frozen是false，那么就无效
+     */
+    frozen?: boolean;
+
+    /**
+     * 对齐方式
+     */
+    align?: 'left' | 'center' | 'right';
+
+    /**
+     *
+     */
+    width: number;
+
+    minWidth?: number;
+
+    /**
+     * 是否可以换行，默认为false
+     */
+    warp?: boolean;
+
+    /**
+     * 单元格转换函数
+     */
+    formatter?: FormatCell;
+
+    /**
+     * 是否将单元格内容作为可信 HTML 渲染（{@html}），而非纯文本转义。
+     * 仅当 field/formatter 输出为可信标记时才应设为 true。
+     */
+    renderHTML?: boolean;
+
+    /**
+     * @deprecated 请使用 renderHTML；名称容易被误读为"转义 HTML"，
+     * 实际含义相反——设为 true 会把内容作为可信 HTML 渲染。仍受支持以兼容旧调用。
+     */
+    escapeHTML?: boolean;
+
+    /**
+     * 超链接设置
+     */
+    href?: HrefBuilder;
+
+    /**
+     * 是否生产hint
+     */
+    hint?: CellHint;
+
+    /**
+     * 渲染器
+     */
+    render?: any;
+
+    /**
+     *
+     */
+    visible?: boolean;
+
+    /**
+     *
+     */
+    resizable?: boolean;
+
+    /**
+     *
+     */
+    compareFunction?: CompareFunction;
+
+    /**
+     * 获取表格的样式
+     */
+    cellStyle?: GetCellStyle;
+}
+```
+
+### `FormatCell`
+
+```ts
+export type FormatCell = (value: any) => string;
+```
+
+### `HrefBuilder`
+
+```ts
+export type HrefBuilder = (item: any) => Array<HrefLink> | HrefLink | string;
+```
+
+### `CellHint`
+
+```ts
+export type CellHint = (value: any) => string;
+```
+
+### `CompareFunction`
+
+```ts
+export type CompareFunction = (o1: any, o2: any) => number;
+```
+
+### `GetCellStyle`
+
+```ts
+export type GetCellStyle = (data: any) => string;
+```
+
+### `HrefLink`
+
+```ts
+export default interface HrefLink {
+    /**
+     * 显示超链接的文字
+     */
+    text: string;
+    /**
+     * 点击的处理函数
+     */
+    action: HrefAction;
+}
+```
+
+### `HrefAction`
+
+```ts
+export type HrefAction = () => void;
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import ConciseDataTable from '@ticatec/uniface-element/ConciseDataTable';
+</script>
+
+<ConciseDataTable
+  list={[
+    {id: 1, name: '张三', department: '研发部'},
+    {id: 2, name: '李四', department: '产品部'}
+  ]}
+  columns={[
+    {field: 'name', title: '姓名', width: 160},
+    {field: 'department', title: '部门', width: 180}
+  ]}
+  onfocus={async (...args: any[]) => { console.log('onfocus', ...args); return true; }}
+  onblur={async (...args: any[]) => { console.log('onblur', ...args); return true; }}
+/>
+```
+
+## 源码
+
+- `src/lib/data_display/concise_data_table/ConciseListTable.svelte`

package/docs/components/concise-data-table/example.svelte

@@ -0,0 +1,16 @@
+<script lang="ts">
+  import ConciseDataTable from '@ticatec/uniface-element/ConciseDataTable';
+</script>
+
+<ConciseDataTable
+  list={[
+    {id: 1, name: '张三', department: '研发部'},
+    {id: 2, name: '李四', department: '产品部'}
+  ]}
+  columns={[
+    {field: 'name', title: '姓名', width: 160},
+    {field: 'department', title: '部门', width: 180}
+  ]}
+  onfocus={async (...args: any[]) => { console.log('onfocus', ...args); return true; }}
+  onblur={async (...args: any[]) => { console.log('onblur', ...args); return true; }}
+/>

package/docs/components/context-menu/README.md

@@ -0,0 +1,99 @@
+# ContextMenu
+
+命令式服务。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+通过命令式 API 在鼠标位置显示上下文菜单。
+
+## 适用场景
+
+- 表格行、树节点和画布右键操作
+- 需要根据当前对象动态构建菜单项
+
+## 导入
+
+```ts
+import ContextMenu from '@ticatec/uniface-element/ContextMenu';
+```
+
+## 公开成员与方法
+
+| 成员 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `visible` | 是 | `boolean` | 否 | `$state(false)` | 是 | 内部响应式状态：标记当前是否正在显示。由 `show()`/`hide()` 等方法统一管理；这是一个单例服务而非组件，不能使用 `bind:visible`，不建议直接修改。 |
+| `position` | 是 | `{ x: number; y: number }` | 否 | `$state({ x: 0, y: 0 })` | 是 | 内部响应式状态；由上方方法统一管理。这是一个单例服务而非组件，不能使用 `bind:position`，仅供参考，不建议直接修改。 |
+| `items` | 是 | `ContextMenuItem[]` | 否 | `$state<ContextMenuItem[]>([])` | 是 | 内部响应式状态；由上方方法统一管理。这是一个单例服务而非组件，不能使用 `bind:items`，仅供参考，不建议直接修改。 |
+| `width` | 是 | `number` | 否 | `$state(150)` | 是 | 内部响应式状态；由上方方法统一管理。这是一个单例服务而非组件，不能使用 `bind:width`，仅供参考，不建议直接修改。 |
+| `height` | 是 | `number` | 否 | `$state(150)` | 是 | 内部响应式状态；由上方方法统一管理。这是一个单例服务而非组件，不能使用 `bind:height`，仅供参考，不建议直接修改。 |
+| `theme` | 是 | `unknown` | 否 | `$state()` | 是 | 内部响应式状态；由上方方法统一管理。这是一个单例服务而非组件，不能使用 `bind:theme`，仅供参考，不建议直接修改。 |
+| `show()` | 否 | `(event: MouseEvent, list: ContextMenuItem[], width = 150, height = 150, currentTheme?: string) => void` | 否 | `—` | 否 | 唤起右键菜单 |
+| `hide()` | 否 | `() => void` | 否 | `—` | 否 | 关闭右键菜单 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `ContextMenuItem`
+
+```ts
+export interface ContextMenuItem {
+    /**
+     * Display text for the menu item
+     */
+    text?: string;
+
+    /**
+     * Action to execute when item is clicked
+     */
+    action?: ActionCallback;
+
+    /**
+     * Whether the item is disabled
+     */
+    disabled?: boolean;
+
+    /**
+     * Whether this is a separator item
+     */
+    separator?: boolean;
+
+    /**
+     * Icon class or name for the menu item
+     */
+    icon?: string;
+
+    /**
+     * Custom CSS styles for the item
+     */
+    style?: string;
+}
+```
+
+### `ActionCallback`
+
+```ts
+export type ActionCallback = () => void;
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import ContextMenu from '@ticatec/uniface-element/ContextMenu';
+
+  function openMenu(event: MouseEvent) {
+    event.preventDefault();
+    ContextMenu.show(event, [{text: '查看', action: () => console.log('查看')}]);
+  }
+</script>
+
+<button type="button" oncontextmenu={openMenu}>在此区域右键点击</button>
+```
+
+## 源码
+
+- `src/lib/overlay/context-menu/ContextMenu.svelte.ts`

package/docs/components/context-menu/example.svelte

@@ -0,0 +1,10 @@
+<script lang="ts">
+  import ContextMenu from '@ticatec/uniface-element/ContextMenu';
+
+  function openMenu(event: MouseEvent) {
+    event.preventDefault();
+    ContextMenu.show(event, [{text: '查看', action: () => console.log('查看')}]);
+  }
+</script>
+
+<button type="button" oncontextmenu={openMenu}>在此区域右键点击</button>