Back to Details

arco-design

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Arco Design React — Skills Reference

Arco Design React — 技能参考

@arco-design/web-react
— An enterprise-level React UI component library by ByteDance.
@arco-design/web-react
— 字节跳动推出的企业级React UI组件库。

Critical Conventions

重要约定

Always follow these rules when writing Arco Design code:
  • Imports: 
    import { Button, Table, Form } from '@arco-design/web-react'
    — always from the package root, never from sub-paths like 
    @arco-design/web-react/es/Button
  • Icons: 
    import { IconSearch, IconPlus } from '@arco-design/web-react/icon'
  • Types: 
    import type { TableProps, FormInstance } from '@arco-design/web-react'
  • Styles: 
    import '@arco-design/web-react/dist/css/arco.css'
    (full) or configure on-demand loading
  • Date library: dayjs (NOT moment.js)
  • Controlled mode: 
    value
    + 
    onChange
    ; Uncontrolled: 
    defaultValue
  • Sub-components: accessed via 
    Component.Sub
    pattern — 
    Form.Item
    , 
    Select.Option
    , 
    Menu.SubMenu
    , 
    Input.Search
    , 
    Input.TextArea
    , 
    Grid.Row
    , 
    Grid.Col
  • Form.Item uses 
    field
    prop     (not 
    name
    like Ant Design)
  • Switch in Form requires 
    triggerPropName="checked"
编写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"

Skill Index

技能索引

Load the relevant file below for full API reference, code examples, and best practices.
加载下方对应的文件即可获取完整的API参考、代码示例和最佳实践。

Setup & Configuration

安装与配置

TopicFileWhen to use
Installationgetting-started.mdInstall 
@arco-design/web-react
, import styles, configure tree-shaking or babel-plugin-import
Global Configconfig-provider.mdSet global component size, theme, locale, default props via 
<ConfigProvider>
Themingtheming.mdCustom theme colors, CSS variable overrides, Less variables, dark mode toggle
Internationalizationinternationalization.mdSwitch languages, add locale packs, customize locale text
Architecturearchitecture.mdUnderstand controlled/uncontrolled patterns, props merging, ref forwarding, CSS naming
主题文件适用场景
安装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命名规范

General Components

通用组件

ComponentFileUse for
Buttonbutton.mdButtons, button groups, icon buttons, loading state
Iconicon.mdBuilt-in icons (
IconXxx
), custom SVG icons, IconFont
Typographytypography.mdHeadings, paragraphs, text ellipsis, copyable/editable text
Linklink.mdHyperlinks with icon, hover states
Dividerdivider.mdHorizontal/vertical dividers, dividers with text
组件文件用途
Buttonbutton.md按钮、按钮组、图标按钮、加载状态
Iconicon.md内置图标（
IconXxx
）、自定义SVG图标、IconFont
Typographytypography.md标题、段落、文本省略、可复制/可编辑文本
Linklink.md带图标、hover效果的超链接
Dividerdivider.md水平/垂直分割线、带文本的分割线

Layout

布局

ComponentFileUse for
Gridgrid.md24-column 
Row
/
Col
grid, responsive breakpoints (xs/sm/md/lg/xl/xxl), gutter
Layoutlayout.mdPage skeleton: 
Header
, 
Sider
, 
Content
, 
Footer
, collapsible sidebar
Spacespace.mdConsistent spacing between elements, horizontal/vertical, wrap
组件文件用途
Gridgrid.md24栅格
Row
/
Col
布局、响应式断点（xs/sm/md/lg/xl/xxl）、间距设置
Layoutlayout.md页面骨架：
Header
、
Sider
、
Content
、
Footer
、可折叠侧边栏
Spacespace.md元素间统一间距设置、水平/垂直排列、自动换行

Navigation

导航

