@ticatec/uniface-element 5.0.5 → 5.1.1

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

@@ -0,0 +1,262 @@
+# ImageEditor
+
+表单组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+图片上传字段：与 AttachmentEditor 同一套实现，瓦片显示缩略图、内置大图预览。
+
+## 适用场景
+
+- 头像、商品图和现场照片
+- 需要图片预览及多图上传管理
+
+## 导入
+
+```ts
+import ImageEditor from '@ticatec/uniface-element/ImageEditor';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `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` | 是 | `(files: ImageFile[]) => void` | 否 | `undefined` | 否 | files 变化后通知（上传完成或删除） |
+| `files` | 是 | `ImageFile[]` | 否 | `$bindable<ImageFile[]>([])` | 是 | 已上传的图片列表（可绑定） |
+| `layout` | 否 | `AttachmentLayout` | 否 | `'icon'` | 否 | 排列方式：icon（缩略图瓦片，自动换行，默认）/ list（每行一张） |
+| `height` | 否 | `number \| string` | 否 | `undefined` | 否 | 内容区高度；超出后内部滚动，不设则随内容自适应 |
+| `uploadFile` | 否 | `FileUpload` | 否 | `undefined` | 否 | 实际执行上传的函数；不传则只展示（不显示上传入口）。onUploaded 的第二个参数可传缩略图地址 |
+| `accept` | 否 | `string` | 否 | `"image/*"` | 否 | 允许的文件类型（同 input accept） |
+| `maxSize` | 否 | `number` | 否 | `1024 * 1024 * 10` | 否 | 单个文件大小上限（字节） |
+| `maxFiles` | 否 | `number` | 否 | `10` | 否 | 图片数量上限（含上传中的） |
+| `multiple` | 否 | `boolean` | 否 | `true` | 否 | 一次是否允许选择 / 拖入多张 |
+| `uploadText` | 否 | `string` | 否 | `undefined` | 否 | 上传入口的文字（空态时作为拖放区提示） |
+| `emptyText` | 否 | `string` | 否 | `undefined` | 否 | 没有图片且不能上传时显示的文字 |
+| `previewable` | 否 | `boolean` | 否 | `true` | 否 | 是否可预览：显示预览按钮，点击打开内置的大图预览 |
+| `onPreview` | 否 | `(file: ImageFile) => void` | 否 | `undefined` | 否 | 自定义预览；传了则不再打开内置预览 |
+| `beforeRemove` | 是 | `BeforeRemove<ImageFile>` | 否 | `undefined` | 否 | 删除图片前的否决钩子：返回 false 取消删除 |
+| `onremove` | 是 | `(file: ImageFile) => void` | 否 | `undefined` | 否 | 图片被删除后通知 |
+| `ondownload` | 否 | `(file: ImageFile) => void` | 否 | `undefined` | 否 | 自定义下载；不传则通过 `file.uri` 直接下载 |
+| `onFileUploaded` | 否 | `(file: ImageFile, source: File) => void` | 否 | `undefined` | 否 | 单张图片上传完成并加入 files 后通知 |
+| `onFileRejected` | 否 | `(file: File, reason: RejectReason) => void` | 否 | `undefined` | 否 | 文件因类型 / 大小 / 数量限制被拒绝时通知 |
+| `onUploadError` | 否 | `(file: File, error: Error) => void` | 否 | `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`
+
+files 变化后通知（上传完成或删除）
+
+- 类型：`(files: ImageFile[]) => void`
+- 默认值：`undefined`
+- 示例写法：`onchange={async (...args: any[]) => { console.log('onchange', ...args); return true; }}`
+
+### `files`
+
+已上传的图片列表（可绑定）
+
+- 类型：`ImageFile[]`
+- 默认值：`$bindable<ImageFile[]>([])`
+- 推荐写法：`bind:files`
+
+### `beforeRemove`
+
+删除图片前的否决钩子：返回 false 取消删除
+
+- 类型：`BeforeRemove<ImageFile>`
+- 默认值：`undefined`
+- 示例写法：参见下方完整示例中的类型化实现。
+
+### `onremove`
+
+图片被删除后通知
+
+- 类型：`(file: ImageFile) => void`
+- 默认值：`undefined`
+- 示例写法：`onremove={async (...args: any[]) => { console.log('onremove', ...args); return true; }}`
+
+## 组件实例方法
+
+通过 `bind:this` 获取组件实例后调用。
+
+| 方法 | 类型 | 说明 |
+| --- | --- | --- |
+| `openFileDialog()` | `() => void` | 打开系统文件选择框（等同于点击上传入口） |
+| `focus()` | `() => void` | 组件实例方法。 |
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `EditorVariant`
+
+```ts
+export type EditorVariant = '' | 'plain' | 'outlined' | 'filled';
+```
+
+### `ImageFile`
+
+```ts
+export default interface ImageFile extends UploadedFile {
+
+    /**
+     * 缩略图地址，可选；缺省时直接用 uri 显示
+     */
+    thumbnail?: string | null;
+}
+```
+
+### `AttachmentLayout`
+
+```ts
+export type AttachmentLayout = 'list' | 'icon';
+```
+
+### `FileUpload`
+
+```ts
+export type FileUpload = (file: File, progressUpdate: ProgressUpdate, onUploaded: OnUploaded, errorHandler: OnError) => UploadProgress;
+```
+
+### `BeforeRemove`
+
+```ts
+export type BeforeRemove<T = any> = (file: T) => boolean | void | Promise<boolean | void>;
+```
+
+### `RejectReason`
+
+```ts
+export type RejectReason = 'accept' | 'size' | 'count';
+```
+
+### `UploadedFile`
+
+```ts
+export interface UploadedFile {
+
+    /**
+     * 文件名
+     */
+    name: string;
+
+    /**
+     * 存储地址（oss 路径 / URL）
+     */
+    uri: string;
+
+    /**
+     * 文件大小（字节），可选；上传完成后由组件写入
+     */
+    size?: number;
+
+    /**
+     * 缩略图地址，可选；有则在瓦片 / 列表里代替类型图标显示
+     */
+    thumbnail?: string | null;
+}
+```
+
+### `ProgressUpdate`
+
+```ts
+export type ProgressUpdate = (uploadBytes: number) => void;
+```
+
+### `OnUploaded`
+
+```ts
+export type OnUploaded = (url: string, thumbnail?: string) => void;
+```
+
+### `OnError`
+
+```ts
+export type OnError = (e: Error) => void;
+```
+
+### `UploadProgress`
+
+```ts
+export interface UploadProgress {
+
+    cancel:()=>Promise<boolean>;
+
+}
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import ImageEditor, {type FileUpload, type ImageFile} from '@ticatec/uniface-element/ImageEditor';
+
+  let files = $state<ImageFile[]>([]);
+  const uploadFile: FileUpload = (file, progress, uploaded) => {
+    progress(file.size);
+    uploaded(URL.createObjectURL(file));
+    return {cancel: async () => true};
+  };
+</script>
+
+<ImageEditor
+  bind:files
+  {uploadFile}
+  height={140}
+  maxFiles={5}
+  variant="outlined"
+  beforeRemove={async (file) => confirm(`确定删除 ${file.name}？`)}
+  onPreview={(file) => console.log('预览', file.uri)}
+/>
+<p>已上传 {files.length} 张图片</p>
+```
+
+## 源码
+
+- `src/lib/form/image_editor/ImageEditor.svelte`

package/docs/components/{image-files → image-editor}/example.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-  import ImageFiles, {type FileUpload, type ImageFile} from '@ticatec/uniface-element/ImageFiles';
+  import ImageEditor, {type FileUpload, type ImageFile} from '@ticatec/uniface-element/ImageEditor';
 
   let files = $state<ImageFile[]>([]);
   const uploadFile: FileUpload = (file, progress, uploaded) => {
@@ -9,11 +9,13 @@
   };
 </script>
 
-<ImageFiles
+<ImageEditor
   bind:files
   {uploadFile}
+  height={140}
   maxFiles={5}
   variant="outlined"
-  removeFileConfirm={async (file) => confirm(`确定删除 ${file.name}？`)}
+  beforeRemove={async (file) => confirm(`确定删除 ${file.name}？`)}
+  onPreview={(file) => console.log('预览', file.uri)}
 />
 <p>已上传 {files.length} 张图片</p>

package/docs/components/input-options-select/README.md

@@ -33,13 +33,13 @@ import InputOptionsSelect from '@ticatec/uniface-element/InputOptionsSelect';
 | `onfocus` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 字段获得焦点时触发的回调 |
 | `onblur` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 字段失去焦点时触发的回调 |
 | `onchange` | 是 | `(value?: any) => void` | 否 | `undefined` | 否 | 字段值发生变化时触发的回调 |
-| `mandatory` | 否 | `boolean` | 否 | `false` | 否 | 是否为必填字段，必填时字段值不能为空 |
+| `clearable` | 否 | `boolean` | 否 | `undefined` | 否 | 是否允许清空（显示清空按钮），默认 true |
 | `text` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
 | `value` | 是 | `any` | 否 | `$bindable()` | 是 | 组件的核心值。支持绑定时建议使用 `bind:value`，外部修改会同步到组件。 |
 | `keyField` | 否 | `string` | 否 | `'code'` | 否 | 数据项中作为唯一值或选中值的字段名。 |
 | `textField` | 否 | `string` | 否 | `"text"` | 否 | 数据项中用于界面显示的文本字段名。 |
 | `retrieveText` | 否 | `RetrieveOptionText` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
-| `displayCode` | 否 | `boolean` | 否 | `false` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `showCode` | 否 | `boolean` | 否 | `false` | 否 | 是否显示选项 code |
 | `menu$height` | 否 | `number` | 否 | `0` | 否 | 高度配置，数值单位为像素。 |
 | `itemRender` | 否 | `any` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
 | `lazyLoader` | 是 | `ListLazyLoader` | 否 | `undefined` | 否 | 异步分页加载器，签名为 `(filterText, pageNo) => Promise<{list, hasMore}>`。ListBox 当前从第 1 页开始请求，滚动到底部且 `hasMore=true` 时继续加载。 |

package/docs/components/list-box/README.md

@@ -22,18 +22,17 @@ import ListBox from '@ticatec/uniface-element/ListBox';
 | 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
 | --- | --- | --- | --- | --- | --- | --- |
 | `readonly` | 是 | `boolean` | 否 | `false` | 否 | 只读状态。保留内容展示，但阻止用户修改。 |
-| `style` | 否 | `string \| null` | 否 | `undefined` | 否 | 附加到组件根元素的内联样式。 |
+| `style` | 否 | `string` | 否 | `undefined` | 否 | 附加到组件根元素的内联样式。 |
 | `list` | 是 | `Array<any>` | 否 | `undefined` | 否 | 组件展示的数据集合。数据项结构由相关列、字段映射或渲染器决定。 |
 | `itemRender` | 否 | `any` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
 | `selectMode` | 是 | `'none' \| 'single' \| 'multiple'` | 否 | `'none'` | 否 | 选择模式：none 只响应普通点击，single 单选，multiple 多选。 |
-| `filter` | 是 | `FunFilter \| null` | 否 | `undefined` | 否 | 本地过滤函数。接收当前数据项和搜索文字，返回 true 时保留该项。仅用于已经加载到内存中的 list。 |
+| `filter` | 是 | `FilterFn \| null` | 否 | `undefined` | 否 | 本地过滤函数。接收当前数据项和搜索文字，返回 true 时保留该项。仅用于已经加载到内存中的 list。 |
 | `lazyLoader` | 是 | `ListLazyLoader \| null` | 否 | `undefined` | 否 | 异步分页加载器，签名为 `(filterText, pageNo) => Promise<{list, hasMore}>`。ListBox 当前从第 1 页开始请求，滚动到底部且 `hasMore=true` 时继续加载。 |
 | `selectedItem` | 是 | `any` | 否 | `undefined` | 否 | 单选模式下的当前选中项；选中变化通过 `onSelectChange` 返回。 |
-| `selectedList` | 是 | `Array<any>` | 否 | `$bindable([])` | 是 | 多选模式下的选中项数组，推荐使用 `bind:selectedList`。 |
+| `selectedItems` | 是 | `Array<any>` | 否 | `$bindable([])` | 是 | 多选模式下的已选项 |
 | `class` | 否 | `string` | 否 | `undefined` | 否 | 附加到组件根元素的 CSS class。 |
 | `item$props` | 否 | `any` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
 | `onchange` | 是 | `OnSelectChange` | 否 | `undefined` | 否 | 用户完成值变更时调用；编程式赋值是否触发请以组件行为说明为准。 |
-| `onSelectChange` | 否 | `OnSelectChange` | 否 | `undefined` | 否 | @deprecated 请使用 onchange；仍受支持以兼容旧调用。 |
 | `onItemDblClick` | 否 | `OnItemDblClick` | 否 | `undefined` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
 | `onItemClick` | 否 | `OnItemClick` | 否 | `undefined` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
 | `title` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
@@ -78,7 +77,7 @@ import ListBox from '@ticatec/uniface-element/ListBox';
 
 本地过滤函数。接收当前数据项和搜索文字，返回 true 时保留该项。仅用于已经加载到内存中的 list。
 
-- 类型：`FunFilter | null`
+- 类型：`FilterFn | null`
 - 默认值：`undefined`
 - 示例写法：参见下方完整示例中的类型化实现。
 
@@ -98,13 +97,13 @@ import ListBox from '@ticatec/uniface-element/ListBox';
 - 默认值：`undefined`
 - 示例写法：参见下方完整示例中的类型化实现。
 
-### `selectedList`
+### `selectedItems`
 
-多选模式下的选中项数组，推荐使用 `bind:selectedList`。
+多选模式下的已选项
 
 - 类型：`Array<any>`
 - 默认值：`$bindable([])`
-- 推荐写法：`bind:selectedList`
+- 推荐写法：`bind:selectedItems`
 
 ### `onchange`
 
@@ -126,10 +125,10 @@ import ListBox from '@ticatec/uniface-element/ListBox';
 
 以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
 
-### `FunFilter`
+### `FilterFn`
 
 ```ts
