React Native Async Storage API 完全指南

前言

在 React Native 应用开发中，数据持久化是一个非常重要的功能需求。React Native Async Storage 提供了一个简单、异步、持久化的键值存储系统，可以满足大多数应用的基本存储需求。本文将全面介绍 Async Storage 的 API 使用方法，帮助开发者更好地理解和运用这个工具。

基础操作

1. 获取数据 - getItem

getItem 方法用于从存储中获取指定键对应的值。这个方法是异步的，返回一个 Promise 对象。

特点：

• 如果键存在，返回对应的字符串值
• 如果键不存在，返回 null
• 可以捕获读取错误
• 存储对象时需要手动反序列化（使用 JSON.parse）

示例代码：

// 获取字符串值
const getStringValue = async () => {
  try {
    const value = await AsyncStorage.getItem('@my_key');
    console.log('获取到的值:', value);
  } catch (error) {
    console.error('读取错误:', error);
  }
};

// 获取对象值
const getObjectValue = async () => {
  try {
    const jsonValue = await AsyncStorage.getItem('@my_object_key');
    return jsonValue != null ? JSON.parse(jsonValue) : null;
  } catch (error) {
    console.error('读取错误:', error);
  }
};

2. 存储数据 - setItem

setItem 方法用于将数据存储到指定键下。如果键已存在，则会更新对应的值。

特点：

• 存储的值必须是字符串
• 存储对象时需要手动序列化（使用 JSON.stringify）
• 可以捕获存储错误

示例代码：

// 存储字符串
const storeStringValue = async (value) => {
  try {
    await AsyncStorage.setItem('@my_key', value);
    console.log('存储成功');
  } catch (error) {
    console.error('存储错误:', error);
  }
};

// 存储对象
const storeObjectValue = async (value) => {
  try {
    const jsonValue = JSON.stringify(value);
    await AsyncStorage.setItem('@my_object_key', jsonValue);
    console.log('对象存储成功');
  } catch (error) {
    console.error('存储错误:', error);
  }
};

高级操作

3. 合并数据 - mergeItem

mergeItem 方法用于合并现有数据和新的数据，特别适合处理 JSON 格式的数据。

特点：

• 只适用于 JSON 字符串
• 会递归合并对象属性
• 新值会覆盖旧值中相同的属性

示例场景：

const initialUser = {
  name: '张三',
  age: 25,
  profile: {
    gender: 'male',
    hobby: 'reading'
  }
};

const updateData = {
  age: 26,
  profile: {
    hobby: 'swimming'
  }
};

const updateUser = async () => {
  try {
    // 先存储初始数据
    await AsyncStorage.setItem('@user', JSON.stringify(initialUser));
    
    // 合并更新数据
    await AsyncStorage.mergeItem('@user', JSON.stringify(updateData));
    
    // 获取合并后的结果
    const mergedUser = await AsyncStorage.getItem('@user');
    console.log(JSON.parse(mergedUser));
    
    /* 输出结果：
    {
      name: '张三',
      age: 26,
      profile: {
        gender: 'male',
        hobby: 'swimming'
      }
    }
    */
  } catch (error) {
    console.error('操作失败:', error);
  }
};

4. 删除数据 - removeItem

removeItem 方法用于删除指定键的数据。

特点：

• 如果键不存在，不会报错
• 可以捕获删除错误

示例代码：

const removeData = async () => {
  try {
    await AsyncStorage.removeItem('@obsolete_key');
    console.log('删除成功');
  } catch (error) {
    console.error('删除错误:', error);
  }
};

批量操作

Async Storage 提供了一系列批量操作方法，可以显著提高多个键值对操作的效率。

5. 获取所有键 - getAllKeys

getAllKeys 方法返回存储中所有的键。

示例代码：

const listAllKeys = async () => {
  try {
    const keys = await AsyncStorage.getAllKeys();
    console.log('所有存储键:', keys);
  } catch (error) {
    console.error('获取键列表错误:', error);
  }
};

