@ticatec/uniface-element 5.0.1 → 5.0.2

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

@@ -0,0 +1,332 @@
+# AttachmentFiles
+
+表单组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+管理普通附件选择、上传、展示与删除的文件字段。
+
+## 适用场景
+
+- 合同、工单和审批附件
+- 需要限制文件数量、大小或类型的上传
+
+## 导入
+
+```ts
+import AttachmentFiles from '@ticatec/uniface-element/AttachmentFiles';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `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` | 否 | `''` | 否 | 自定义内联样式，会应用到字段根容器上 |
+| `onfocus` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 字段获得焦点时触发的回调 |
+| `onblur` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 字段失去焦点时触发的回调 |
+| `onchange` | 是 | `(value?: any) => void` | 否 | `undefined` | 否 | 字段值发生变化时触发的回调 |
+| `files` | 是 | `AttachmentFile[]` | 否 | `$bindable<AttachmentFile[]>([])` | 是 | 当前文件列表；增删文件后会更新绑定值。 |
+| `uploadFile` | 否 | `FileUpload` | 否 | `undefined` | 否 | 实际执行上传的函数；接收文件、进度回调与完成回调，需返回 `{cancel}` 以支持取消上传。 |
+| `onUpload` | 否 | `() => void` | 否 | `undefined` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
+| `onFileUploaded` | 否 | `(file: UploadFile) => void` | 否 | `undefined` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
+| `accept` | 否 | `string` | 否 | `"*/*"` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `maxSize` | 否 | `number` | 否 | `1024 * 1024 * 10` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `maxFiles` | 否 | `number` | 否 | `10` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `removeFileConfirm` | 否 | `(file: AttachmentFile) => Promise<boolean>` | 否 | `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; }}`
+
+### `files`
+
+当前文件列表；增删文件后会更新绑定值。
+
+- 类型：`AttachmentFile[]`
+- 默认值：`$bindable<AttachmentFile[]>([])`
+- 推荐写法：`bind:files`
+
+## 组件实例方法
+
+通过 `bind:this` 获取组件实例后调用。
+
+| 方法 | 类型 | 说明 |
+| --- | --- | --- |
+| `focus()` | `() => void` | 组件实例方法。 |
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `EditorVariant`
+
+```ts
+export type EditorVariant = '' | 'plain' | 'outlined' | 'filled';
+```
+
+### `AttachmentFile`
+
+```ts
+export default interface AttachmentFile {
+
+    /**
+     * 附件名
+     */
+    name: string;
+
+    /**
+     * 文件类型
+     */
+    type: FileType;
+
+    /**
+     * oss保存的文件路径
+     */
+    uri: string;
+}
+```
+
+### `FileUpload`
+
+```ts
+export type FileUpload = (file: File, progressUpdate: ProgressUpdate, onUploaded: OnUploaded, errorHandler: ErrorHandler) => UploadProgress;
+```
+
+### `UploadFile`
+
+```ts
+export default class UploadFile {
+
+    /**
+     * 待上传的文件
+     */
+    readonly file: File;
+
+    /**
+     * 上传后的文件地址
+     */
+    private _url: string | null = null;
+
+    /**
+     * 上传的缩率图
+     * @private
+     */
+    private _thumbnail: string | null | undefined = null;
+    /**
+     * 状态
+     */
+    private _status: ProgressStatus = ProgressStatus.progressing;
+    /**
+     * 已经上传的字节数
+     */
+    private _uploadedBytes: number = 0;
+    /**
+     * 上传的实例
+     */
+    private loader?: UploadProgress;
+
+    private readonly onCompleted: OnCompleted;
+
+    private readonly uploadFile: FileUpload;
+
+    private updateStatus: UpdateStatus = null as unknown as UpdateStatus;
+
+    constructor(file: File, uploadFile: FileUpload, onCompleted: OnCompleted) {
+        this.file = file;
+        this.uploadFile = uploadFile;
+        this.onCompleted = onCompleted;
+        this.loader = this.startUploading();
+    }
+
+    private startUploading() {
+        return  this.uploadFile(this.file, (bytes: number) => {
+            this._uploadedBytes = bytes;
+            this.updateStatus?.();
+        }, (url: string, thumbnail?: string) => {
+            this._url = url;
+            this._thumbnail = thumbnail;
+            this._status = ProgressStatus.successful;
+            this.onCompleted(this.file, url);
+            this.updateStatus?.();
+        }, (e: Error) => {
+            this._status = ProgressStatus.failure;
+            this.updateStatus?.();
+        });
+    }
+
+    restart() {
+        this._status = ProgressStatus.progressing;
+        this.loader = this.startUploading();
+        this.updateStatus?.();
+    }
+
+    get url(): string | null {
+        return this._url;
+    }
+
+    get thumbnail() : string | undefined | null {
+        return this._thumbnail;
+    }
+
+    get status(): ProgressStatus {
+        return this._status;
+    }
+
+    get progress(): number {
+        return Math.round(this._uploadedBytes * 100 / this.file.size);
+    }
+
+    async cancel(): Promise<boolean> {
+        let result = this.loader != null ? await this.loader.cancel() : true;
+        if (result) {
+            this._status = ProgressStatus.canceled;
+            this.updateStatus?.();
+        }
+        return result;
+    }
+
+    setUpdateStatus(value: UpdateStatus) {
+        this.updateStatus = value;
+    }
+}
+```
+
+### `FileType`
+
+```ts
+export enum FileType {
+    IMAGE = 'img',
+    PDF = 'pdf',
+    DOC = 'doc',
+    XLS = 'xml',
+    PPT = 'ppt',
+    AUDIO = 'wav',
+    VIDEO = 'mov',
+    OTHER = 'dat'
+}
+```
+
+### `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>;
+
+}
+```
+
+### `ProgressStatus`
+
+```ts
+export enum ProgressStatus {
+    progressing='progressing',
+    successful='successful',
+    failure='failure',
+    canceled='canceled'
+}
+```
+
+### `OnCompleted`
+
+```ts
+export type OnCompleted = (file: File, url: string, thumbnail?: string) => void;
+```
+
+### `UpdateStatus`
+
+```ts
+export type UpdateStatus = () => void;
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import AttachmentFiles from '@ticatec/uniface-element/AttachmentFiles';
+  let files = $state<any>([]);
+</script>
+
+<AttachmentFiles
+  bind:files
+  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({files})}</p>
+```
+
+## 源码
+
+- `src/lib/form/attachment_files/AttachmentEditor.svelte`

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

@@ -0,0 +1,16 @@
+<script lang="ts">
+  import AttachmentFiles from '@ticatec/uniface-element/AttachmentFiles';
+  let files = $state<any>([]);
+</script>
+
+<AttachmentFiles
+  bind:files
+  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({files})}</p>

package/docs/components/box/README.md

@@ -0,0 +1,63 @@
+# Box
+
+布局组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+提供边框、标题和内容区的通用容器。
+
+## 适用场景
+
+- 仪表盘模块和详情卡片区域
+- 需要统一间距与视觉分组的内容
+
+## 导入
+
+```ts
+import Box from '@ticatec/uniface-element/Box';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `title` | 否 | `string` | 否 | `''` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `round` | 否 | `boolean` | 否 | `false` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `style` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的内联样式。 |
+| `contentStyle` | 否 | `string` | 否 | `''` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `theme` | 否 | `string` | 否 | `undefined` | 否 | 组件主题标识，通常通过 `data-theme` 选择对应 CSS 变量。 |
+| `children` | 是 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 子内容，用于自定义组件主体。 |
+| `header` | 否 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 渲染入口，用于替换或补充默认内容。 |
+| `footer` | 否 | `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 Box from '@ticatec/uniface-element/Box';
+</script>
+
+<Box
+  title="示例标题"
+  round={true}
+>
+  <div>在这里放置子内容</div>
+</Box>
+```
+
+## 源码
+
+- `src/lib/layouts/box/Box.svelte`

