@ticatec/uniface-element 5.0.1 → 5.0.2

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

@@ -0,0 +1,65 @@
+# HeaderLayout
+
+应用布局组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+以顶部区域为核心的应用页面布局。
+
+## 适用场景
+
+- 顶部导航型后台和内容门户
+- 需要固定 Header 与可滚动主体
+
+## 导入
+
+```ts
+import HeaderLayout from '@ticatec/uniface-element/app-layout/HeaderLayout';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `headerHeight` | 否 | `string` | 否 | `"48px"` | 否 | 高度配置；字符串可以使用 px、rem、% 等 CSS 单位。 |
+| `sidebarWidth` | 否 | `string` | 否 | `'300px'` | 否 | 宽度配置；字符串可以使用 px、rem、% 等 CSS 单位。 |
+| `sidebarResize` | 否 | `boolean` | 否 | `false` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `sidebarMaxWidth` | 否 | `string \| null` | 否 | `null` | 否 | 宽度配置；字符串可以使用 px、rem、% 等 CSS 单位。 |
+| `sidebarMinWidth` | 否 | `string \| null` | 否 | `null` | 否 | 宽度配置；字符串可以使用 px、rem、% 等 CSS 单位。 |
+| `header` | 否 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 渲染入口，用于替换或补充默认内容。 |
+| `sidebar` | 否 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 渲染入口，用于替换或补充默认内容。 |
+| `children` | 是 | `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 HeaderLayout from '@ticatec/uniface-element/app-layout/HeaderLayout';
+</script>
+
+<HeaderLayout
+  headerHeight="48px"
+  sidebarWidth="240px"
+  sidebarMaxWidth="240px"
+  sidebarMinWidth="240px"
+>
+  <div>在这里放置子内容</div>
+</HeaderLayout>
+```
+
+## 源码
+
+- `src/lib/app_layout/HeaderLayout.svelte`

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

@@ -0,0 +1,12 @@
+<script lang="ts">
+  import HeaderLayout from '@ticatec/uniface-element/app-layout/HeaderLayout';
+</script>
+
+<HeaderLayout
+  headerHeight="48px"
+  sidebarWidth="240px"
+  sidebarMaxWidth="240px"
+  sidebarMinWidth="240px"
+>
+  <div>在这里放置子内容</div>
+</HeaderLayout>

package/docs/components/icon/README.md

@@ -0,0 +1,87 @@
+# Icon
+
+通用组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+显示图标并支持尺寸、颜色和交互状态。
+
+## 适用场景
+
+- 按钮装饰、状态提示和独立操作图标
+- 统一使用项目图标字体或图标资源
+
+## 导入
+
+```ts
+import Icon from '@ticatec/uniface-element/Icon';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `name` | 是 | `string` | 是 | `—` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `onclick` | 是 | `MouseClickHandler \| null` | 否 | `null` | 否 | 用户点击组件时调用，参数通常为 MouseEvent。 |
+| `style` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的内联样式。 |
+| `theme` | 否 | `string` | 否 | `''` | 否 | 组件主题标识，通常通过 `data-theme` 选择对应 CSS 变量。 |
+| `class` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的 CSS class。 |
+| `tooltip` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `disabled` | 是 | `boolean` | 否 | `false` | 否 | 禁用交互。禁用后通常不可聚焦、不可修改，也不会触发变更操作。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `name`
+
+可选配置，具体取值范围和数据结构见类型列。
+
+- 类型：`string`
+- 默认值：`—`
+- 示例写法：`name="示例"`
+
+### `onclick`
+
+用户点击组件时调用，参数通常为 MouseEvent。
+
+- 类型：`MouseClickHandler | null`
+- 默认值：`null`
+- 示例写法：`onclick={async (...args: any[]) => { console.log('onclick', ...args); return true; }}`
+
+### `disabled`
+
+禁用交互。禁用后通常不可聚焦、不可修改，也不会触发变更操作。
+
+- 类型：`boolean`
+- 默认值：`false`
+- 示例写法：`disabled={false}`
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `MouseClickHandler`
+
+```ts
+export type MouseClickHandler = (event: MouseEvent) => void;
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import Icon from '@ticatec/uniface-element/Icon';
+</script>
+
+<Icon
+  name="示例"
+  onclick={async (...args: any[]) => { console.log('onclick', ...args); return true; }}
+  disabled={false}
+/>
+```
+
+## 源码
+
+- `src/lib/general/icon/Icon.svelte`

