@ticatec/uniface-element 5.0.4 → 5.1.0

package/dist/form/input_options_select/README_CN.md

@@ -1,246 +1,73 @@
 # InputOptionsSelect
 
-带可展开选项列表的文本输入组件。与纯 `OptionsSelect` 下拉框不同，这个组件从普通文本输入开始 —— 输入内容时会实时过滤选项，匹配的选项在下方面板中展开。适合用户经常输入部分值而非浏览的场景。
+> **5.1.0 重命名**：本文使用 [API 命名规范](../../../docs/NAMING_CN.md) 中的名字；旧名 `mandatory` 已在 5.1.0 移除（5.1.0 不保留兼容别名）。
 
-> 可以理解为 `<input>` 和 `<select>` 之间的桥梁。输入过滤，点击选中。
+可输入的远程检索选择器：用户在输入框里键入关键字，组件通过 `lazyLoader` 分页拉取候选项并在下方面板展示，点击某一项后把它的 key 写入 `value`。适合候选数据量大、必须走服务端检索的场景（客户、产品、地址快速定位）。
+
+> 与 `OptionsSelect` 的区别：`OptionsSelect` 接收完整的 `options` 数组做本地筛选；`InputOptionsSelect` **没有** `options` 属性，所有候选都来自 `lazyLoader`。
 
 ## 特性
 
-- **文本输入 + 下拉** —— 输入时实时过滤选项；下拉面板显示匹配的选项。
-- **单选** —— 点击选项选中该项并关闭下拉。
-- **`value` 是选项的 key** —— 绑定到你指定的 `keyField`。
-- **自定义字段映射** —— `keyField` / `textField` 定义选项对象的映射方式。
-- **自定义选项文本检索** —— 传 `retrieveOptionText` 可格式化或转换下拉中显示的文本。
-- **隐藏 / 禁用单个选项** —— `hideOptions` / `disableOptions`。
-- **快速过滤** —— `filterFunction` 控制过滤逻辑。
-- **必填模式** —— 隐藏清空按钮，用户无法把字段清空。
-- **紧凑模式** —— 适用于表格单元格和密集表单。
-- **禁用 / 只读** —— 下拉被抑制，渲染普通输入框。
-- **共享的 form-editor 属性** —— `variant`、`style`、`error`、`tooltip`、`theme`、`placeholder`、`onfocus` / `onblur` / `onchange`。
-- **键盘导航** —— 方向键移动选中、Enter 确认、Escape 关闭、下拉打开时 Tab 被锁住。
-
-## 安装
-
-```bash
-npm install @ticatec/uniface-element
-```
+- **输入即检索**：停止输入 200ms 后调用 `lazyLoader(text, 1)`；继续输入会中止上一次未完成的请求。
+- **滚动分页**：面板滚到底部时调用 `lazyLoader(text, pageNo + 1)`，直到返回 `hasMore: false`。
+- **`value` 是选项的 key**：由 `keyField` 决定；显示文本由 `textField` 或 `retrieveText` 决定。
+- **自定义项渲染**：`itemRender` 传入一个接收 `item` 的 Svelte 组件。
+- **不可清空模式**：`clearable={false}` 隐藏清空按钮。
+- **共享的表单字段属性**：继承 `CommonPickerProps`（`variant`、`compact`、`disabled`、`readonly`、`style`、`error`、`tooltip`、`theme`、`placeholder`、`onfocus` / `onblur` / `onchange`）。
 
 ## 引入
 
 ```typescript
 import InputOptionsSelect from "@ticatec/uniface-element/InputOptionsSelect";
+import type {ListLazyLoader} from "@ticatec/uniface-element/types";
 ```
 