-export type FunFilter = (item: any, text: string) => boolean;
+export type FilterFn = (item: any, text: string) => boolean;
 ```
 
 ### `ListLazyLoader`
@@ -193,7 +192,7 @@ export interface LoadResult {
   filter={filterUser}
   filterText="研发"
   title="员工列表"
-  onSelectChange={(user) => selectedUser = user}
+  onchange={(user) => selectedUser = user}
 />
 <p>当前选中：{selectedUser?.name ?? '无'}</p>
 
@@ -202,7 +201,7 @@ export interface LoadResult {
   list={users}
   itemRender={ListItem}
   selectMode="multiple"
-  bind:selectedList={selectedUsers}
+  bind:selectedItems={selectedUsers}
 />
 <p>已选择：{selectedUsers.map((user) => user.name).join('、') || '无'}</p>
 
@@ -212,7 +211,7 @@ export interface LoadResult {
   selectMode="single"
   {lazyLoader}
   title="滚动到底部自动加载下一页"
-  onSelectChange={(user) => console.log('lazy selected', user)}
+  onchange={(user) => console.log('lazy selected', user)}
 />
 ```
 

package/docs/components/list-box/example.svelte

@@ -38,7 +38,7 @@
   filter={filterUser}
   filterText="研发"
   title="员工列表"