package/docs/components/icon/example.svelte

@@ -0,0 +1,9 @@
+<script lang="ts">
+  import Icon from '@ticatec/uniface-element/Icon';
+</script>
+
+<Icon
+  name="示例"
+  onclick={async (...args: any[]) => { console.log('onclick', ...args); return true; }}
+  disabled={false}
+/>

package/docs/components/icon-button/README.md

@@ -0,0 +1,91 @@
+# IconButton
+
+通用组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+仅以图标呈现的紧凑按钮。
+
+## 适用场景
+
+- 刷新、关闭、编辑和工具栏操作
+- 空间有限且图标语义明确的操作
+
+## 导入
+
+```ts
+import IconButton from '@ticatec/uniface-element/IconButton';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `type` | 否 | `ButtonType` | 否 | `'default'` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `htmlType` | 否 | `'button' \| 'submit' \| 'reset'` | 否 | `'button'` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `disabled` | 是 | `boolean` | 否 | `false` | 否 | 禁用交互。禁用后通常不可聚焦、不可修改，也不会触发变更操作。 |
+| `size` | 否 | `ButtonSize` | 否 | `'medium'` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `style` | 否 | `string` | 否 | `undefined` | 否 | 附加到组件根元素的内联样式。 |
+| `icon` | 否 | `string` | 否 | `''` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `tooltip` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `onclick` | 是 | `(event: MouseEvent) => void` | 否 | `undefined` | 否 | 用户点击组件时调用，参数通常为 MouseEvent。 |
+| `theme` | 否 | `string` | 否 | `undefined` | 否 | 组件主题标识，通常通过 `data-theme` 选择对应 CSS 变量。 |
+| `children` | 是 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 子内容，用于自定义组件主体。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `disabled`
+
+禁用交互。禁用后通常不可聚焦、不可修改，也不会触发变更操作。
+
+- 类型：`boolean`
+- 默认值：`false`
+- 示例写法：`disabled={false}`
+
+### `onclick`
+
+用户点击组件时调用，参数通常为 MouseEvent。
+
+- 类型：`(event: MouseEvent) => void`
+- 默认值：`undefined`
+- 示例写法：`onclick={async (...args: any[]) => { console.log('onclick', ...args); return true; }}`
+
+### `children`
+
+Svelte Snippet 子内容，用于自定义组件主体。
+
+- 类型：`Snippet`
+- 默认值：`undefined`
+- 示例写法：`children={children}`
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `ButtonType`
+
+```ts
+export type ButtonType = 'default' | 'primary' | 'secondary' | 'third' | 'forth';
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import IconButton from '@ticatec/uniface-element/IconButton';
+</script>
+
+<IconButton
+  onclick={async (...args: any[]) => { console.log('onclick', ...args); return true; }}
+  disabled={false}
+>
+  <div>在这里放置子内容</div>
+</IconButton>
+```
+
+## 源码
+
+- `src/lib/general/button/IconButton.svelte`

package/docs/components/icon-button/example.svelte

@@ -0,0 +1,10 @@
+<script lang="ts">
+  import IconButton from '@ticatec/uniface-element/IconButton';
+</script>
+
+<IconButton
+  onclick={async (...args: any[]) => { console.log('onclick', ...args); return true; }}
+  disabled={false}
+>
+  <div>在这里放置子内容</div>
+</IconButton>

package/docs/components/image-files/README.md

@@ -0,0 +1,174 @@
+# ImageFiles
+
+表单组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+管理图片上传、缩略图、预览和删除的图片字段。
+
+## 适用场景
+
+- 头像、商品图和现场照片
+- 需要图片预览及多图上传管理
+
+## 导入
+
+```ts
+import ImageFiles from '@ticatec/uniface-element/ImageFiles';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `variant` | 是 | `EditorVariant` | 否 | `getEditorVariant()` | 否 | 视觉样式变体，可选值：`""`(默认)、`plain`、`outlined`、`filled`；具体含义见组件说明。 |
+| `disabled` | 是 | `boolean` | 否 | `false` | 否 | 禁用交互。禁用后通常不可聚焦、不可修改，也不会触发变更操作。 |
+| `readonly` | 是 | `boolean` | 否 | `false` | 否 | 只读状态。保留内容展示，但阻止用户修改。 |
+| `files` | 是 | `ImageFile[]` | 是 | `$bindable([] as ImageFile[])` | 是 | 当前文件列表；增删文件后会更新绑定值。 |
+| `style` | 否 | `string` | 否 | `""` | 否 | 附加到组件根元素的内联样式。 |
+| `removeFileConfirm` | 否 | `RemoveConfirm` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `uploadFile` | 是 | `FileUpload` | 是 | `—` | 否 | 实际执行上传的函数；接收文件、进度回调与完成回调，需返回 `{cancel}` 以支持取消上传。 |
+| `maxFiles` | 否 | `number` | 否 | `1` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `text` | 否 | `string \| null` | 否 | `null as string \| null` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `variant`
+
+视觉样式变体，可选值：`""`(默认)、`plain`、`outlined`、`filled`；具体含义见组件说明。
+
+- 类型：`EditorVariant`
+- 默认值：`getEditorVariant()`
+- 示例写法：`variant="plain"`
+
+### `disabled`
+
+禁用交互。禁用后通常不可聚焦、不可修改，也不会触发变更操作。
+
+- 类型：`boolean`
+- 默认值：`false`
+- 示例写法：`disabled={false}`
+
+### `readonly`
+
+只读状态。保留内容展示，但阻止用户修改。
+
+- 类型：`boolean`
+- 默认值：`false`
+- 示例写法：`readonly={false}`
+
+### `files`
+
+当前文件列表；增删文件后会更新绑定值。
+
+- 类型：`ImageFile[]`
+- 默认值：`$bindable([] as ImageFile[])`
+- 推荐写法：`bind:files`
+
+### `uploadFile`
+
+实际执行上传的函数；接收文件、进度回调与完成回调，需返回 `{cancel}` 以支持取消上传。
+
+- 类型：`FileUpload`
+- 默认值：`—`
+- 示例写法：参见下方完整示例中的类型化实现。
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `EditorVariant`
+
+```ts
+export type EditorVariant = '' | 'plain' | 'outlined' | 'filled';
+```
+
+### `ImageFile`
+
+```ts
+export default interface ImageFile {
+
+    /**
+     * 附件名
+     */
+    name: string;
+
+    /**
+     * oss保存的文件路径
+     */
+    uri: string;
+
+    thumbnail?: string | undefined | null;
+}
+```
+
+### `RemoveConfirm`
+
+```ts
+export type RemoveConfirm = (file: ImageFile) => Promise<boolean>;
+```
+
+### `FileUpload`
+
+```ts
+export type FileUpload = (file: File, progressUpdate: ProgressUpdate, onUploaded: OnUploaded, errorHandler: ErrorHandler) => UploadProgress;
+```
+
+### `ProgressUpdate`
+
+```ts
+export type ProgressUpdate = (uploadBytes: number) => void;
+```
+
+### `OnUploaded`
+
+```ts
+export type OnUploaded = (url: string, thumbnail?: string) => void;
+```
+
+### `ErrorHandler`
+
+```ts
+export type ErrorHandler = (e: Error) => void;
+```
+
+### `UploadProgress`
+
+```ts
+export interface UploadProgress {
+
+    cancel:()=>Promise<boolean>;
+
+}
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import ImageFiles, {type FileUpload, type ImageFile} from '@ticatec/uniface-element/ImageFiles';
+
+  let files = $state<ImageFile[]>([]);
+  const uploadFile: FileUpload = (file, progress, uploaded) => {
+    progress(file.size);
+    uploaded(URL.createObjectURL(file));
+    return {cancel: async () => true};
+  };
+</script>
+
+<ImageFiles
+  bind:files
+  {uploadFile}
+  maxFiles={5}
+  variant="outlined"
+  removeFileConfirm={async (file) => confirm(`确定删除 ${file.name}？`)}
+/>
+<p>已上传 {files.length} 张图片</p>
+```
+
+## 源码
+
+- `src/lib/form/image-files/ImageFilesField.svelte`