-## 基础用法
+## 基本用法
 
 ```svelte
 <script lang="ts">
   import InputOptionsSelect from "@ticatec/uniface-element/InputOptionsSelect";
+  import type {ListLazyLoader} from "@ticatec/uniface-element/types";
 
   let value = $state<string | null>(null);
+  let text = $state('');
 
-  const options = [
-    { code: "JS", text: "JavaScript" },
-    { code: "TS", text: "TypeScript" },
-    { code: "PY", text: "Python" },
-    { code: "GO", text: "Go" }
-  ];
+  const loadCustomers: ListLazyLoader = async (keyword, pageNo) => {
+    const res = await fetch(`/api/customers?q=${encodeURIComponent(keyword)}&page=${pageNo}`);
+    const data = await res.json();          // { list: [...], hasMore: boolean }
+    return {list: data.list, hasMore: data.hasMore};
+  };
 </script>
 
-<InputOptionsSelect {options} bind:value placeholder="输入搜索..." />
+<InputOptionsSelect bind:value {text} lazyLoader={loadCustomers} placeholder="输入客户名称检索"
+                    onchange={(item) => text = item?.text ?? ''}/>
 ```
 
 ## 属性（Props）
 
-`InputOptionsSelect` 继承自 `CommonFieldProps`，因此自动获得 `variant`、`compact`、`disabled`、`readonly`、`style`、`error`、`tooltip`、`theme`、`placeholder`、`onfocus` / `onblur` / `onchange`。
+继承 `CommonPickerProps` 的属性不再重复列出。
 
 | 属性 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `value` | `any`（可绑定） | — | 选中项的 key。`bind:value={...}` 双向同步；外部修改会更新显示文本。 |
