tang-ui-x 1.3.1 → 1.3.3

package/README.md

@@ -65,8 +65,8 @@ pnpm add tang-ui-x
 </template>
 
 <script module="TButton" lang="uts">
-  import TButton from 'tang-ui-x/components/TButton/index.uvue'
-  export default TButton
+import TButton from 'tang-ui-x/components/TButton/index.uvue'
+export default TButton
 </script>
 ```
 
@@ -178,37 +178,37 @@ const languages = getAvailableLocales()  // ['zh-CN', 'en-US', 'zh-TW']
 添加组件库未内置的语言（如日语、韩语等）：
 
 ```typescript
-import { registerLocale, setLanguage } from 'tang-ui-x'
+import { registerLocale, setLanguage } from "tang-ui-x";
 
 // 注册日语语言包
-registerLocale('ja-JP', {
+registerLocale("ja-JP", {
   common: {
-    confirm: '確認',
-    cancel: 'キャンセル',
-    ok: 'OK',
-    close: '閉じる',
-    loading: '読み込み中...',
-    noData: 'データなし'
+    confirm: "確認",
+    cancel: "キャンセル",
+    ok: "OK",
+    close: "閉じる",
+    loading: "読み込み中...",
+    noData: "データなし",
   },
   dialog: {
-    title: 'ヒント',
-    confirmText: '確認',
-    cancelText: 'キャンセル'
+    title: "ヒント",
+    confirmText: "確認",
+    cancelText: "キャンセル",
   },
   empty: {
-    title: 'データなし',
-    description: '関連コンテンツがありません',
-    actionText: '更新'
+    title: "データなし",
+    description: "関連コンテンツがありません",
+    actionText: "更新",
   },
   searchBar: {
-    placeholder: '検索キーワードを入力',
-    cancelText: 'キャンセル'
-  }
+    placeholder: "検索キーワードを入力",
+    cancelText: "キャンセル",
+  },
   // ... 其他组件模块
-})
+});
 
 // 切换到日语
-setLanguage('ja-JP')
+setLanguage("ja-JP");
 ```
 
 #### 方式二：覆盖默认翻译
@@ -216,17 +216,17 @@ setLanguage('ja-JP')
 只覆盖部分翻译文本，其他保持默认：
 
 ```typescript
-import { registerLocale } from 'tang-ui-x'
+import { registerLocale } from "tang-ui-x";
 
 // 自定义简体中文的部分翻译
-registerLocale('zh-CN', {
+registerLocale("zh-CN", {
   common: {
-    confirm: '好的',  // 覆盖默认的"确定"
-    cancel: '算了'    // 覆盖默认的"取消"
+    confirm: "好的", // 覆盖默认的"确定"
+    cancel: "算了", // 覆盖默认的"取消"
     // 其他键（ok, close, loading 等）保持默认值
-  }
+  },
   // 其他模块（dialog, empty 等）保持默认翻译
-})
+});
 ```
 
 ### 语言包注册模式
@@ -238,6 +238,7 @@ Tang UI X 提供了两种语言包注册模式，以满足不同的使用场景
 合并模式会将新语言包与现有语言包合并，新内容覆盖旧内容，但未覆盖的内容会被保留。这是 `registerLocale` 函数的默认行为。
 
 **使用场景：**
+
 - 只想覆盖部分翻译文本
 - 添加新的翻译键而不影响现有翻译
 - 逐步自定义组件库的翻译
@@ -245,17 +246,17 @@ Tang UI X 提供了两种语言包注册模式，以满足不同的使用场景
 **示例 1：覆盖部分通用文本**
 
 ```typescript
-import { registerLocale } from 'tang-ui-x'
+import { registerLocale } from "tang-ui-x";
 
 // 只覆盖 common 模块的部分键
