Skip to main content

JapaneseText2 组件迁移指南

🔄 迁移概述​

新的优化版本完全向后兼容，你可以直接替换现有的组件使用，无需修改任何代码。同时，新版本提供了许多增强功能。

📋 兼容性对比​

✅ 完全兼容的功能​

所有原有的 props 都保持不变：

// 旧版本的用法完全适用于新版本
<JapaneseText2
    texts={["こんにちは"]}
    translations={["你好"]}
    annotations={[{"こんにちは": "こんにちは"}]}
    notes={{0: {"こんにちは": "日语的问候语"}}}
/>

🆕 新增功能​

1. 增强的笔记系统​

// 新版本支持更丰富的笔记数据
<JapaneseText2
    notes={[
        [
            {
                text: "こんにちは",
                note: "日语最常用的问候语",
                type: "vocabulary",        // 新增：笔记类型
                difficulty: "beginner",    // 新增：难度级别
                tags: ["问候", "日常"]     // 新增：标签
            }
        ]
    ]}
/>

2. 用户偏好设置​

<JapaneseText2
    initialPreferences={{
        display: {
            showFurigana: true,
            showTranslation: true,
            showNotes: true,
            showLineNumbers: false,    // 新增：行号显示
            compactMode: false         // 新增：紧凑模式
        },
        typography: {
            fontSize: "medium",        // 新增：字体大小
            lineSpacing: "normal"      // 新增：行间距
        },
        interaction: {
            keyboardShortcuts: true,   // 新增：键盘快捷键
            animationSpeed: "normal"   // 新增：动画速度
        },
        accessibility: {
            screenReaderOptimized: false,  // 新增：屏幕阅读器优化
            highContrast: false,           // 新增：高对比度
            reducedMotion: false           // 新增：减少动画
        }
    }}
/>

3. 事件回调​

<JapaneseText2
    onPreferenceChange={(preferences) => {
        console.log('用户偏好已更改:', preferences);
    }}
    onError={(error, context) => {
        console.error('组件错误:', error, context);
    }}
/>

🚀 迁移步骤​

步骤 1：直接替换​

现有的代码无需任何修改即可使用新组件：

// 原有代码保持不变
import JapaneseText2 from '@site/src/components/Language/JapaneseText2';

<JapaneseText2
    texts={["今日はいい天気ですね"]}
    translations={["今天天气真好呢"]}
    annotations={[{"今日": "きょう", "天気": "てんき"}]}
    notes={{0: {"今日": "今天", "天気": "天气"}}}
/>

步骤 2：启用新功能（可选）​

根据需要添加新的配置选项：

<JapaneseText2
    // 原有 props 保持不变
    texts={["今日はいい天気ですね"]}
    translations={["今天天气真好呢"]}
    annotations={[{"今日": "きょう", "天気": "てんき"}]}
    notes={{0: {"今日": "今天", "天気": "天气"}}}
    
    // 新增配置（可选）
    initialPreferences={{
        display: {
            showLineNumbers: true,  // 显示行号
            compactMode: false      // 非紧凑模式
        },
        typography: {
            fontSize: "large"       // 大字体
        }
    }}
    
    // 新增事件处理（可选）
    onPreferenceChange={(prefs) => {
        localStorage.setItem('userPrefs', JSON.stringify(prefs));
    }}
/>

📊 功能对比表​

功能旧版本新版本说明
基础文本显示✅✅完全兼容
注音显示✅✅完全兼容
翻译显示✅✅完全兼容
笔记功能✅✅完全兼容 + 增强
响应式设计✅✅大幅改进
键盘导航❌✅新增功能
用户偏好❌✅新增功能
错误处理基础完善大幅改进
性能优化基础高级大幅改进
无障碍支持基础完善大幅改进
移动端优化基础完善大幅改进

🎯 推荐的迁移策略​

阶段 1：无缝替换​

  • 直接使用新组件，无需修改现有代码
  • 验证所有功能正常工作

阶段 2：启用基础新功能​

  • 添加 showLineNumbers: true 显示行号
  • 设置合适的 fontSize 和 lineSpacing
  • 启用 keyboardShortcuts: true

阶段 3：优化用户体验​

  • 根据用户反馈调整默认设置
  • 添加偏好设置变更的事件处理
  • 启用无障碍功能（如需要）

阶段 4：充分利用高级功能​

  • 使用增强的笔记系统（类型、难度、标签）
  • 实现用户偏好的持久化存储
  • 添加错误监控和处理

🔍 常见问题​

Q: 新组件会影响现有页面的样式吗？​

A: 不会。新组件保持了与旧版本相同的默认样式，同时提供了更好的响应式支持。

Q: 如何禁用新功能，保持原有行为？​

A: 新功能默认都是关闭或兼容模式，你无需做任何配置。

Q: 性能会有影响吗？​

A: 新版本的性能更好，特别是在处理大量文本时。

Q: 移动端体验有什么改进？​

A: 新版本提供了更好的触摸交互、响应式布局和移动端专用的笔记面板。

📝 示例：完整迁移​

这里是一个完整的迁移示例，展示如何从基础用法逐步启用新功能：

📝

没有文本内容

请提供要显示的日文文本。

通过这种渐进式的迁移方式，你可以在保持现有功能稳定的同时，逐步享受新版本带来的增强体验。