从零到一：Univer组件设计系统构建可复用UI组件库全指南

你是否还在为企业级文档协作系统开发中重复编写UI组件而烦恼？是否希望拥有一套统一的设计规范来提升开发效率和用户体验？本文将详细介绍Univer组件设计系统，带你快速掌握如何构建和使用可复用的UI组件库，让你的开发工作事半功倍。读完本文，你将了解Univer组件设计系统的核心架构、组件使用方法、定制化技巧以及最佳实践。

组件设计系统概述

Univer组件设计系统是一套为企业级文档和数据协作解决方案打造的UI组件库，旨在确保Univer插件UI的一致性并减少自定义开发的工作量。该系统基于React和Less开发，提供了丰富的基础组件和设计指南，方便开发者快速构建符合设计规范的用户界面。

核心目标

Univer组件设计系统的核心目标包括：

• 提供一致的UI体验 across 所有Univer产品
• 减少重复开发工作，提高开发效率
• 简化组件的定制化过程，支持个性化需求
• 确保组件的可访问性和跨浏览器兼容性

主要组件包

Univer组件设计系统主要包含以下几个核心包：

• @univerjs/design：提供基础设计组件和样式，是整个设计系统的核心。packages/design/README.md
• @univerjs/ui：提供UI扩展接口，用于扩展工具栏、上下文菜单等。
• @univerjs/uniui：实验性UI组件库，包含一些新的组件和功能。packages-experimental/uniui/README.md

快速开始

安装组件库

要开始使用Univer组件设计系统，首先需要安装相关的npm包。推荐使用pnpm进行包管理：

# 使用npm
npm install @univerjs/design

# 使用pnpm
pnpm add @univerjs/design

注意：@univerjs/design包包含CSS样式，并且具有最高优先级。请在导入任何其他Univer样式文件之前导入它。

基本使用示例

以下是一个简单的示例，展示如何在Univer项目中使用Button组件：

import { Button } from '@univerjs/design';

function MyComponent() {
  return (
    <Button onClick={() => console.log('Button clicked!')}>
      Click Me
    </Button>
  );
}

在Sheets中使用组件

Univer组件设计系统的组件可以无缝集成到各种Univer产品中。以下是一个在表格应用中使用RangeSelector组件的示例：

import { Button } from '@univerjs/design';
import { RangeSelector } from '@univerjs/sheets-formula-ui';
import { useRef } from 'react';

export const ButtonRangeSelector = () => {
  const selectorRef = useRef(null);
  
  return (
    <>
      <Button onClick={() => selectorRef.current?.showDialog([])}>
        Start Select
      </Button>
      <RangeSelector
        selectorRef={selectorRef}
        hideEditor
        onChange={(_, str) => {
          console.log('Selected range:', str);
        }}
      />
    </>
  );
};

示例代码来源

核心组件介绍

Univer组件设计系统提供了丰富的UI组件，涵盖了从基础控件到复杂交互组件的各种需求。以下是一些常用的核心组件：

基础组件

基础组件是构建UI的基本积木，包括按钮、输入框、选择器等。

Button组件

Button组件是最常用的交互组件之一，支持多种样式和状态。

import { Button } from '@univerjs/design';

// 主要按钮
<Button type="primary">Primary Button</Button>

// 次要按钮
<Button type="secondary">Secondary Button</Button>

// 危险按钮
<Button type="danger">Danger Button</Button>

// 禁用状态
<Button disabled>Disabled Button</Button>

Input组件

Input组件用于接收用户文本输入，支持多种类型和状态。

import { Input } from '@univerjs/design';

// 基本输入框
<Input placeholder="Enter text here" />

// 密码输入框
<Input type="password" placeholder="Enter password" />

// 带前缀图标的输入框
<Input placeholder="Search" prefix={<SearchOutlined />} />

数据展示组件

数据展示组件用于以清晰、直观的方式呈现数据，包括表格、列表、卡片等。

Table组件

Table组件用于展示结构化数据，支持排序、筛选和分页等功能。

