@ticatec/uniface-element 5.0.1 → 5.0.2

package/docs/components/criteria-field/README.md

@@ -0,0 +1,69 @@
+# CriteriaField
+
+布局组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+用于搜索条件区域的带标签字段容器。
+
+## 适用场景
+
+- 高级查询和筛选面板
+- 需要统一排列查询控件与字段标签
+
+## 导入
+
+```ts
+import CriteriaField from '@ticatec/uniface-element/CriteriaField';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `style` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的内联样式。 |
+| `theme` | 否 | `string` | 否 | `undefined` | 否 | 组件主题标识，通常通过 `data-theme` 选择对应 CSS 变量。 |
+| `label` | 是 | `string` | 是 | `—` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `label$style` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `labelSuffix` | 否 | `string` | 否 | `':'` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `children` | 是 | `Snippet` | 是 | `—` | 否 | Svelte Snippet 子内容，用于自定义组件主体。 |
+| `size` | 否 | `'' \| 'x15' \| 'x20' \| 'x25' \| 'x30' \| 'x35' \| 'x40'` | 否 | `''` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `label`
+
+可选配置，具体取值范围和数据结构见类型列。
+
+- 类型：`string`
+- 默认值：`—`
+- 示例写法：`label="示例标签"`
+
+### `children`
+
+Svelte Snippet 子内容，用于自定义组件主体。
+
+- 类型：`Snippet`
+- 默认值：`—`
+- 示例写法：`children={children}`
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import CriteriaField from '@ticatec/uniface-element/CriteriaField';
+</script>
+
+<CriteriaField
+  label="示例标签"
+>
+  <div>在这里放置子内容</div>
+</CriteriaField>
+```
+
+## 源码
+
+- `src/lib/layouts/criteria_field/CriteriaField.svelte`

package/docs/components/criteria-field/example.svelte

@@ -0,0 +1,9 @@
+<script lang="ts">
+  import CriteriaField from '@ticatec/uniface-element/CriteriaField';
+</script>
+
+<CriteriaField
+  label="示例标签"
+>
+  <div>在这里放置子内容</div>
+</CriteriaField>

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

