rsuite

React Suite 技能

此技能可帮助 AI 助手使用 React Suite v6+ 构建用户界面。启用后，助手会遵循 React Suite 在组件、样式、主题、无障碍访问和国际化方面的约定。

何时使用此技能

当项目依赖 rsuite（检查 package.json）或用户要求使用 React Suite 构建 UI 时，启用此技能。

安装

在目标项目中安装 React Suite：

npm install rsuite

在应用入口处导入一次样式表：

import 'rsuite/dist/rsuite.min.css';

按组件导入（推荐，有助于减小打包体积）：

import Button from 'rsuite/Button';
import 'rsuite/Button/styles/index.css';

核心原则

1. 优先使用内置组件，而非自定义组件。 React Suite 提供 80 多个组件。从头构建之前，请先检查是否已有可用组件。
2. 通过 as 和 render* 属性组合组件。 大多数组件都接受 as 来更改渲染的元素，并接受 renderX 属性来覆盖子部分。
3. 使用 CustomProvider 进行全局配置（区域设置、主题、RTL、classPrefix）。
4. 通过 CSS 变量（--rs-*）应用主题，不要覆盖类名。
5. 使用 @rsuite/icons 提供图标，而不是临时编写 SVG。
6. 使用 rsuite 中的 Form、Form.Group、Form.Control 和 Schema 处理表单。
7. 遵循无障碍访问要求： 始终为输入项提供标签，为自定义触发器提供 aria-* 属性，并为交互元素添加键盘事件处理程序。

常见模式

全局 Provider

import { CustomProvider } from 'rsuite';
import zhCN from 'rsuite/locales/zh_CN';

<CustomProvider theme="dark" locale={zhCN}>
  <App />
</CustomProvider>;

按钮

import { Button } from 'rsuite';

<Button appearance="primary" size="md" onClick={handleClick}>
  Submit
</Button>;

有效的 appearance 值：default | primary | link | subtle | ghost。 有效的 size 值：xs | sm | md | lg。 有效的 color 值：red | orange | yellow | green | cyan | blue | violet。

带验证的表单

import { Form, Schema, Button } from 'rsuite';

const model = Schema.Model({
  name: Schema.Types.StringType().isRequired('Name is required.'),
  email: Schema.Types.StringType().isEmail('Invalid email.')
});

<Form model={model} onSubmit={handleSubmit}>
  <Form.Group controlId="name">
    <Form.ControlLabel>Name</Form.ControlLabel>
    <Form.Control name="name" />
  </Form.Group>
  <Form.Group controlId="email">
    <Form.ControlLabel>Email</Form.ControlLabel>
    <Form.Control name="email" type="email" />
  </Form.Group>
  <Button type="submit" appearance="primary">Save</Button>
</Form>;

表格

import { Table } from 'rsuite';
const { Column, HeaderCell, Cell } = Table;

<Table data={data} autoHeight>
  <Column flexGrow={1}>
    <HeaderCell>Name</HeaderCell>
    <Cell dataKey="name" />
  </Column>
  <Column width={120}>
    <HeaderCell>Age</HeaderCell>
    <Cell dataKey="age" />
  </Column>
</Table>;

消息和 toaster

import { useToaster, Message } from 'rsuite';

const toaster = useToaster();
toaster.push(<Message type="success">Saved.</Message>, { placement: 'topCenter' });

主题

React Suite 提供以 --rs- 为前缀的 CSS 变量。在根选择器中覆盖这些变量：

:root {
  --rs-primary-500: #3498ff;
  --rs-text-primary: #1f2d3d;
}

通过 CustomProvider 在运行时切换主题；theme 属性接受 "light"、"dark" 或 "high-contrast"。

完整变量列表请参阅 https://rsuitejs.com/guide/css-variables。

图标

npm install @rsuite/icons

import SearchIcon from '@rsuite/icons/Search';

<Button startIcon={<SearchIcon />}>Search</Button>;

获取最新文档

若要获取组件、属性和钩子的实时数据，请按以下顺序优先使用官方来源：

1. MCP 服务 — @rsuite/mcp 提供 get_component_props、list_components、list_hooks、search_components。请参阅 https://rsuitejs.com/guide/mcp-server。
2. LLMs.txt — https://rsuitejs.com/llms.txt 和 https://rsuitejs.com/llms-full.txt。
3. 此技能附带的辅助脚本（见下文），可调用公开的 React Suite 文档 API。

脚本

此技能附带实用脚本，可通过编程方式获取组件数据：

• scripts/list_components.mjs — 列出所有 React Suite 组件
• scripts/get_component_props.mjs <ComponentName> — 获取指定组件的属性
• scripts/list_hooks.mjs — 列出所有自定义钩子
• scripts/search_components.mjs <query> — 按名称搜索组件

使用 Node 18+ 运行：

node scripts/list_components.mjs
node scripts/get_component_props.mjs Button

应做 / 避免

• 应在全局范围内导入一次 rsuite/dist/rsuite.min.css。
• 应在 Form 中使用 Form.Control（而非原始 Input），以便自动接入验证。
• 应选择具有语义的 appearance/color 值来表示状态，而不是使用内联样式。
• 避免直接修改组件类名；应改为覆盖 CSS 变量。
• 避免将 MUI/AntD 组件与 React Suite 混用——每个应用选择一套系统。
• 避免手动实现下拉菜单、日期选择器或树形选择器——请使用 Dropdown、DatePicker、TreePicker。

参考资料

• 文档：https://rsuitejs.com
• 组件：https://rsuitejs.com/components/overview
• GitHub：https://github.com/rsuite/rsuite
• MCP 服务：https://rsuitejs.com/guide/mcp-server
• LLMs.txt：https://rsuitejs.com/guide/llms