@ticatec/uniface-element 0.2.4 → 0.3.0

package/dist/text-editor/README_CN.md

@@ -0,0 +1,466 @@
+# 文本编辑器组件
+
+一个功能强大的文本输入组件，提供全面的输入处理、事件转发和显示模式。基于 `CommonEditor` 基础组件构建，具备高级功能，如前缀/后缀支持、清除功能和灵活的样式设置。
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## 导入
+
+```typescript
+import TextEditor from "@ticatec/uniface-element/TextEditor";
+```
+
+## 基本用法
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  
+  let inputValue = '';
+</script>
+
+<TextEditor 
+  bind:value={inputValue} 
+  placeholder="输入文本..."
+/>
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `value` | `string` | `""` | 当前输入值 |
+| `disabled` | `boolean` | `false` | 输入框是否禁用 |
+| `readonly` | `boolean` | `false` | 输入框是否只读 |
+| `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | 输入框的视觉变体 |
+| `compact` | `boolean` | `false` | 是否使用紧凑间距 |
+| `style` | `string` | `""` | 附加 CSS 样式 |
+| `prefix` | `string` | `""` | 显示的文本前缀 |
+| `suffix` | `string` | `""` | 显示的文本后缀 |
+| `removable` | `boolean` | `true` | 是否显示清除按钮 |
+| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | 显示模式（编辑/查看） |
+| `class` | `string` | `""` | CSS 类名 |
+
+## 事件
+
+文本编辑器组件转发所有原生输入事件：
+
+| 事件 | 描述 |
+|-------|-------------|
+| `input` | 每次输入更改时触发 |
+| `change` | 输入框失去焦点或按下回车键时触发 |
+| `focus` | 输入框获得焦点时触发 |
+| `blur` | 输入框失去焦点时触发 |
+| `keydown` | 按下键盘按键时触发 |
+| `keyup` | 释放键盘按键时触发 |
+| `keypress` | 按下键盘按键时触发 |
+| `compositionstart` | IME 组合输入开始时触发 |
+| `compositionend` | IME 组合输入结束时触发 |
+| `compositionupdate` | IME 组合输入期间触发 |
+
+## 方法
+
+| 方法 | 描述 |
+|--------|-------------|
+| `setFocus()` | 以编程方式使输入框获得焦点 |
+
+## 示例
+
+### 基本文本输入
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  
+  let userName = '';
+  let email = '';
+</script>
+
+<div class="form-group">
+  <label>用户名：</label>
+  <TextEditor bind:value={userName} placeholder="输入用户名" />
+</div>
+
+<div class="form-group">
+  <label>邮箱：</label>
+  <TextEditor bind:value={email} placeholder="输入邮箱地址" />
+</div>
+
+<style>
+  .form-group {
+    margin-bottom: 16px;
+  }
+  
+  label {
+    display: block;
+    margin-bottom: 4px;
+    font-weight: 500;
+  }
+</style>
+```
+
+### 带事件处理程序
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  
+  let inputValue = '';
+  let isFocused = false;
+  
+  function handleInput(event) {
+    console.log('输入更改：', event.target.value);
+  }
+  
+  function handleChange(event) {
+    console.log('更改确认：', event.target.value);
+  }
+  
+  function handleFocus(event) {
+    console.log('输入框已聚焦');
+    isFocused = true;
+  }
+  
+  function handleBlur(event) {
+    console.log('输入框已失焦');
+    isFocused = false;
+  }
+</script>
+
+<TextEditor 
+  bind:value={inputValue}
+  placeholder="输入一些内容..."
+  on:input={handleInput}
+  on:change={handleChange}
+  on:focus={handleFocus}
+  on:blur={handleBlur}
+/>
+
+{#if isFocused}
+  <p>输入框当前已聚焦</p>
+{/if}
+```
+
+### 不同变体
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  
+  let value1 = '', value2 = '', value3 = '', value4 = '';
+</script>
+
+<!-- 默认变体 -->
+<TextEditor bind:value={value1} placeholder="默认" />
+
+<!-- 简单变体 -->
+<TextEditor bind:value={value2} variant="plain" placeholder="简单" />
+
+<!-- 轮廓变体 -->
+<TextEditor bind:value={value3} variant="outlined" placeholder="轮廓" />
+
+<!-- 填充变体 -->
+<TextEditor bind:value={value4} variant="filled" placeholder="填充" />
+```
+
+### 带前缀和后缀
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  
+  let amount = '';
+  let website = '';
+  let username = '';
+</script>
+
+<!-- 带前缀的货币输入 -->
+<TextEditor 
+  bind:value={amount} 
+  prefix="$" 
+  placeholder="0.00"
+/>
+
+<!-- 带前缀的网站 URL -->
+<TextEditor 
+  bind:value={website} 
+  prefix="https://" 
+  placeholder="example.com"
+/>
+
+<!-- 带后缀的用户名 -->
+<TextEditor 
+  bind:value={username} 
+  suffix="@company.com" 
+  placeholder="用户名"
+/>
+```
+
+### 带图标
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  import Icon from "@ticatec/uniface-element/Icon";
+  
+  let searchTerm = '';
+  let email = '';
+</script>
+
+<!-- 带前导图标的搜索输入 -->
+<TextEditor bind:value={searchTerm} placeholder="搜索...">
+  <svelte:fragment slot="leading-icon">
+    <Icon name="search" />
+  </svelte:fragment>
+</TextEditor>
+
+<!-- 带尾随图标的邮箱输入 -->
+<TextEditor bind:value={email} placeholder="输入邮箱">
+  <svelte:fragment slot="trailing-icon">
+    <Icon name="email" />
+  </svelte:fragment>
+</TextEditor>
+```
+
+### 禁用和只读状态
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  
+  let normalValue = '';
+  let readonlyValue = '这是只读的';
+  let disabledValue = '';
+</script>
+
+<!-- 正常输入 -->
+<TextEditor bind:value={normalValue} placeholder="正常输入" />
+
+<!-- 只读输入 -->
+<TextEditor bind:value={readonlyValue} readonly />
+
+<!-- 禁用输入 -->
+<TextEditor bind:value={disabledValue} disabled placeholder="禁用输入" />
+```
+
+### 紧凑模式
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  
+  let compactValue = '';
+</script>
+
+<div class="toolbar">
+  <TextEditor 
+    bind:value={compactValue} 
+    compact 
+    placeholder="紧凑输入" 
+  />
+</div>
+
+<style>
+  .toolbar {
+    display: flex;
+    align-items: center;
+    padding: 8px;
+    background: #f8f9fa;
+  }
+</style>
+```
+
+### 无清除按钮
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  
+  let value = '';
+</script>
+
+<TextEditor 
+  bind:value 
+  removable={false}
+  placeholder="无清除按钮"
+/>
+```
+
+### 表单集成
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  import Button from "@ticatec/uniface-element/Button";
+  
+  let formData = {
+    firstName: '',
+    lastName: '',
+    company: '',
+    title: ''
+  };
+  
+  function handleSubmit() {
+    console.log('表单提交：', formData);
+  }
+  
+  function resetForm() {
+    formData = {
+      firstName: '',
+      lastName: '',
+      company: '',
+      title: ''
+    };
+  }
+</script>
+
+<form on:submit|preventDefault={handleSubmit}>
+  <div class="form-row">
+    <div class="form-field">
+      <label>名字</label>
+      <TextEditor bind:value={formData.firstName} placeholder="张" />
+    </div>
+    <div class="form-field">
+      <label>姓氏</label>
+      <TextEditor bind:value={formData.lastName} placeholder="伟" />
+    </div>
+  </div>
+  
+  <div class="form-field">
+    <label>公司</label>
+    <TextEditor bind:value={formData.company} placeholder="某某公司" />
+  </div>
+  
+  <div class="form-field">
+    <label>职位</label>
+    <TextEditor bind:value={formData.title} placeholder="软件工程师" />
+  </div>
+  
+  <div class="form-actions">
+    <Button type="secondary" label="重置" onClick={resetForm} />
+    <Button type="primary" label="提交" onClick={handleSubmit} />
+  </div>
+</form>
+
+<style>
+  .form-row {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 16px;
+    margin-bottom: 16px;
+  }
+  
+  .form-field {
+    margin-bottom: 16px;
+  }
+  
+  label {
+    display: block;
+    margin-bottom: 4px;
+    font-weight: 500;
+  }
+  
+  .form-actions {
+    display: flex;
+    gap: 12px;
+    justify-content: flex-end;
+  }
+</style>
+```
+
+### 编程式焦点
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  import Button from "@ticatec/uniface-element/Button";
+  
+  let textEditor;
+  let inputValue = '';
+  
+  function focusInput() {
+    textEditor.setFocus();
+  }
+</script>
+
+<Button label="聚焦输入框" onClick={focusInput} />
+
+<TextEditor 
+  bind:this={textEditor}
+  bind:value={inputValue}
+  placeholder="点击按钮聚焦我"
+/>
+```
+
+### 显示模式
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  import { DisplayMode } from "@ticatec/uniface-element/common/DisplayMode";
+  
+  let value = '示例文本';
+  let isEditing = false;
+</script>
+
+<button on:click={() => isEditing = !isEditing}>
+  {isEditing ? '切换到查看模式' : '切换到编辑模式'}
+</button>
+
+<TextEditor 
+  bind:value 
+  displayMode={isEditing ? DisplayMode.Edit : DisplayMode.View}
+  placeholder="输入文本..."
+/>
+```
+
+## 功能
+
+- **全面事件处理**：自动转发所有原生输入事件
+- **高级输入支持**：处理国际化文本输入的组合事件
+- **灵活显示**：支持编辑和查看模式
+- **清除功能**：可选的清除按钮，行为可自定义
+- **图标支持**：支持前导和尾随图标插槽
+- **前缀/后缀**：支持文本前缀和后缀
+- **焦点管理**：支持编程式焦点控制
+- **灵活样式**：支持多种视觉变体和自定义样式
+
+## 事件转发
+
+文本编辑器组件使用高级事件转发系统，自动转发所有原生输入事件，同时允许对特定事件（如 `input` 和 `change`）进行自定义处理。
+
+## 可访问性
+
+- 适当的语义化 HTML 结构
+- 支持键盘导航
+- 屏幕阅读器兼容
+- 焦点指示器和管理
+- 适当的 ARIA 属性
+
+## 最佳实践
+
+1. **事件处理**：使用 `on:input` 进行实时反馈，使用 `on:change` 进行确认更改
+2. **验证**：在事件处理程序中实现验证逻辑
+3. **占位符文本**：提供有用的占位符文本以提升用户体验
+4. **标签**：始终将输入框与适当的标签关联
+5. **错误状态**：适当处理和显示验证错误
+6. **焦点管理**：使用编程式焦点提升可访问性
+
+## 浏览器支持
+
+- 支持完整输入事件的现代浏览器
+- 兼容 Svelte 5+
+- 支持国际化输入法编辑器（IME）
+- 触控友好界面
+
+## 相关组件
+
+- `PasswordEditor` - 带可见性切换的专用密码输入
+- `SearchBox` - 带内置搜索图标的搜索专用输入
+- `NumberEditor` - 带验证的数字输入
+- `MemoEditor` - 多行文本输入（textarea）
+- `PromptsTextEditor` - 带自动建议的文本输入

package/dist/text-editor/TextEditor.svelte

@@ -1,11 +1,11 @@
 <script lang="ts">
-
     import {DisplayMode} from "../common/DisplayMode";
     import prefixFilter from "../utils/prefixFilter";
     import CommonEditor from "../common-editor/CommonEditor.svelte";
-    import {tick} from "svelte";
+    import {forwardAllEvents} from "../lib/forwardAllEvents";
+    import {onMount} from "svelte";
 
-    const excludeAttrs = ['type', 'readonly', 'disabled', 'required', "form", "wrap"]
+    const excludeAttrs = ['type', 'readonly', 'disabled', 'required', "form", "wrap"];
 
     export let disabled: boolean = false;
     export let readonly: boolean = false;
@@ -18,21 +18,18 @@
     export let prefix: string = '';
     export let removable: boolean = true;
     export let displayMode: DisplayMode = DisplayMode.Edit;
-    export let onChange: ((value: string) => void) | undefined = undefined;
 
     export const setFocus = () => {
         setTimeout(()=> {
             editor && editor.focus();
         }, 50);
-    }
-
+    };
 
     let className: string = '';
     let input$: any;
