shadcn_ui-getting-started

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Shadcn UI for Flutter — Getting Started

Flutter版Shadcn UI — 入门指南

Instructions

操作步骤

Installation

安装

From the project root:

bash

flutter pub add shadcn_ui

Or add to

pubspec.yaml

yaml

dependencies:
  shadcn_ui: ^0.2.4  # use latest version

从项目根目录执行：

bash

flutter pub add shadcn_ui

或者添加到

pubspec.yaml

文件中：

yaml

dependencies:
  shadcn_ui: ^0.2.4  # 使用最新版本

Shadcn only (pure)

仅使用Shadcn（纯模式）

Use

ShadApp

for apps that use only Shadcn UI components (no Material/Cupertino):

dart

import 'package:shadcn_ui/shadcn_ui.dart';

void main() {
  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return ShadApp();
  }
}

For declarative routing use

ShadApp.router

如果应用仅使用Shadcn UI组件（不使用Material/Cupertino），请使用

ShadApp

：

dart

import 'package:shadcn_ui/shadcn_ui.dart';

void main() {
  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return ShadApp();
  }
}

如需声明式路由，请使用

ShadApp.router

。

Shadcn + Material

Use

ShadApp.custom

with

appBuilder

to wrap

MaterialApp

and use shadcn and Material together. Wrap the app with

ShadAppBuilder

in the builder:

dart

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

return ShadApp.custom(
  themeMode: ThemeMode.dark,
  darkTheme: ShadThemeData(
    brightness: Brightness.dark,
    colorScheme: const ShadSlateColorScheme.dark(),
  ),
  appBuilder: (context) {
    return MaterialApp(
      theme: Theme.of(context),
      builder: (context, child) {
        return ShadAppBuilder(child: child!);
      },
    );
  },
);

Use

MaterialApp.router

when using the Router API.

ShadApp builds a default Material

ThemeData

from

ShadThemeData

(fontFamily, extensions, colorScheme mapping, dividerTheme, textSelectionTheme, iconTheme, scrollbarTheme). Override with

Theme.of(context).copyWith(...)

without losing shadcn defaults.

使用

ShadApp.custom

配合

appBuilder

来包裹

MaterialApp

，实现Shadcn与Material的协同使用。在builder中用

ShadAppBuilder

包裹应用：

dart

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

return ShadApp.custom(
  themeMode: ThemeMode.dark,
  darkTheme: ShadThemeData(
    brightness: Brightness.dark,
    colorScheme: const ShadSlateColorScheme.dark(),
  ),
  appBuilder: (context) {
    return MaterialApp(
      theme: Theme.of(context),
      builder: (context, child) {
        return ShadAppBuilder(child: child!);
      },
    );
  },
);

使用Router API时，请使用

MaterialApp.router

。

ShadApp会基于

ShadThemeData

生成默认的Material

ThemeData

（包括字体家族、扩展、配色方案映射、分割线主题、文本选择主题、图标主题、滚动条主题）。可通过

Theme.of(context).copyWith(...)

进行重写，且不会丢失Shadcn的默认配置。

Shadcn + Cupertino

Use

CupertinoApp

inside

appBuilder

for Cupertino + shadcn:

dart

import 'package:shadcn_ui/shadcn_ui.dart';
import 'package:flutter/cupertino.dart';
import 'package:flutter_localizations/flutter_localizations.dart';

return ShadApp.custom(
  themeMode: ThemeMode.dark,
  darkTheme: ShadThemeData(
    brightness: Brightness.dark,
    colorScheme: const ShadSlateColorScheme.dark(),
  ),
  appBuilder: (context) {
    return CupertinoApp(
      theme: CupertinoTheme.of(context),
      localizationsDelegates: const [
        DefaultMaterialLocalizations.delegate,
        DefaultCupertinoLocalizations.delegate,
        DefaultWidgetsLocalizations.delegate,
      ],
      builder: (context, child) {
        return ShadAppBuilder(child: child!);
      },
    );
  },
);

Use

CupertinoApp.router

for Router-based navigation. Override Cupertino theme with

CupertinoTheme.of(context).copyWith(...)

在

appBuilder

中使用

CupertinoApp

，实现Cupertino与Shadcn的协同使用：

dart

import 'package:shadcn_ui/shadcn_ui.dart';
import 'package:flutter/cupertino.dart';
import 'package:flutter_localizations/flutter_localizations.dart';

return ShadApp.custom(
  themeMode: ThemeMode.dark,
  darkTheme: ShadThemeData(
    brightness: Brightness.dark,
    colorScheme: const ShadSlateColorScheme.dark(),
  ),
  appBuilder: (context) {
    return CupertinoApp(
      theme: CupertinoTheme.of(context),
      localizationsDelegates: const [
        DefaultMaterialLocalizations.delegate,
        DefaultCupertinoLocalizations.delegate,
        DefaultWidgetsLocalizations.delegate,
      ],
      builder: (context, child) {
        return ShadAppBuilder(child: child!);
      },
    );
  },
);

如需基于Router的导航，请使用

CupertinoApp.router

。可通过

CupertinoTheme.of(context).copyWith(...)

重写Cupertino主题。

Bundled packages

捆绑包

Shadcn UI re-exports these packages; no extra imports needed:

flutter_animate — Animations; components accept
```
List<Effect>
```
for customization.
lucide_icons_flutter — Icons via
```
LucideIcons
```
(e.g.
```
LucideIcons.activity
```
). Browse at https://lucide.dev/icons/
two_dimensional_scrollables — Used by
```
ShadTable
```
.
intl — i18n and message translation.
universal_image — Multiple image formats; used by
```
ShadAvatar
```
.

Shadcn UI会重新导出以下包，无需额外导入：

flutter_animate — 动画库；组件支持通过
```
List<Effect>
```
进行自定义。
lucide_icons_flutter — 通过
```
LucideIcons
```
使用图标（例如
```
LucideIcons.activity
```
）。可在https://lucide.dev/icons/浏览图标。
two_dimensional_scrollables — 供
```
ShadTable
```
使用。
intl — 国际化与消息翻译。
universal_image — 支持多种图片格式；供
```
ShadAvatar
```
使用。

Submit your app

提交你的应用

To add your app to the showcase: open the GitHub template and fill the form.

如需将你的应用添加到展示区：打开GitHub模板并填写表单。