UI组件移动开发跨平台【免费下载链接】gluestack-uiReact React Native Components Patterns (copy-paste components patterns crafted with Tailwind CSS (NativeWind))项目地址https://gitcode.com/gh_mirrors/gl/gluestack-ui点击查看免费下载本文面向希望在 gluestack-ui 开源仓库中贡献组件、包、文档的开发者与 AI 编程 Agent。文章以仓库内的 .claude/skills/contribute/SKILL.md 为主线系统讲解其定义的子技能体系create-component、enhance-component、create-package、create-docs、test-component、review-pr、前置环境准备yarn、yarn sync、yarn dev、铁律式约束源文件与生成文件分离以及对应的工作流落地方式。读完本文你将掌握如何在 gluestack-ui 中安全、规范、可复用地参与贡献并理解这一套 Agent 技能体系背后的仓库架构与同步引擎原理。一、为什么需要贡献者技能枢纽gluestack-ui 是一个跨平台React Native / Expo / Next.js的 UI 组件库仓库同时维护着多个目的地应用apps/website文档站、apps/kitchen-sink组件展示与测试、apps/starter-kit-next与apps/starter-kit-expo脚手架模板等。向这样的仓库贡献组件最大痛点不是写代码而是在正确的位置写代码、让改动同步到所有应用、并且通过所有测试。为此仓库在 .claude/skills/contribute/SKILL.md 中定义了一个面向 AI Agent 的贡献者技能枢纽Contributor Hub将全部贡献流程组织为/contribute命名空间下的若干子技能/contribute # 主入口即本文档 /create-component # 创建新组件 /enhance-component # 增强现有组件 /create-package # 开发 gluestack-core / gluestack-utils 包 /create-docs # 编写组件文档 /test-component # 跨应用测试组件 /review-pr # PR 提交前自检对应地仓库中每个子技能都有独立的技能文件.claude/skills/create-component/SKILL.md、.claude/skills/enhance-component/SKILL.md、.claude/skills/create-package/SKILL.md、.claude/skills/create-docs/SKILL.md、.claude/skills/test-component/SKILL.md、.claude/skills/review-pr/SKILL.md。这套体系让 Agent 在进入仓库后可以按命令如/create-component触发对应工作流并由 Agent 引导完成全流程。二、六个子技能一览主入口文档按任务类型划分了 6 个可用的子技能命令本节逐一说明其职责与适用场景。1. 组件创建/create-component用于从零创建一个新的 React Native / Expo 组件是整个体系中最重的一个工作流。根据.claude/skills/create-component/SKILL.md的说明Agent 会先进入 Plan Mode分析现有组件模式通过 AskUserQuestion 全面收集需求组件名、分类、用途、动画库偏好等提出并确认组件 API 设计讨论 tradeoffs 与设计决策确保与现有组件的模式一致性按照 compound component API 模式实现生成完整的文档与示例在 kitchen-sink、website 等应用中完成测试。值得注意的是该子技能明确要求6 个确认点不可跳过且实现时必须遵循用户选择的动画库react-native-reanimated 或 legendapp/motion不得擅自替换。2. 组件增强/enhance-component当需要为现有组件增加新特性、新变体或修复缺陷时使用该命令。它的输入是已有组件工作重点是改对位置——即只改源文件src/并通过同步引擎验证改动传播到所有应用。3. 包开发/create-package用于创建或修改packages/gluestack-core组件工厂与 creator与packages/gluestack-utilshooks、aria 工具、NativeWind 工具中的代码。包开发通常配合 yalc 本地链接工作流见下文第四节改动会实时反馈到已链接的应用中。4. 文档/create-docs为组件创建或更新文档内容通常包括示例examples、API 参考、props 说明与最佳实践。文档源文件位于src/components/ui/component/docs/最终会同步到 website 应用。5. 测试/test-component在 kitchen-sink、website、starter-kits 等多个应用中测试组件确保跨平台兼容性iOS / Android / Web。这与仓库的多目的地应用结构直接对应——一个源组件要被同步到多个技术栈各异的应用中运行。6. PR 审查/review-pr提交 pull request 之前执行的预提交检查清单确保代码质量与完整性只提交源文件、无生成文件混入、文档已更新、跨应用测试通过等。三、Quick Start按任务选择命令主入口文档提供了一个简明的任务 → 命令对照表可直接作为日常开发路由当前任务应使用的命令创建新组件/create-component改进现有组件/enhance-component开发包core/utils/create-package编写文档/create-docs测试改动/test-component准备提交 PR/review-pr所有子技能均以层级化方式组织在/contribute命名空间之下主入口只做路由不承载具体实现逻辑——每个命令触发后Agent 会引导完成全过程并具备以下共性特征逐步工作流、模式分析与一致性检查、多重确认点、tradeoff 讨论、自动化实现与完整测试验证。四、前置准备进入贡献工作流前的硬性要求主入口文档的 Important Guidelines 部分是开始一切贡献的前提也是仓库 CONTRIBUTING.md 与 ONBOARDING.md 的核心精神先阅读 CONTRIBUTING.md了解完整的贡献指南安装依赖并完成初始同步yarn与yarn sync启动监听模式yarn dev理解源文件 → 目的地文件文件系统source-to-destination铁律apps/*/components/ui/中的文件是生成文件永远不要直接编辑一律编辑src/中的源文件。4.1 环境初始化命令详解结合根目录 package.json 中的 scripts 配置可以还原完整的初始化步骤# 1. 安装所有工作区依赖仓库使用 yarn workspaces yarn # 2. 一次性同步将 src/ 中的源文件复制到所有 apps/ yarn sync # 3. 启动持续监听watch模式实时同步改动 yarn devyarn sync的实际执行体是 scripts/dev.ts 中的同步模式tsx scripts/dev.ts --sync。它通过 chokidar 扫描src/包括src/components、src/utils、src/docs、src/sidebar.json对每个文件调用各 mapper 的component()或nonComponent()方法处理完成后进程自动退出。而yarn dev则是同一脚本的持久化模式tsx --watch scripts/dev.ts持续监听文件变化并触发同步。4.2 关键开发命令速查以下命令均可在根目录执行来源于 ONBOARDING.md 与 package.json# 监听/同步按 mapper 过滤 yarn dev # 监听全部 mapper yarn dev:website # 仅 website mapper yarn dev:kitchen-sink # 仅 kitchen-sink mapper yarn sync # 一次性全量同步 yarn sync:website # 一次性同步 website yarn sync:kitchen-sink # 一次性同步 kitchen-sink yarn dev --componentbutton # 仅监听某个组件scripts/dev.ts 支持 --component 参数 # 构建与格式化 yarn build # 构建全部包yarn workspaces run build yarn format # prettier --write yarn format:check # prettier --check # 脚手架 yarn create:component # 交互式组件脚手架tsx scripts/create.ts # 版本管理Changesets yarn changeset # 创建 changeset yarn changeset:version # 消费 changesets 并升级版本 yarn changeset:status # 查看 changeset 状态其中yarn create:component对应 scripts/create.ts会交互式询问组件名kebab-case、组件类型等并在src/components/ui/component-name/下生成目录骨架、示例与文档模板。五、底层原理source-to-destination 同步引擎理解这套 Agent 工作流绕不开其背后的源文件 → 目的地文件生成系统。这是 CONTRIBUTING.md 与 ONBOARDING.md 共同强调的架构基石。5.1 目录职责划分gluestack-ui/ ├── src/ # 源文件唯一事实来源 single source of truth │ ├── components/ui/ # 核心 UI 组件Button、Input、Modal 等 │ ├── docs-components/ # 文档专用组件 │ ├── docs/ # Markdown/MDX 文档页面 │ └── sidebar.json # 文档侧边栏配置 ├── packages/ # 发布的 npm 包 │ ├── gluestack-core/ # 组件工厂无样式 │ ├── gluestack-utils/ # hooks、aria 工具、NativeWind 工具 │ ├── gluestack-ui/ # CLInpx gluestack-ui init/add/upgrade │ ├── create-gluestack/ # 项目引导npx create-gluestack │ └── ui-next-adapter/ # RNW 组件在 Next.js RSC 中的适配层 ├── apps/ # 目的地应用生成文件所在地 │ ├── website/ # 文档站Next.js │ ├── kitchen-sink/ # 组件展示与测试Expo │ ├── starter-kit-next/ # Next.js 脚手架模板 │ └── starter-kit-expo/ # Expo 脚手架模板 └── scripts/ # 同步引擎 ├── dev.ts # 监听 src/驱动 mappers ├── create.ts # 新组件脚手架 └── mappers/ # 各应用专属同步逻辑铁律apps/*/components/ui/中的内容被 .gitignore 忽略一旦你手动修改了那里的文件下一次yarn sync就会被覆盖。因此永远只编辑src/。5.2 同步流程scripts/dev.ts 使用 chokidar 监听src/保存文件后触发以下流程解析路径判断是组件文件src/components/ui/button/index.tsx→ 组件button还是非组件文件docs、sidebar.json对所有激活的 mapper 调用mapper.component(button, changed)或mapper.nonComponent(filePath)每个 mapper 将文件复制到各自的目的地应用并剔除自身不需要的文件。从源码可以看到三个关键细节防抖DEBOUNCE_DELAY 10001 秒避免高频保存触发重复处理冷却PROCESSED_FILE_COOLDOWN 30003 秒防止同一文件反复处理造成死循环过滤器支持--mappername与--componentname命令行参数分别用于只运行某个 mapper 或只处理某个组件。5.3 四个 mapper 的分工scripts/mappers/index.ts 注册了 4 个 mapper与 ONBOARDING.md 中的描述一致Mapper复制到复制内容kitchen-sinkapps/kitchen-sink/组件代码并依据 sidebar 自动生成_layout.tsx路由与components-list.tswebsiteapps/website/文档、示例、sidebar.jsonstarter-kitsNext Expo 脚手架应用仅组件代码starter-kit-expo-uniwindapps/starter-kit-expo-uniwind/组件代码UniWind 版本以 kitchen-sink mapper 为例其配置见scripts/mappers/kitchen-sink/componentsOperations.ts明确指定了源路径与目的地路径并忽略docs、examples、dependencies.json这类非组件文件const mapperConfig { sourcePath: path.resolve(src/components/ui), destPath: path.resolve(apps/kitchen-sink/components/ui), ignoreFiles: [docs, examples, dependencies.json], };5.4 生成文件的 .gitignore 保护每个目的地应用都配置了 gitignore 规则防止生成文件被误提交见 CONTRIBUTING.mdwebsite 应用忽略components/ui/、components/docs-components/、sidebar.json其他应用忽略components/ui/。这就保证了 git 历史里只包含源文件改动yarn sync即可随时在本地重建全部生成文件。六、两层组件架构Agent 实现组件的核心模式/create-component工作流强调遵循 compound component API 模式。这套模式在 ONBOARDING.md 中被概括为两层架构creator纯逻辑、零样式与 styled component纯样式。6.1 第一层Creatorpackages/gluestack-core/creator 是一个工厂函数接收原生组件Pressable、View、Text、ActivityIndicator返回带有交互状态管理、可访问性与 Context 的复合组件。以packages/gluestack-core/src/button/creator/index.tsx为例export function createButton({ Root, Text, Group, Spinner, Icon }) { const Button ButtonMain(Root); // 包裹 Rootpress/hover/focus/aria Button.Text ButtonText(Text); // 读取 Button context传递状态 props Button.Group ButtonGroup(Group); // 处理间距、依附、反转 Button.Spinner ButtonSpinner(Spinner); Button.Icon ButtonIcon(Icon); return Button; }主包装器使用gluestack-ui/utils/aria提供的usePress、useHover、useFocus、useFocusRing将交互状态以数据属性data-hover、data-focus、data-active、data-disabled、data-focus-visible的形式同时写入 React Native 的dataSet与 DOM 属性并通过 React Context 共享给子组件Text、Icon、Spinner。子组件通过 Context 读取状态并回传给被包裹的组件例如 ButtonText 会把 hover/focus/active/disabled 状态透传为data-hovertrue等属性从而让 NativeWind 能通过data-[hovertrue]:bg-primary/90这类选择器精准命中交互态样式。6.2 第二层样式组件src/components/ui/可复制粘贴copy-pasteable的组件文件调用 creator 时传入 React Native 原生组件再用tva()应用 Tailwind 类。src/components/ui/button/index.tsx是完整范式use client; import { createButton } from gluestack-ui/core/button/creator; import { tva, useStyleContext, withStyleContext } from gluestack-ui/utils/nativewind-utils; import { ActivityIndicator, Pressable, Text, View } from react-native; const SCOPE BUTTON; // 第 1 步用 Style Context 包裹原生组件 const Root withStyleContext(Pressable, SCOPE); // 第 2 步创建无样式的复合组件 const UIButton createButton({ Root: Root, Text, Group: View, Spinner: ActivityIndicator, Icon: StyledUIIcon, }); // 第 3 步用 tva() 定义变体 const buttonStyle tva({ base: rounded-md flex-row items-center justify-center>{ title: ComponentName, path: /ui/docs/components/component }Step 5同步并测试yarn sync # 一次性同步到所有 apps cd apps/kitchen-sink yarn dev # 在 Expo 中测试组件 cd apps/website yarn dev # 测试文档与示例Step 6如引入新 npm 依赖更新packages/gluestack-ui/src/dependencies.ts使 CLI 在用户执行npx gluestack-ui add component时能安装正确的依赖包。八、本地包开发yalc 链接工作流当改动涉及packages/gluestack-core或packages/gluestack-utils时需要在应用内实时看到包内改动这就要用到 yalc 链接工作流仓库使用 yalc 而非 npm link以获得更可靠的依赖解析。# 前置条件全局安装 yalc npm install -g yalc # Step 1构建并发布到 yalc同时启动 watch yarn link:create # Step 2将本地包链接到应用 yarn link:apps根 package.json 中的实现细节yarn link:create实际是concurrently yarn link:create-utils sleep 15 yarn link:create-core——先构建并发布gluestack-ui/utils15 秒后再构建发布gluestack-ui/core两者都处于 watch 模式改动自动重建并重新发布到 yalcyarn link:apps依次执行link:apps-website在apps/website中yalc link gluestack-ui/utils gluestack-ui/core与link:apps-kitchen-sink以及link:apps-src在src中链接这样应用与源组件都能即时拿到包的最新改动。之后的开发体验是修改packages/gluestack-utils/src/或packages/gluestack-core/src/中的文件 → 自动重建并发布到 yalc → 已链接的应用即时生效。开发结束后清理yarn unlink:apps # 移除 yalc 链接应用回退到已发布版本常用变体还包括yarn link:create-utils仅 utils、yarn link:create-core仅 core、yarn link:apps-website仅 website、yarn link:apps-kitchen-sink仅 kitchen-sink等。故障排查三板斧源自 CONTRIBUTING.md# 1. 检查链接是否生效 cd apps/website yalc check # 2. 确认包构建无误 cd packages/gluestack-utils yarn build cd packages/gluestack-core yarn build # 3. 重置与重新链接 yalc clean yarn unlink:apps yarn link:create yarn link:apps九、文档与示例的规范要求9.1 文档结构组件文档源文件放在src/components/ui/component-name/下├── examples/ # 用法示例 │ ├── basic/ │ ├── meta.json # 示例元数据 │ └── template.handlebars └── docs/ # 主文档 └── index.mdx9.2 文档最佳实践提供覆盖不同变体与用例的完整示例以类型与描述完整记录所有 props提供组件使用相关的可访问性accessibility指引包含常见模式与最佳实践新增组件文档时同步更新src/sidebar.json。子技能文档 .claude/skills/create-component/SKILL.md 进一步细化了示例文件格式meta.json必须包含title、description、可选的argTypes以及必需的reactLive列出所有用到的组件template.handlebars以function Example()开头、不含 import 与 export 语句它们都在reactLive中并使用{{size}}、{{variant}}这类 Handlebars 变量对接 argTypes。建议创建 35 个示例覆盖 basic、customized-component、controlled、with-[feature] 与真实业务场景。十、测试在多个应用中验证主入口文档中/test-component的目标是在多个应用中测试确保跨平台兼容性。测试落地路径如下Kitchen Sinkcd apps/kitchen-sink yarn dev主要测试环境包含全部组件的各种配置源文件改动即时热更新最适合组件开发与测试Websitecd apps/website yarn dev完整文档体验包含组件示例与 API 文档最适合文档类改动验证Starter Kits验证组件在全新项目中的可用性、安装流程是否顺畅、依赖是否缺失。CONTRIBUTING.md 给出的提交前测试清单包括组件在 Kitchen Sink 中正确渲染、文档在 Website 上正常展示、组件在脚手架模板中可用、TypeScript 类型完整、可访问性特性已实现、示例覆盖常见用例、props 文档齐全、跨平台Web 与原生兼容、低端设备性能达标。十一、PR 提交流程与发布规范11.1 Pull Request 流程从main创建特性分支只修改源文件用 kitchen-sink 与 website 应用充分测试必要时更新文档推送分支到 fork向gluestack/gluestack-ui创建 pull request响应评审意见。11.2 提交前自检常见陷阱❌ 编辑apps/*/components/ui/中的生成文件❌ 提交生成文件❌ 未在多个应用中测试❌ 忘记更新文档❌ 在不理解 mapper 系统的情况下改动。11.3 Changesets 版本管理仓库使用 Changesets 管理发布每个修改了包的 PR 都必须包含 changesetyarn changeset # 创建 changeset交互式选择包 bump 类型 yarn changeset:version # 消费 changesets升级版本 yarn changeset:status # 检查当前 changeset 状态十二、可编辑文件与禁编辑文件对照应编辑源文件绝不要编辑生成文件src/components/ui/*apps/*/components/ui/*src/docs-components/*apps/website/components/docs-components/*src/sidebar.jsonapps/website/sidebar.jsonsrc/docs/*apps/website/app/ui/docs/*packages/gluestack-core/src/*packages/gluestack-core/lib/*packages/gluestack-utils/src/*packages/gluestack-utils/lib/*十三、常见问题排查生成的本地文件缺失执行yarn sync改动未生效检查yarn dev是否正在运行并监听文件变化git 试图提交生成文件检查对应应用目录下的 .gitignore 配置Mapper 脚本不工作确认在根目录执行、依赖已安装、脚本文件权限正常。十四、结语一次贡献的心智模型用 ONBOARDING.md 的 Mental Model 收束全文你在这里编辑src/components/ui/name/index.tsx │ [yarn dev] │ ┌─────────────┼─────────────┐ ▼ ▼ ▼ kitchen-sink website starter-kits (测试) (文档) (模板) │ 若组件需要新的核心逻辑 packages/gluestack-core/src/name/creator/ │ 若组件需要新的 hooks/aria packages/gluestack-utils/src/一句话总结在src/中编辑源文件剩下的交给 mapper永远不要碰生成文件。配合 .claude/skills/contribute/SKILL.md 定义的子技能体系无论是人还是 AI Agent都能在 gluestack-ui 中完成从组件创建、包开发、文档编写到跨应用测试与 PR 提交的完整贡献闭环。赞分享UI组件移动开发跨平台【免费下载链接】gluestack-uiReact React Native Components Patterns (copy-paste components patterns crafted with Tailwind CSS (NativeWind))项目地址https://gitcode.com/gh_mirrors/gl/gluestack-ui点击查看免费下载相关推荐awesome-claude-skills 中的 Ncscale 自动化技能基于 Rube MCP 的 Claude Skills 工作流实战指南awesome claude skills 中的 Ncscale 自动化技能基于 Rube MCP 的 Claude Skills 工作流实战指南 本文基于当AI 技能AI 插件人工智能工作流自动化PyCaret 4.0 仓库的 AI 代理协作手册基于 Claude Code 的开源贡献工作流与实践指南PyCaret 4.0 仓库的 AI 代理协作手册基于 Claude Code 的开源贡献工作流与实践指南 CLAUDE.md 是 PyCaret 4.0 仓提示工程AI 安全治理变更描述变更描述 简要说明本次PR的目的和主要内容 相关Issue Fixes issue number 测试验证 单元测试通过 浏览器测试通过 文档示例验证 无障碍前端UI组件上一篇Karpenter Provider for AWS EC2NodeClass 完全指南从 NodePool 关联到 AWS 专属节点配置下一篇Slate v2 根运行时选择器守卫硬切换用静态权威测试锁定 React 组件与运行时模块的职责边界创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考