-  onSelectChange={(user) => selectedUser = user}
+  onchange={(user) => selectedUser = user}
 />
 <p>当前选中：{selectedUser?.name ?? '无'}</p>
 
@@ -47,7 +47,7 @@
   list={users}
   itemRender={ListItem}
   selectMode="multiple"
-  bind:selectedList={selectedUsers}
+  bind:selectedItems={selectedUsers}
 />
 <p>已选择：{selectedUsers.map((user) => user.name).join('、') || '无'}</p>
 
@@ -57,5 +57,5 @@
   selectMode="single"
   {lazyLoader}
   title="滚动到底部自动加载下一页"
-  onSelectChange={(user) => console.log('lazy selected', user)}
+  onchange={(user) => console.log('lazy selected', user)}
 />

package/docs/components/lookup-editor/README.md

@@ -33,7 +33,7 @@ import LookupEditor from '@ticatec/uniface-element/LookupEditor';
 | `onfocus` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 字段获得焦点时触发的回调 |
 | `onblur` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 字段失去焦点时触发的回调 |
 | `onchange` | 是 | `(value?: any) => void` | 否 | `undefined` | 否 | 字段值发生变化时触发的回调 |
-| `mandatory` | 否 | `boolean` | 否 | `false` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `clearable` | 否 | `boolean` | 否 | `true` | 否 | 是否允许清空（显示清空按钮），默认 true |
 | `value` | 是 | `any` | 否 | `$bindable()` | 是 | 组件的核心值。支持绑定时建议使用 `bind:value`，外部修改会同步到组件。 |
 | `text` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
 | `onaction` | 否 | `() => void` | 否 | `undefined` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |

package/docs/components/navigator/README.md

@@ -25,7 +25,7 @@ import Navigator from '@ticatec/uniface-element/Navigator';
 | `activeItem` | 是 | `any` | 否 | `$bindable()` | 是 | 可选配置，具体取值范围和数据结构见类型列。 |
 | `style` | 否 | `string` | 否 | `""` | 否 | 附加到组件根元素的内联样式。 |
 | `highlights` | 否 | `Array<any>` | 否 | `[]` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
-| `itemClickHandler` | 否 | `ItemClickHandler` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `onItemClick` | 否 | `OnItemClick` | 否 | `undefined` | 否 | 项点击回调 |
 | `retrieveStatus` | 否 | `RetrieveItemStatus` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
 
 > 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
@@ -66,6 +66,7 @@ import Navigator from '@ticatec/uniface-element/Navigator';
     {label: '用户管理', data: {path: '/users'}}
   ]}
   bind:activeItem
+  onItemClick={async (...args: any[]) => { console.log('onItemClick', ...args); return true; }}
 />
 <p>当前状态：{JSON.stringify({activeItem})}</p>
 ```

package/docs/components/navigator/example.svelte

@@ -9,5 +9,6 @@
     {label: '用户管理', data: {path: '/users'}}
   ]}
   bind:activeItem
+  onItemClick={async (...args: any[]) => { console.log('onItemClick', ...args); return true; }}
 />
 <p>当前状态：{JSON.stringify({activeItem})}</p>

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

@@ -21,24 +21,27 @@ import NavigatorMenu from '@ticatec/uniface-element/NavigatorMenu';
 
 | 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
 | --- | --- | --- | --- | --- | --- | --- |
-| `menuItems` | 是 | `Array<MenuNode>` | 是 | `—` | 否 | 菜单层级数据集合；每一项可包含子菜单，结构由 `textField` 与子项字段共同决定。 |
+| `items` | 是 | `Array<MenuNode>` | 否 | `[]` | 否 | 菜单节点列表 |
 | `style` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的内联样式。 |
 | `textField` | 是 | `string \| GetText<MenuItem>` | 是 | `—` | 否 | 数据项中用于界面显示的文本字段名。 |
-| `onItemClick` | 是 | `OnMenuClick` | 是 | `—` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
-| `variant` | 是 | `Variant` | 否 | `'vertical'` | 否 | 视觉样式变体，可选值：`vertical`、`horizontal`；具体含义见组件说明。 |
-| `theme` | 否 | `string` | 否 | `''` | 否 | 组件主题标识，通常通过 `data-theme` 选择对应 CSS 变量。 |
+| `onItemClick` | 是 | `OnMenuItemClick` | 是 | `—` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
+| `direction` | 否 | `Direction` | 否 | `'vertical'` | 否 | 菜单方向 |
+| `theme` | 否 | `string` | 否 | `undefined` | 否 | 组件主题标识，通常通过 `data-theme` 选择对应 CSS 变量。 |
 
 > 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
 
 ## 重要属性说明
 
-### `menuItems`
+### `items`
 
-菜单层级数据集合；每一项可包含子菜单，结构由 `textField` 与子项字段共同决定。
+菜单节点列表
 
 - 类型：`Array<MenuNode>`
-- 默认值：`—`
-- 示例写法：`menuItems={[]}`
+- 默认值：`[]`
+- 示例写法：`items={[
+    {item: {text: '首页', path: '/'}},
+    {item: {text: '用户管理', path: '/users'}}
+  ]}`
 
 ### `textField`
 
@@ -52,18 +55,10 @@ import NavigatorMenu from '@ticatec/uniface-element/NavigatorMenu';
 
 事件或行为回调；参数与返回值以类型签名为准。
 
-- 类型：`OnMenuClick`
+- 类型：`OnMenuItemClick`
 - 默认值：`—`
 - 示例写法：`onItemClick={async (...args: any[]) => { console.log('onItemClick', ...args); return true; }}`
 
-### `variant`
-
-视觉样式变体，可选值：`vertical`、`horizontal`；具体含义见组件说明。
-
-- 类型：`Variant`
-- 默认值：`'vertical'`
-- 示例写法：`variant="vertical"`
-
 ## 相关类型定义
 
 以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
@@ -86,10 +81,16 @@ export default interface MenuItem {
 }
 ```
 
