AWS Amplify UI React Core 3.4.1 版本发布：增强存储浏览器组件控制能力

AWS Amplify 是一个由亚马逊提供的开发平台，旨在帮助开发者快速构建可扩展的全栈应用程序。其中的 UI 组件库提供了丰富的预构建组件，可以轻松集成到 React、Vue 等前端框架中。本次发布的 @aws-amplify/ui-react-core@3.4.1 版本主要针对 StorageBrowser 组件进行了功能增强。

存储浏览器组件的新特性

StorageBrowser 是 AWS Amplify UI 中用于浏览和管理云存储内容的组件。在本次更新中，开发团队为该组件新增了三个重要属性，使其具备了更灵活的控制能力：

1. defaultValue：用于设置组件的初始值
2. value：用于实现受控组件的当前值
3. onValueChange：值变化时的回调函数

这些新特性使得 StorageBrowser 组件现在可以支持两种使用模式：受控组件模式和非受控组件模式。

受控组件模式实现

受控组件模式下，组件的状态完全由父组件控制。这在需要与其他组件状态同步或实现复杂交互时非常有用。以下是使用 Next.js 实现的受控组件示例：

'use client';

import React from 'react';
import { useRouter, usePathname, useSearchParams } from 'next/navigation';

import { StorageBrowser } from '@aws-amplify/ui-react-storage';
import { StorageBrowserEventValue } from '@aws-amplify/ui-react-storage/browser';

export default function Page() {
  const router = useRouter();
  const pathname = usePathname();
  const params = useSearchParams();

  const value = params.get('value');

  const handleValueChange = React.useCallback(
    (nextValue: StorageBrowserEventValue) => {
      const nextParams = new URLSearchParams();
      nextParams.set('value', JSON.stringify(nextValue));

      router.push(`${pathname}?${nextParams.toString()}`);
    },
    [pathname, router]
  );

  return (
    <StorageBrowser
      onValueChange={handleValueChange}
      value={value ? JSON.parse(value) : null}
    />
  );
}

在这个实现中，StorageBrowser 的状态通过 URL 参数持久化，任何状态变化都会更新 URL，实现了完全可控的存储浏览器体验。

非受控组件模式实现

对于简单的使用场景，可以使用 defaultValue 属性来初始化组件状态，而不需要完全控制组件的每个状态变化：

'use client';

import { StorageBrowser } from '@aws-amplify/ui-react-storage';
import { useSearchParams } from 'next/navigation';

export default function Page() {
  const params = useSearchParams();

  const value = params.get('value');

  return <StorageBrowser defaultValue={value ? JSON.parse(value) : null} />;
}

这种模式更加简洁，适用于不需要精确控制组件内部状态的场景。

技术实现细节

本次更新的核心是为 StorageBrowser 组件添加了 React 标准的受控组件模式支持。技术实现上：

1. 组件内部维护了自己的状态，但当外部传入 value 属性时，会优先使用外部值
2. 状态变化时，会优先调用外部传入的 onValueChange 回调
3. 通过 TypeScript 类型确保了值类型的严格性，StorageBrowserEventValue 类型定义了所有可能的状态值

这种实现方式既保持了组件的易用性，又提供了足够的灵活性来满足复杂场景的需求。

适用场景与最佳实践

新的控制特性特别适用于以下场景：

1. 状态持久化：如示例所示，可以将组件状态保存在 URL 或本地存储中
2. 多组件协同：多个 StorageBrowser 组件可以共享状态
3. 复杂表单集成：作为大型表单的一部分，与其他表单元素状态同步

最佳实践建议：

• 对于简单场景，使用 defaultValue 初始化即可
• 需要精确控制或与其他状态同步时，使用受控模式
• 注意性能优化，避免在 onValueChange 中执行昂贵操作

总结

AWS Amplify UI React Core 3.4.1 版本的这一更新，使得 StorageBrowser 组件更加灵活和强大。通过支持受控和非受控两种模式，开发者可以根据具体需求选择最适合的使用方式。这一改进体现了 AWS Amplify 团队对开发者体验的持续关注，使得在 React 应用中集成云存储功能变得更加简单和高效。