operp-print-designer 1.1.4 → 1.1.6

package/README.md

@@ -58,6 +58,83 @@ function Previewer() {
 | `dataSource` | `PrintDesignerDataSource` | 否 | 外部数据源，传入后优先于模板内部数据源用于渲染和打印 |
 | `onSave` | `(data: TemplateData) => void` | 否 | 保存回调函数，当用户点击保存按钮时触发 |
 | `onPrint` | `() => void` | 否 | 打印回调函数，当用户点击打印按钮时触发 |
+| `locale` | `'zh-CN' \| 'en-US' \| 'ja-JP' \| 'auto'` | 否 | 界面语言，默认 `'zh-CN'`；传 `'auto'` 自动跟随宿主应用语言 |
+
+## 多语言（i18n）
+
+组件内置基于 [i18next](https://www.i18next.com/) 的多语言支持，目前提供 **简体中文 / English / 日本語** 三种语言。
+只需传入 `locale` 属性即可切换语言，组件内部全部界面文案（工具栏、面板标题、属性项、按钮、提示、弹窗等）以及 antd 内置文案（ColorPicker、Empty、Popconfirm 等）都会同步切换。
+
+```tsx
+import { useState } from 'react';
+import PrintDesigner, { type Locale } from 'operp-print-designer';
+
+function App() {
+  const [locale, setLocale] = useState<Locale>('zh-CN');
+
+  return (
+    <PrintDesigner
+      locale={locale}           // 'zh-CN' | 'en-US' | 'ja-JP'
+      initialTemplateData={templateData}
+      onSave={(data) => console.log(data)}
+    />
+  );
+}
+```
+
+### 切换语言
+
+`locale` 是响应式属性，改变后组件会立即重新渲染并切换文案：
+
+```tsx
+<button onClick={() => setLocale(locale === 'zh-CN' ? 'en-US' : 'zh-CN')}>切换语言</button>
+```
+
+### 自动跟随宿主语言（`locale="auto"`）
+
+宿主应用自己有多语言切换时，传 `'auto'` 即可让设计器跟随，**无需自己同步状态**：
+
+```tsx
+<PrintDesigner locale="auto" />
+```
+
+探测优先级（高 → 低）：
+
+1. 宿主的 i18next 实例（`<I18nextProvider>` 注入的、或 `i18next.use(initReactI18next).init()` 初始化的、或仅 `i18next.init()` 的全局单例），并订阅其 `languageChanged` 事件实时跟随；
+2. `<html lang>`（监听其变化）；
+3. `navigator.language`（监听浏览器的 `languagechange` 事件）；
+4. 都未命中时回退 `'zh-CN'`。
+
+语言写法兼容 `'zh'` / `'en'` / `'ja'` / `'zh_CN'` / `'zh-Hant'` 等，自动归一化到最近的支持语言。
+不使用 i18next 的宿主也可以显式传具体语言：`<PrintDesigner locale={currentLang} />`。
+
+### 语言相关导出
+
+```tsx
+import {
+  printDesignerI18n,         // 组件库内部独立的 i18next 实例
+  DEFAULT_LOCALE,            // 'zh-CN'
+  SUPPORTED_LOCALES,         // ['zh-CN', 'en-US', 'ja-JP']
+  LOCALE_NAMES,              // { 'zh-CN': '简体中文', 'en-US': 'English', 'ja-JP': '日本語' }
+  matchLocale,               // 匹配不到返回 null（不做兜底），供自定义探测逻辑使用
+  normalizeLocale,           // 兼容 'zh' / 'zh_cn' / 'en' 等写法，归一化为标准 locale
+  detectEnvironmentLocale,   // 从 <html lang> / navigator 探测当前环境语言
+  useResolvedLocale,         // 完整的解析 hook（含跟随宿主变化的逻辑）
+  useHostI18nInstance,       // 读取宿主的 i18next 实例
+} from 'operp-print-designer';
+```
+
+### 注意
+
+- 组件库使用 **独立的 i18next 实例**（`createInstance`）并通过 `I18nextProvider` 注入，不会影响宿主应用自身的 i18n 配置，也不会注册为 react-i18next 的全局实例。
+- `i18next` / `react-i18next` 是 **peerDependencies**（不重复打包），与宿主共用同一份模块实例——这也是 `locale="auto"` 能读到宿主语言的前提。npm 7+ 会自动安装；如使用 pnpm 并关闭了 `auto-install-peers`，请确保宿主已安装这两个包。
+- 语言包使用**平铺键值对**（如 `'toolbar.new'`），需要扩展/覆盖文案时可调用：
+
+```tsx
+printDesignerI18n.addResourceBundle('en-US', 'translation', {
+  'toolbar.new': 'Create',
+}, true, true);
+```
 
 ## 类型定义
 

package/dist/components/PrintDesigner/index.d.ts

@@ -1,5 +1,6 @@
 import React from 'react';
 import { PrintDesignerDataSource, TemplateData } from '../../types';
+import { type LocaleOption } from '../../i18n';
 export interface PrintDesignerProps {
     /** 是否为预览模式（只读） */
     isPreview?: boolean;
@@ -11,6 +12,22 @@ export interface PrintDesignerProps {
     onSave?: (templateData: TemplateData) => void;
     /** 打印回调 */
     onPrint?: () => void;
+    /**
+     * 界面语言。
+     * - 具体语言：`'zh-CN' | 'en-US' | 'ja-JP'`，也兼容 `'zh'` / `'en'` / `'zh_CN'` 等简写
+     * - `'auto'`：自动跟随宿主应用（宿主 i18next 实例 → `<html lang>` → `navigator.language`）
+     * @default 'zh-CN'
+     */
+    locale?: LocaleOption | (string & {});
 }
+/**
+ * 打印设计器入口。
+ *
+ * `locale` 支持三种用法：
+ * - `'zh-CN' | 'en-US' | 'ja-JP'`（默认 `'zh-CN'`）：固定语言；
+ * - `'auto'`：自动跟随宿主应用的语言（宿主 i18next 实例 → `<html lang>` → `navigator.language`），
+ *   宿主切换语言时同步切换；此时无需传 `i18n.language`，宿主零改动即可跟随；
+ * - 其它语言简写（`'zh'` / `'en'` / `'ja'` / `'zh_CN'` 等）：自动归一化。
+ */
 declare const PrintDesigner: React.FC<PrintDesignerProps>;
 export default PrintDesigner;

package/dist/constants/index.d.ts

@@ -1,11 +1,16 @@
-import { PaperSizePreset } from '../types';
+import { PaperSizePreset, CanvasComponentType } from '../types';
 /** 纸张预设尺寸 - 宽高 mm (portrait) */
 export declare const PAPER_SIZES: Record<Exclude<PaperSizePreset, 'custom'>, {
     width: number;
     height: number;
 }>;
-/** 默认页面设置 */
-export declare const DEFAULT_PAGE_SETTINGS: {
+/**
+ * 创建默认页面设置。
+ *
+ * 以函数形式提供，保证页眉/页脚/页码等种子文案随当前语言实时生成，
+ * 而不是在模块加载时被固定成某一种语言。
+ */
+export declare function createDefaultPageSettings(): {
     paperSize: PaperSizePreset;
     customWidth: number;
     customHeight: number;
@@ -28,51 +33,7 @@ export declare const DEFAULT_GRID_SETTINGS: {
     cellSize: number;
     cols: number;
 };
-/** 组件类型中文名 */
-export declare const COMPONENT_TYPE_LABELS: Record<string, string>;
-/** 组件类型默认属性 */
-export declare const COMPONENT_DEFAULTS: {
-    text: {
-        content: string;
-        fontSize: number;
-        fontWeight: "normal";
-        fontStyle: "normal";
-        textAlign: "left";
-        color: string;
-        backgroundColor: string;
-        format: string;
-    };
-    image: {
-        src: string;
-        fit: "contain";
-        content: string;
-    };
-    table: {
-        rows: number;
-        cols: number;
-        borderWidth: number;
-        borderColor: string;
-        headerBackgroundColor: string;
-        headerColor: string;
-        headerFontSize: number;
-        content: string;
-    };
-    barcode: {
-        value: string;
-        format: "CODE128";
-        content: string;
-    };
-    qrcode: {
-        value: string;
-        errorLevel: "M";
-        color: string;
-        backgroundColor: string;
-        content: string;
-    };
-    line: {
-        color: string;
-        thickness: number;
-        style: "solid";
-        content: string;
-    };
-};
+/** 获取组件类型名称（跟随当前语言） */
+export declare function getComponentTypeLabel(type: CanvasComponentType | string): string;
+/** 创建组件类型默认属性（跟随当前语言） */
+export declare function createComponentDefaults(type: CanvasComponentType): Record<string, unknown>;

package/dist/i18n/antdLocale.d.ts

@@ -0,0 +1,7 @@
+import type { Locale as AntdLocale } from 'antd/es/locale';
+import type { Locale } from './index';
+/**
+ * antd 内置文案（ColorPicker、Empty、Table、Popconfirm 等）对应的语言包。
+ * 通过 antd ConfigProvider 注入，使第三方组件文案跟随 locale 切换。
+ */
+export declare const ANTD_LOCALES: Record<Locale, AntdLocale>;

package/dist/i18n/index.d.ts

@@ -0,0 +1,37 @@
+import { type i18n as I18nInstance } from 'i18next';
+/** 支持的Locale */
+export type Locale = 'zh-CN' | 'en-US' | 'ja-JP';
+/** 默认Locale */
+export declare const DEFAULT_LOCALE: Locale;
+/** 全部支持的Locale列表 */
+export declare const SUPPORTED_LOCALES: Locale[];
+/** 各Locale对应的显示名称 */
+export declare const LOCALE_NAMES: Record<Locale, string>;
+/** locale 属性的可取值：具体语言，或 'auto'（自动跟随宿主运行环境） */
+export type LocaleOption = Locale | 'auto';
+/**
+ * 尝试把输入匹配到受支持的 Locale（兼容 zh、zh-CN、zh_cn、zh-Hant、en、ja 等写法）。
+ * 匹配不到返回 null，不做兜底 —— 供「自动探测」按优先级逐个候选源尝试。
+ */
+export declare function matchLocale(locale?: string | null): Locale | null;
+/** 归一化外部传入的 locale（兼容 zh、zh-CN、zh_cn、en、ja 等写法），匹配不到时回退默认语言 */
+export declare function normalizeLocale(locale?: string | null): Locale;
+/**
+ * 从运行环境（DOM / 浏览器）探测语言，作为宿主 i18next 实例不可用时的兜底：
+ * `<html lang>` → `navigator.language` → `navigator.languages`。
+ */
+export declare function detectEnvironmentLocale(): Locale | null;
+/**
+ * 组件库独立 i18n 实例。
+ *
+ * 使用 `createInstance` 而不是 i18next 的默认单例，避免污染宿主应用自己的 i18next 实例。
+ * 组件内部通过 `<I18nextProvider i18n={printDesignerI18n}>` 使用该实例。
+ *
+ * 注意：这里【不能】调用 `.use(initReactI18next)` —— 那会把本实例注册为 react-i18next 的
+ * 全局实例（`setI18n`），导致宿主未初始化 i18n 时 `getI18n()` 读到组件库自己，
+ * 干扰 `locale="auto"` 对宿主语言的探测。组件内部统一由 I18nextProvider 提供实例。
+ */
+export declare const printDesignerI18n: I18nInstance;
+/** 非 React 模块（store / constants）中使用的翻译函数 */
+export declare const t: typeof printDesignerI18n.t;
+export default printDesignerI18n;

package/dist/i18n/locales/en-US.d.ts

@@ -0,0 +1,5 @@
+/**
+ * English (US) language pack (flat key-value pairs)
+ */
+declare const enUS: Record<string, unknown>;
+export default enUS;

package/dist/i18n/locales/ja-JP.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 日本語（ja-JP）言語パック（フラットなキー・バリュー形式）
+ */
+declare const jaJP: Record<string, unknown>;
+export default jaJP;

package/dist/i18n/locales/zh-CN.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 简体中文语言包（平铺键值对）
+ */
+declare const zhCN: Record<string, unknown>;
+export default zhCN;

package/dist/i18n/useResolvedLocale.d.ts

@@ -0,0 +1,23 @@
+import type { i18n as I18nInstance } from 'i18next';
+import { type Locale, type LocaleOption } from './index';
+/**
+ * 读取宿主应用的 i18next 实例，并在宿主切换语言时触发重渲染。
+ *
+ * 取值优先级：
+ * 1. React 上下文里的实例（宿主使用 `<I18nextProvider>` 的场景）；
+ * 2. `initReactI18next` 注册的实例（宿主使用 `i18next.use(initReactI18next).init()` 的场景）；
+ * 3. i18next 全局单例（宿主仅 `i18next.init()` 的场景，且已初始化）。
+ *
+ * 前提：组件库把 i18next / react-i18next 声明为 peerDependency（不重复打包），
+ * 这样宿主与组件库指向同一份模块实例，才能读到宿主的语言。
+ */
+export declare function useHostI18nInstance(): I18nInstance | null;
+/**
+ * 解析最终生效的界面语言。
+ *
+ * - 传入具体语言：归一化后直接使用（兼容 'zh' / 'en' / 'zh_CN' 等写法）；
+ * - 传入 `'auto'`：按「宿主 i18next 实例 → `<html lang>` → `navigator.language`」顺序探测，
+ *   并持续跟随宿主变化（宿主实例的 languageChanged 事件、`<html lang>` 的变更、浏览器语言变化）。
+ */
+export declare function useResolvedLocale(locale?: string): Locale;
+export type { Locale, LocaleOption };

package/dist/index.d.ts

@@ -5,3 +5,6 @@ export type { PrintDesignerProps } from './components/PrintDesigner';
 export type { CanvasComponent, CanvasComponentType, PageSettings, GridSettings, TemplateData, DataSource, DataSourceType, PrintDesignerDataSource, TableColumnConfig, DataBinding, DataBindingConfig, } from './types';
 export { getRenderValue, getObjectFromDataSource, getArrayFromDataSource, formatRenderValue, safeParseJSON, getValueByPath, } from './utils/dataHelper';
 export { useDesignerStore } from './store';
+export { printDesignerI18n, DEFAULT_LOCALE, SUPPORTED_LOCALES, LOCALE_NAMES, matchLocale, normalizeLocale, detectEnvironmentLocale, } from './i18n';
+export type { Locale, LocaleOption } from './i18n';
+export { useResolvedLocale, useHostI18nInstance } from './i18n/useResolvedLocale';