设计系统

provideRtkDesignSystem() 工具允许你使用自定义设计系统来覆盖现有的设计系统。

每个移动平台都提供了一个设计令牌系统，用于控制颜色、边框、排版和间距。你可以在启动会议之前配置令牌，UI Kit 会将它们应用到所有组件中。

<script type="module">
	import { provideRtkDesignSystem } from "https://cdn.jsdelivr.net/npm/@cloudflare/realtimekit-ui@latest/dist/index.js";
</script>

import { provideRtkDesignSystem } from "@cloudflare/realtimekit-react-ui";

import { provideRtkDesignSystem } from "@cloudflare/realtimekit-angular-ui";

import RealtimeKitUI

import com.cloudflare.realtimekit.ui.RealtimeKitUIBuilder
import com.cloudflare.realtimekit.ui.RealtimeKitUIInfo
import com.cloudflare.realtimekit.ui.token.*
import com.cloudflare.realtimekit.models.RtkMeetingInfo

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

import {
	RtkUIProvider,
	provideRtkDesignSystem,
	generateBrandColors,
	generateBackgroundColors,
} from "@cloudflare/realtimekit-react-native-ui";

<div id="app"></div>

<script>
	provideRtkDesignSystem(document.getElementById("app"), {
		googleFont: "Lobster",
		// sets light background colors
		theme: "light",
		colors: {
			danger: "#ffac00",
			brand: {
				300: "#00FFE1",
				400: "#00FFFF",
				500: "#00E1D4",
				600: "#007B74",
				700: "#00655F",
			},
			text: "#071428",
			"text-on-brand": "#ffffff",
			"video-bg": "#E5E7EB",
		},
		borderRadius: "extra-rounded",
	});
</script>

<div id="app"></div>

<script>
	provideRtkDesignSystem(document.getElementById("app"), {
		googleFont: "Lobster",
		// sets light background colors
		theme: "light",
		colors: {
			danger: "#ffac00",
			brand: {
				300: "#00FFE1",
				400: "#00FFFF",
				500: "#00E1D4",
				600: "#007B74",
				700: "#00655F",
			},
			text: "#071428",
			"text-on-brand": "#ffffff",
			"video-bg": "#E5E7EB",
		},
		borderRadius: "extra-rounded",
	});
</script>

function Example() {
	const meetingEl = useRef();
	const { meeting } = useRealtimeKitMeeting();

	useEffect(() => {
		provideRtkDesignSystem(meetingEl.current, {
			googleFont: "Lobster",
			// sets light background colors
			theme: "light",
			colors: {
				danger: "#ffac00",
				brand: {
					300: "#00FFE1",
					400: "#00FFFF",
					500: "#00E1D4",
					600: "#007B74",
					700: "#00655F",
				},
				text: "#071428",
				"text-on-brand": "#ffffff",
				"video-bg": "#E5E7EB",
			},
			borderRadius: "extra-rounded",
		});
	}, []);

	return (
		<div style={{ height: "400px" }}>
			<RtkMeeting meeting={meeting} ref={meetingEl} mode="fill" />
		</div>
	);
}

构建一个 RtkDesignTokens 对象并将其传递给 RealtimeKitUIInfo。然后调用 RealtimeKitUIBuilder.build() 来启动会议。

import android.graphics.Color

val customColors = RtkColorTokens(
    brand = BrandColor(
        shade300 = Color.parseColor("#FF9A6C"),
        shade400 = Color.parseColor("#FF8552"),
        shade500 = Color.parseColor("#FF6B35"),
        shade600 = Color.parseColor("#E55A24"),
        shade700 = Color.parseColor("#CC4A14"),
    ),
    background = BackgroundColor(
        shade600 = Color.parseColor("#666666"),
        shade700 = Color.parseColor("#4C4C4C"),
        shade800 = Color.parseColor("#333333"),
        shade900 = Color.parseColor("#1A1A1A"),
        shade1000 = Color.parseColor("#080808"),
    ),
    text = TextColor(
        onBrand = TextColor.TextColorOnBrand(
            shade1000 = Color.parseColor("#FF111111"),
            shade900 = Color.parseColor("#E0111111"),
            shade800 = Color.parseColor("#C2111111"),
            shade700 = Color.parseColor("#A3111111"),
            shade600 = Color.parseColor("#85111111"),
        ),
        onBackground = TextColor.TextColorOnBackground(
            shade1000 = Color.parseColor("#FFFFFFFF"),
            shade900 = Color.parseColor("#E0FFFFFF"),
            shade800 = Color.parseColor("#C2FFFFFF"),
            shade700 = Color.parseColor("#A3FFFFFF"),
            shade600 = Color.parseColor("#85FFFFFF"),
        ),
    ),
)

