frontend/QUICK_REFERENCE.md

🚀 VaultScreen 优化 - 快速参考

一分钟快速开始

1. 导入新组件

import { VaultButton, LabeledInput, AssetCard } from '@/components/vault';
import { useAddFlow, useMnemonicFlow } from '@/hooks/vault';

2. 使用 Hooks

// 替换 8 个状态变量
const addFlow = useAddFlow();

// 替换 8 个助记词相关状态
const mnemonicFlow = useMnemonicFlow();

3. 快速替换示例

你想替换	用这个	代码行数减少
按钮	<VaultButton>	15 行 → 3 行
输入框	<LabeledInput>	8 行 → 5 行
资产卡片	<AssetCard>	66 行 → 5 行
状态管理	useAddFlow()	8 个变量 → 1 个对象

---

📋 组件速查表

VaultButton

// Primary 按钮（渐变蓝色）
<VaultButton variant="primary" icon="plus" onPress={handleAdd}>
  Add Treasure
</VaultButton>

// Secondary 按钮（透明背景）
<VaultButton variant="secondary" onPress={handleCancel}>
  Cancel
</VaultButton>

// Danger 按钮（红色）
<VaultButton variant="danger" loading={isDeleting} onPress={handleDelete}>
  Delete
</VaultButton>

// Ghost 按钮（完全透明）
<VaultButton variant="ghost" onPress={handleBack}>
  Back
</VaultButton>

Props:

• variant: 'primary' | 'secondary' | 'danger' | 'ghost'
• icon: Feather icon 名称（可选）
• loading: boolean（显示加载动画）
• disabled: boolean
• fullWidth: boolean
• onPress: () => void

---

LabeledInput

// 单行输入
<LabeledInput
  label="TITLE"
  placeholder="Enter title"
  value={value}
  onChangeText={setValue}
/>

// 多行输入
<LabeledInput
  label="CONTENT"
  value={content}
  onChangeText={setContent}
  multiline
/>

// 带错误提示
<LabeledInput
  label="EMAIL"
  value={email}
  onChangeText={setEmail}
  error={emailError}
/>

Props:

• label: string
• placeholder: string（可选）
• value: string
• onChangeText: (text: string) => void
• multiline: boolean（可选）
• error: string（可选）
• 支持所有 TextInput 的 props

---

AssetCard

<AssetCard
  asset={asset}
  index={index}
  onPress={handleOpenDetail}
/>

Props:

• asset: VaultAsset 对象
• index: number（用于动画延迟）
• onPress: (asset: VaultAsset) => void

特性:

• ✅ 自动入场动画
• ✅ 显示资产类型图标
• ✅ 显示创建日期
• ✅ 加密状态徽章

---

🎣 Hooks 速查表

useAddFlow

const addFlow = useAddFlow();

// 访问状态
addFlow.state.step          // 当前步骤 (1-3)
addFlow.state.label         // 标题
addFlow.state.content       // 内容
addFlow.state.selectedType  // 资产类型
addFlow.state.verified      // 是否已验证
addFlow.state.method        // 'text' | 'file' | 'scan'
addFlow.state.accountProvider // 'bank' | 'steam' | 'facebook' | 'custom'

// 更新状态
addFlow.setStep(2)
addFlow.setLabel('My Treasure')
addFlow.setContent('Secret content')
addFlow.setType('private_key')
addFlow.setVerified(true)
addFlow.setMethod('text')
addFlow.setProvider('bank')

// 工具方法
addFlow.canProceed()  // 检查是否可以进入下一步
addFlow.reset()       // 重置所有状态

---

useMnemonicFlow

const mnemonicFlow = useMnemonicFlow();

// 访问状态
mnemonicFlow.state.words         // 助记词数组
mnemonicFlow.state.parts         // 分组后的助记词
mnemonicFlow.state.step          // 步骤 (1-5)
mnemonicFlow.state.heirStep      // 继承人步骤
mnemonicFlow.state.replaceIndex  // 替换的单词索引
mnemonicFlow.state.progressIndex // 进度索引
mnemonicFlow.state.isCapturing   // 是否正在截图

// 更新状态
mnemonicFlow.setWords(words)
mnemonicFlow.setParts(parts)
mnemonicFlow.setStep(2)
mnemonicFlow.setHeirStep('asset')
mnemonicFlow.replaceWord(3, 'newWord')