ComponentFileUse for
Menumenu.mdSidebar nav, top nav bar, sub-menus, menu groups, collapsible
Tabstabs.mdTab switching, card tabs, editable/closable tabs, extra content
Dropdowndropdown.mdDropdown menus, context menus, button dropdowns
Breadcrumbbreadcrumb.mdNavigation hierarchy path, route breadcrumbs
Paginationpagination.mdPage navigation, size changer, simple/mini mode
Stepssteps.mdStep-by-step workflows, vertical/dot steps, error state
Affixaffix.mdPin element to viewport on scroll
Anchoranchor.mdIn-page anchor navigation, scroll-to-section
PageHeaderpage-header.mdPage title + back button + breadcrumb + actions
组件文件用途
Menumenu.md侧边栏导航、顶部导航栏、子菜单、菜单组、可折叠
Tabstabs.md标签页切换、卡片式标签、可编辑/可关闭标签、额外内容区
Dropdowndropdown.md下拉菜单、上下文菜单、按钮下拉框
Breadcrumbbreadcrumb.md导航层级路径、路由面包屑
Paginationpagination.md分页导航、每页数量切换、简洁/迷你模式
Stepssteps.md分步流程、垂直/点状步骤条、错误状态
Affixaffix.md滚动时将元素固定在视口内
Anchoranchor.md页内锚点导航、滚动到指定区块
PageHeaderpage-header.md页面标题+返回按钮+面包屑+操作区

Data Entry

数据录入

ComponentFileUse for
Formform.mdForm building, validation, 
Form.Item
(uses 
field
prop), 
Form.List
, 
useForm
hook
Inputinput.mdText input, 
Input.Password
, 
Input.Search
, 
Input.TextArea
, prefix/suffix
Selectselect.mdDropdown select, multi-select, search, remote search, 
Select.Option
, virtual scroll
DatePickerdate-picker.mdDate/range picker (
RangePicker
), week/month/quarter/year, disabled dates (dayjs)
TimePickertime-picker.mdTime selection, range, 12h format, step intervals
InputNumberinput-number.mdNumeric input, stepper, precision, min/max
Checkboxcheckbox.mdMulti-select, 
Checkbox.Group
, select all / indeterminate
Radioradio.mdSingle select, 
Radio.Group
, button-style radio
Switchswitch.mdToggle switch, loading, text labels (use 
triggerPropName="checked"
in Form)
Sliderslider.mdRange slider, marks, vertical, step, tooltip format
Raterate.mdStar rating, half-star, readonly, custom characters
Cascadercascader.mdMulti-level cascade (province/city), remote load, search
TreeSelecttree-select.mdSelect from tree structure, checkable, searchable, async load
Transfertransfer.mdTransfer items between two lists, search, simple mode
AutoCompleteauto-complete.mdInput autocomplete, search suggestions
Mentionsmentions.md@mention users/topics in text input
InputTaginput-tag.mdTag input, add/remove tags, drag sort
Uploadupload.mdFile upload, drag-and-drop, image upload with preview
ColorPickercolor-picker.mdColor selection (hex/rgb/hsl)
VerificationCodeverification-code.mdOTP / verification code input
组件文件用途
Formform.md表单搭建、校验、
Form.Item
（使用
field
属性）、
Form.List
、
useForm
钩子
Inputinput.md文本输入框、
Input.Password
、
Input.Search
、
Input.TextArea
、前缀/后缀
Selectselect.md下拉选择、多选、搜索、远程搜索、
Select.Option
、虚拟滚动
DatePickerdate-picker.md日期/范围选择器（
RangePicker
）、周/月/季度/年选择、禁用日期（dayjs格式）
TimePickertime-picker.md时间选择、范围选择、12小时制、步长间隔
InputNumberinput-number.md数值输入、步进器、精度设置、最大值/最小值限制
Checkboxcheckbox.md多选、
Checkbox.Group
、全选/半选状态
Radioradio.md单选、
Radio.Group
、按钮式单选
Switchswitch.md开关切换、加载状态、文本标签（Form中使用时需设置
triggerPropName="checked"
）
Sliderslider.md范围滑块、刻度标记、垂直模式、步长、提示框格式化
Raterate.md星级评分、半星、只读模式、自定义字符
Cascadercascader.md多级联动选择（省/市）、远程加载、搜索
TreeSelecttree-select.md树形结构选择、可勾选、可搜索、异步加载
Transfertransfer.md双列表穿梭框、搜索、简洁模式
AutoCompleteauto-complete.md输入自动补全、搜索建议
Mentionsmentions.md文本输入中@提及用户/话题
InputTaginput-tag.md标签输入、添加/删除标签、拖拽排序
Uploadupload.md文件上传、拖拽上传、带预览的图片上传
ColorPickercolor-picker.md颜色选择（hex/rgb/hsl格式）
VerificationCodeverification-code.mdOTP/验证码输入框