-### `OnMenuClick`
+### `OnMenuItemClick`
+
+```ts
+export type OnMenuItemClick = (item: MenuItem) => void;
+```
+
+### `Direction`
 
 ```ts
-export type OnMenuClick = (item: MenuItem) => void;
+export type Direction = 'vertical' | 'horizontal';
 ```
 
 ## 示例
@@ -101,10 +102,12 @@ export type OnMenuClick = (item: MenuItem) => void;
 </script>
 
 <NavigatorMenu
-  menuItems={[]}
   textField="text"
   onItemClick={async (...args: any[]) => { console.log('onItemClick', ...args); return true; }}
-  variant="vertical"
+  items={[
+    {item: {text: '首页', path: '/'}},
+    {item: {text: '用户管理', path: '/users'}}
+  ]}
 />
 ```
 

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

@@ -3,8 +3,10 @@
 </script>
 
 <NavigatorMenu
-  menuItems={[]}
   textField="text"
   onItemClick={async (...args: any[]) => { console.log('onItemClick', ...args); return true; }}
-  variant="vertical"
+  items={[
+    {item: {text: '首页', path: '/'}},
+    {item: {text: '用户管理', path: '/users'}}
+  ]}
 />

package/docs/components/options-multi-select/README.md

@@ -33,7 +33,7 @@ import OptionsMultiSelect from '@ticatec/uniface-element/OptionsMultiSelect';
 | `onfocus` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 字段获得焦点时触发的回调 |
 | `onblur` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 字段失去焦点时触发的回调 |
 | `onchange` | 是 | `(value?: any) => void` | 否 | `undefined` | 否 | 字段值发生变化时触发的回调 |
-| `mandatory` | 否 | `boolean` | 否 | `false` | 否 | 是否为必填字段，必填时字段值不能为空 |
+| `clearable` | 否 | `boolean` | 否 | `undefined` | 否 | 是否允许清空（显示清空按钮），默认 true |
 | `onkeydown` | 否 | `(event: KeyboardEvent) => void` | 否 | `undefined` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
 | `onkeyup` | 否 | `(event: KeyboardEvent) => void` | 否 | `undefined` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
 | `onkeypress` | 否 | `(event: KeyboardEvent) => void` | 否 | `undefined` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
@@ -44,7 +44,7 @@ import OptionsMultiSelect from '@ticatec/uniface-element/OptionsMultiSelect';
 | `keyField` | 否 | `string` | 否 | `"code"` | 否 | 数据项中作为唯一值或选中值的字段名。 |
 | `textField` | 否 | `string` | 否 | `"text"` | 否 | 数据项中用于界面显示的文本字段名。 |
 | `emptyText` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
-| `disableOptions` | 否 | `Array<string>` | 否 | `[]` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `disabledOptions` | 否 | `Array<string>` | 否 | `[]` | 否 | 要渲染但禁用的选项 key 列表 |
 | `hideOptions` | 否 | `Array<string>` | 否 | `[]` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
 | `tagColor` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
 | `tagVariant` | 否 | `'borderless' \| 'border' \| 'round'` | 否 | `'border'` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |

package/docs/components/options-select/README.md

@@ -33,19 +33,19 @@ import OptionsSelect from '@ticatec/uniface-element/OptionsSelect';
 | `onfocus` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 字段获得焦点时触发的回调 |
 | `onblur` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 字段失去焦点时触发的回调 |
 | `onchange` | 是 | `(value?: any) => void` | 否 | `undefined` | 否 | 字段值发生变化时触发的回调 |
-| `mandatory` | 否 | `boolean` | 否 | `false` | 否 | 是否为必填字段，必填时字段值不能为空 |
+| `clearable` | 否 | `boolean` | 否 | `undefined` | 否 | 是否允许清空（显示清空按钮），默认 true |
 | `emptyText` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
 | `value` | 是 | `any` | 是 | `$bindable()` | 是 | 组件的核心值。支持绑定时建议使用 `bind:value`，外部修改会同步到组件。 |
 | `options` | 是 | `Array<Option>` | 是 | `—` | 否 | 可选项数据源；通常配合 `keyField` 与 `textField` 指定值字段和显示字段。 |
 | `keyField` | 否 | `string` | 否 | `"code"` | 否 | 数据项中作为唯一值或选中值的字段名。 |
 | `textField` | 否 | `string` | 否 | `"text"` | 否 | 数据项中用于界面显示的文本字段名。 |
 | `menu$height` | 否 | `number` | 否 | `0` | 否 | 高度配置，数值单位为像素。 |
-| `disableOptions` | 否 | `Array<string>` | 否 | `[]` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `disabledOptions` | 否 | `Array<string>` | 否 | `[]` | 否 | 要渲染但禁用的选项 key 列表 |
 | `hideOptions` | 否 | `Array<string>` | 否 | `[]` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
 | `itemRender` | 否 | `any` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
-| `filterPlaceholder` | 否 | `string` | 否 | `i18nRes.common.filterPlaceholder.toString()` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `filterPlaceholder` | 否 | `string` | 否 | `i18nRes.common.filterPlaceholder()` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
 | `filterFunction` | 否 | `(option: Option, keyword: string) => boolean` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
-| `noResultsText` | 否 | `string` | 否 | `i18nRes.common.noResultsText.toString()` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `noResultsText` | 否 | `string` | 否 | `i18nRes.common.noResultsText()` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
 
 > 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
 

package/docs/components/page/README.md

@@ -30,8 +30,8 @@ import Page from '@ticatec/uniface-element/Page';
 | `reload` | 否 | `PageAction` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
 | `style` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的内联样式。 |
 | `theme` | 否 | `string` | 否 | `undefined` | 否 | 组件主题标识，通常通过 `data-theme` 选择对应 CSS 变量。 |
-| `pageHeader` | 否 | `Snippet<[string, string?, PageAction?, PageAction?]>` | 否 | `undefined` | 否 | Svelte Snippet 渲染入口，用于替换或补充默认内容。 |
-| `headerExt` | 否 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 渲染入口，用于替换或补充默认内容。 |
+| `header` | 否 | `Snippet<[string, string?, PageAction?, PageAction?]>` | 否 | `undefined` | 否 | Svelte Snippet 渲染入口，用于替换或补充默认内容。 |
+| `headerExtra` | 否 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 渲染入口，用于替换或补充默认内容。 |
 | `children` | 是 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 子内容，用于自定义组件主体。 |
 
 > 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。