@ticatec/uniface-element 5.0.4 → 5.1.0

package/dist/form/group_box/group-check-box/README.md

@@ -1,5 +1,7 @@
 # GroupCheckBox
 
+> **Renamed in 5.1.0**: this document uses the names from the [API Naming Guide](../../../../docs/NAMING.md); the old names `itemStyle` were removed in 5.1.0 (no compatibility aliases are kept).
+
 A multi-select group of checkboxes wrapped in the shared form editor shell. Options are rendered in a horizontal row; the bound `value` can be either a **delimiter-joined string** or a **bitmask number**.
 
 ## Installation
@@ -68,7 +70,7 @@ import GroupCheckBox from "@ticatec/uniface-element/GroupCheckBox";
 | `disabledOptions` | `string[]` | `[]` | Keys of options that stay disabled |
 | `hideOptions` | `string[]` | `[]` | Keys of options that are not rendered |
 | `style` | `string` | `""` | Inline style on the form editor |
-| `itemStyle` | `string` | `""` | Inline style applied to each `CheckBox` |
+| `item$style` | `string` | `""` | Inline style applied to each `CheckBox` |
 | `class` | `string` | `""` | Extra class on the form editor |
 | `onchange` | `(value: string \| number) => void` | — | Fired after a **user** toggle; receives the new `value` |
 | `onfocus` | `(e: FocusEvent) => void` | — | First focus into the group |
@@ -301,7 +303,7 @@ Keep `options` order stable when using bit mode; reordering changes bit meanings
 - Root list: `.group-check-box` — `display: flex; flex-direction: row; align-items: center`
 - Compact: `.group-check-box.compact`
 - Shell chrome (border, fill, error) comes from `FormEditor` via `variant` / `error` / `tooltip`
-- Per-item look: `itemStyle` on each checkbox; checkbox tokens are those of [`CheckBox`](../../checkbox/README.md)
+- Per-item look: `item$style` on each checkbox; checkbox tokens are those of [`CheckBox`](../../checkbox/README.md)
 
 ```svelte
 <GroupCheckBox
@@ -309,7 +311,7 @@ Keep `options` order stable when using bit mode; reordering changes bit meanings
   bind:value={value}
   variant="outlined"
   style="min-width: 320px;"
-  itemStyle="margin-right: 4px;"
+  item$style="margin-right: 4px;"
 />
 ```
 

package/dist/form/group_box/group-check-box/README_CN.md

@@ -1,5 +1,7 @@
 # GroupCheckBox 组复选框
 
+> **5.1.0 重命名**：本文使用 [API 命名规范](../../../../docs/NAMING_CN.md) 中的名字；旧名 `itemStyle` 已在 5.1.0 移除（5.1.0 不保留兼容别名）。
+
 多选复选框组，包在共享表单编辑器外壳中。选项横向排列；绑定的 `value` 可以是**分隔符拼接的字符串**，也可以是**位掩码数字**。
 
 ## 安装
@@ -68,7 +70,7 @@ import GroupCheckBox from "@ticatec/uniface-element/GroupCheckBox";
 | `disabledOptions` | `string[]` | `[]` | 保持禁用的选项键 |
 | `hideOptions` | `string[]` | `[]` | 不渲染的选项键 |
 | `style` | `string` | `""` | 表单编辑器内联样式 |
-| `itemStyle` | `string` | `""` | 应用到每个 `CheckBox` 的内联样式 |
+| `item$style` | `string` | `""` | 应用到每个 `CheckBox` 的内联样式 |
 | `class` | `string` | `""` | 表单编辑器额外 CSS 类 |
 | `onchange` | `(value: string \| number) => void` | — | **用户**切换后回调，参数为新的 `value` |
 | `onfocus` | `(e: FocusEvent) => void` | — | 焦点进入组时触发 |
@@ -301,7 +303,7 @@ import GroupCheckBox from "@ticatec/uniface-element/GroupCheckBox";
 - 列表根节点：`.group-check-box` — `display: flex; flex-direction: row; align-items: center`
 - 紧凑：`.group-check-box.compact`
 - 边框 / 填充 / 错误等外壳样式来自 `FormEditor` 的 `variant` / `error` / `tooltip`
