react-hot-toast开发规范：代码风格与最佳实践

【免费下载链接】react-hot-toast Smoking Hot React Notifications 🔥 项目地址: https://gitcode.com/gh_mirrors/re/react-hot-toast

项目概述

react-hot-toast是一个轻量级、可定制的React通知组件库，旨在提供优雅的用户反馈体验。本文档详细介绍了该项目的代码风格与最佳实践，帮助开发者在贡献代码或基于此项目进行二次开发时保持代码质量和一致性。

TypeScript配置规范

项目采用严格的TypeScript配置以确保类型安全和代码质量。核心配置位于tsconfig.json文件中，主要包含以下关键设置：

• "strict": true - 启用所有严格类型检查选项
• "noImplicitReturns": true - 确保函数有明确的返回值
• "noUnusedParameters": true - 禁止未使用的函数参数
• "forceConsistentCasingInFileNames": true - 强制文件名大小写一致

类型定义是项目的重要组成部分，所有公共API都应提供完整的类型定义。例如，src/core/types.ts中定义了Toast和Toaster的核心接口：

export interface Toast {
  type: ToastType;
  id: string;
  toasterId?: string;
  message: ValueOrFunction<Renderable, Toast>;
  icon?: Renderable;
  duration?: number;
  pauseDuration: number;
  position?: ToastPosition;
  removeDelay?: number;
  
  // 其他属性...
}

组件设计规范

功能单一原则

每个组件应专注于单一功能，保持代码简洁和可维护性。项目中的组件结构清晰，如：

• src/components/toaster.tsx - 负责通知容器和布局
• src/components/toast-bar.tsx - 实现单个通知的展示
• src/components/toast-icon.tsx - 处理通知图标渲染

组件接口设计

公共组件应设计清晰的接口，使用TypeScript接口明确定义props类型。例如Toaster组件的接口定义：

export interface ToasterProps {
  position?: ToastPosition;
  toastOptions?: DefaultToastOptions;
  reverseOrder?: boolean;
  gutter?: number;
  containerStyle?: React.CSSProperties;
  containerClassName?: string;
  toasterId?: string;
  children?: (toast: Toast) => React.ReactElement;
}

状态管理规范

项目采用简洁的状态管理模式，核心状态逻辑位于src/core/store.ts。关键规范包括：

• 使用不可变数据模式更新状态
• 提供明确的状态更新函数（Action）
• 分离状态逻辑与UI渲染

动画与交互规范

为确保一致的用户体验，项目制定了明确的动画与交互规范：

减少运动偏好支持

尊重用户系统设置，当检测到"prefers-reduced-motion"时，使用简化动画：

export const prefersReducedMotion = (() => {
  let shouldReduceMotion: boolean | undefined = undefined;
  
  return () => {
    if (shouldReduceMotion === undefined && typeof window !== 'undefined') {
      const mediaQuery = matchMedia('(prefers-reduced-motion: reduce)');
      shouldReduceMotion = !mediaQuery || mediaQuery.matches;
    }
    return shouldReduceMotion;
  };
})();

动画实现方式

使用CSS-in-JS方案（goober）实现组件样式和动画，确保样式隔离和组件自包含：

const activeClass = css`
  z-index: 9999;
  > * {
    pointer-events: auto;
  }
`;

错误处理最佳实践

异常处理

异步操作中应妥善处理异常，如src/core/toast.ts中的promise处理：

toast.promise = <T>(
  promise: Promise<T> | (() => Promise<T>),
  msgs: {
    loading: Renderable;
    success?: ValueOrFunction<Renderable, T>;
    error?: ValueOrFunction<Renderable, any>;
  },
  opts?: DefaultToastOptions
) => {
  // 实现...
  
  promise
    .then((p) => {
      // 成功处理...
    })
    .catch((e) => {
      const errorMessage = msgs.error ? resolveValue(msgs.error, e) : undefined;
      
      if (errorMessage) {
        toast.error(errorMessage, {
          id,
          ...opts,
          ...opts?.error,
        });
      } else {
        toast.dismiss(id);
      }
    });
    
  return promise;
};

错误状态展示

提供明确的错误状态UI，通过src/components/error.tsx组件统一展示错误图标。

性能优化建议

减少不必要渲染

使用React.memo、useCallback和useMemo优化组件性能，避免不必要的重渲染：

const ToastWrapper = React.memo(({
  id,
  className,
  style,
  onHeightUpdate,
  children,
}: ToastWrapperProps) => {
  const ref = React.useCallback(
    (el: HTMLElement | null) => {
      // 实现...
    },
    [id, onHeightUpdate]
  );
  
  // 实现...
});

延迟加载

对于非关键组件或大型功能，考虑使用动态导入实现延迟加载。

文档编写规范

项目文档位于site/pages/docs/目录，遵循以下规范：

• 使用MDX格式编写，支持JSX组件嵌入
• 每个API提供完整的使用示例
• 包含参数说明和返回值描述
• 提供代码示例和效果演示

例如site/pages/docs/version-2.mdx详细介绍了2.0版本的新特性和迁移指南。

版本控制与兼容性

语义化版本

遵循语义化版本控制（SemVer）：

• 主版本号（Major）：不兼容的API变更
• 次版本号（Minor）：向后兼容的功能新增
• 修订号（Patch）：向后兼容的问题修复

兼容性处理

对于重大API变更，提供详细的迁移指南，如site/pages/docs/version-2.mdx中列出了2.0版本的所有breaking changes。

总结

遵循以上开发规范有助于保持react-hot-toast项目的代码质量和可维护性。核心原则包括：

1. 使用TypeScript确保类型安全
2. 保持组件功能单一和接口清晰
3. 优化动画和交互体验
4. 重视错误处理和边界情况
5. 编写完善的文档和示例

更多详细信息可参考项目官方文档：

• 官方文档首页
• API参考
• 代码仓库

【免费下载链接】react-hot-toast Smoking Hot React Notifications 🔥 项目地址: https://gitcode.com/gh_mirrors/re/react-hot-toast