arco_design 0.1.0

Arco Design for Flutter — a faithful port of arco-design v2.66.16 design tokens, theme system and component set.

Arco Design for Flutter

在 Flutter 上还原 arco-design v2.66.16 设计语言与组件行为的组件库。

• 令牌数值取自官方发布产物，色板算法与线上 CSS 逐值一致（260/260）。
• 组件只依赖语义令牌，切换亮暗主题或自定义主色时自动跟随。
• 几何与配色逐条对照官方 2.66.16 编译产物 arco.css 实现，注释中标出对应选择器。

当前进度

49 个组件目录 / 460 项测试，P0 基座、P1 基础通用、P2 表单域主体与 P3 反馈浮层及导航均已完成：

分期	内容
P0 基座	令牌层、主题层、ArcoButton(+Group)、示例应用
P1 基础通用	布局排版（Divider Space Row/Col Layout Title/Text/Paragraph/Link）、展示（Tag Badge Avatar Card Empty Result Skeleton）、反馈（Spin Progress Alert）、自绘 ArcoIcon、ConfigProvider
P2 表单域	输入（Input TextArea InputNumber InputTag AutoComplete Select Cascader DatePicker TimePicker）、选择（Checkbox Radio Switch Slider Rate）、Form
P3 反馈浮层与导航	Portal Trigger Tooltip Popover Dropdown Modal Drawer Message Notification Popconfirm Menu Tabs

未完成部分（P2 剩余 7 个、P3 剩余 17 个、P4 数据密集型）见 实现规划；接手开发请先读 交接快照（进度、环境命令、门禁流程、踩坑记录）。

环境要求

项	版本
Flutter	>= 3.32（开发使用 3.44.4）
Dart	^3.12.2
Flutter 版本管理	可选，本项目使用 puro

在 Git Bash 中直接调用 puro 需要先补上 PATHEXT： export PATHEXT=".COM;.EXE;.BAT;.CMD"

快速开始

dependencies:
  arco_design:
    path: path/to/arco_design

import 'package:arco_design/arco_design.dart';
import 'package:flutter/material.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ArcoTheme.light(),
      darkTheme: ArcoTheme.dark(),
      themeMode: ThemeMode.system,
      home: Scaffold(
        body: Center(
          child: ArcoButton(
            type: ArcoButtonType.primary,
            icon: const Icon(Icons.add),
            onPressed: () {},
            child: const Text('新建'),
          ),
        ),
      ),
    );
  }
}

自定义主色

传入任意主色，库会用官方算法推导出完整的 10 阶色板：

MaterialApp(
  theme: ArcoTheme.light(primary: const Color(0xFF722ED1)),
  darkTheme: ArcoTheme.dark(primary: const Color(0xFF722ED1)),
  home: const HomePage(),
);

读取令牌

final ArcoColorTokens c = context.arco.colors;

Container(
  color: c.bg2,
  border: Border.all(color: c.border),
  child: Text('内容', style: TextStyle(color: c.text1)),
);

分层结构

层	位置	内容
令牌层	lib/src/tokens	色板算法与预设色板、语义色、尺寸 / 间距 / 圆角 / 阴影 / 字体 / 动效 / 层级
主题层	lib/src/theme	ArcoThemeData（ThemeExtension）、ArcoTheme、Material 桥接
组件层	lib/src/components	基于语义令牌实现的组件

示例应用

export PATHEXT=".COM;.EXE;.BAT;.CMD"   # Git Bash
cd example
puro flutter run -d chrome

示例应用包含：概览、设计令牌（色板 / 语义色 / 字体 / 圆角 / 阴影）、Button 全量形态矩阵， 并提供亮暗主题与自定义主色的实时切换。

开发

# 静态分析
puro flutter analyze

# 测试（沙箱/代理环境下需临时清空代理变量）
env -u http_proxy -u https_proxy -u HTTP_PROXY -u HTTPS_PROXY \
  NO_PROXY="127.0.0.1,localhost" puro flutter test

# 重新生成预设色板
python tool/refresh_official_palette.py   # 拉取官方 CSS → 参考文件
python tool/gen_palette_presets.py        # 参考文件 → Dart 常量

已知问题

• 仓库内 components/style/theme/color/compiled-colors.less 与线上 CSS 存在 1–2/255 的偏差，本项目以线上发布 CSS 为真值。
• Flutter 3.44 的 CFE 在 List<ThemeExtension<dynamic>> 字面量上存在类型归一化 缺陷（analyze 不报错、编译失败），代码中已规避。
• 更多踩坑记录见实现规划 · 环境注意事项。

许可证

见 LICENSE。