-| `options` | `Array<any>` | — | 完整的选项对象数组。 |
-| `keyField` | `string` | `"code"` | 作为选项身份的字段。 |
-| `textField` | `string` | `"text"` | 显示用的字段。 |
-| `placeholder` | `string` | — | `value` 为空时输入框的占位文字。 |
-| `emptyText` | `string` | — | 当 `value` 找不到对应选项时显示的文本。 |
-| `disableOptions` | `Array<string>` | `[]` | 要渲染但禁用（变灰）的选项 key。 |
-| `hideOptions` | `Array<string>` | `[]` | 完全不渲染的选项 key。 |
-| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | 视觉风格。 |
-| `compact` | `boolean` | `false` | 紧凑布局。 |
-| `disabled` | `boolean` | `false` | 完全禁用 —— 普通输入框，无下拉。 |
-| `readonly` | `boolean` | `false` | 只读 —— 视觉同 disabled，语义是"查看，不可编辑"。 |
-| `mandatory` | `boolean` | `false` | 隐藏清空（×）按钮。 |
-| `style` | `string` | — | 编辑器根节点的内联 CSS。 |
-| `error` | `string` | — | 校验错误文本，触发编辑器的 error 状态。 |
-| `tooltip` | `string` | — | 编辑器的 hover tooltip。 |
-| `theme` | `string` | — | 渲染为下拉根的 `data-theme`，用于作用域样式覆盖。 |
-| `itemRender` | `{ component: any; props?: Record<string, any> } \| undefined` | — | 自定义每项渲染的 Svelte 组件。子组件接收 `item`、`disabled`、`onclick`。 |
-| `filterFunction` | `((option: any, keyword: string) => boolean) \| undefined` | — | 过滤函数。传入后，输入时会按每个选项调用。 |
-| `noResultsText` | `string` | `"No results found"` | 过滤后列表为空时显示的文本。 |
-| `retrieveOptionText` | `(option: any) => string \| null \| undefined` | — | 可选的文本转换函数。接收选项对象，返回要显示的文本。返回 `undefined` 时使用 `textField` 的原始值。 |
-| `onchange` | `(value: any) => void` | — | 用户选中时触发**一次**，参数是**完整的选项对象**（不是 key）。父组件编程式修改 `value` 不会触发。 |
-| `onfocus` | `(e: FocusEvent) => void` | — | 输入框获焦。 |
-| `onblur` | `(e: FocusEvent) => void` | — | 输入框失焦。在弹窗关闭且焦点真正离开编辑器后触发。 |
-
-## 事件
-
-| 事件 | 签名 | 说明 |
-|------|------|------|
-| `onchange` | `(value: any) => void` | 用户选中时触发，参数是**完整的选项对象**（不是 key）。 |
-| `onfocus` | `(e: FocusEvent) => void` | 输入框获焦。 |
-| `onblur` | `(e: FocusEvent) => void` | 输入框失焦。在弹窗关闭且焦点真正离开编辑器后触发。 |
-
-## `retrieveOptionText`
-
-这个钩子可以格式化或转换输入框和下拉中显示的文本。它接收完整的选项对象，返回显示字符串。
-
-```svelte
-<script lang="ts">
-  import InputOptionsSelect from "@ticatec/uniface-element/InputOptionsSelect";
-
-  let value = $state<string | null>(null);
-
-  const options = [
-    { code: 1001, text: "张三",   age: 30, department: "工程部" },
-    { code: 1002, text: "李四",   age: 25, department: "市场部" },
-    { code: 1003, text: "王五",   age: 35, department: "工程部" }
-  ];
-
-  // 下拉中显示 "张三 (工程部)"
-  const retrieveOptionText = (option: any) => {
-    return `${option.text} (${option.department})`;
-  };
-</script>
-
-<InputOptionsSelect
-  {options}
-  bind:value
-  retrieveOptionText={retrieveOptionText}
-  placeholder="搜索员工..."
-/>
-```
-
-## `itemRender`
-
-传 `{component, props?}`。子组件接收：
-
-| 属性 | 来源 |
-|------|------|
-| `item` | 当前选项对象。 |
-| `disabled` | 选项 key 在 `disableOptions` 中时为 `true`。 |
-| `onclick` | 内部处理函数 —— 点击时调用它来选中这一项。 |
-| `...props` | 你放在 `itemRender.props` 里的属性都会展开到组件上。 |
-
-## 示例
-
-### 员工搜索，自定义下拉文本格式
-
-```svelte
-<script lang="ts">
-  import InputOptionsSelect from "@ticatec/uniface-element/InputOptionsSelect";
-
-  let value = $state<string | null>(null);
-
-  const employees = [
-    { id: "E001", name: "Alice", dept: "Engineering", email: "alice@example.com" },
-    { id: "E002", name: "Bob",   dept: "Marketing",  email: "bob@example.com" },
-    { id: "E003", name: "Carol", dept: "Engineering", email: "carol@example.com" },
-    { id: "E004", name: "Dave",  dept: "Sales",      email: "dave@example.com" }
-  ];
-
-  // 下拉中显示 "Alice (Engineering)"
-  const retrieveOptionText = (emp: any) => `${emp.name} (${emp.dept})`;
-
-  // 按 name / dept / email 任一字段过滤
-  const filter = (emp: any, keyword: string) =>
-    !keyword || [emp.name, emp.dept, emp.email].some(v =>
-      v.toLowerCase().includes(keyword.toLowerCase())
-    );
-</script>
-
-<InputOptionsSelect
-  {options: employees}
-  keyField="id"
-  textField="name"
-  bind:value={value}
-  retrieveOptionText={retrieveOptionText}
-  filterFunction={filter}
-  placeholder="搜索员工..."
-/>
-```
-
-### 禁用 / 隐藏选项
-
-```svelte
-<script lang="ts">
-  import InputOptionsSelect from "@ticatec/uniface-element/InputOptionsSelect";
-
-  let value = $state<string | null>(null);
-
-  const statuses = [
-    { code: "ACTIVE",    text: "Active" },
-    { code: "SUSPENDED", text: "Suspended" },
-    { code: "BANNED",    text: "Banned" },
-    { code: "DELETED",   text: "Deleted" }
-  ];
-</script>
-
-<InputOptionsSelect
-  {options: statuses}
-  bind:value={value}
-  disableOptions={["BANNED"]}
-  hideOptions={["DELETED"]}
-  placeholder="选择状态"
-/>
-```
-
-### 只读模式
-
-```svelte
-<script lang="ts">
-  import InputOptionsSelect from "@ticatec/uniface-element/InputOptionsSelect";
-
-  let value = $state("E001");
-
-  const options = [
-    { code: "E001", text: "Alice" },
-    { code: "E002", text: "Bob" }
-  ];
-</script>
-
-<InputOptionsSelect
-  {options}
-  bind:value={value}
-  readonly
-/>
-```
+| `value` | `any`（可绑定） | — | 选中项的 key（`item[keyField]`）。用户重新输入时会被置为 `null`。 |
+| `text` | `string` | — | 输入框当前显示的文本。组件在选中项后会更新它；初始化时由调用方传入已选项的显示文本。 |
+| `lazyLoader` | `ListLazyLoader` | — | `(text, pageNo) => Promise<{list, hasMore}>`。**必需**，否则输入不会触发任何检索。 |
+| `keyField` | `string` | `"code"` | 作为 `value` 的字段。 |
+| `textField` | `string` | `"text"` | 默认显示文本字段。 |
+| `retrieveText` | `(item) => string` | — | 自定义显示文本；返回值优先于 `textField`。 |
+| `itemRender` | Svelte 组件 | — | 自定义每一项的渲染，组件接收 `item` 属性。 |
+| `menu$height` | `number` | `0` | 面板固定高度（px）；`0` 表示自适应，最高 300px。 |
+| `clearable` | `boolean` | `true` | 是否显示清空按钮；`false` 时用户不能把值清空。 |
+| `onchange` | `(item: any) => void` | — | 用户点击选中某一项时触发，参数是**完整的选项对象**。清空或重新输入不会触发。 |
 
 ## 行为说明
 