-- 单项外观：`itemStyle`；复选框主题变量见 [`CheckBox`](../../checkbox/README_CN.md)
+- 单项外观：`item$style`；复选框主题变量见 [`CheckBox`](../../checkbox/README_CN.md)
 
 ```svelte
 <GroupCheckBox
@@ -309,7 +311,7 @@ import GroupCheckBox from "@ticatec/uniface-element/GroupCheckBox";
   bind:value={value}
   variant="outlined"
   style="min-width: 320px;"
-  itemStyle="margin-right: 4px;"
+  item$style="margin-right: 4px;"
 />
 ```
 

package/dist/form/group_box/group-radio-box/GroupRadioBox.svelte

@@ -1,7 +1,8 @@
 <script lang="ts">
     import RadioButton from "../../radio_button/RadioButton.svelte";
     import FormEditor from "../../FormEditor.svelte";
-    import type {EditorEvents, EditorVariant} from "../../types";
+    import type {EditorVariant} from "../../types";
+    import type {EditorEvents} from "../../events";
 
     interface OptionItem {
         [key: string]: any;
@@ -17,14 +18,15 @@
         options: Array<OptionItem>;
         keyField?: string;
         textField?: string;
-        itemStyle?: string;
+        /** 每个选项的内联样式 */
+        item$style?: string;
         disabledOptions?: Array<string>;
         variant?: EditorVariant;
         compact?: boolean;
         class?: string;
         onchange?: (value: any) => void;
-        onblur?: (e: FocusEvent) => void;
-        onfocus?: (e: FocusEvent) => void;
+        onblur?: (event: FocusEvent) => void;
+        onfocus?: (event: FocusEvent) => void;
     }
 
     let {
@@ -37,7 +39,7 @@
         options,
         keyField = "code",
         textField = "text",
-        itemStyle = '',
+        item$style = '',
         disabledOptions = [],
         variant,
         compact = false,
@@ -116,7 +118,7 @@
     {readonly}
     {compact}
     {style}
-    className={className}
+    class={className}
 >
     <!-- onclick only forwards focus to the first radio when the container's own
          background is clicked; each RadioButton inside is independently
@@ -130,7 +132,7 @@
                 {readonly}
                 disabled={disabled || disabledOptions.indexOf(op[keyField]) > -1}
                 label={op[textField]}
-                style={itemStyle}
+                style={item$style}
                 bind:group={value}
                 value={op[keyField]}
                 onchange={handleRadioChange}

package/dist/form/group_box/group-radio-box/GroupRadioBox.svelte.d.ts

@@ -12,14 +12,15 @@ interface Props {
     options: Array<OptionItem>;
     keyField?: string;
     textField?: string;
-    itemStyle?: string;
+    /** 每个选项的内联样式 */
+    item$style?: string;
     disabledOptions?: Array<string>;
     variant?: EditorVariant;
     compact?: boolean;
     class?: string;
     onchange?: (value: any) => void;
-    onblur?: (e: FocusEvent) => void;
-    onfocus?: (e: FocusEvent) => void;
+    onblur?: (event: FocusEvent) => void;
+    onfocus?: (event: FocusEvent) => void;
 }
 declare const GroupRadioBox: import("svelte").Component<Props, {
     focus: () => void;

package/dist/form/group_box/group-radio-box/README.md

@@ -1,5 +1,7 @@
 # GroupRadioBox
 
+> **Renamed in 5.1.0**: this document uses the names from the [API Naming Guide](../../../../docs/NAMING.md); the old names `itemStyle` were removed in 5.1.0 (no compatibility aliases are kept).
+
 A flexible group radio box component that allows users to select a single option from a predefined list. Features comprehensive state management, custom styling variants, and focus/blur event handling for seamless form integration.
 
 ## Installation
@@ -57,7 +59,7 @@ import GroupRadioBox from "@ticatec/uniface-element/GroupRadioBox";
 | `compact` | `boolean` | `false` | Whether to use compact spacing |
 | `disabledOptions` | `Array<string>` | `[]` | Array of option keys to disable |
 | `style` | `string` | `""` | Additional CSS styles |
-| `itemStyle` | `string` | `""` | CSS styles for individual radio button items |
+| `item$style` | `string` | `""` | CSS styles for individual radio button items |
 | `class` | `string` | `""` | Custom CSS class |
 | `onchange` | `(value: any) => void` | - | Change event handler |
 | `onfocus` | `(() => void) \| null` | `null` | Focus event handler |

package/dist/form/group_box/group-radio-box/README_CN.md

@@ -1,5 +1,7 @@
 # GroupRadioBox 组单选框组件
 
+> **5.1.0 重命名**：本文使用 [API 命名规范](../../../../docs/NAMING_CN.md) 中的名字；旧名 `itemStyle` 已在 5.1.0 移除（5.1.0 不保留兼容别名）。
+
 一个灵活的组单选框组件，允许用户从预定义的选项列表中选择单个选项。具备全面的状态管理、自定义样式变体以及焦点/失焦事件处理，可无缝集成到表单中。
 
 ## 安装
@@ -57,7 +59,7 @@ import GroupRadioBox from "@ticatec/uniface-element/GroupRadioBox";
 | `compact` | `boolean` | `false` | 是否使用紧凑间距 |
 | `disabledOptions` | `Array<string>` | `[]` | 要禁用的选项键数组 |
 | `style` | `string` | `""` | 附加 CSS 样式 |
-| `itemStyle` | `string` | `""` | 单个单选框项目的 CSS 样式 |
+| `item$style` | `string` | `""` | 单个单选框项目的 CSS 样式 |
 | `class` | `string` | `""` | 自定义 CSS 类 |
 | `onchange` | `(value: any) => void` | - | 更改事件处理程序 |
 | `onfocus` | `(() => void) \| null` | `null` | 焦点事件处理程序 |

package/dist/form/image_editor/ImageEditor.svelte

@@ -0,0 +1,118 @@
+<script lang="ts">
+    import type CommonFieldProps from "../common_editor/CommonFieldProps";
+    import type {BeforeRemove} from "../types";
+    import AttachmentEditor from "../attachment_files/AttachmentEditor.svelte";
+    import type {AttachmentLayout} from "../attachment_files/AttachmentFile";
+    import type {FileUpload} from "../attachment_files/FileUpload";
+    import type {RejectReason} from "../attachment_files/UploadTask";
+    import ImagePreview from "./ImagePreview.svelte";
+    import type ImageFile from "./ImageFile";
+
+    interface Props extends CommonFieldProps {
+        /** 已上传的图片列表（可绑定） */
+        files?: ImageFile[];
+        /** 排列方式：icon（缩略图瓦片，自动换行，默认）/ list（每行一张） */
+        layout?: AttachmentLayout;
+        /** 内容区高度；超出后内部滚动，不设则随内容自适应 */
+        height?: number | string;
+        /** 实际执行上传的函数；不传则只展示（不显示上传入口）。onUploaded 的第二个参数可传缩略图地址 */
+        uploadFile?: FileUpload;
+        /** 允许的文件类型（同 input accept） */
+        accept?: string;
+        /** 单个文件大小上限（字节） */
+        maxSize?: number;
+        /** 图片数量上限（含上传中的） */
+        maxFiles?: number;
+        /** 一次是否允许选择 / 拖入多张 */
+        multiple?: boolean;
+        /** 上传入口的文字（空态时作为拖放区提示） */
+        uploadText?: string;
+        /** 没有图片且不能上传时显示的文字 */
+        emptyText?: string;
+        /** 是否可预览：显示预览按钮，点击打开内置的大图预览 */
+        previewable?: boolean;
+        /** 自定义预览；传了则不再打开内置预览 */
+        onPreview?: (file: ImageFile) => void;
+        /** 删除图片前的否决钩子：返回 false 取消删除 */
+        beforeRemove?: BeforeRemove<ImageFile>;
+        /** 图片被删除后通知 */
+        onremove?: (file: ImageFile) => void;
+        /** 自定义下载；不传则通过 `file.uri` 直接下载 */
+        ondownload?: (file: ImageFile) => void;
+        /** 单张图片上传完成并加入 files 后通知 */
+        onFileUploaded?: (file: ImageFile, source: File) => void;
+        /** 文件因类型 / 大小 / 数量限制被拒绝时通知 */
+        onFileRejected?: (file: File, reason: RejectReason) => void;
+        /** 上传失败时通知（任务保留在列表中，可重试或移除） */
+        onUploadError?: (file: File, error: Error) => void;
+        /** files 变化后通知（上传完成或删除） */
+        onchange?: (files: ImageFile[]) => void;
+    }
+
+    let {
+        disabled = false,
+        readonly = false,
+        variant,
+        compact = false,
+        theme,
+        tooltip,
+        error,
+        style = '',
+        files = $bindable<ImageFile[]>([]),
+        layout = 'icon',
+        height,
+        uploadFile,
+        accept = "image/*",
+        maxSize = 1024 * 1024 * 10,
+        maxFiles = 10,
+        multiple = true,
+        uploadText,
+        emptyText,
+        previewable = true,
+        onPreview,
+        beforeRemove,
+        onremove,
+        ondownload,
+        onFileUploaded,
+        onFileRejected,
+        onUploadError,
+        onfocus,
+        onblur,
+        onchange
+    }: Props = $props();
+
+    let editor: {openFileDialog: () => void; focus: () => void} | undefined = $state(undefined);
+    let showPreview = $state(false);
+    let previewSrc = $state('');
+
+    const handlePreview = (file: ImageFile) => {
+        if (onPreview) {
+            onPreview(file);
+        } else {
+            previewSrc = file.uri;
+            showPreview = true;
+        }
+    };
+
+    /**
+     * 打开系统文件选择框（等同于点击上传入口）
+     */
+    export function openFileDialog() {
+        editor?.openFileDialog();
+    }
+
+    export function focus() {
+        editor?.focus();
+    }
+</script>
+
+<AttachmentEditor bind:this={editor} bind:files showThumbnail
+                  {disabled} {readonly} {variant} {compact} {theme} {tooltip} {error} {style}
+                  {layout} {height} {uploadFile} {accept} {maxSize} {maxFiles} {multiple} {uploadText} {emptyText}
+                  onPreview={previewable || onPreview ? handlePreview : undefined}
+                  {beforeRemove} {onremove} {ondownload} {onFileUploaded} {onFileRejected} {onUploadError}
+                  {onfocus} {onblur} {onchange}/>
+
+{#if showPreview}
+    <ImagePreview bind:visible={showPreview} src={previewSrc}/>
+{/if}

package/dist/form/image_editor/ImageEditor.svelte.d.ts

@@ -0,0 +1,52 @@
+import type CommonFieldProps from "../common_editor/CommonFieldProps";
+import type { BeforeRemove } from "../types";
+import type { AttachmentLayout } from "../attachment_files/AttachmentFile";
+import type { FileUpload } from "../attachment_files/FileUpload";
+import type { RejectReason } from "../attachment_files/UploadTask";
+import type ImageFile from "./ImageFile";
+interface Props extends CommonFieldProps {
+    /** 已上传的图片列表（可绑定） */
+    files?: ImageFile[];
+    /** 排列方式：icon（缩略图瓦片，自动换行，默认）/ list（每行一张） */
+    layout?: AttachmentLayout;
+    /** 内容区高度；超出后内部滚动，不设则随内容自适应 */
+    height?: number | string;
+    /** 实际执行上传的函数；不传则只展示（不显示上传入口）。onUploaded 的第二个参数可传缩略图地址 */
+    uploadFile?: FileUpload;
+    /** 允许的文件类型（同 input accept） */
+    accept?: string;
+    /** 单个文件大小上限（字节） */
+    maxSize?: number;
+    /** 图片数量上限（含上传中的） */
+    maxFiles?: number;
+    /** 一次是否允许选择 / 拖入多张 */
+    multiple?: boolean;
+    /** 上传入口的文字（空态时作为拖放区提示） */
+    uploadText?: string;
+    /** 没有图片且不能上传时显示的文字 */
+    emptyText?: string;
+    /** 是否可预览：显示预览按钮，点击打开内置的大图预览 */
+    previewable?: boolean;
+    /** 自定义预览；传了则不再打开内置预览 */
+    onPreview?: (file: ImageFile) => void;
+    /** 删除图片前的否决钩子：返回 false 取消删除 */
+    beforeRemove?: BeforeRemove<ImageFile>;
+    /** 图片被删除后通知 */
+    onremove?: (file: ImageFile) => void;
+    /** 自定义下载；不传则通过 `file.uri` 直接下载 */
+    ondownload?: (file: ImageFile) => void;
+    /** 单张图片上传完成并加入 files 后通知 */
+    onFileUploaded?: (file: ImageFile, source: File) => void;
+    /** 文件因类型 / 大小 / 数量限制被拒绝时通知 */
+    onFileRejected?: (file: File, reason: RejectReason) => void;
+    /** 上传失败时通知（任务保留在列表中，可重试或移除） */
+    onUploadError?: (file: File, error: Error) => void;
+    /** files 变化后通知（上传完成或删除） */
+    onchange?: (files: ImageFile[]) => void;
+}
+declare const ImageEditor: import("svelte").Component<Props, {
+    openFileDialog: () => void;
+    focus: () => void;
+}, "files">;
+type ImageEditor = ReturnType<typeof ImageEditor>;
+export default ImageEditor;

package/dist/form/image_editor/ImageFile.d.ts

@@ -0,0 +1,11 @@
+import type { UploadedFile } from "../attachment_files/AttachmentFile";
+/**
+ * ImageEditor 的列表项：name / uri / size? / thumbnail?
+ * 缩略图缺省时直接用 uri 显示
+ */
+export default interface ImageFile extends UploadedFile {
+    /**
+     * 缩略图地址，可选；缺省时直接用 uri 显示
+     */
+    thumbnail?: string | null;
+}

package/dist/form/image_editor/ImageFile.js

@@ -0,0 +1 @@
+export {};

package/dist/form/{image-files → image_editor}/ImagePreview.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
-    import Button, {IconButton} from "../../general/button";
+    import {IconButton} from "../../general/button";
+    import {registerEscapeHandler} from "../../overlay/common/escapeClose";
 
     let {
         src = "",
@@ -47,6 +48,13 @@
         scale /= 1.2;
     }
 
+    // Escape 关闭（走共享的 escape 栈，嵌套在 Dialog 里时先关预览）
+    $effect(() => {
+        if (visible) {
+            return registerEscapeHandler(() => { visible = false; });
+        }
+    });
+
     $effect(() => {
         window.addEventListener("resize", updateContainerSize);
         updateContainerSize();
@@ -91,7 +99,7 @@
 
 <style>
     .uniface-image-preview-overlay {
-        position: absolute;
+        position: fixed;
         top: 0;
         left: 0;
         bottom: 0;

package/dist/form/image_editor/README.md

@@ -0,0 +1,89 @@
+# ImageEditor
+
+An image upload field built on the same implementation as [AttachmentEditor](../attachment_files/README.md): the whole field is a drop zone, the upload entry is a "+" tile (or a dashed row in `list` layout) at the end of the content, tiles show thumbnails, uploads run inline with a progress ring and a cancel button, and a preview button opens the built-in full-size viewer.
+
+> Renamed in 5.1.0: `ImageFilesField` → `ImageEditor`, import path `@ticatec/uniface-element/ImageFiles` → `@ticatec/uniface-element/ImageEditor` (no compatibility aliases).
+
+## Features
+
+- **Thumbnail tiles** (`thumbnail ?? uri`), wrapping automatically; `layout="list"` shows one row per image with a small thumbnail.
+- **Drag & drop** anywhere in the field; `accept` defaults to `image/*`.
+- **Local preview while uploading** (object URL) under the progress ring; cancel / retry / discard.
+- **Built-in preview** — the eye button opens a full-screen viewer with zoom; replace it with `onPreview`, or turn it off with `previewable={false}`.
+- **Limits and notifications** identical to AttachmentEditor: `maxSize`, `maxFiles`, `multiple`, `onFileRejected`, `onUploadError`, `beforeRemove`, `onremove`, `onchange`.
+- **Readonly / disabled** — preview and download stay, delete and the upload entry disappear.
+
+## Import
+
+```typescript
+import ImageEditor from "@ticatec/uniface-element/ImageEditor";
+import type {ImageFile, FileUpload} from "@ticatec/uniface-element/ImageEditor";
+```
+
+## Basic usage
+
+```svelte
+<script lang="ts">
+  import ImageEditor from "@ticatec/uniface-element/ImageEditor";
+  import type {ImageFile, FileUpload} from "@ticatec/uniface-element/ImageEditor";
+
+  let files = $state<ImageFile[]>([]);
+
+  const uploadFile: FileUpload = (file, progressUpdate, onUploaded, onError) => {
+    const xhr = new XMLHttpRequest();
+    xhr.upload.onprogress = (e) => progressUpdate(e.loaded);
+    xhr.onload = () => {
+      const res = JSON.parse(xhr.responseText);      // {url, thumbnail}
+      xhr.status < 300 ? onUploaded(res.url, res.thumbnail) : onError(new Error(xhr.statusText));
+    };
+    xhr.onerror = () => onError(new Error('Network error'));
+    const body = new FormData();
+    body.append('file', file);
+    xhr.open('POST', '/api/images');
+    xhr.send(body);
+    return {cancel: async () => { xhr.abort(); return true; }};
+  };
+</script>
+
+<ImageEditor bind:files {uploadFile} maxFiles={6} height={140}/>
+```
+
+## Props
+
+Props inherited from `CommonFieldProps` (`variant`, `compact`, `disabled`, `readonly`, `theme`, `tooltip`, `error`, `style`, `onfocus`, `onblur`) are not repeated. Everything below except the first three rows behaves exactly as in AttachmentEditor.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `files` | `ImageFile[]` (bindable) | `[]` | Uploaded images: `{name, uri, thumbnail?, size?}`. |
+| `layout` | `'icon' \| 'list'` | `'icon'` | Thumbnail tiles, or one row per image. |
+| `accept` | `string` | `"image/*"` | Allowed types. |
+| `previewable` | `boolean` | `true` | Show the preview button; opens the built-in viewer unless `onPreview` is set. |
+| `onPreview` | `(file: ImageFile) => void` | — | Custom preview handler (replaces the built-in viewer). |
+| `height` | `number \| string` | — | Content height; scrolls inside. |
+| `uploadFile` | `FileUpload` | — | Upload function. `onUploaded(url, thumbnail?)` — pass the thumbnail URL as the second argument when the server generates one. |
+| `maxSize` / `maxFiles` / `multiple` | | `10 MB` / `10` / `true` | Limits. |
+| `uploadText` / `emptyText` | `string` | i18n | Upload entry text / empty text. |
+| `beforeRemove` | `BeforeRemove<ImageFile>` | — | Veto hook; `false` keeps the image. |
+| `onremove` / `ondownload` / `onFileUploaded` / `onFileRejected` / `onUploadError` / `onchange` | | — | Same as AttachmentEditor. |
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `openFileDialog()` | Opens the system file dialog. |
+| `focus()` | Focuses the first control inside the field. |
+
+## `ImageFile`
+
+```typescript
+interface ImageFile {
+  name: string;
+  uri: string;          // full-size image URL, also used for preview / download
+  thumbnail?: string;   // optional; falls back to uri
+  size?: number;        // bytes, optional
+}
+```
+
+## Related components
+
+- [AttachmentEditor](../attachment_files/README.md) — the general file version of this field.

package/dist/form/image_editor/README_CN.md

@@ -0,0 +1,89 @@
+# ImageEditor
+
+图片上传字段，与 [AttachmentEditor](../attachment_files/README_CN.md) 是同一套实现：整个字段都是拖放区，上传入口是内容末尾的 "+" 瓦片（`list` 方式是底部虚线行），瓦片显示缩略图，上传进度内联显示（进度环 + 取消），预览按钮打开内置的大图查看器。
+
+> 5.1.0 重命名：`ImageFilesField` → `ImageEditor`，引入路径 `@ticatec/uniface-element/ImageFiles` → `@ticatec/uniface-element/ImageEditor`（不保留兼容别名）。
+
+## 特性
+
+- **缩略图瓦片**（`thumbnail ?? uri`），自动换行；`layout="list"` 每行一张、带小缩略图。
+- **拖放上传**：字段内任意位置；`accept` 默认 `image/*`。
+- **上传中显示本地预览**（object URL）叠加进度环；可取消 / 重试 / 移除。
+- **内置预览**：眼睛按钮打开全屏查看器（可缩放）；`onPreview` 可替换为自定义预览，`previewable={false}` 关闭。
+- **限制与通知**与 AttachmentEditor 完全相同：`maxSize`、`maxFiles`、`multiple`、`onFileRejected`、`onUploadError`、`beforeRemove`、`onremove`、`onchange`。
+- **只读 / 禁用**：预览和下载保留，删除和上传入口消失。
+
+## 引入
+
+```typescript
+import ImageEditor from "@ticatec/uniface-element/ImageEditor";
+import type {ImageFile, FileUpload} from "@ticatec/uniface-element/ImageEditor";
+```
+
+## 基本用法
+
+```svelte
+<script lang="ts">
+  import ImageEditor from "@ticatec/uniface-element/ImageEditor";
+  import type {ImageFile, FileUpload} from "@ticatec/uniface-element/ImageEditor";
+
+  let files = $state<ImageFile[]>([]);
+
+  const uploadFile: FileUpload = (file, progressUpdate, onUploaded, onError) => {
+    const xhr = new XMLHttpRequest();
+    xhr.upload.onprogress = (e) => progressUpdate(e.loaded);
+    xhr.onload = () => {
+      const res = JSON.parse(xhr.responseText);      // {url, thumbnail}
+      xhr.status < 300 ? onUploaded(res.url, res.thumbnail) : onError(new Error(xhr.statusText));
+    };
+    xhr.onerror = () => onError(new Error('网络错误'));
+    const body = new FormData();
+    body.append('file', file);
+    xhr.open('POST', '/api/images');
+    xhr.send(body);
+    return {cancel: async () => { xhr.abort(); return true; }};
+  };
+</script>
+
+<ImageEditor bind:files {uploadFile} maxFiles={6} height={140}/>
+```
+
+## 属性（Props）
+
+继承自 `CommonFieldProps` 的属性（`variant`、`compact`、`disabled`、`readonly`、`theme`、`tooltip`、`error`、`style`、`onfocus`、`onblur`）不再重复。除前三行外，其余行为与 AttachmentEditor 完全一致。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `files` | `ImageFile[]`（可绑定） | `[]` | 已上传的图片：`{name, uri, thumbnail?, size?}`。 |
+| `layout` | `'icon' \| 'list'` | `'icon'` | 缩略图瓦片，或每行一张。 |
+| `accept` | `string` | `"image/*"` | 允许的类型。 |
+| `previewable` | `boolean` | `true` | 显示预览按钮；未设置 `onPreview` 时打开内置查看器。 |
+| `onPreview` | `(file: ImageFile) => void` | — | 自定义预览（替代内置查看器）。 |
+| `height` | `number \| string` | — | 内容区高度，超出内部滚动。 |
+| `uploadFile` | `FileUpload` | — | 上传函数。`onUploaded(url, thumbnail?)`：服务端生成了缩略图时通过第二个参数传回。 |
+| `maxSize` / `maxFiles` / `multiple` | | `10 MB` / `10` / `true` | 限制。 |
+| `uploadText` / `emptyText` | `string` | i18n | 上传入口文字 / 空态文字。 |
+| `beforeRemove` | `BeforeRemove<ImageFile>` | — | 否决钩子：返回 `false` 则不删除。 |
+| `onremove` / `ondownload` / `onFileUploaded` / `onFileRejected` / `onUploadError` / `onchange` | | — | 同 AttachmentEditor。 |
+
+## 方法
+
+| 方法 | 说明 |
+|------|------|
+| `openFileDialog()` | 打开系统文件框。 |
+| `focus()` | 把焦点移到字段内第一个控件。 |
+
+## `ImageFile`
+
+```typescript
+interface ImageFile {
+  name: string;
+  uri: string;          // 原图地址，也用于预览 / 下载
+  thumbnail?: string;   // 可选；缺省用 uri
+  size?: number;        // 字节，可选
+}
+```
+
+## 相关组件
+
+- [AttachmentEditor](../attachment_files/README_CN.md)：通用文件版本。

package/dist/form/image_editor/index.d.ts

@@ -0,0 +1,11 @@
+import ImageEditor from "./ImageEditor.svelte";
+import ImagePreview from "./ImagePreview.svelte";
+import type ImageFile from "./ImageFile";
+import type { AttachmentLayout, UploadedFile } from "../attachment_files/AttachmentFile";
+import type { RejectReason, UploadStatus, UploadTask } from "../attachment_files/UploadTask";
+import type { OnError, FileUpload, OnUploaded, ProgressUpdate, UploadProgress } from "../attachment_files/FileUpload";
+export default ImageEditor;
+export { ImagePreview };
+export type { ImageFile, UploadedFile, AttachmentLayout, RejectReason, UploadStatus, UploadTask };
+export type { BeforeRemove } from "../types";
+export type { OnError, FileUpload, OnUploaded, ProgressUpdate, UploadProgress };

package/dist/form/image_editor/index.js

@@ -0,0 +1,4 @@
+import ImageEditor from "./ImageEditor.svelte";
+import ImagePreview from "./ImagePreview.svelte";
+export default ImageEditor;
+export { ImagePreview };