val designTokens = RtkDesignTokens(
    colors = customColors,
    borderRadius = RtkBorderRadiusToken.Rounded,
    borderWidth = RtkBorderWidthToken.Thin,
)

val uiKitInfo = RealtimeKitUIInfo(
    activity = this,
    rtkMeetingInfo = RtkMeetingInfo(authToken = "<auth_token>"),
    designTokens = designTokens,
)
RealtimeKitUIBuilder.build(uiKitInfo).startMeeting()

构建一个 RtkDesignTokens 对象，并通过 designToken 参数将其传递给 RealtimeKitUIInfo。

Flutter 支持两种颜色配置方法：

简易（Simple） — 提供单个基础颜色，SDK 会自动生成所有色调
高级（Advanced） — 提供包含所有色调值的显式 RtkColorSwatch

简易颜色配置：

final designTokens = RtkDesignTokens(
  colorToken: RtkColorToken(
    backgroundColor: const Color(0xFF0B0B0B),
    brandColor: const Color(0xFFF17F1F),
    textOnBrand: Colors.white,
    textOnBackground: Colors.white,
  ),
  borderRadius: RtkBorderRadius.rounded,
  borderWidth: RtkBorderWidth.none,
);

final uiKitInfo = RealtimeKitUIInfo(meetingInfo, designToken: designTokens);
final rtkUI = RealtimeKitUIBuilder.build(uiKitInfo: uiKitInfo);
Navigator.push(context, MaterialPageRoute(builder: (_) => rtkUI));

高级颜色配置 — 使用 RtkColorSwatch 精确控制每个色调：

final designTokens = RtkDesignTokens(
  colorToken: RtkColorToken(
    brandColorSwatch: RtkColorSwatch(500, {
      300: const Color(0xFFFF9A6C),
      400: const Color(0xFFFF8552),
      500: const Color(0xFFFF6B35),
      600: const Color(0xFFE55A24),
      700: const Color(0xFFCC4A14),
    }),
    backgroundColorSwatch: RtkColorSwatch(1000, {
      600: const Color(0xFF666666),
      700: const Color(0xFF4C4C4C),
      800: const Color(0xFF333333),
      900: const Color(0xFF1A1A1A),
      1000: const Color(0xFF080808),
    }),
    textOnBrand: Colors.white,
    textOnBackground: Colors.white,
  ),
  borderRadius: RtkBorderRadius.extrarounded,
  borderWidth: RtkBorderWidth.thin,
);

在渲染之前或渲染期间，使用 DesignTokens 对象调用 provideRtkDesignSystem()。将你的会议组件包裹在 RtkUIProvider 中。

import { useEffect } from 'react';

function App() {
  useEffect(() => {
    provideRtkDesignSystem({
      theme: 'darkest',
      colors: {
        brand: generateBrandColors('#FF6B35'),
        text: '#FFFFFF',
      },
      borderRadius: 'rounded',
      borderWidth: 'thin',
      fontFamily: 'Helvetica',
    });
  }, []);

  return (
    <RtkUIProvider>
      {/* Your meeting components */}
    </RtkUIProvider>
  );
}

generateBrandColors() 辅助函数可从单个十六进制值派生出五个品牌色调。使用 generateBackgroundColors() 也可以对背景颜色实现相同的行为。

iOS UI Kit 使用 DesignLibrary.shared 作为其核心设计令牌注册表。创建一个符合 DesignLibraryConfiguratorProtocol 的自定义配置器，并在开始会议之前将其传递给设计库。

import RealtimeKitUI

class CustomConfigurator: DesignLibraryConfiguratorProtocol {
    let colorBrandBase: BrandColorToken.Shade = .init(hex: "#FF6B35")!
    let colorBackgroundBase: BackgroundColorToken.Shade = .init(hex: "#080808")!

    let textColorBackgroundBase: TextColorToken.Background.Shade = .init(hex: "#FFFFFF")!
    let textColorBrandBase: TextColorToken.Brand.Shade = .init(hex: "#111111")!

    let statusDangerColor: StatusColor.Shade = .init(hex: "#FF2D2D")!
    let statusSuccessColor: StatusColor.Shade = .init(hex: "#83D017")!
    let statusWarningColor: StatusColor.Shade = .init(hex: "#FFCD07")!

    let cornerRadiusRoundFactor: CGFloat = 4.0
    let cornerRadiusExtraRoundFactor: CGFloat = 8.0
    let cornerRadiusCircularFactor: CGFloat = 8.0

    let borderSizeThinFactor: CGFloat = 1.0
    let borderSizeFatFactor: CGFloat = 2.0
}

// Apply the custom configurator
DesignLibrary.shared.setConfigurator(configurator: CustomConfigurator())