-### 与 OptionsSelect 的区别
-
-| 方面 | InputOptionsSelect | OptionsSelect |
-|------|-------------------|---------------|
-| 输入方式 | `<input>` + 实时过滤 | 点击打开下拉框 |
-| 过滤时机 | 逐字符触发，客户端过滤 | 点击打开后过滤 |
-| 适用场景 | 用户经常输入的场景 | 用户浏览的场景 |
-
-### 只读 / 禁用渲染
-
-两种模式都渲染普通 `<input readonly>`，显示文本。清空按钮、下拉箭头、下拉面板都不渲染。
-
-### `emptyText` 与 `placeholder`
-
-- `placeholder` —— 输入框的原生占位文字，`value` 为空时显示。
-- `emptyText` —— 覆盖显示文本，用于当前 `value` 在 `options` 中找不到对应项的场景。
-
-## 无障碍
-
-- 下拉通过 `Popover`（portal 渲染到 `document.body`）实现，有 scroll/resize 监听。
-- 键盘：方向键移动选中，Enter 确认，Escape 关闭，下拉打开时 Tab 被锁。
-- 完整的 ARIA 需要外层 `<label>` / `FormField` 配合 `error` 文本。
+- 只有输入非空文本才会检索；清空输入不会调用 `lazyLoader`。
+- 面板在 `options.length > 0 || loading` 时打开，检索结果为空时自动关闭。
+- `readonly` / `disabled` 时输入框不可编辑，也不会检索。
 
 ## 相关组件
 
-- [OptionsSelect](../options_select/README_CN.md) —— 纯下拉变体。
-- [OptionsMultiSelect](../options_multi_select/README_CN.md) —— 多选变体。
-- [LookupEditor](../lookup_editor/README_CN.md) —— 大列表 / 远程数据的懒加载选择器。
+- `OptionsSelect`：本地选项数组的单选下拉。
+- `LookupEditor`：通过弹出查找界面选择复杂对象。
+- `ListBox`：同样支持 `lazyLoader` 的列表框。

package/dist/form/lookup_editor/LookupEditor.svelte

@@ -6,7 +6,8 @@
 
 
     interface Props extends CommonFieldProps {
-        mandatory?: boolean;
+        /** 是否允许清空（显示清空按钮），默认 true */
+        clearable?: boolean;
         value?: any;
         text?: string;
         onaction?: () => void;
@@ -14,6 +15,7 @@
     }
 
     let {
+        leadingIcon,
         theme,
         style,
         tooltip,
@@ -21,7 +23,7 @@
         disabled = false,
         readonly = false,
         compact = false,
-        mandatory = false,
+        clearable = true,
         variant,
         value = $bindable(),
         text,
@@ -32,6 +34,7 @@
         onblur
     }: Props = $props();
 
