gluestack-components

用途

gluestack-components 是一项围绕 gluestack-ui 组件库的使用知识，用于在 React 与 React Native 平台上构建可访问、性能良好的界面。gluestack-ui 提供 50 多个无样式、可访问的组件，可在 Web 与移动端无缝工作。组件可以复制粘贴到项目中，并使用 NativeWind（React Native 版的 Tailwind CSS）进行样式化。

主要能力

组件通过 CLI 安装：

初始化：

npx gluestack-ui init

添加单个组件：

npx gluestack-ui add button
npx gluestack-ui add input
npx gluestack-ui add modal

添加多个组件：

npx gluestack-ui add button input select modal

添加全部组件：

npx gluestack-ui add --all

每个组件遵循一致的组合模式，由子组件构成，例如 Button 搭配 ButtonText、ButtonSpinner、ButtonIcon 使用。组件支持统一的属性 API：

variant 变体：solid、outline、link
size 尺寸：xs、sm、md、lg、xl
action 语义色：primary、secondary、positive、negative

文档涵盖的核心组件包括：Button（含加载状态与图标）、Input（搭配 FormControl 的标签与校验）、Select（下拉选择）、Modal（对话框）、Toast（通知）、Accordion（可展开内容区）、Checkbox 与 Radio（选择控件）。

使用方式与示例

Button 示例（含加载状态）：

import { Button, ButtonText, ButtonSpinner, ButtonIcon } from '@/components/ui/button';
import { SaveIcon } from 'lucide-react-native';

function SaveButton({ isLoading, onPress }: { isLoading: boolean; onPress: () => void }) {
  return (
    <Button
      size="md"
      variant="solid"
      action="primary"
      isDisabled={isLoading}
      onPress={onPress}
    >
      {isLoading ? (
        <ButtonSpinner />
      ) : (
        <ButtonIcon as={SaveIcon} />
      )}
      <ButtonText>{isLoading ? 'Saving...' : 'Save'}</ButtonText>
    </Button>
  );
}

Input 搭配 FormControl 实现标签、帮助文本与错误提示；Select 使用 SelectTrigger、SelectPortal、SelectContent、SelectItem 等组合；Modal 使用 ModalBackdrop、ModalContent、ModalHeader、ModalBody、ModalFooter；Toast 通过 useToast 触发；Accordion 支持 type="multiple" 与展开状态渲染；Checkbox 与 Radio 通过 Indicator 和 Icon 组合。

最佳实践

用组合代替配置：优先使用子组件组合，如 <Button><ButtonIcon as={PlusIcon} /><ButtonText>Add</ButtonText></Button>，而非堆砌属性的写法。
表单字段使用 FormControl 包裹，以获得一致的校验体验（isRequired、isInvalid）。
处理平台差异：例如通过 Platform.OS === 'web' 判断调整 Modal 的尺寸。
为异步操作提供加载状态反馈。
在 gluestack-ui 之上封装应用级可复用组件，例如 PrimaryButton。

常见模式与限制

常见模式包括带校验的表单（如登录表单）以及带操作按钮的数据列表（编辑、删除）。文档还列出了反模式，例如不要把内联 style 与 NativeWind 的 className 混用，应统一使用 NativeWind 类名。

关于收费、价格、平台支持细节、组件完整清单及性能效果等事实，资料未完整提供，暂未提供。

技能介绍

用途

主要能力

使用方式与示例

最佳实践

常见模式与限制