arco-design

Arco Design React — 技能参考

@arco-design/web-react — 字节跳动推出的企业级 React UI 组件库。

重要约定

编写 Arco Design 代码时，始终遵循以下规则：

• 导入：import { Button, Table, Form } from '@arco-design/web-react' — 始终从包根路径导入，切勿从 @arco-design/web-react/es/Button 这类子路径导入
• 图标：import { IconSearch, IconPlus } from '@arco-design/web-react/icon'
• 类型：import type { TableProps, FormInstance } from '@arco-design/web-react'
• 样式：import '@arco-design/web-react/dist/css/arco.css'（完整样式），或配置按需加载
• 日期库：dayjs（不是 moment.js）
• 受控模式：value + onChange；非受控模式：defaultValue
• 子组件：通过 Component.Sub 模式访问 — Form.Item、Select.Option、Menu.SubMenu、Input.Search、Input.TextArea、Grid.Row、Grid.Col
• Form.Item 使用 field 属性（不像 Ant Design 使用 name）
• Form 中的 Switch 需要设置 triggerPropName="checked"

技能索引

加载下方的相关文件，查看完整的 API 参考、代码示例和最佳实践。

安装与配置

主题	文件	使用场景
安装	getting-started.md	安装 @arco-design/web-react、导入样式、配置 tree-shaking 或 babel-plugin-import
全局配置	config-provider.md	通过 <ConfigProvider> 设置全局组件尺寸、主题、语言环境和默认属性
主题	theming.md	自定义主题颜色、覆盖 CSS 变量、Less 变量，切换深色模式
国际化	internationalization.md	切换语言、添加语言包、自定义语言文本
架构	architecture.md	了解受控/非受控模式、属性合并、ref 转发和 CSS 命名

通用组件

组件	文件	用途
按钮	button.md	按钮、按钮组、图标按钮、加载状态
图标	icon.md	内置图标（IconXxx）、自定义 SVG 图标、IconFont
排版	typography.md	标题、段落、文本省略、可复制/可编辑文本
链接	link.md	带图标的超链接、悬停状态
分隔线	divider.md	水平/垂直分隔线、带文本的分隔线

布局

组件	文件	用途
Grid	grid.md	24 列 Row/Col 网格、响应式断点（xs/sm/md/lg/xl/xxl）、间距
Layout	layout.md	页面骨架：Header、Sider、Content、Footer、可折叠侧边栏
Space	space.md	统一元素间距，支持水平/垂直排列和换行

导航

组件	文件	用途
菜单	menu.md	侧边栏导航、顶部导航栏、子菜单、菜单组、可折叠菜单
标签页	tabs.md	标签页切换、卡片标签页、可编辑/可关闭的标签页、额外内容
下拉菜单	dropdown.md	下拉菜单、上下文菜单、按钮下拉菜单
面包屑	breadcrumb.md	导航层级路径、路由面包屑
分页	pagination.md	页面导航、每页条数切换、简洁/迷你模式
步骤条	steps.md	分步工作流、垂直/点状步骤、错误状态
固钉	affix.md	滚动时将元素固定在视口中
锚点	anchor.md	页面内锚点导航、滚动到指定区块
页面头部	page-header.md	页面标题 + 返回按钮 + 面包屑 + 操作项

数据录入

组件	文件	用途
表单	form.md	构建表单、校验、Form.Item（使用 field 属性）、Form.List、useForm hook
输入框	input.md	文本输入、Input.Password、Input.Search、Input.TextArea、前缀/后缀
选择器	select.md	下拉选择、多选、搜索、远程搜索、Select.Option、虚拟滚动
日期选择器	date-picker.md	日期/范围选择器（RangePicker）、周/月/季度/年份、禁用日期（dayjs）
时间选择器	time-picker.md	时间选择、范围、12 小时制、步进间隔
数字输入框	input-number.md	数字输入、步进器、精度、最小值/最大值
复选框	checkbox.md	多选、Checkbox.Group、全选/半选
单选框	radio.md	单选、Radio.Group、按钮样式的单选框
开关	switch.md	切换开关、加载状态、文本标签（在 Form 中使用 triggerPropName="checked"）
滑动输入条	slider.md	范围滑动输入条、刻度标记、垂直模式、步长、提示框格式
评分	rate.md	星级评分、半星、只读、自定义字符
级联选择器	cascader.md	多级级联（省/市）、远程加载、搜索
树选择器	tree-select.md	从树形结构中选择、可勾选、可搜索、异步加载
穿梭框	transfer.md	在两个列表之间转移项目、搜索、简洁模式
自动完成	auto-complete.md	输入自动补全、搜索建议
提及	mentions.md	在文本输入中 @提及用户/话题
标签输入框	input-tag.md	标签输入、添加/移除标签、拖动排序
上传	upload.md	文件上传、拖放上传、带预览的图片上传
颜色选择器	color-picker.md	颜色选择（hex/rgb/hsl）
验证码	verification-code.md	OTP / 验证码输入