+
     let editor: HTMLInputElement | undefined = $state(undefined);
 
     export function focus() {
@@ -59,11 +62,11 @@
 
 </script>
 
-<CommonEditor {theme} {clear} {style} {tooltip} {error} {readonly} {disabled} {compact} {variant} textValue={text??''} canClean={!mandatory}>
+<CommonEditor {theme} {clear} {style} {tooltip} {error} {readonly} {disabled} {compact} {variant} {leadingIcon} textValue={text??''} {clearable}>
     <input bind:this={editor} {placeholder} readonly value={text ?? ''} {onfocus} {onblur}/>
     {#snippet trailingIcon()}
         {#if !disabled && !readonly}
-            <i class="icon_google_arrow_drop_down action_icon" role="button" tabindex="0" aria-label="Lookup"
+            <i class="icon_google_arrow_drop_down action_icon" role="button" tabindex="-1" aria-label="Lookup"
                onmousedown={(event: MouseEvent)=> {event.preventDefault()}}
                onclick={handleActionClick} onkeydown={handleActionKeyDown}></i>
         {/if}
@@ -72,7 +75,6 @@
 
 <style>
     .action_icon {
-        visibility: hidden;
         cursor: pointer;
     }
 
@@ -80,9 +82,4 @@
         position: relative;
         top: 1px;
     }
-
-    :global(.uniface-common-editor:hover) .action_icon,
-    :global(.uniface-common-editor:focus-within) .action_icon {
-        visibility: visible;
-    }
 </style>

package/dist/form/lookup_editor/LookupEditor.svelte.d.ts

@@ -1,7 +1,8 @@
 import type { Snippet } from "svelte";
 import type CommonFieldProps from "../common_editor/CommonFieldProps";
 interface Props extends CommonFieldProps {
-    mandatory?: boolean;
+    /** 是否允许清空（显示清空按钮），默认 true */
+    clearable?: boolean;
     value?: any;
     text?: string;
     onaction?: () => void;

package/dist/form/memo_editor/MemoEditor.svelte

@@ -4,7 +4,7 @@
     import prefixFilter, {eventFilter} from "../../utils/prefixFilter";
 
     import type CommonFieldProps from "../common_editor/CommonFieldProps";
-    import type {KeyboardEvents} from "../common_editor/EditorEvents";
+    import type {KeyboardEvents} from "../events";
 
     const excludeAttrs = ['readonly', 'disabled', 'required', 'rows', 'form', 'wrap'];
 
@@ -68,7 +68,7 @@
 
 </script>
 
-<FormEditor {variant} {theme} {error} {tooltip} style="{style}; {heightStyle}" {readonly} {disabled} {compact} className={allowHorizontal ? 'memo-resize-horizontal' : ''}>
+<FormEditor {variant} {theme} {error} {tooltip} style="{style}; {heightStyle}" {readonly} {disabled} {compact} class="{className} {allowHorizontal ? 'memo-resize-horizontal' : ''}">
     <div class="memo-inner" style={heightStyle} class:resize-horizontal={allowHorizontal}>
         <textarea
                 bind:this={editor}

package/dist/form/memo_editor/MemoEditor.svelte.d.ts

@@ -1,5 +1,5 @@
 import type CommonFieldProps from "../common_editor/CommonFieldProps";
-import type { KeyboardEvents } from "../common_editor/EditorEvents";
+import type { KeyboardEvents } from "../events";
 interface Props extends CommonFieldProps, KeyboardEvents {
     class?: string;
     value?: any;

package/dist/form/number_editor/NumberEditor.svelte

@@ -5,7 +5,7 @@
     import utils from "../../overlay/common/utils";
     import prefixFilter from "../../utils/prefixFilter";
     import type CommonFieldProps from "../common_editor/CommonFieldProps";
-    import type {KeyboardEvents} from "../common_editor/EditorEvents";
+    import type {KeyboardEvents} from "../events";
 
     const excludeAttrs = ['type', 'readonly', 'disabled', 'required', 'wrap', 'value', 'max', 'min', 'step'];
 
@@ -41,6 +41,11 @@
         max,
         min,
         onchange,
+        onfocus,
+        onblur,
+        onkeydown,
+        onkeyup,
+        onkeypress,
         leadingIcon,
         trailingIcon,
         ...restProps
@@ -72,6 +77,7 @@
 
 <CommonEditor
     textValue={displayValue}
+    {style}
     {suffix}
     {prefix}
     {readonly}
@@ -93,6 +99,12 @@
             {allowNegative}
             {max}
             {min}
+            {onchange}
+            {onfocus}
+            {onblur}
+            {onkeydown}
+            {onkeyup}
+            {onkeypress}
             {...input$}
         />
     {/if}

package/dist/form/number_editor/NumberEditor.svelte.d.ts

@@ -1,6 +1,6 @@
 import type { Snippet } from 'svelte';
 import type CommonFieldProps from "../common_editor/CommonFieldProps";
-import type { KeyboardEvents } from "../common_editor/EditorEvents";
+import type { KeyboardEvents } from "../events";
 interface Props extends CommonFieldProps, KeyboardEvents {
     value?: any;
     precision?: number;

package/dist/form/number_range/NumberRange.svelte

@@ -39,15 +39,15 @@
 
     let editor: NumberInput | undefined = $state(undefined);
 
-    const showFromClean = $derived(!disabled && !readonly && fromValue != null);
-    const showToClean = $derived(!disabled && !readonly && toValue != null);
+    const fromClearable = $derived(!disabled && !readonly && fromValue != null);
+    const toClearable = $derived(!disabled && !readonly && toValue != null);
 
     const cleanFrom = () => { fromValue = undefined; editor?.focus(); };
     const cleanTo = () => { toValue = undefined; };
 </script>
 
-<CommonRangeEditor {compact} {disabled} {readonly} {error} {tooltip} {theme} {className} {style} {variant} {showFromClean} {showToClean} {cleanFrom} {cleanTo}>
-    {#snippet fromChild()}
+<CommonRangeEditor {compact} {disabled} {readonly} {error} {tooltip} {theme} class={className} {style} {variant} {fromClearable} {toClearable} {cleanFrom} {cleanTo}>
+    {#snippet from()}
         <NumberInput
                 bind:this={editor}
                 style="width: 100%; text-align: center"
@@ -57,7 +57,7 @@
                 max={toValue ?? undefined}
                 bind:value={fromValue}/>
     {/snippet}
-    {#snippet toChild()}
+    {#snippet to()}
         <NumberInput
                 style="width: 100%; text-align: center"
                 {allowNegative}

package/dist/form/options_multi_select/OptionsMultiSelect.svelte

@@ -5,7 +5,7 @@
     import type PickerProps from "../common_editor/CommonPickerProps";
     import {CommonPicker} from "../common_editor";
     import CheckBox from "../checkbox";
-    import type {KeyboardEvents} from "../common_editor/EditorEvents";
+    import type {KeyboardEvents} from "../events";
 
 
     interface Props extends PickerProps, KeyboardEvents {
@@ -16,7 +16,8 @@
         keyField?: string;
         textField?: string;
         emptyText?: string;
-        disableOptions?: Array<string>;
+        /** 要渲染但禁用的选项 key 列表 */
+        disabledOptions?: Array<string>;
         hideOptions?: Array<string>;
         tagColor?: string;
         tagVariant?: 'borderless' | 'border' | 'round';
@@ -30,7 +31,7 @@
         variant,
         compact,
         disabled,
-        mandatory = false,
+        clearable,
         readonly,
         menu$height = 0,
         value = $bindable(),
@@ -40,7 +41,7 @@
         textField = "text",
         placeholder,
         emptyText,
-        disableOptions = [],
+        disabledOptions = [],
         hideOptions = [],
         onchange,
         onfocus,
@@ -49,7 +50,8 @@
         tagVariant = 'border'
     }: Props = $props();
 
-    export const focus = () => {
+
+    export function focus() {
         setTimeout(() => {
             editor?.focus();
         }, 50);
@@ -110,9 +112,7 @@
 
         // 删除tag后确保获得焦点
         if (!hasFocus) {
-            setTimeout(() => {
-                //editor?.focus();
-            }, 10);
+            //editor?.focus();
         }
 
         e.stopPropagation();
@@ -156,13 +156,13 @@
 
 </script>
 
-<CommonPicker {variant} {style} {compact} {tooltip} {error} {readonly} {disabled} {theme} {placeholder} {value} {mandatory} {clear}
-              bind:isOpen {onblur} {onfocus} autoFit {input$style}>
+<CommonPicker {variant} {style} {compact} {tooltip} {error} {readonly} {disabled} {theme} {placeholder} {value} {clearable} {clear}
+              bind:expanded={isOpen} {onblur} {onfocus} autoFit {input$style}>
     <div class="option-field">
         <div class="options-editor" onclick={openPopupLayer} onkeydown={handleEditorKeyDown} tabindex="0" role="button" aria-haspopup="listbox" aria-expanded={isOpen}>
             {#if selectedList.length > 0 }
                 {#each selectedList as code}
-                    <Tag style="flex-shrink: 0" size={compact ? 'small' : 'middle'} color={tagColor} variant={tagVariant}
+                    <Tag style="flex-shrink: 0" size={compact ? 'small' : 'medium'} color={tagColor} variant={tagVariant}
                          text={getOptionItem(code)}
                          removable={!readonly && !disabled && !isOpen} ondelete={removeOption(code)}/>
                 {/each}
@@ -177,11 +177,11 @@
             {/if}
         </div>
     </div>
-    {#snippet popupLayer()}
+    {#snippet popup()}
         <div class="options-popover" style={mh} role="listbox" aria-multiselectable="true">
             {#each options as op}
                 {#if hideOptions.indexOf(op[keyField]) < 0}
-                    {@const itemDisabled = disableOptions.indexOf(op[keyField]) > -1}
+                    {@const itemDisabled = disabledOptions.indexOf(op[keyField]) > -1}
                     <div class="option-item" class:disabled={itemDisabled} onclick={itemDisabled ? null : toggleOption(op[keyField])}
                          onkeydown={handleOptionKeyDown(op[keyField], itemDisabled)}
                          role="option" tabindex={itemDisabled ? -1 : 0}

package/dist/form/options_multi_select/OptionsMultiSelect.svelte.d.ts

@@ -1,5 +1,5 @@
 import type PickerProps from "../common_editor/CommonPickerProps";
-import type { KeyboardEvents } from "../common_editor/EditorEvents";
+import type { KeyboardEvents } from "../events";
 interface Props extends PickerProps, KeyboardEvents {
     menu$height?: number;
     value?: string;
@@ -8,7 +8,8 @@ interface Props extends PickerProps, KeyboardEvents {
     keyField?: string;
     textField?: string;
     emptyText?: string;
-    disableOptions?: Array<string>;
+    /** 要渲染但禁用的选项 key 列表 */
+    disabledOptions?: Array<string>;
     hideOptions?: Array<string>;
     tagColor?: string;
     tagVariant?: 'borderless' | 'border' | 'round';

package/dist/form/options_multi_select/README.md

@@ -1,5 +1,7 @@
 # OptionsMultiSelect
 
+> **Renamed in 5.1.0**: this document uses the names from the [API Naming Guide](../../../docs/NAMING.md); the old names `disableOptions` were removed in 5.1.0 (no compatibility aliases are kept).
+
 A multi-selection dropdown picker. Selected items render inline as removable tags; the dropdown shows a checkbox per option. The bound `value` is a **delimited string** (default `;`), not an array — convenient for storing straight into a single text column.
 
 > This is the **multi-select** picker. For single-select see [OptionsSelect](../options_select/README.md); for cascading (tree-shaped) data see [CascadeOptionSelect](../cascade_options_select/README.md).
@@ -12,7 +14,7 @@ A multi-selection dropdown picker. Selected items render inline as removable tag
 - **Delimited-string `value`** — `"A;B;C"`-style. Set `delimiter` to use a different separator (`,` / `|` / etc.).
 - **`onchange` fires the array** of selected keys, regardless of the storage delimiter. So you always get a clean `Array<string>` to work with.
 - **Custom field mapping** via `keyField` / `textField`.
-- **Hide or disable individual options** via `hideOptions` / `disableOptions`.
+- **Hide or disable individual options** via `hideOptions` / `disabledOptions`.
 - **Tag styling** — `tagVariant` (`borderless` / `border` / `round`) and `tagColor` (`"0"` … `"12"`, mapped to the `--uniface-tag-g{n}-color` tokens).
 - **Compact mode** — switches tags to their small size variant for table cells and dense forms.
 - **Read-only / disabled** modes — tags render without the × buttons; dropdown is suppressed.
@@ -67,7 +69,7 @@ import OptionsMultiSelect from "@ticatec/uniface-element/OptionsMultiSelect";
 | `delimiter` | `string` | `";"` | Separator for joining keys in `value`. |
 | `placeholder` | `string` | — | Shown when nothing is selected. |
 | `emptyText` | `string` | — | Shown when nothing is selected, in place of the placeholder. Useful for "All items" or "No filter" labels in read-only mode. |
-| `disableOptions` | `Array<string>` | `[]` | Keys rendered but unclickable (dimmed checkbox). |
+| `disabledOptions` | `Array<string>` | `[]` | Keys rendered but unclickable (dimmed checkbox). |
 | `hideOptions` | `Array<string>` | `[]` | Keys not rendered at all. |
 | `tagColor` | `string` | — | Maps to the `--uniface-tag-g{n}-color` token family. Accepts `"0"` … `"12"`. |
 | `tagVariant` | `'borderless' \| 'border' \| 'round'` | `'border'` | Visual style of each tag. |
@@ -164,7 +166,7 @@ Use `,` instead of `;` for CSV-style storage:
 <OptionsMultiSelect
   {options}
   bind:value
-  disableOptions={["ARCHIVED"]}
+  disabledOptions={["ARCHIVED"]}
   hideOptions={["DRAFT"]}
   placeholder="Visible statuses"
 />

package/dist/form/options_multi_select/README_CN.md

@@ -1,5 +1,7 @@
 # OptionsMultiSelect
 
+> **5.1.0 重命名**：本文使用 [API 命名规范](../../../docs/NAMING_CN.md) 中的名字；旧名 `disableOptions` 已在 5.1.0 移除（5.1.0 不保留兼容别名）。
+
 多选下拉选择器。选中的项以内置可删除 tag 的形式行内展示；下拉里每个选项是一个 checkbox。绑定的 `value` 是**分隔符拼接的字符串**（默认 `;`），不是数组 —— 适合直接存进一个文本列。
 
 > 这是**多选**组件。单选见 [OptionsSelect](../options_select/README_CN.md)；树形级联见 [CascadeOptionSelect](../cascade_options_select/README_CN.md)。
@@ -12,7 +14,7 @@
 - **`value` 是分隔字符串** —— `"A;B;C"` 这种形式。改 `delimiter` 可以换分隔符（`,` / `|` 等）。
 - **`onchange` 拿到的是数组** —— 不管存储用什么分隔符，回调始终给你干净的 `Array<string>`。
 - **自定义字段映射**：`keyField` / `textField`。
-- **隐藏 / 禁用单个选项**：`hideOptions` / `disableOptions`。
+- **隐藏 / 禁用单个选项**：`hideOptions` / `disabledOptions`。
 - **Tag 样式**：`tagVariant`（`borderless` / `border` / `round`）+ `tagColor`（`"0"` … `"12"`，对应 `--uniface-tag-g{n}-color` 这组 token）。
 - **紧凑模式** —— 切到 tag 的小尺寸，适合表格单元格和密集表单。
 - **只读 / 禁用** —— tag 不显示 ×；下拉不弹。
@@ -67,7 +69,7 @@ import OptionsMultiSelect from "@ticatec/uniface-element/OptionsMultiSelect";
 | `delimiter` | `string` | `";"` | `value` 拼接用的分隔符。 |
 | `placeholder` | `string` | — | 没有选中时输入框的占位文字。 |
 | `emptyText` | `string` | — | 没有选中时**替换** placeholder 显示的文字。常用于只读模式下显示"全部"或"不限"。 |
-| `disableOptions` | `Array<string>` | `[]` | 要渲染但禁用（checkbox 变灰）的 keys。 |
+| `disabledOptions` | `Array<string>` | `[]` | 要渲染但禁用（checkbox 变灰）的 keys。 |
 | `hideOptions` | `Array<string>` | `[]` | 完全不渲染的 keys。 |
 | `tagColor` | `string` | — | 对应 `--uniface-tag-g{n}-color` 这组 token。可填 `"0"` … `"12"`。 |
 | `tagVariant` | `'borderless' \| 'border' \| 'round'` | `'border'` | tag 的视觉风格。 |
@@ -155,7 +157,7 @@ import OptionsMultiSelect from "@ticatec/uniface-element/OptionsMultiSelect";
 <OptionsMultiSelect
   {options}
   bind:value
-  disableOptions={["ARCHIVED"]}
+  disabledOptions={["ARCHIVED"]}
   hideOptions={["DRAFT"]}
   placeholder="可见状态"
 />