// 工具方法
mnemonicFlow.reset()  // 重置所有状态

---

🎨 样式使用

import { modalStyles } from '@/styles/vault/modalStyles';

// 在 Modal 中使用
<View style={modalStyles.modalOverlay}>
  <View style={modalStyles.modalContent}>
    <View style={modalStyles.modalHandle} />
    <View style={modalStyles.modalHeader}>
      <Text style={modalStyles.modalTitle}>Title</Text>
    </View>
  </View>
</View>

---

💻 常见替换模式

模式 1: 按钮组替换

之前:

<View style={styles.modalButtons}>
  <TouchableOpacity style={styles.cancelButton} onPress={handleCancel}>
    <Text style={styles.cancelButtonText}>Cancel</Text>
  </TouchableOpacity>
  <TouchableOpacity style={styles.confirmButton} onPress={handleConfirm}>
    <LinearGradient colors={[...]} style={styles.confirmButtonGradient}>
      <Text style={styles.confirmButtonText}>Confirm</Text>
    </LinearGradient>
  </TouchableOpacity>
</View>

之后:

<View style={styles.modalButtons}>
  <VaultButton variant="secondary" onPress={handleCancel} fullWidth>
    Cancel
  </VaultButton>
  <VaultButton variant="primary" onPress={handleConfirm} fullWidth>
    Confirm
  </VaultButton>
</View>

---

模式 2: 表单输入替换

之前:

<Text style={styles.modalLabel}>TITLE</Text>
<TextInput
  style={styles.input}
  placeholder="Enter title"
  placeholderTextColor={colors.nautical.sage}
  value={title}
  onChangeText={setTitle}
/>
<Text style={styles.modalLabel}>CONTENT</Text>
<TextInput
  style={[styles.input, styles.inputMultiline]}
  placeholder="Enter content"
  value={content}
  onChangeText={setContent}
  multiline
/>

之后:

<LabeledInput label="TITLE" placeholder="Enter title" value={title} onChangeText={setTitle} />
<LabeledInput label="CONTENT" placeholder="Enter content" value={content} onChangeText={setContent} multiline />

---

模式 3: 状态管理替换

之前:

const [step, setStep] = useState(1);
const [verified, setVerified] = useState(false);
const [label, setLabel] = useState('');

// 使用
if (step === 1) { /* ... */ }
setStep(2);
setLabel('New Value');

之后:

const flow = useAddFlow();

// 使用
if (flow.state.step === 1) { /* ... */ }
flow.setStep(2);
flow.setLabel('New Value');

---

⚡ 性能优化 Tips

// 1. 使用 useCallback 包装事件处理函数
const handleOpenDetail = useCallback((asset: VaultAsset) => {
  setSelectedAsset(asset);
  setShowDetail(true);
}, []);

// 2. 使用 React.memo 包装组件
const AssetList = React.memo(({ assets, onPress }) => (
  assets.map((asset, index) => (
    <AssetCard key={asset.id} asset={asset} index={index} onPress={onPress} />
  ))
));

// 3. 延迟加载大型模态框
const AddTreasureModal = React.lazy(() => import('./modals/AddTreasureModal'));

---

📦 完整示例

import React, { useState } from 'react';
import { View, ScrollView } from 'react-native';
import { VaultButton, LabeledInput, AssetCard } from '@/components/vault';
import { useAddFlow } from '@/hooks/vault';

export default function VaultScreen() {
  const addFlow = useAddFlow();
  const [showModal, setShowModal] = useState(false);

  return (
    <View style={{ flex: 1 }}>
      <ScrollView>
        {assets.map((asset, index) => (
          <AssetCard
            key={asset.id}
            asset={asset}
            index={index}
            onPress={handleOpenDetail}
          />
        ))}
      </ScrollView>

      <VaultButton
        variant="primary"
        icon="plus"
        onPress={() => {
          addFlow.reset();
          setShowModal(true);
        }}
      >
        Add Treasure
      </VaultButton>
    </View>
  );
}

---

📚 完整文档

• 📖 VAULT_REFACTOR_GUIDE.md - 完整重构指南
• 💡 VAULT_USAGE_EXAMPLE.tsx - 实用代码示例
• 📝 VAULT_OPTIMIZATION_SUMMARY.md - 优化总结

---

快速开始，立即提升代码质量！ ⚡