一张设置页能否用起来,取决于开关是否真的改变设置、保存失败后修改是否还在,以及大字号和键盘会不会挡住操作。expo-native-ui 帮 Agent 处理原生控件、平台样式和屏幕结构;下面以“通知偏好”页面为例,从安装走到设备验收。这个例子只处理应用内设置,不默认接入系统推送权限。
先接入 Skill,确认项目能运行什么
Codex 用户在终端安装 Expo 官方插件;Claude Code 用户改用 claude plugin install expo@claude-plugins-official。其他支持 Agent Skills 的客户端可在项目目录运行 npx skills@latest add expo/skills --skill '*',按提示选择客户端。插件提供 Expo Skills 和 MCP 配置,但不会给你的 App 安装 @expo/ui,也不会生成页面。安装后刷新 Agent 会话。
codex plugin add expo@openai-curated
进入已有 Expo 项目,先让 Agent 读取 package.json 中的 Expo SDK 版本、页面文件、现有控件库和保存设置的位置。当前 expo-native-ui 会先参考同一插件中的 expo-ui Skill 来选控件。Expo 官方说明:SDK 56 及以上的 @expo/ui 原生控件可在 Expo Go 中使用;旧 SDK 不要直接套用最新版示例,先查对应版本可用的控件或继续用项目现有方案。
如果已选定 @expo/ui 控件,而项目尚未安装这个库,再在Expo 项目目录运行下面的命令,由 Expo 选择与当前 SDK 匹配的版本。它安装的是 App 依赖,与上面的 Agent 插件是两件事。
npx expo install @expo/ui
第一次给 Agent 什么输入
把方括号中的路径和保存方式换成自己的项目资料,再发给 Agent:
使用 expo-native-ui 改造 [现有设置页路径],做应用内通知偏好页:三个开关、频率选择和保存按钮。本次不接入系统推送注册。
先读 package.json、现有页面和设置保存逻辑,告诉我 SDK 版本、iOS/Android 可用的控件、是否需要安装 @expo/ui,以及 Expo Go 能否运行。
先列出页面的加载、正常、保存中、保存失败状态,再修改代码。保存失败保留草稿并允许重试;如果项目没有持久化入口,就明确做成仅供预览的本地状态,不要假装已经保存。
完成后说明改了哪些文件、如何在两端打开页面,以及哪些检查尚未实际执行。
预期先得到控件与数据来源的选择,再得到页面代码和可运行的验证步骤。对于三个开关,先问清它们控制的是已有业务设置、设备权限,还是仅改变本地预览;这三者不能用同一个“保存成功”提示代替。@expo/ui 的通用 Switch 是受控控件,需要 Host 包裹,并让 value 与 onValueChange 连到状态;按钮还需要把修改送到项目真实的保存入口。
跑起来后怎样判断完成
在项目目录运行 npx expo start,用 Expo Go 扫终端二维码打开应用;Android 模拟器可按 a,iOS 模拟器可按 i。先试 Expo Go:只有项目用了它不包含的原生模块或特殊原生配置时,才改用开发构建。如果二维码打不开,先检查设备与电脑网络;实体 iPhone 的 Expo Go 还需与 Expo CLI 登录同一 Expo 账号。
在目标平台按一次真实流程检查:打开设置页,改变开关和频率,点保存,重新进入页面,确认结果与项目实际保存方式一致。再让保存请求失败一次,检查错误提示、草稿是否保留、重试是否可用;若页面仅使用本地状态,就不要把重新打开后的持久化当成已完成。最后分别在 iOS 和 Android 看深色模式、大字号、长文案、键盘遮挡和屏幕阅读器标签。交付时请 Agent 列明已在设备上检查与未检查的项目,不能用一张截图代替交互验收。
卡住时先查哪一层
**Agent 找不到 Skill:**确认 Expo 插件已启用,刷新会话并明确要求使用 expo-native-ui;组件选型还应加载 expo-ui。安装 Agent 插件不等于 App 已有 @expo/ui。
**@expo/ui 导入失败或 Expo Go 打不开:**先核对项目 SDK、是否执行过与 SDK 匹配的 npx expo install @expo/ui,以及项目是否引入 Expo Go 不包含的原生模块。不要把所有运行失败都归因于页面设计,也不要为普通设置页直接创建云端构建。
**开关能点,保存却没效果:**检查 Switch 的值与更新回调、保存按钮的处理函数、保存去向和失败分支。空处理函数或只弹“成功”提示不算完成设置功能。
**Android 按钮比 iOS 大:**一个公开复现发生在 Expo SDK 57.0.22、@expo/ui 57.0.18 的模拟器上:要求 34dp 的 Button 在 Android 显示为 48dp,iOS 则为 34dp。设计紧凑工具栏时,在两端检查实际尺寸与触控范围;这是特定版本的底层控件报告,不代表每个项目都会遇到。