-    let editor: any;
+    let editor: HTMLInputElement;
 
     $: variant = variant ?? '';
-
     $: input$ = prefixFilter($$props, "input$", excludeAttrs);
 
     let oldValue = value;
@@ -40,27 +37,62 @@
     const clean = () => {
         value = '';
         editor.focus();
+    };
+
+    // 原生 input 行为：value 实时变化就触发 input
+    function handleInput(e: InputEvent) {
+        value = (e.target as HTMLInputElement).value;
     }
 
-    $: if (oldValue != value) {
-        onChange?.(value);
-        oldValue = value;
+    // 原生 change 行为：用户确认输入后触发（blur 或回车）
+    function handleChange(e: Event) {
+        if (oldValue !== value) {
+            oldValue = value;
+        }
     }
 
+    onMount(() => {
+        if (editor) {
+            const forward = forwardAllEvents(editor, $$props, {
+                input: handleInput,
+                change: handleChange
+            });
 
+            return () => forward.destroy?.();
+        }
+    });
 </script>
-<CommonEditor {displayMode} {style} {value} {suffix} {prefix} {readonly} {disabled} {variant} {compact}
-              hasLeadingIcon={$$slots['leading-icon']!=null} hasTrailingIcon={$$slots['trailing-icon']!=null}
-              showActionIcon={!readonly && !disabled && removable && value?.length > 0} placeholder={input$['placeholder']}
-              class={className} clean={clean}>
+
+<CommonEditor
+        {displayMode} {style} {value} {suffix} {prefix} {readonly} {disabled} {variant} {compact}
+        hasLeadingIcon={$$slots['leading-icon']!=null} hasTrailingIcon={$$slots['trailing-icon']!=null}
+        showActionIcon={!readonly && !disabled && removable && value?.length > 0}
+        placeholder={input$['placeholder']}
+        class={className} clean={clean}>
+
     <svelte:fragment slot="leading-icon">
         {#if $$slots['leading-icon']}
             <slot name="leading-icon"/>
         {/if}
     </svelte:fragment>
-    <input bind:this={editor} {...input$} type="text" style="flex: 1 1 auto" bind:value={value}
-           on:blur on:focus on:keydown on:keyup on:keypress on:input on:compositionstart
-           on:compositionend on:compositionupdate/>
+
+    <input
+            bind:this={editor}
+            {...input$}
+            type="text"
+            style="flex: 1 1 auto"
+            bind:value={value}
+            on:blur
+            on:focus
+            on:keydown
+            on:keyup
+            on:keypress
+            on:input
+            on:compositionstart
+            on:compositionend
+            on:compositionupdate
+    />
+
     <svelte:fragment slot="trailing-icon">
         {#if $$slots['trailing-icon']}
             <div class="editor-embed-icon">
@@ -68,4 +100,4 @@
             </div>
         {/if}
     </svelte:fragment>
-</CommonEditor>
+</CommonEditor>

package/dist/text-editor/TextEditor.svelte.d.ts

@@ -25,7 +25,6 @@ declare const TextEditor: $$__sveltets_2_IsomorphicComponent<{
     prefix?: string | undefined;
     removable?: boolean | undefined;
     displayMode?: DisplayMode | undefined;
-    onChange?: ((value: string) => void) | undefined | undefined;
     setFocus?: (() => void) | undefined;
 }, {
     blur: FocusEvent;