Data Display

数据展示

ComponentFileUse for
Tabletable.mdData tables, sort, filter, pagination, fixed columns/header, virtual scroll, row selection, expandable rows
Listlist.mdData lists, paginated, virtual scroll, grid layout
Cardcard.mdCard containers, cover, 
Card.Grid
, 
Card.Meta
, actions
Treetree.mdTree structure, checkable, draggable, virtual scroll, async load
Tooltiptooltip.mdHover text hints (for rich content use Popover)
Popoverpopover.mdClick/hover popup cards with rich content
Avataravatar.mdUser avatars, avatar groups, image/text/icon avatars
Badgebadge.mdNumeric badges, status dots, count indicators
Tagtag.mdStatus tags, closable, 
Tag.CheckableTag
, colored tags
Carouselcarousel.mdImage carousels, slideshows
Collapsecollapse.mdCollapsible panels, accordion mode, FAQ
Descriptionsdescriptions.mdKey-value detail display, bordered, responsive columns
Calendarcalendar.mdCalendar view, event marking
Commentcomment.mdComment display, nested replies, actions
Emptyempty.mdEmpty state placeholder
Imageimage.mdImage display, preview, lazy load, 
Image.PreviewGroup
Statisticstatistic.mdNumeric display, countdown, trend indicators
Timelinetimeline.mdTimelines, activity feeds, changelog
组件文件用途
Tabletable.md数据表格、排序、筛选、分页、固定列/表头、虚拟滚动、行选择、可展开行
Listlist.md数据列表、分页、虚拟滚动、网格布局
Cardcard.md卡片容器、封面、
Card.Grid
、
Card.Meta
、操作区
Treetree.md树形结构展示、可勾选、可拖拽、虚拟滚动、异步加载
Tooltiptooltip.mdhover文字提示（富内容请使用Popover）
Popoverpopover.md点击/hover弹出的富内容卡片
Avataravatar.md用户头像、头像组、图片/文字/图标头像
Badgebadge.md数字徽标、状态点、计数指示器
Tagtag.md状态标签、可关闭、
Tag.CheckableTag
、彩色标签
Carouselcarousel.md图片轮播、幻灯片
Collapsecollapse.md可折叠面板、手风琴模式、FAQ
Descriptionsdescriptions.md键值对详情展示、带边框、响应式列数
Calendarcalendar.md日历视图、事件标记
Commentcomment.md评论展示、嵌套回复、操作区
Emptyempty.md空状态占位符
Imageimage.md图片展示、预览、懒加载、
Image.PreviewGroup
Statisticstatistic.md数值展示、倒计时、趋势指示器
Timelinetimeline.md时间线、动态流、更新日志

Feedback

反馈