数据展示

组件	文件	适用场景
表格	table.md	数据表格、排序、筛选、分页、固定列/表头、虚拟滚动、行选择、可展开行
列表	list.md	数据列表、分页、虚拟滚动、网格布局
卡片	card.md	卡片容器、封面、Card.Grid、Card.Meta、操作
树	tree.md	树形结构、可勾选、可拖动、虚拟滚动、异步加载
文字提示	tooltip.md	悬停文字提示（富内容请使用 Popover）
弹出框	popover.md	点击/悬停弹出包含富内容的卡片
头像	avatar.md	用户头像、头像组、图片/文字/图标头像
徽标	badge.md	数字徽标、状态圆点、计数指示器
标签	tag.md	状态标签、可关闭标签、Tag.CheckableTag、彩色标签
走马灯	carousel.md	图片走马灯、幻灯片
折叠面板	collapse.md	可折叠面板、手风琴模式、常见问题
描述列表	descriptions.md	键值详情展示、带边框、响应式列
日历	calendar.md	日历视图、事件标记
评论	comment.md	评论展示、嵌套回复、操作
空状态	empty.md	空状态占位符
图片	image.md	图片展示、预览、懒加载、Image.PreviewGroup
统计数值	statistic.md	数值展示、倒计时、趋势指示器
时间轴	timeline.md	时间轴、活动动态、更新日志

反馈

组件	文件	适用场景
模态框	modal.md	模态对话框、Modal.confirm()、useModal 钩子、模态框中的表单
消息提示	message.md	全局轻提示：Message.success()、error()、warning()、loading()
通知	notification.md	包含标题 + 内容 + 操作的富内容通知轻提示
抽屉	drawer.md	滑出的侧边面板、表单编辑、嵌套抽屉
警告提示	alert.md	行内警告横幅（信息/成功/警告/错误）、横幅模式
进度条	progress.md	线性/环形进度条、步骤进度
气泡确认框	popconfirm.md	删除/提交前的轻量确认弹窗
结果页	result.md	结果页面（成功/失败/403/404/500）
骨架屏	skeleton.md	带动画的加载骨架占位符
加载中	spin.md	包裹内容的加载指示器

其他

组件	文件	用途
BackTop	back-top.md	回到顶部按钮
Portal	portal.md	将子元素渲染到其他 DOM 节点
ResizeBox	resize-box.md	可调整大小的容器、分隔窗格
Trigger	trigger.md	基础弹出层定位（Tooltip/Popover/Dropdown 的底层组件）
Watermark	watermark.md	覆盖在页面内容上的文本/图片水印

模式与最佳实践

主题	文件	适用场景
表单模式	form-patterns.md	动态表单、联动校验、嵌套表单、异步提交、复杂布局
表格模式	table-patterns.md	远程数据、可编辑行、大数据量虚拟滚动、自定义筛选器
Modal 模式	modal-patterns.md	模态框中的表单、确认流程、嵌套抽屉、全局消息
受控与非受控	controlled-uncontrolled.md	选择 value+onChange 还是 defaultValue 模式
响应式设计	responsive-design.md	网格断点、自适应布局、适配移动设备的设计

Hooks

从 @arco-design/web-react/hooks 导入。仅在需要完全自定义 UI 时使用这些无头 Hook，否则优先使用对应组件。

Hook	文件	用途
useVerificationCode	use-verification-code.md	自定义 OTP 输入框，支持焦点、粘贴和键盘导航
useWatermark	use-watermark.md	具备防篡改保护的动态 Canvas 水印