SDK 会从每个基础颜色自动生成色调变化。品牌色调范围为 300–700，背景色调范围为 600–1000，均通过调亮基础颜色派生。

UI Kit 在其设计系统中使用设计令牌 ↗。

设计令牌是用于维护设计系统的设计相关值，通过排版、间距、颜色等值提供自定义系统整体设计的灵活性。

这些设计令牌借助 CSS 变量 ↗在组件之间存储和共享。

令牌系统涵盖了颜色、边框、排版和间距。下表显示了所有移动平台上的默认值。

令牌	Android	Flutter	iOS	React Native
品牌颜色	`#2160FD`	`#2160FD`	`#0246FD`	`#2160FD`
背景	`#080808`	`#080808`	`#050505`	`#080808`
背景上的文本	`#FFFFFF`	`#FFFFFF`	`#FFFFFF`	`#FFFFFF`
品牌上的文本	`#111111`	—	`#111111`	`#FFFFFF`
危险（Danger）	`#FF2D2D`	`#FF2D2D`	`#FF2D2D`	`#FF2D2D`
成功（Success）	`#83D017`	`#83D017`	`#83D017`	`#83D017`
警告（Warning）	`#FFCD07`	`#FFCD07`	`#FFCD07`	`#FFCD07`

你可以使用此令牌轻松调整 UI Kit 组件中使用的字体系列。你可以使用 provideRtkDesignSystem 工具通过两种方式编辑此值。

--rtk-font-family: Inter;

使用

在你的设计令牌中设置其中任一值。

使用 fontFamily - 使用自定义字体系列，你必须手动加载该字体。
使用 googleFont - 使用 Google 字体，字体会自动加载。

const designTokens = {
	fontFamily: "Custom Font",
	// or
	googleFont: "A Google Font",
};

无法通过 RtkDesignTokens API 进行字体自定义。UI Kit 默认使用系统字体。

Flutter UI Kit 捆绑了 Inter 字体并默认使用它。无法通过 RtkDesignTokens API 进行自定义字体配置。

将 fontFamily 字符串传递给 provideRtkDesignSystem() 以使用自定义字体。在调用此函数之前，你必须在应用中加载该字体。

provideRtkDesignSystem({
	fontFamily: "Helvetica",
});

iOS UI Kit 默认使用系统字体（UIFont.systemFont）。字体自定义未通过 DesignLibraryConfiguratorProtocol 公开。若要更改字体，请创建一个自定义的 AppThemeProtocol 实现，并覆盖单个组件的外观属性。

class CustomTheme: AppThemeProtocol {
    // ...
    var clockViewAppearance: RtkTextAppearance {
        let model = RtkTextAppearanceModel()
        model.font = UIFont(name: "Helvetica", size: 12) ?? .systemFont(ofSize: 12)
        return model
    }
    // ...
}

CSS 变量采用以下格式设置：R G B。

以下是所有的颜色令牌及其默认值。

--rtk-colors-brand-500: 33 96 253;
--rtk-colors-background-1000: 8 8 8;
/* ... rest of the shades */

使用

默认情况下，theme 属性提供了一组常用的 background 色调。

主题（Theme）值为：light、dark、darkest。

像这样编辑颜色令牌。将仅设置你指定的颜色。

const designTokens = {
	theme: "darkest",
	colors: {
		brand: { 500: "#0D51FD" },
		background: { 1000: "#080808" },
		text: "#ffffff",
		"text-on-brand": "#ffffff",
		"video-bg": "#181818",
	},
};

品牌颜色色调范围为 300（最浅）到 700（最深），其中 500 为主要色调。背景色调范围为 600（最浅）到 1000（最深）。

在你的 DesignLibraryConfiguratorProtocol 实现中设置 colorBrandBase 和 colorBackgroundBase。SDK 会通过以 12% 的增量调亮基础颜色，自动为品牌生成 300–700 色调，为背景生成 600–1000 色调。

iOS 还在 BackgroundColorToken 上公开了一个 video 属性，用于在没有活动数据流时控制视频卡片背后的颜色。默认值为 shade800。

class CustomConfigurator: DesignLibraryConfiguratorProtocol {
    let colorBrandBase: BrandColorToken.Shade = .init(hex: "#FF6B35")!
    let colorBackgroundBase: BackgroundColorToken.Shade = .init(hex: "#1A1A1A")!

    let textColorBackgroundBase: TextColorToken.Background.Shade = .init(hex: "#FFFFFF")!
    let textColorBrandBase: TextColorToken.Brand.Shade = .init(hex: "#111111")!

    let statusDangerColor: StatusColor.Shade = .init(hex: "#FF2D2D")!
    let statusSuccessColor: StatusColor.Shade = .init(hex: "#83D017")!
    let statusWarningColor: StatusColor.Shade = .init(hex: "#FFCD07")!