import { Table } from '@univerjs/design';

const columns = [
  { title: 'Name', dataIndex: 'name', key: 'name' },
  { title: 'Age', dataIndex: 'age', key: 'age' },
  { title: 'Address', dataIndex: 'address', key: 'address' },
];

const data = [
  { key: '1', name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
  { key: '2', name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
  { key: '3', name: 'Joe Black', age: 32, address: 'Sidney No. 1 Lake Park' },
];

<Table columns={columns} dataSource={data} />

Card组件

Card组件用于将相关信息组织在一个容器中，提供清晰的视觉层次。

import { Card } from '@univerjs/design';

<Card title="Card Title">
  <p>Card content</p>
  <p>Card content</p>
  <p>Card content</p>
</Card>

交互组件

交互组件用于实现复杂的用户交互功能，如对话框、下拉菜单、日期选择器等。

Dialog组件

Dialog组件用于创建模态对话框，常用于确认操作或显示详细信息。

import { Dialog, Button } from '@univerjs/design';
import { useState } from 'react';

function MyDialog() {
  const [visible, setVisible] = useState(false);

  return (
    <>
      <Button onClick={() => setVisible(true)}>Open Dialog</Button>
      <Dialog
        title="Basic Dialog"
        visible={visible}
        onCancel={() => setVisible(false)}
        onOk={() => setVisible(false)}
      >
        <p>Some contents...</p>
        <p>Some contents...</p>
        <p>Some contents...</p>
      </Dialog>
    </>
  );
}

Dropdown组件

Dropdown组件用于创建下拉菜单，提供更多操作选项。

import { Dropdown, Button, Menu, MenuItem } from '@univerjs/design';

const menu = (
  <Menu>
    <MenuItem key="1">Action 1</MenuItem>
    <MenuItem key="2">Action 2</MenuItem>
    <MenuItem key="3">Action 3</MenuItem>
  </Menu>
);

<Dropdown overlay={menu}>
  <Button>Dropdown</Button>
</Dropdown>

组件架构与设计理念

组件分层设计

Univer组件设计系统采用分层设计理念，将组件分为以下几个层次：

1. 基础组件层：提供最基本的UI元素，如按钮、输入框等，不包含业务逻辑。
2. 复合组件层：由多个基础组件组合而成，提供更复杂的功能，如表格、表单等。
3. 业务组件层：针对特定业务场景封装的组件，如公式编辑器、数据验证组件等。

这种分层设计使得组件具有良好的复用性和可维护性，同时也方便进行定制化和扩展。

响应式设计

Univer组件设计系统采用响应式设计理念，确保组件在不同设备和屏幕尺寸上都能提供良好的用户体验。组件会根据运行环境自动调整布局和样式：

|- controllers/
  |- render-controllers/
    |- common/        # 通用逻辑
    |- desktop/       # 桌面端特定逻辑
    |- mobile/        # 移动端特定逻辑
|- views/
  |- components/
    |- common/        # 通用组件
    |- desktop/       # 桌面端特定组件
    |- mobile/        # 移动端特定组件

主题定制

Univer组件设计系统支持主题定制，可以通过ConfigProvider组件来全局配置主题：

import { ConfigProvider } from '@univerjs/design';

const customTheme = {
  token: {
    colorPrimary: '#0052cc',
    colorSuccess: '#36b37e',
    fontSize: 14,
    // 更多主题变量...
  },
};

function App() {
  return (
    <ConfigProvider theme={customTheme}>
      <MyApp />
    </ConfigProvider>
  );
}

高级用法

自定义组件

除了使用内置组件外，Univer组件设计系统还支持创建自定义组件。创建自定义组件的步骤如下：

1. 创建组件文件，实现组件逻辑
2. 导出组件，遵循Univer命名规范
3. 在需要使用的地方导入并使用

以下是一个自定义按钮组件的示例：

// src/components/custom-button/MyButton.tsx
import { Button, type IButtonProps } from '@univerjs/design';
import React from 'react';

export interface IMyButtonProps extends IButtonProps {
  // 自定义属性
  icon?: React.ReactNode;
}

export const MyButton: React.FC<IMyButtonProps> = ({ icon, children, ...props }) => {
  return (
    <Button {...props}>
      {icon && <span style={{ marginRight: 4 }}>{icon}</span>}
      {children}
    </Button>
  );
};

组件通信

在复杂应用中，组件之间的通信非常重要。Univer组件设计系统提供了多种组件通信方式：

1. Props传递：父组件通过props向子组件传递数据和回调函数
2. Context API：使用React Context在组件树中共享数据
3. 状态管理：对于更复杂的状态管理，可以集成Redux或MobX等状态管理库
4. 事件总线：使用Univer提供的事件系统进行跨组件通信

以下是一个使用Context API进行组件通信的示例：

import { createContext, useContext, ReactNode } from 'react';

// 创建Context
interface AppContextType {
  theme: 'light' | 'dark';
  toggleTheme: () => void;
}

const AppContext = createContext<AppContextType | undefined>(undefined);

// 创建Provider组件
export function AppProvider({ children }: { children: ReactNode }) {
  const [theme, setTheme] = React.useState<'light' | 'dark'>('light');
  
  const toggleTheme = () => {
    setTheme(prev => prev === 'light' ? 'dark' : 'light');
  };
  
  return (
    <AppContext.Provider value={{ theme, toggleTheme }}>
      {children}
    </AppContext.Provider>
  );
}

// 自定义Hook简化使用
export function useAppContext() {
  const context = useContext(AppContext);
  if (context === undefined) {
    throw new Error('useAppContext must be used within an AppProvider');
  }
  return context;
}

性能优化

为了确保应用具有良好的性能，Univer组件设计系统提供了多种性能优化手段：

1. 懒加载组件：使用动态import()语法懒加载非关键组件
2. 组件缓存：使用React.memo缓存组件渲染结果
3. 虚拟滚动：对于大数据列表，使用虚拟滚动减少DOM节点数量
4. 代码分割：将代码分割成小块，按需加载

以下是一个使用懒加载的示例：

// examples/src/sheets-no-worker/lazy.ts
import { lazy } from 'react';

// 懒加载组件
export const LazyComponent = lazy(() => import('./very-lazy'));

最佳实践

组件命名规范

为了确保代码的一致性和可读性，Univer组件设计系统遵循严格的命名规范：

1. 文件和文件夹：使用kebab-case命名
2. React组件：使用PascalCase命名
3. 接口：以"I"开头，使用PascalCase命名
4. 常量：使用UPPER_SNAKE_CASE命名

详细的命名规范可以参考Univer命名规范文档。

组件文档

为了提高组件的可维护性和易用性，每个组件都应该有完善的文档。Univer使用Storybook来开发和测试组件，并自动生成组件文档：

# 启动Storybook
pnpm storybook:dev

测试策略

Univer组件设计系统采用多种测试策略来确保组件质量：

1. 单元测试：使用Vitest测试单个组件的功能
2. 集成测试：测试组件之间的交互
3. E2E测试：使用Playwright进行端到端测试
4. 视觉测试：使用视觉比较测试确保UI一致性

总结与展望

Univer组件设计系统为企业级文档协作解决方案提供了强大的UI组件支持，通过统一的设计规范和丰富的组件库，大大提高了开发效率和用户体验。本文介绍了组件设计系统的核心概念、使用方法、架构设计和最佳实践，希望能帮助开发者更好地理解和使用Univer组件库。

未来，Univer组件设计系统将继续完善和扩展，计划添加更多实用组件和功能，如：

• 更丰富的数据可视化组件
• 增强的表单控件和验证功能
• 改进的主题系统和定制能力
• 更好的TypeScript类型支持

如果你对Univer组件设计系统有任何建议或反馈，欢迎通过GitHub Issues提出。同时，也欢迎你参与到Univer的开源项目中，一起推动组件设计系统的发展和完善。