ComponentFileUse for
Modalmodal.mdModal dialogs, 
Modal.confirm()
, 
useModal
hook, form-in-modal
Messagemessage.mdGlobal toast: 
Message.success()
, 
error()
, 
warning()
, 
loading()
Notificationnotification.mdRich notification toasts with title + content + actions
Drawerdrawer.mdSlide-out side panels, form editing, nested drawers
Alertalert.mdInline alert banners (info/success/warning/error), banner mode
Progressprogress.mdLinear/circular progress bars, step progress
Popconfirmpopconfirm.mdLightweight confirmation popup before delete/submit
Resultresult.mdResult pages (success/fail/403/404/500)
Skeletonskeleton.mdLoading skeleton placeholders with animation
Spinspin.mdLoading spinner wrapping content
组件文件用途
Modalmodal.md模态弹窗、
Modal.confirm()
、
useModal
钩子、弹窗内表单
Messagemessage.md全局轻提示：
Message.success()
、
error()
、
warning()
、
loading()
Notificationnotification.md带标题+内容+操作的富内容通知提示
Drawerdrawer.md滑出侧边面板、表单编辑、嵌套抽屉
Alertalert.md内联警告栏（信息/成功/警告/错误）、通栏模式
Progressprogress.md线性/环形进度条、分步进度
Popconfirmpopconfirm.md删除/提交前的轻量确认弹窗
Resultresult.md结果页（成功/失败/403/404/500）
Skeletonskeleton.md带动画的加载骨架屏占位符
Spinspin.md包裹内容的加载指示器

Other

其他

ComponentFileUse for
BackTopback-top.mdScroll-to-top button
Portalportal.mdRender children into different DOM node
ResizeBoxresize-box.mdResizable containers, split panes
Triggertrigger.mdBase popup positioning (underlies Tooltip/Popover/Dropdown)
Watermarkwatermark.mdText/image watermarks over page content
组件文件用途
BackTopback-top.md回到顶部按钮
Portalportal.md将子元素渲染到其他DOM节点
ResizeBoxresize-box.md可调整大小的容器、分割面板
Triggertrigger.md基础弹窗定位能力（Tooltip/Popover/Dropdown的底层依赖）
Watermarkwatermark.md页面内容上的文字/图片水印

Patterns & Best Practices

模式与最佳实践

TopicFileWhen to use
Form Patternsform-patterns.mdDynamic forms, linked validation, nested forms, async submit, complex layouts
Table Patternstable-patterns.mdRemote data, editable rows, virtual scroll large data, custom filters
Modal Patternsmodal-patterns.mdForm-in-modal, confirmation flows, nested drawers, global messages
Controlled vs Uncontrolledcontrolled-uncontrolled.mdChoosing 
value
+
onChange
vs 
defaultValue
pattern
Responsive Designresponsive-design.mdGrid breakpoints, adaptive layout, mobile-friendly design
主题文件适用场景
表单最佳实践form-patterns.md动态表单、联动校验、嵌套表单、异步提交、复杂布局
表格最佳实践table-patterns.md远程数据、可编辑行、大数据虚拟滚动、自定义筛选
弹窗最佳实践modal-patterns.md弹窗内表单、确认流程、嵌套抽屉、全局提示
受控vs非受控模式controlled-uncontrolled.md选择
value
+
onChange
还是
defaultValue
模式
响应式设计responsive-design.md栅格断点、自适应布局、移动端适配

Hooks

Hooks

Import from 
@arco-design/web-react/hooks
. Use these headless hooks only when you need a fully custom UI — otherwise prefer the corresponding component.
HookFileUse for
useVerificationCodeuse-verification-code.mdCustom OTP input with focus, paste, keyboard navigation
useWatermarkuse-watermark.mdDynamic canvas watermark with tamper protection
从
@arco-design/web-react/hooks
导入。仅当你需要完全自定义UI时使用这些无头钩子 — 否则优先使用对应的组件。
钩子文件用途
useVerificationCodeuse-verification-code.md自定义验证码输入，支持聚焦、粘贴、键盘导航
useWatermarkuse-watermark.md带防篡改能力的动态画布水印