6. 批量获取 - multiGet

multiGet 方法可以一次性获取多个键的值。

示例代码：

const getMultipleValues = async () => {
  try {
    const values = await AsyncStorage.multiGet(['@key1', '@key2', '@key3']);
    console.log('批量获取结果:', values);
    // 输出格式: [['@key1', 'value1'], ['@key2', 'value2'], ['@key3', null]]
  } catch (error) {
    console.error('批量获取错误:', error);
  }
};

7. 批量存储 - multiSet

multiSet 方法可以一次性存储多个键值对。

示例代码：

const storeMultipleValues = async () => {
  try {
    await AsyncStorage.multiSet([
      ['@key1', 'value1'],
      ['@key2', 'value2'],
      ['@key3', 'value3']
    ]);
    console.log('批量存储成功');
  } catch (error) {
    console.error('批量存储错误:', error);
  }
};

8. 批量合并 - multiMerge

multiMerge 方法可以一次性合并多个键的 JSON 数据。

示例代码：

const mergeMultipleData = async () => {
  try {
    await AsyncStorage.multiMerge([
      ['@user1', JSON.stringify({age: 26})],
      ['@user2', JSON.stringify({name: '李四'})]
    ]);
    console.log('批量合并成功');
  } catch (error) {
    console.error('批量合并错误:', error);
  }
};

9. 批量删除 - multiRemove

multiRemove 方法可以一次性删除多个键。

示例代码：

const removeMultipleKeys = async () => {
  try {
    await AsyncStorage.multiRemove(['@temp_key1', '@temp_key2']);
    console.log('批量删除成功');
  } catch (error) {
    console.error('批量删除错误:', error);
  }
};

清空存储

10. 清空所有数据 - clear

clear 方法会清空整个 Async Storage 的所有数据，包括其他库或模块存储的数据，使用需谨慎。

示例代码：

const clearStorage = async () => {
  try {
    await AsyncStorage.clear();
    console.log('存储已清空');
  } catch (error) {
    console.error('清空错误:', error);
  }
};

Hooks 风格 API

Async Storage 还提供了一个实验性的 Hooks API，可以更方便地在函数组件中使用。

11. useAsyncStorage

useAsyncStorage 是一个自定义 Hook，为指定键返回一个包含各种操作方法的对象。

示例代码：

import { useAsyncStorage } from '@react-native-async-storage/async-storage';

function UserProfile() {
  const [name, setName] = useState('');
  const { getItem, setItem } = useAsyncStorage('@user_name');

  // 初始化读取
  useEffect(() => {
    const loadName = async () => {
      try {
        const storedName = await getItem();
        if (storedName) setName(storedName);
      } catch (error) {
        console.error('读取名字错误:', error);
      }
    };
    loadName();
  }, []);

  // 更新名字
  const updateName = async (newName) => {
    try {
      await setItem(newName);
      setName(newName);
    } catch (error) {
      console.error('存储名字错误:', error);
    }
  };

  return (
    <View>
      <Text>当前用户名: {name}</Text>
      <Button 
        title="更新为随机名字"
        onPress={() => updateName(`用户${Math.floor(Math.random() * 100)}`)}
      />
    </View>
  );
}

最佳实践

1. 错误处理：始终使用 try/catch 包裹 Async Storage 操作，防止未处理的 Promise 拒绝
2. 序列化：存储对象时一定要使用 JSON.stringify，读取时使用 JSON.parse
3. 键命名：使用有意义的键名前缀，如 '@app_name:key' 格式，避免冲突
4. 性能优化：对于多个操作，优先使用批量方法（multi*）
5. 清理策略：定期清理不再需要的数据，避免存储空间浪费

总结

React Native Async Storage 提供了一套完整的 API 来满足应用数据持久化的需求。从基本的读写操作到高级的批量处理和合并功能，开发者可以根据具体场景选择最合适的方法。通过本文的介绍，希望您能够更加熟练地使用 Async Storage 来构建更强大的 React Native 应用。