    // Border properties (required by protocol)
    let cornerRadiusRoundFactor: CGFloat = 4.0
    let cornerRadiusExtraRoundFactor: CGFloat = 8.0
    let cornerRadiusCircularFactor: CGFloat = 8.0
    let borderSizeThinFactor: CGFloat = 1.0
    let borderSizeFatFactor: CGFloat = 2.0
}

Android 在 RtkColorTokens 上提供了一个 videoBackground 字段，用于在没有活动视频流时设置视频卡片背后显示的颜色。默认值为 #333333。

val customColors = RtkColorTokens(
    brand = BrandColor( /* ... */ ),
    background = BackgroundColor( /* ... */ ),
    text = TextColor( /* ... */ ),
    videoBackground = Color.parseColor("#1A1A1A"),
)

React Native 提供了三个预设主题，可设置协调的背景颜色调色板。

主题	描述
`darkest`	非常深的背景（默认）
`dark`	深色背景
`light`	浅色背景

将 theme 属性传递给 provideRtkDesignSystem()。你可以将预设主题与自定义颜色覆盖相结合。

provideRtkDesignSystem({
	theme: "dark",
	colors: {
		brand: generateBrandColors("#0246FD"),
	},
});

间距比例用于在整个组件中设置宽度、高度、外边距、内边距、位置等。

间距比例基准的默认值是 4px。
其余的值都以此基准计算，并设置为 --rtk-space-1。
当前间距比例范围为 0 到 96。

--rtk-space-1: 4px;
/* ... rest of the spacing scale */

使用

使用 spacingBase 属性设置间距比例的基准。

const designTokens = {
	spacingBase: 4, // value in px
};

spacingBase 属性以像素为单位设置间距比例的基准单位。UI Kit 中的所有间距值均派生自此基准。

provideRtkDesignSystem({
	spacingBase: 4, // default: 4px
});

在此平台上无法通过设计令牌 API 进行间距配置。

iOS UI Kit 使用基准单位为 4 点（points）的 SpaceToken。间距比例范围为 space0 (0) 到 space9 (36)。间距配置未通过公开的 DesignLibraryConfiguratorProtocol 暴露。所有间距值均在内部从基准单位派生。

边框宽度（Border Width）和边框半径（Border Radius）属性也可以使用设计令牌进行自定义！

令牌名称	值
`borderWidth`	`none`, `thin`, `fat`
`borderRadius`	`sharp`, `rounded`, `extra-rounded`, `circular`

使用

const designTokens = {
	borderWidth: "thin",
	borderRadius: "rounded",
};

所有移动平台都支持相同的边框半径和边框宽度选项。

令牌	值
`borderRadius`	`sharp`, `rounded`, `extra-rounded`, `circular`
`borderWidth`	`none`, `thin`, `fat`

将 borderRadius 和 borderWidth 直接传递给 RtkDesignTokens 构造函数。

val designTokens = RtkDesignTokens(
    colors = customColors,
    borderRadius = RtkBorderRadiusToken.Circular,
    borderWidth = RtkBorderWidthToken.Thin,
)

将 borderRadius 和 borderWidth 传递给 RtkDesignTokens 构造函数。

final designTokens = RtkDesignTokens(
  colorToken: colorToken,
  borderRadius: RtkBorderRadius.rounded,
  borderWidth: RtkBorderWidth.thin,
);

将 borderRadius 和 borderWidth 传递给 provideRtkDesignSystem()。

provideRtkDesignSystem({
	borderRadius: "extra-rounded",
	borderWidth: "fat",
});

在你的 DesignLibraryConfiguratorProtocol 实现中设置 cornerRadiusRoundFactor、cornerRadiusExtraRoundFactor、cornerRadiusCircularFactor、borderSizeThinFactor 和 borderSizeFatFactor。这些系数控制着用于每种边框样式的乘数。

class CustomConfigurator: DesignLibraryConfiguratorProtocol {
    // ... color properties ...

    let cornerRadiusRoundFactor: CGFloat = 4.0
    let cornerRadiusExtraRoundFactor: CGFloat = 8.0
    let cornerRadiusCircularFactor: CGFloat = 8.0

    let borderSizeThinFactor: CGFloat = 1.0
    let borderSizeFatFactor: CGFloat = 2.0
}

DesignLibrary.shared.setConfigurator(configurator: CustomConfigurator())

iOS 使用 BorderRadiusToken.RadiusType，其值包括 .sharp、.rounded、.extrarounded 和 .circular。边框宽度使用 BorderWidthToken.Width，其值包括 .none、.thin 和 .fat。

前提条件

覆盖设计系统

导入

使用

设计令牌

排版

使用

颜色

使用

间距

使用

边框

使用