package/docs/components/box/example.svelte

@@ -0,0 +1,10 @@
+<script lang="ts">
+  import Box from '@ticatec/uniface-element/Box';
+</script>
+
+<Box
+  title="示例标题"
+  round={true}
+>
+  <div>在这里放置子内容</div>
+</Box>

package/docs/components/breadcrumbs/README.md

@@ -0,0 +1,86 @@
+# Breadcrumbs
+
+导航组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+展示当前位置层级并支持返回上级的面包屑导航。
+
+## 适用场景
+
+- 多层后台菜单和详情页路径
+- 文件目录、分类目录与层级页面导航
+
+## 导入
+
+```ts
+import Breadcrumbs from '@ticatec/uniface-element/Breadcrumbs';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `items` | 是 | `Array<Breadcrumb>` | 否 | `[]` | 否 | 组件的数据项集合。 |
+| `separator` | 否 | `string` | 否 | `"/"` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `theme` | 否 | `string` | 否 | `undefined` | 否 | 组件主题标识，通常通过 `data-theme` 选择对应 CSS 变量。 |
+| `onclick` | 是 | `(event: MouseEvent, item: any) => void` | 否 | `undefined` | 否 | 用户点击组件时调用，参数通常为 MouseEvent。 |
+| `style` | 否 | `string` | 否 | `""` | 否 | 附加到组件根元素的内联样式。 |
+| `leadingSeparator` | 否 | `boolean` | 否 | `false` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `items`
+
+组件的数据项集合。
+
+- 类型：`Array<Breadcrumb>`
+- 默认值：`[]`
+- 示例写法：`items={[
+    {label: '首页', data: {path: '/'}},
+    {label: '用户管理', data: {path: '/users'}}
+  ]}`
+
+### `onclick`
+
+用户点击组件时调用，参数通常为 MouseEvent。
+
+- 类型：`(event: MouseEvent, item: any) => void`
+- 默认值：`undefined`
+- 示例写法：`onclick={async (...args: any[]) => { console.log('onclick', ...args); return true; }}`
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `Breadcrumb`
+
+```ts
+export default interface Breadcrumb {
+    label: string;
+    data: any;
+}
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import Breadcrumbs from '@ticatec/uniface-element/Breadcrumbs';
+</script>
+
+<Breadcrumbs
+  onclick={async (...args: any[]) => { console.log('onclick', ...args); return true; }}
+  items={[
+    {label: '首页', data: {path: '/'}},
+    {label: '用户管理', data: {path: '/users'}}
+  ]}
+/>
+```
+
+## 源码
+
+- `src/lib/navigation/breadcrumbs/Breadcrumbs.svelte`

package/docs/components/breadcrumbs/example.svelte

@@ -0,0 +1,11 @@
+<script lang="ts">
+  import Breadcrumbs from '@ticatec/uniface-element/Breadcrumbs';
+</script>
+
+<Breadcrumbs
+  onclick={async (...args: any[]) => { console.log('onclick', ...args); return true; }}
+  items={[
+    {label: '首页', data: {path: '/'}},
+    {label: '用户管理', data: {path: '/users'}}
+  ]}
+/>

package/docs/components/button/README.md

@@ -0,0 +1,103 @@
+# Button
+
+通用组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+标准操作按钮，支持视觉变体、图标和原生提交类型。
+
+## 适用场景
+
+- 保存、确认、创建等主要操作
+- 表单提交或普通页面命令
+
+## 导入
+
+```ts
+import Button from '@ticatec/uniface-element/Button';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `type` | 否 | `ButtonType` | 否 | `'default'` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `htmlType` | 否 | `'button' \| 'submit' \| 'reset'` | 否 | `'button'` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `label` | 否 | `string` | 否 | `''` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `variant` | 是 | `'plain' \| 'round' \| ''` | 否 | `''` | 否 | 视觉样式变体，可选值：`plain`、`round`、`""`(默认)；具体含义见组件说明。 |
+| `disabled` | 是 | `boolean` | 否 | `false` | 否 | 禁用交互。禁用后通常不可聚焦、不可修改，也不会触发变更操作。 |
+| `style` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的内联样式。 |
+| `size` | 否 | `'big' \| 'medium' \| 'small'` | 否 | `'medium'` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `onclick` | 是 | `(event: MouseEvent) => void` | 否 | `undefined` | 否 | 用户点击组件时调用，参数通常为 MouseEvent。 |
+| `autofocus` | 否 | `boolean` | 否 | `false` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `icon` | 否 | `string \| null` | 否 | `null` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `theme` | 否 | `string` | 否 | `undefined` | 否 | 组件主题标识，通常通过 `data-theme` 选择对应 CSS 变量。 |
+| `tooltip` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `children` | 是 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 子内容，用于自定义组件主体。 |
+| `data-*` | 否 | `any` | 否 | `透传` | 否 | 匹配此前缀的属性会透传给内部元素。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `variant`
+
+视觉样式变体，可选值：`plain`、`round`、`""`(默认)；具体含义见组件说明。
+
+- 类型：`'plain' | 'round' | ''`
+- 默认值：`''`
+- 示例写法：`variant="plain"`
+
+### `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 Button from '@ticatec/uniface-element/Button';
+</script>
+
+<Button
+  onclick={async (...args: any[]) => { console.log('onclick', ...args); return true; }}
+  label="示例标签"
+  variant="plain"
+  disabled={false}
+/>
+```
+
+## 源码
+
+- `src/lib/general/button/Button.svelte`

package/docs/components/button/example.svelte

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