入选理由:官方提供预编译 CSS、主题和明确的 Button 属性,可用本地计数练习核对接入结果,补充现有目录中的组件实现实践;同时说明 React 19、主题版本及 Beta 限制。
入选:2026-11-11 · 资料核对:2026-11-11。根据官方资料整理,未进行安装与功能实测。
Astryx:在 React 页面接入主题并验证按钮交互
它解决什么问题
每次开发表单或设置页,都要重新处理按钮的样式、禁用状态和主题,容易让同一个应用的界面不一致。Astryx 提供 React 组件、预编译 CSS 与主题系统,可以先复用基础控件,再逐步组合页面。
本篇先完成一个小任务:在独立页面上显示计数,用主按钮增加数值,再用次按钮清零。通过样式、状态更新和禁用状态三个检查点,确认主题与组件接入路径。步骤根据官方资料核对,未进行安装、浏览器效果或兼容性实测。
适合谁,哪些情况不适合
适合已有 React 基础、想给原型或内部工具建立一致界面的开发者。只需先会运行项目、修改组件和读取终端错误。
已有大型样式系统的项目,应先在独立页面比较 CSS 层级与主题,确认后再扩大范围。需要 Vue、原生移动控件或其他非 React 接口时,本文不能直接套用。也不要因为使用了组件库,就省略应用自己的交互、对比度和键盘操作检查。
环境与准备
Astryx 要求 React 与 React DOM 至少为 19。本篇用 Vite 的 React TypeScript 模板,准备 Node.js 24、npm 和现代浏览器。先运行 node --version、npm --version;Vite 官方说明模板可能有自己的最低版本要求,安装时若出现引擎警告,应先核对环境。
本次核对的 Core 与 Neutral 主题均为 0.7.13,主题声明依赖同版本 Core。示例固定这两个包及 create-vite 9.3.4,并使用满足 Core 要求的 StyleX 0.19.0。StyleX 在这里作为组件的依赖,Astryx 使用预编译样式,不需要额外设置 StyleX 编译插件。
下方文件创建命令采用 macOS、Linux 终端语法。Windows 用户可以使用对应终端方法编辑相同文件。安装需要联网下载依赖;页面中的计数逻辑不需要模型 API 或云端服务。
安装与第一次使用
1. 建立新的练习项目。 在终端执行:
astryx_demo_dir=$(mktemp -d) &&
cd "$astryx_demo_dir" &&
npm create vite@9.3.4 astryx-lab -- --template react-ts --no-interactive &&
cd astryx-lab &&
npm install &&
npm install --save-exact @astryxdesign/core@0.7.13 @astryxdesign/theme-neutral@0.7.13 @stylexjs/stylex@0.19.0
如果 npm 询问是否下载 create-vite,先核对包名和版本。随后运行 npm ls react react-dom @astryxdesign/core @astryxdesign/theme-neutral,确认 React 为 19 或以上、两个 Astryx 包均为 0.7.13。先解决依赖错误,再编辑文件。
2. 设置样式与主题。 下面的文件都在刚创建的 astryx-lab 中。完整替换 src/index.css,移除模板默认样式:
@import '@astryxdesign/core/reset.css';
@import '@astryxdesign/core/astryx.css';
@import '@astryxdesign/theme-neutral/theme.css';
body {
margin: 0;
font-family: system-ui, sans-serif;
}
顺序依次是重置、组件样式、主题变量覆盖,应保持不变。再将 src/main.tsx 替换为:
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { Theme } from '@astryxdesign/core/theme';
import { neutralTheme } from '@astryxdesign/theme-neutral/built';
import App from './App';
import './index.css';
createRoot(document.getElementById('root')!).render(
<StrictMode>
<Theme theme={neutralTheme}>
<App />
</Theme>
</StrictMode>,
);
Theme 为下方组件提供主题,/built 使用已构建的主题对象。本篇没有页面链接组件,因此不需要接入路由库的链接适配。
3. 放入可检查的按钮。 将 src/App.tsx 完整替换为:
import { useState } from 'react';
import { Button } from '@astryxdesign/core/Button';
export default function App() {
const [count, setCount] = useState(0);
return (
<main style={{ maxWidth: 480, margin: '48px auto', padding: 24 }}>
<h1>Astryx 按钮练习</h1>
<p role="status">当前计数:{count}</p>
<div style={{ display: 'flex', gap: 12 }}>
<Button
label="增加一次"
variant="primary"
onClick={() => setCount((value) => value + 1)}
/>
<Button
label="清零"
variant="secondary"
isDisabled={count === 0}
onClick={() => setCount(0)}
/>
</div>
</main>
);
}
Button 使用 label 提供文字,variant 决定主次样式,onClick 是同步点击回调,isDisabled 控制禁用。本例不导入模板的 App.css,避免它干扰练习。
4. 启动并检查。 运行 npm run dev,打开终端实际显示的本地 URL。依次检查:初始计数为 0,清零按钮禁用;点击两次“增加一次”,数值变成 2;点击“清零”,数值回到 0,清零按钮再次禁用。两个按钮应分别显示主按钮和次按钮样式。
还可以用 Tab 键移动焦点,再用键盘激活可用按钮,检查焦点是否可见。以上是待检查的预期行为,不是本次执行过的界面测试。停止开发服务可在终端按 Ctrl+C。之后运行 npm run build 检查项目能否完成类型检查和构建;构建通过仍需配合浏览器中的交互检查。
主要能力与典型场景
- 先做一致的基础操作。 在保存、取消或筛选操作中选择合适的按钮变体,并为动作写清楚标签。
- 逐步组合表单与列表。 完成基础接入后,按当前版本的组件文档选择输入、布局、表格等能力,不凭组件名称猜属性。
- 统一主题。 用主题提供器与 CSS 变量管理视觉约定;更换主题时让包版本相互对应,再检查组件状态。
- 处理异步动作。 官方还提供
clickAction来处理返回 Promise 的动作及加载状态。接入真实保存操作前,需另外设计错误、重复提交和结果提示。
常见问题与排错
- 出现 React 或主题 peer dependency 冲突。 先运行上面的
npm ls检查版本,不用强制忽略错误。Core 与主题应保持匹配,React 不能低于 19。 - 只有文字,看不到组件样式。 确认
main.tsx导入index.css,三条 CSS 导入存在且顺序正确,App 位于 Theme 内。 - 布局或颜色与预期不同。 检查是否还导入了模板的 App.css、其他重置样式或旧 Tailwind 配置。新项目可先只保留本例文件,再逐项加回样式。
- 按钮属性报错。 对照当前版本的 Button 文档。禁用属性是
isDisabled,文字由label提供;不要把其他组件库的属性照搬过来。 - 打开地址无响应。 确认开发服务仍在运行,并使用终端显示的端口;端口占用时 Vite 可能选择其他端口。
- 想使用实验组件或图表却找不到包。 官方列出的 lab 尚未发布到 npm,部分图表包只有 canary 标签,不能当作与本例相同的稳定入口。
费用、隐私与限制
Astryx 源码采用 MIT。本篇只在自有机器运行组件和计数状态,不需要购买模型服务;包下载、构建与部署使用的资源由所选环境承担。安装阶段会访问包注册表。
项目仍标注 Beta,更新时应阅读发行说明并核对版本对应关系。组件是否满足实际页面的可访问性要求,还需要在真实内容、配色和交互中检查。本例没有保存数据、调用接口或演示生产部署;以后接入用户资料时,应按应用自己的数据与权限设计处理。