@seaart/language-dialog-embed

SeaArt 网站公共语言选择弹框。包负责语言列表、选中状态、进入/离开动画和弹框生命周期；选择后仅通过 onSelect(locale) 返回语言值。语言 JSON 加载、账号语言保存、Cookie、i18n 状态、缓存刷新与路由跳转都由调用方处理。

安装

pnpm add @seaart/language-dialog-embed

npm 使用

import { openLanguageEmbed } from '@seaart/language-dialog-embed';

const controller = openLanguageEmbed({
  title: '语言',
  currentLocale: 'en',
  async onSelect(locale) {
    // locale 例如 en、ja、zhCN；仅返回字符串。
    await changeLocaleInHostApp(locale);
  },
  onError(error) {
    reportLocaleChangeError(error);
  },
});

controller.close();

浏览器脚本

<script src="./dist/seaart-language.global.js"></script>
<script>
  const controller = SeaArtLanguage.open({
    title: 'Language',
    currentLocale: 'en',
    onSelect(locale) {
      window.location.href = getLocalizedUrl(locale);
    },
  });
</script>

全局对象为 SeaArtLanguage，其 open 方法等同于 openLanguageEmbed。

初始化参数

openLanguageEmbed(options) 与 SeaArtLanguage.open(options) 支持以下参数：

| 参数 | 类型 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | --- | | onSelect | (locale: string) => void \| Promise<void> | 是 | - | 用户选择语言后触发，只返回语言值。Promise 成功 resolve 后自动关闭。 | | currentLocale | string | 否 | '' | 当前选中语言，用于高亮与勾选。 | | languages | LanguageOption[] | 否 | DEFAULT_LANGUAGES | 可选语言列表；未传时使用主站当前 16 种语言。 | | title | string | 否 | 'Language' | 弹框标题。调用方可传入已翻译的文案。 | | onClose | () => void | 否 | - | 弹框完全关闭并移除 DOM 后触发，包括选择成功后的自动关闭。 | | onError | (error: unknown) => void | 否 | - | onSelect 抛错或 Promise reject 时触发；弹框保持打开。 | | className | string | 否 | - | 添加到最外层 .seaart-language-embed.el-overlay 节点的自定义 class。 |

语言列表

languages 的结构：

type LanguageOption = {
  value: string;
  label: string;
};

openLanguageEmbed({
  currentLocale: 'zhCN',
  languages: [
    { value: 'en', label: 'English' },
    { value: 'zhCN', label: '中文' },
  ],
  onSelect(locale) {},
});

默认语言值与主站保持一致：en、ja、ar、ko、de、fr、ru、es、pt、th、indo、vi、tr、it、zhCN、zhTW。默认展示为各语言原生名称。

回调与控制器

onSelect 只接收一个参数：

| 参数 | 类型 | 说明 | | --- | --- | --- | | locale | string | 用户选择的语言值，例如 zhCN。 |

选择当前已选中的语言不会触发 onSelect。选择其他语言时，列表会进入 loading 状态，直到 onSelect 完成。

打开后返回 LanguageEmbedController：

| 方法 | 参数 | 说明 | | --- | --- | --- | | close() | - | 播放关闭动画，结束后移除弹框并触发 onClose。 | | update(options) | Partial<Omit<LanguageEmbedOptions, 'onSelect'>> | 更新标题、当前语言、语言列表、onClose、onError 或 class，并重新渲染；不能替换 onSelect。关闭过程中调用无效。 |

主站接入边界

当前主站的语言切换还会保存账号设置、写入 lang Cookie 与 localStorage、加载 i18n JSON、切换语言路由并刷新菜单/SEO 缓存。这些业务不在公共包内，应由 onSelect 的调用方自行处理：

openLanguageEmbed({
  currentLocale: getCurrentLocale(),
  async onSelect(locale) {
    if (isLoggedIn()) {
      await saveAccountLocale({ lang: locale });
    }
    await loadLocaleMessages(locale);
    persistLocale(locale);
    navigateToLocale(locale);
  },
});

运行行为

• 仅可在浏览器中调用，需要 window 与 document。
• 点击遮罩空白区域、关闭按钮或按 Esc 会关闭弹框。
• 弹框使用主站 Element Plus 风格的 el-overlay / el-dialog DOM class，遮罩带高斯模糊；进入和离开动画均为 300ms。
• onSelect 成功后关闭；失败时保留弹框，调用方可通过 onError 展示错误提示。

测试与构建

pnpm --filter @seaart/language-dialog-embed typecheck
pnpm --filter @seaart/language-dialog-embed test
pnpm --filter @seaart/language-dialog-embed build

License

UNLICENSED