-registerLocale('zh-CN', {
+registerLocale("zh-CN", {
   common: {
-    confirm: '好的',  // 覆盖默认的"确定"
-    cancel: '算了'    // 覆盖默认的"取消"
+    confirm: "好的", // 覆盖默认的"确定"
+    cancel: "算了", // 覆盖默认的"取消"
     // ok, close, loading, noData 等其他键保持默认值
-  }
+  },
   // dialog, empty, searchBar 等其他模块保持默认翻译
-})
+});
 
 // 结果：
 // - common.confirm → "好的"（已覆盖）
@@ -269,21 +270,21 @@ registerLocale('zh-CN', {
 **示例 2：添加新的翻译键**
 
 ```typescript
-import { registerLocale } from 'tang-ui-x'
+import { registerLocale } from "tang-ui-x";
 
 // 为现有语言添加新的翻译键
-registerLocale('zh-CN', {
+registerLocale("zh-CN", {
   common: {
-    save: '保存',      // 新增键
-    delete: '删除',    // 新增键
-    edit: '编辑'       // 新增键
+    save: "保存", // 新增键
+    delete: "删除", // 新增键
+    edit: "编辑", // 新增键
   },
   // 添加新的自定义模块
   myComponent: {
-    title: '我的组件',
-    description: '这是自定义组件'
-  }
-})
+    title: "我的组件",
+    description: "这是自定义组件",
+  },
+});
 
 // 原有的所有翻译都会保留，只是新增了这些键
 ```
@@ -291,14 +292,18 @@ registerLocale('zh-CN', {
 **示例 3：使用 registerLocaleWithMode 显式指定合并模式**
 
 ```typescript
-import { registerLocaleWithMode } from 'tang-ui-x'
+import { registerLocaleWithMode } from "tang-ui-x";
 
 // 显式指定合并模式（与 registerLocale 效果相同）
-registerLocaleWithMode('zh-CN', {
-  common: {
-    confirm: '好的'
-  }
-}, 'merge')
+registerLocaleWithMode(
+  "zh-CN",
+  {
+    common: {
+      confirm: "好的",
+    },
+  },
+  "merge",
+);
 ```
 
 #### 替换模式
@@ -306,6 +311,7 @@ registerLocaleWithMode('zh-CN', {
 替换模式会完全替换现有语言包，不保留任何原有内容。使用此模式时，您需要提供完整的语言包，否则缺失的模块和键将无法使用。
 
 **使用场景：**
+
 - 完全自定义某个语言的所有翻译
 - 从外部 JSON 文件加载完整的语言包
 - 确保语言包的完整性和一致性
@@ -313,34 +319,34 @@ registerLocaleWithMode('zh-CN', {
 **方式 1：使用 replaceLocale 函数**
 
 ```typescript
-import { replaceLocale } from 'tang-ui-x'
+import { replaceLocale } from "tang-ui-x";
 
 // 完全替换简体中文语言包
-replaceLocale('zh-CN', {
+replaceLocale("zh-CN", {
   common: {
-    confirm: '好的',
-    cancel: '取消',
-    ok: 'OK',
-    close: '关闭',
-    loading: '加载中...',
-    noData: '暂无数据'
+    confirm: "好的",
+    cancel: "取消",
+    ok: "OK",
+    close: "关闭",
+    loading: "加载中...",
+    noData: "暂无数据",
   },
   dialog: {
-    title: '提示',
-    confirmText: '好的',
-    cancelText: '取消'
+    title: "提示",
+    confirmText: "好的",
+    cancelText: "取消",
   },
   empty: {
-    title: '暂无数据',
-    description: '当前没有相关内容',
-    actionText: '刷新试试'
+    title: "暂无数据",
+    description: "当前没有相关内容",
+    actionText: "刷新试试",
   },
   searchBar: {
-    placeholder: '请输入搜索关键词',
-    cancelText: '取消'
-  }
+    placeholder: "请输入搜索关键词",
+    cancelText: "取消",
+  },
   // 必须提供所有组件模块，否则缺失的模块将无法使用
-})
+});
 
 // 注意：原有的所有翻译都被清除，只保留新提供的内容
 ```
@@ -348,21 +354,25 @@ replaceLocale('zh-CN', {
 **方式 2：使用 registerLocaleWithMode 指定替换模式**
 
 ```typescript
-import { registerLocaleWithMode } from 'tang-ui-x'
+import { registerLocaleWithMode } from "tang-ui-x";
 
 // 使用替换模式注册语言包
-registerLocaleWithMode('zh-CN', {
-  common: {
-    confirm: '好的',
-    cancel: '取消'
-    // ... 其他键
+registerLocaleWithMode(
+  "zh-CN",
+  {
+    common: {
+      confirm: "好的",
+      cancel: "取消",
+      // ... 其他键
+    },
+    dialog: {
+      title: "提示",
+      // ... 其他键
+    },
+    // ... 其他模块
   },
-  dialog: {
-    title: '提示'
-    // ... 其他键
-  }
-  // ... 其他模块
-}, 'replace')
+  "replace",
+);
 ```
 
 #### 从 JSON 文件注册语言包
@@ -402,63 +412,65 @@ registerLocaleWithMode('zh-CN', {
 **使用合并模式加载 JSON 文件：**
 
 ```typescript
-import { registerLocale } from 'tang-ui-x'
-import customZhCN from './locales/custom-zh-CN.json'
+import { registerLocale } from "tang-ui-x";
+import customZhCN from "./locales/custom-zh-CN.json";
 
 // 合并模式：保留未覆盖的默认翻译
-registerLocale('zh-CN', customZhCN)
+registerLocale("zh-CN", customZhCN);
 ```
 
 **使用替换模式加载 JSON 文件：**
 
 ```typescript
-import { replaceLocale } from 'tang-ui-x'
-import completeZhCN from './locales/complete-zh-CN.json'
+import { replaceLocale } from "tang-ui-x";
+import completeZhCN from "./locales/complete-zh-CN.json";
 
 // 替换模式：完全替换，不保留默认翻译
-replaceLocale('zh-CN', completeZhCN)
+replaceLocale("zh-CN", completeZhCN);
 ```
 
 **从多个 JSON 文件组合语言包：**
 
 ```typescript
-import { registerLocale } from 'tang-ui-x'
-import commonTranslations from './locales/common.json'
-import dialogTranslations from './locales/dialog.json'
-import emptyTranslations from './locales/empty.json'
+import { registerLocale } from "tang-ui-x";
+import commonTranslations from "./locales/common.json";
+import dialogTranslations from "./locales/dialog.json";
+import emptyTranslations from "./locales/empty.json";
 
 // 组合多个 JSON 文件
 const customLocale = {
   common: commonTranslations,
   dialog: dialogTranslations,
-  empty: emptyTranslations
-}
+  empty: emptyTranslations,
+};
 
 // 注册组合后的语言包
-registerLocale('zh-CN', customLocale)
+registerLocale("zh-CN", customLocale);
 ```
 
 #### 两种模式的对比
 
-| 特性 | 合并模式（merge） | 替换模式（replace） |
-|------|------------------|-------------------|
-| **默认行为** | ✓ 是（registerLocale） | ✗ 否（需显式使用） |
-| **保留原有内容** | ✓ 是 | ✗ 否 |
-| **覆盖指定键** | ✓ 是 | ✓ 是 |
-| **需要完整语言包** | ✗ 否 | ✓ 是 |
-| **适合部分自定义** | ✓ 是 | ✗ 否 |
-| **适合完全自定义** | ✗ 否 | ✓ 是 |
-| **使用函数** | registerLocale<br>registerLocaleWithMode(..., 'merge') | replaceLocale<br>registerLocaleWithMode(..., 'replace') |
+| 特性               | 合并模式（merge）                                      | 替换模式（replace）                                     |
+| ------------------ | ------------------------------------------------------ | ------------------------------------------------------- |
+| **默认行为**       | ✓ 是（registerLocale）                                 | ✗ 否（需显式使用）                                      |
+| **保留原有内容**   | ✓ 是                                                   | ✗ 否                                                    |
+| **覆盖指定键**     | ✓ 是                                                   | ✓ 是                                                    |
+| **需要完整语言包** | ✗ 否                                                   | ✓ 是                                                    |
+| **适合部分自定义** | ✓ 是                                                   | ✗ 否                                                    |
+| **适合完全自定义** | ✗ 否                                                   | ✓ 是                                                    |
+| **使用函数**       | registerLocale<br>registerLocaleWithMode(..., 'merge') | replaceLocale<br>registerLocaleWithMode(..., 'replace') |
 
 #### 选择合适的模式
 
 **使用合并模式的情况：**
+
 - ✓ 只想修改少数几个翻译文本
 - ✓ 想要添加新的翻译键
 - ✓ 希望保留组件库的默认翻译作为后备
 - ✓ 逐步自定义翻译，不想一次性提供所有内容
 
 **使用替换模式的情况：**
+
 - ✓ 需要完全控制语言包内容
 - ✓ 从外部系统或 CMS 加载完整的翻译
 - ✓ 确保翻译的完整性和一致性
@@ -509,13 +521,13 @@ async function loadFromJSON() {
     // 假设从服务器获取语言包
     const response = await fetch('/api/locales/zh-CN.json')
     const localeData = await response.json()
-    
+
     // 使用合并模式
     registerLocale('zh-CN', localeData)
-    
+
     // 或使用替换模式
     // replaceLocale('zh-CN', localeData)
-    
+
     console.log('已从 JSON 加载语言包')
   } catch (error) {
     console.error('加载语言包失败:', error)
@@ -528,7 +540,7 @@ function explicitMode() {
   registerLocaleWithMode('zh-CN', {
     common: { confirm: '好的' }
   }, 'merge')
-  
+
   // 替换模式
   registerLocaleWithMode('en-US', {
     common: {
@@ -575,27 +587,27 @@ function explicitMode() {
     loading: '加载中...',
     noData: '暂无数据'
   },
-  
+
   // 对话框模块
   dialog: {
     title: '提示',
     confirmText: '确定',
     cancelText: '取消'
   },
-  
+
   // 空状态模块
   empty: {
     title: '暂无数据',
     description: '当前没有相关内容',
     actionText: '刷新试试'
   },
-  
+
   // 搜索框模块
   searchBar: {
     placeholder: '请输入搜索关键词',
     cancelText: '取消'
   }
-  
+
   // ... 其他组件模块
 }
 ```
@@ -618,17 +630,17 @@ function explicitMode() {
   <view>
     <!-- 使用默认翻译 -->
     <TEmpty />
-    
+
     <!-- 使用自定义文本（优先级高于翻译） -->
-    <TEmpty 
-      title="没有找到结果" 
+    <TEmpty
+      title="没有找到结果"
       description="请尝试其他搜索条件"
       actionText="重新搜索"
     />
-    
+
     <!-- 使用默认翻译，但会随语言切换自动更新 -->
     <TSearchBar />
-    
+
     <!-- 使用自定义占位符 -->
     <TSearchBar placeholder="搜索商品" />
   </view>
@@ -641,24 +653,24 @@ function explicitMode() {
 
 ```typescript
 // 定义带占位符的翻译
-registerLocale('zh-CN', {
+registerLocale("zh-CN", {
   common: {
-    hello: '你好，{name}',
-    itemCount: '共 {count} 个项目',
-    welcome: '{user}，欢迎回来！'
-  }
-})
+    hello: "你好，{name}",
+    itemCount: "共 {count} 个项目",
+    welcome: "{user}，欢迎回来！",
+  },
+});
 
 // 使用参数
-const { $t } = useI18n()
+const { $t } = useI18n();
 
-const greeting = $t('common.hello', { name: '张三' })
+const greeting = $t("common.hello", { name: "张三" });
 // 结果: "你好，张三"
 
-const count = $t('common.itemCount', { count: 5 })
+const count = $t("common.itemCount", { count: 5 });
 // 结果: "共 5 个项目"
 
-const welcome = $t('common.welcome', { user: 'Admin' })
+const welcome = $t("common.welcome", { user: "Admin" });
 // 结果: "Admin，欢迎回来！"
 ```
 
@@ -683,11 +695,11 @@ const description = computed(() => $t('empty.description'))
     <text>{{ title }}</text>
     <text>{{ description }}</text>
     <text>当前语言: {{ locale }}</text>
-    
+
     <!-- 组件内的文本也会自动更新 -->
     <TEmpty />
     <TSearchBar />
-    
+
     <button @click="setLocale('en-US')">English</button>
     <button @click="setLocale('zh-CN')">中文</button>
   </view>
@@ -726,10 +738,10 @@ function switchLanguage(code: string) {
 <template>
   <view class="language-switcher">
     <text class="title">选择语言 / Select Language</text>
-    
+
     <view class="language-list">
-      <view 
-        v-for="lang in availableLocales" 
+      <view
+        v-for="lang in availableLocales"
         :key="lang"
         class="language-item"
         :class="{ active: locale === lang }"
@@ -739,7 +751,7 @@ function switchLanguage(code: string) {
         <text v-if="locale === lang" class="check">✓</text>
       </view>
     </view>
-    
+
     <text class="current">当前语言: {{ languageNames[locale] }}</text>
   </view>
 </template>
@@ -798,39 +810,41 @@ function switchLanguage(code: string) {
 #### 步骤 1: 导入 useI18n
 
 ```typescript
-import { useI18n } from 'tang-ui-x'
+import { useI18n } from "tang-ui-x";
 ```
 
 #### 步骤 2: 在 setup 中获取翻译函数
 
 ```typescript
-const { $t } = useI18n()
+const { $t } = useI18n();
 ```
 
 #### 步骤 3: 替换硬编码文本
 
 ```typescript
 // 之前
-const confirmText = '确定'
+const confirmText = "确定";
 
 // 之后
-const confirmText = $t('common.confirm')
+const confirmText = $t("common.confirm");
 ```
 
 #### 步骤 4: 支持用户覆盖（推荐）
 
 ```typescript
 interface Props {
-  title?: string
-  description?: string
+  title?: string;
+  description?: string;
 }
 
-const props = defineProps<Props>()
-const { $t } = useI18n()
+const props = defineProps<Props>();
+const { $t } = useI18n();
 
 // 优先使用用户传入的值，否则使用翻译
-const displayTitle = computed(() => props.title || $t('empty.title'))
-const displayDescription = computed(() => props.description || $t('empty.description'))
+const displayTitle = computed(() => props.title || $t("empty.title"));
+const displayDescription = computed(
+  () => props.description || $t("empty.description"),
+);
 ```
 
 #### 步骤 5: 更新模板
@@ -890,10 +904,10 @@ function handleAction() {
 
 ```typescript
 {
-  $t: (key: string, params?: Record<string, any>) => string
-  locale: ComputedRef<string>
-  availableLocales: ComputedRef<string[]>
-  setLocale: (locale: string) => boolean
+  $t: (key: string, params?: Record<string, any>) => string;
+  locale: ComputedRef;
+  availableLocales: ComputedRef<string[]>;
+  setLocale: (locale: string) => boolean;
 }
 ```
 
@@ -934,8 +948,10 @@ function handleAction() {
 A: 使用 `registerLocale` 函数注册新语言包，然后使用 `setLanguage` 切换。
 
 ```typescript
-registerLocale('ja-JP', { /* 日语翻译 */ })
-setLanguage('ja-JP')
+registerLocale("ja-JP", {
+  /* 日语翻译 */
+});
+setLanguage("ja-JP");
 ```
 
 #### Q: 如何覆盖默认翻译？
@@ -943,11 +959,11 @@ setLanguage('ja-JP')
 A: 使用 `registerLocale` 注册同语言代码的语言包，只需包含要覆盖的键。
 
 ```typescript
-registerLocale('zh-CN', {
+registerLocale("zh-CN", {
   common: {
-    confirm: '好的'  // 只覆盖这一个键
-  }
-})
+    confirm: "好的", // 只覆盖这一个键
+  },
+});
 ```
 
 #### Q: 组件的文本不随语言切换更新？
@@ -956,10 +972,10 @@ A: 确保使用 `computed` 包装翻译文本：
 
 ```typescript
 // ❌ 错误：不会更新
-const title = $t('common.title')
+const title = $t("common.title");
 
 // ✓ 正确：会自动更新
-const title = computed(() => $t('common.title'))
+const title = computed(() => $t("common.title"));
 ```
 
 #### Q: 如何在组件外使用翻译？
@@ -967,9 +983,9 @@ const title = computed(() => $t('common.title'))
 A: 使用全局函数或直接访问 I18nManager：
 
 ```typescript
-import { getCurrentLocale } from 'tang-ui-x'
+import { getCurrentLocale } from "tang-ui-x";
 
-const locale = getCurrentLocale()
+const locale = getCurrentLocale();
 ```
 
 #### Q: 支持哪些语言？
@@ -999,8 +1015,8 @@ i18n 系统已在以下平台测试并验证：
 
 ```typescript
 // ✓ 使用静态导入（跨平台兼容）
-import zhCNCommon from '../locales/zh-CN/common.json'
-import enUSCommon from '../locales/en-US/common.json'
+import zhCNCommon from "../locales/zh-CN/common.json";
+import enUSCommon from "../locales/en-US/common.json";
 
 // ✗ 避免动态导入（小程序不支持）
 // const module = await import(`../locales/${locale}/common.json`)
@@ -1016,8 +1032,8 @@ i18n 系统使用同步初始化方式，避免异步操作可能带来的平台
 
 ```typescript
 // 同步初始化，所有平台都支持
-import { useI18n } from 'tang-ui-x'
-const { $t } = useI18n()
+import { useI18n } from "tang-ui-x";
+const { $t } = useI18n();
 ```
 
 **4. JSON 文件处理**
@@ -1076,7 +1092,7 @@ function switchLanguage(lang: string) {
     <button @click="switchLanguage('zh-CN')">中文</button>
     <button @click="switchLanguage('en-US')">English</button>
     <button @click="switchLanguage('zh-TW')">繁體中文</button>
-    
+
     <text>当前语言: {{ locale }}</text>
   </view>
 </template>
@@ -1094,6 +1110,7 @@ function switchLanguage(lang: string) {
 ## 📚 组件列表
 
 ### 基础组件 (5个)
+
 - TButton - 按钮
 - TIcon - 图标
 - TText - 文本
@@ -1101,6 +1118,7 @@ function switchLanguage(lang: string) {
 - TDivider - 分割线
 
 ### 布局组件 (8个)
+
 - TCard - 卡片
 - TList - 列表
 - TListItem - 列表项
@@ -1111,6 +1129,7 @@ function switchLanguage(lang: string) {
 - TCol - 栅格列
 
 ### 表单组件 (13个)
+
 - TInput - 输入框
 - TNumberInput - 数字输入
 - TTextarea - 多行文本输入
@@ -1126,6 +1145,7 @@ function switchLanguage(lang: string) {
 - TPicker - 选择器
 
 ### 数据展示 (9个)
+
 - Tags - 标签
 - TBadge - 徽标
 - TAvatar - 头像
@@ -1138,6 +1158,7 @@ function switchLanguage(lang: string) {
 - TSwiper - 轮播图
 
 ### 反馈组件 (5个)
+
 - TLoading - 加载
 - TToast - 轻提示
 - TDialog - 对话框
@@ -1145,6 +1166,7 @@ function switchLanguage(lang: string) {
 - TActionSheet - 动作面板
 
 ### 导航组件 (2个)
+
 - Tabs - 标签页
 - TNavBar - 导航栏