@@ -0,0 +1,365 @@
+# DataTable
+
+数据表格组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+支持列配置、选择、操作、冻结和扩展行的数据表格。
+
+## 适用场景
+
+- 企业列表页和大数据管理界面
+- 需要排序、选择、自定义单元格或行操作
+
+## 导入
+
+```ts
+import DataTable from '@ticatec/uniface-element/DataTable';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `columns` | 是 | `Array<DataColumn>` | 是 | `—` | 否 | 表格列定义，控制字段、标题、宽度、格式化、链接和自定义渲染。 |
+| `actionsColumn` | 否 | `ActionsColumn<T> \| null` | 否 | `null` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `indicatorColumn` | 否 | `IndicatorColumn \| null` | 否 | `null` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `rowHeight` | 否 | `number` | 否 | `42` | 否 | 高度配置，数值单位为像素。 |
+| `headerHeight` | 否 | `number` | 否 | `48` | 否 | 高度配置，数值单位为像素。 |
+| `list` | 是 | `Array<T>` | 是 | `—` | 否 | 组件展示的数据集合。数据项结构由相关列、字段映射或渲染器决定。 |
+| `selectedRows` | 是 | `Array<T>` | 否 | `$bindable([])` | 是 | 当前选中的行数据数组，推荐使用 `bind:selectedRows`；数组项与 `list` 中的数据引用一致。 |
+| `inlineRowHeight` | 是 | `number` | 否 | `$bindable(80)` | 是 | 高度配置，数值单位为像素。 |
+| `rowBorder` | 否 | `boolean` | 否 | `false` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `colBorder` | 否 | `boolean` | 否 | `false` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `emptyIndicator` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `getRowFontStyle` | 否 | `GetRowFontStyle<T>` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `style` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的内联样式。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `columns`
+
+表格列定义，控制字段、标题、宽度、格式化、链接和自定义渲染。
+
+- 类型：`Array<DataColumn>`
+- 默认值：`—`
+- 示例写法：`columns={[
+    {field: 'name', text: '姓名', width: 160},
+    {field: 'department', text: '部门', width: 180}
+  ]}`
+
+### `list`
+
+组件展示的数据集合。数据项结构由相关列、字段映射或渲染器决定。
+
+- 类型：`Array<T>`
+- 默认值：`—`
+- 示例写法：`list={[
+    {id: 1, name: '张三', department: '研发部'},
+    {id: 2, name: '李四', department: '产品部'}
+  ]}`
+
+### `selectedRows`
+
+当前选中的行数据数组，推荐使用 `bind:selectedRows`；数组项与 `list` 中的数据引用一致。
+
+- 类型：`Array<T>`
+- 默认值：`$bindable([])`
+- 推荐写法：`bind:selectedRows`
+
+### `inlineRowHeight`
+
+高度配置，数值单位为像素。
+
+- 类型：`number`
+- 默认值：`$bindable(80)`
+- 推荐写法：`bind:inlineRowHeight`
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `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;
+}
+```
+
+### `ActionsColumn`
+
+```ts
+export default interface ActionsColumn<T = any> {
+    /**
+     * 宽度
+     */
+    width: number;
+    /**
+     *
+     */
+    getActions: GetRowActions<T>;
+
+    /**
+     * 对齐方式，默认靠左对齐
+     */
+    align?: 'left' | 'center';
+}
+```
+
+### `IndicatorColumn`
+
+```ts
+export default interface IndicatorColumn {
+    /**
+     *
+     */
+    width: number;
+    /**
+     *
+     */
+    selectable?: boolean;
+
+    /**
+     *
+     */
+    buildInlineComponent?: (data:any) => Promise<any>;
+
+
+    /**
+     * 是否显示行号
+     */
+    displayNo?: boolean
+}
+```
+
+### `GetRowFontStyle`
+
+```ts
+export type GetRowFontStyle<T = any> = (data: T) => RowFontStyle;
+```
+
+### `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;
+```
+
+### `GetRowActions`
+
+```ts
+export type GetRowActions = (data: any) => Array<CellAction>;
+```
+
+### `RowFontStyle`
+
+```ts
+export interface RowFontStyle {
+    /**
+     * 字体大小
+     */
+    size?: string;
+    /**
+     * 字体颜色
+     */
+    color?: string;
+    /**
+     * 字重
+     */
+    weight?: number | string;
+}
+```
+
+### `HrefLink`
+
+```ts
+export default interface HrefLink {
+    /**
+     * 显示超链接的文字
+     */
+    text: string;
+    /**
+     * 点击的处理函数
+     */
+    action: HrefAction;
+}
+```
+
+### `CellAction`
+
+```ts
+export interface CellAction {
+    /**
+     * action的文本
+     */
+    text: string;
+    /**
+     * action的类型
+     */
+    type?: ButtonType;
+    /**
+     * 点击处理
+     */
+    handle: HandleAction;
+}
+```
+
+### `HrefAction`
+
+```ts
+export type HrefAction = () => void;
+```
+
+### `ButtonType`
+
+```ts
+export type ButtonType = 'default' | 'primary' | 'secondary' | 'third' | 'forth';
+```
+
+### `HandleAction`
+
+```ts
+export type HandleAction = (data: any) => Promise<void>;
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import DataTable from '@ticatec/uniface-element/DataTable';
+  let selectedRows = $state<any>([]);
+  let inlineRowHeight = $state<any>(80);
+</script>
+
+<DataTable
+  columns={[
+    {field: 'name', text: '姓名', width: 160},
+    {field: 'department', text: '部门', width: 180}
+  ]}
+  list={[
+    {id: 1, name: '张三', department: '研发部'},
+    {id: 2, name: '李四', department: '产品部'}
+  ]}
+  bind:selectedRows
+  bind:inlineRowHeight
+  rowBorder={true}
+  colBorder={true}
+  rowHeight={48}
+  headerHeight={48}
+/>
+<p>当前状态：{JSON.stringify({selectedRows, inlineRowHeight})}</p>
+```
+
+## 源码
+
+- `src/lib/data_table/DataTable.svelte`

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

@@ -0,0 +1,23 @@
+<script lang="ts">
+  import DataTable from '@ticatec/uniface-element/DataTable';
+  let selectedRows = $state<any>([]);
+  let inlineRowHeight = $state<any>(80);
+</script>
+
+<DataTable
+  columns={[
+    {field: 'name', text: '姓名', width: 160},
+    {field: 'department', text: '部门', width: 180}
+  ]}
+  list={[
+    {id: 1, name: '张三', department: '研发部'},
+    {id: 2, name: '李四', department: '产品部'}
+  ]}
+  bind:selectedRows
+  bind:inlineRowHeight
+  rowBorder={true}
+  colBorder={true}
+  rowHeight={48}
+  headerHeight={48}
+/>
+<p>当前状态：{JSON.stringify({selectedRows, inlineRowHeight})}</p>

package/docs/components/date-picker/README.md

@@ -0,0 +1,136 @@
+# DatePicker
+
+表单组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+选择单个日期的表单控件。
+
+## 适用场景
+
+- 生日、计划日期和业务发生日期
+- 需要格式化输入与日历选择
+
+## 导入
+
+```ts
+import DatePicker from '@ticatec/uniface-element/DatePicker';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `theme` | 否 | `string` | 否 | `undefined` | 否 | 主题样式名称，用于切换组件外观主题 |
+| `tooltip` | 否 | `string` | 否 | `undefined` | 否 | 悬停提示信息，鼠标悬浮在字段上时显示 |
+| `error` | 否 | `string` | 否 | `undefined` | 否 | 错误信息，用于在字段下方展示校验错误提示 |
+| `disabled` | 是 | `boolean` | 否 | `false` | 否 | 是否禁用该字段，禁用后字段不可编辑且不响应交互 |
+| `readonly` | 是 | `boolean` | 否 | `false` | 否 | 是否只读，只读状态下字段不可编辑但可聚焦和复制 |
+| `compact` | 否 | `boolean` | 否 | `false` | 否 | 是否启用紧凑模式，紧凑模式下字段内部间距更小 |
+| `variant` | 是 | `EditorVariant` | 否 | `undefined` | 否 | 编辑器外观样式变体 |
+| `placeholder` | 是 | `string` | 否 | `undefined` | 否 | 占位提示文本，字段值为空时在输入区域内展示 |
+| `style` | 否 | `string` | 否 | `undefined` | 否 | 自定义内联样式，会应用到字段根容器上 |
+| `onfocus` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 字段获得焦点时触发的回调 |
+| `onblur` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 字段失去焦点时触发的回调 |
+| `onchange` | 是 | `(value?: any) => void` | 否 | `undefined` | 否 | 字段值发生变化时触发的回调 |
+| `mandatory` | 否 | `boolean` | 否 | `false` | 否 | 是否为必填字段，必填时字段值不能为空 |
+| `onkeydown` | 否 | `(event: KeyboardEvent) => void` | 否 | `undefined` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
+| `onkeyup` | 否 | `(event: KeyboardEvent) => void` | 否 | `undefined` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
+| `onkeypress` | 否 | `(event: KeyboardEvent) => void` | 否 | `undefined` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
+| `value` | 是 | `UniDate` | 否 | `$bindable<UniDate>()` | 是 | 组件的核心值。支持绑定时建议使用 `bind:value`，外部修改会同步到组件。 |
+| `min` | 否 | `UniDate` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `max` | 否 | `UniDate` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `disabled`
+
+是否禁用该字段，禁用后字段不可编辑且不响应交互
+
+- 类型：`boolean`
+- 默认值：`false`
+- 示例写法：`disabled={false}`
+
+### `readonly`
+
+是否只读，只读状态下字段不可编辑但可聚焦和复制
+
+- 类型：`boolean`
+- 默认值：`false`
+- 示例写法：`readonly={false}`
+
+### `variant`
+
+编辑器外观样式变体
+
+- 类型：`EditorVariant`
+- 默认值：`undefined`
+- 示例写法：`variant="plain"`
+
+### `placeholder`
+
+占位提示文本，字段值为空时在输入区域内展示
+
+- 类型：`string`
+- 默认值：`undefined`
+- 示例写法：`placeholder="请输入或选择"`
+
+### `onchange`
+
+字段值发生变化时触发的回调
+
+- 类型：`(value?: any) => void`
+- 默认值：`undefined`
+- 示例写法：`onchange={async (...args: any[]) => { console.log('onchange', ...args); return true; }}`
+
+### `value`
+
+组件的核心值。支持绑定时建议使用 `bind:value`，外部修改会同步到组件。
+
+- 类型：`UniDate`
+- 默认值：`$bindable<UniDate>()`
+- 推荐写法：`bind:value`
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `EditorVariant`
+
+```ts
+export type EditorVariant = '' | 'plain' | 'outlined' | 'filled';
+```
+
+### `UniDate`
+
+```ts
+export type UniDate = dayjs.Dayjs | Date | string | undefined;
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import DatePicker from '@ticatec/uniface-element/DatePicker';
+  let value = $state<any>('2026-08-22');
+</script>
+
+<DatePicker
+  bind:value
+  onchange={async (...args: any[]) => { console.log('onchange', ...args); return true; }}
+  onfocus={async (...args: any[]) => { console.log('onfocus', ...args); return true; }}
+  variant="plain"
+  placeholder="请输入或选择"
+  disabled={false}
+  readonly={false}
+  compact={true}
+/>
+<p>当前状态：{JSON.stringify({value})}</p>
+```
+
+## 源码
+
+- `src/lib/form/date_picker/DatePicker.svelte`

package/docs/components/date-picker/example.svelte

@@ -0,0 +1,16 @@
+<script lang="ts">
+  import DatePicker from '@ticatec/uniface-element/DatePicker';
+  let value = $state<any>('2026-08-22');
+</script>
+
+<DatePicker
+  bind:value
+  onchange={async (...args: any[]) => { console.log('onchange', ...args); return true; }}
+  onfocus={async (...args: any[]) => { console.log('onfocus', ...args); return true; }}
+  variant="plain"
+  placeholder="请输入或选择"
+  disabled={false}
+  readonly={false}
+  compact={true}
+/>
+<p>当前状态：{JSON.stringify({value})}</p>