package/docs/components/image-files/example.svelte

@@ -0,0 +1,19 @@
+<script lang="ts">
+  import ImageFiles, {type FileUpload, type ImageFile} from '@ticatec/uniface-element/ImageFiles';
+
+  let files = $state<ImageFile[]>([]);
+  const uploadFile: FileUpload = (file, progress, uploaded) => {
+    progress(file.size);
+    uploaded(URL.createObjectURL(file));
+    return {cancel: async () => true};
+  };
+</script>
+
+<ImageFiles
+  bind:files
+  {uploadFile}
+  maxFiles={5}
+  variant="outlined"
+  removeFileConfirm={async (file) => confirm(`确定删除 ${file.name}？`)}
+/>
+<p>已上传 {files.length} 张图片</p>

package/docs/components/indicator/README.md

@@ -0,0 +1,53 @@
+# Indicator
+
+命令式服务。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+通过命令式 API 显示全局处理中指示层。
+
+## 适用场景
+
+- 保存、导入和长任务执行期间
+- 需要阻止重复操作并提示正在处理
+
+## 导入
+
+```ts
+import Indicator from '@ticatec/uniface-element/Indicator';
+```
+
+## 公开成员与方法
+
+| 成员 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `message` | 是 | `string` | 否 | `$state('')` | 是 | 内部响应式状态；由上方方法统一管理。这是一个单例服务而非组件，不能使用 `bind:message`，仅供参考，不建议直接修改。 |
+| `visible` | 是 | `boolean` | 否 | `$state(false)` | 是 | 内部响应式状态：标记当前是否正在显示。由 `show()`/`hide()` 等方法统一管理；这是一个单例服务而非组件，不能使用 `bind:visible`，不建议直接修改。 |
+| `show()` | 否 | `(msg: string) => void` | 否 | `—` | 否 | 显示加载指示器 |
+| `hide()` | 否 | `() => void` | 否 | `—` | 否 | 隐藏加载指示器 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import Indicator from '@ticatec/uniface-element/Indicator';
+
+  async function runTask() {
+    Indicator.show('处理中…');
+    try {
+      await new Promise((resolve) => setTimeout(resolve, 1500));
+    } finally {
+      Indicator.hide();
+    }
+  }
+</script>
+
+<button type="button" onclick={runTask}>开始任务（1.5 秒后自动隐藏）</button>
+```
+
+## 源码
+
+- `src/lib/overlay/indicator/Indicator.svelte.ts`

package/docs/components/indicator/example.svelte

@@ -0,0 +1,14 @@
+<script lang="ts">
+  import Indicator from '@ticatec/uniface-element/Indicator';
+
+  async function runTask() {
+    Indicator.show('处理中…');
+    try {
+      await new Promise((resolve) => setTimeout(resolve, 1500));
+    } finally {
+      Indicator.hide();
+    }
+  }
+</script>
+
+<button type="button" onclick={runTask}>开始任务（1.5 秒后自动隐藏）</button>