迁移指南

本指南介绍将组件从 UI1（decentraland-ui）到 UI2（decentraland-ui2).

何时迁移

迁移可以基于三个有效原因开始：

1. 技术改进

你希望迁移某个组件的原因有：

• 更好的主题支持

• 改进的 TypeScript 类型

• 与其他 UI2 组件保持一致

• 性能优化

• 可访问性改进

2. 更新组件

• 某个 UI1 组件需要更新

• 目前还没有对应的 UI2 版本

• 要求：先在 UI2 中创建它，然后再使用

3. 项目需求

• 该组件将用于新项目或现有项目

• 有足够时间正确完成迁移

• 项目资源允许进行彻底迁移

不要 仅仅因为“想迁移”就迁移组件。每次迁移都应有明确的业务或技术理由。

---

迁移流程

步骤 1：规划

在开始迁移之前：

1. 识别依赖

   • 它使用了哪些其他组件？

   • 目前有哪些项目在使用它？

   • 是否计划了任何破坏性变更？

2. 审查当前使用情况

   • 有多少项目使用这个组件？

   • 最常用的是哪些属性？

   • 是否存在已知问题？

3. 定义范围

   • 这会是 1:1 迁移吗？

   • 是否有计划中的改进？

   • 时间安排是什么？

步骤 2：创建 UI2 组件

遵循 自定义组件 UI2 候选组件指南。

要求：

• styled-components 使用对象语法

• 只使用主题值（不使用任意值）

• 添加完整的 Storybook stories

• 编写完整测试

• 记录所有属性和行为

示例结构：

ui2/src/components/Button/
├── Button.tsx
├── Button.styles.ts
├── Button.stories.tsx
├── Button.test.tsx
├── types.ts
├── index.ts
└── README.md

步骤 3：保持兼容性

UI2 组件 必须 应暴露与 UI1 版本相同的属性和行为。

相同的属性

// UI1 按钮
interface ButtonProps {
  primary?: boolean;
  size?: 'small' | 'medium' | 'large';
  onClick?: () => void;
  disabled?: boolean;
  children: React.ReactNode;
}

// UI2 按钮 - 必须支持相同的属性
interface ButtonProps {
  primary?: boolean;
  size?: 'small' | 'medium' | 'large';
  onClick?: () => void;
  disabled?: boolean;
  children: React.ReactNode;
  // 可以添加新的可选属性
  variant?: 'text' | 'outlined' | 'contained';
}

向后兼容的更改

如果你需要更改或添加属性：

1. 首先，先将新属性作为可选项添加到 UI1

2. 然后，将 UI1 的使用方迁移为使用这些新属性

3. 最后，使用新的 API 创建 UI2 组件

// 步骤 1：为 UI1 添加可选属性
interface ButtonProps {
  primary?: boolean;
  // 新的可选属性
  variant?: 'primary' | 'secondary';
}

// 步骤 2：更新 UI1 实现
export function Button({ primary, variant = primary ? 'primary' : 'secondary' }: ButtonProps) {
  // 内部使用 variant 代替 primary
}

// 步骤 3：使用新的 API 创建 UI2
interface ButtonProps {
  // variant 现在是主要属性
  variant?: 'primary' | 'secondary';
  // 为兼容性保留 primary，并标记为已弃用
  /** @deprecated 请改用 variant */
  primary?: boolean;
}

步骤 4：将 UI1 组件标记为弃用

在 UI1 组件中添加弃用提示：

/**
 * @deprecated 此组件已迁移到 UI2。
 * 请改为从 'decentraland-ui2' 导入：
 * 
 * ```tsx
 * import { Button } from 'decentraland-ui2';
 * ```
 * 
 * 查看迁移指南：https://docs.decentraland.org/contributor-guides/web-ui-standards/migration
 */
export function Button(props: ButtonProps) {
  // ... 现有实现
}

步骤 5：逐步采用

不要强制立即迁移。允许逐步采用：

1. 发布 UI2 组件

2. 记录 迁移路径

3. 更新 新项目以使用 UI2

4. 迁移 在合适时机迁移现有项目

5. 规划 最终移除 UI1（附带通知）

---

迁移示例

示例 1：简单组件

迁移一个基础 Card 组件：

UI1 版本

// decentraland-ui/src/components/Card/Card.tsx
import React from 'react';
import './Card.css';

export interface CardProps {
  className?: string;
  children: React.ReactNode;
}

export function Card({ className, children }: CardProps) {
  return (
    <div className={`dcl-card ${className || ''}`}>
      {children}
    </div>
  );
}

UI2 版本

// decentraland-ui2/src/components/Card/Card.tsx
import { styled } from '@mui/material/styles';

export interface CardProps {
  className?: string;
  children: React.ReactNode;
}

const StyledCard = styled('div')(({ theme }) => ({
  backgroundColor: theme.palette.background.paper,
  borderRadius: theme.shape.borderRadius,
  padding: theme.spacing(2),
  boxShadow: theme.shadows[1],
  
  [theme.breakpoints.down('sm')]: {
    padding: theme.spacing(1),
  },
}));

export function Card({ className, children }: CardProps) {
  return (
    <StyledCard className={className}>
      {children}
    </StyledCard>
  );
}

示例 2：带变体的组件

迁移一个 Button 及其变体：

UI1 版本

// UI1
import './Button.css';

interface ButtonProps {
  primary?: boolean;
  secondary?: boolean;
  size?: 'small' | 'medium' | 'large';
}

export function Button({ primary, secondary, size = 'medium', ...props }: ButtonProps) {
  const classes = [
    'dcl-button',
    primary && 'primary',
    secondary && 'secondary',
    `size-${size}`,
  ].filter(Boolean).join(' ');
  
  return <button className={classes} {...props} />;
}

UI2 版本

// UI2
import { styled } from '@mui/material/styles';

interface ButtonProps {
  /** @deprecated 请改用 variant="contained" */
  primary?: boolean;
  /** @deprecated 请改用 variant="outlined" */
  secondary?: boolean;
  variant?: 'text' | 'outlined' | 'contained';
  size?: 'small' | 'medium' | 'large';
}

const StyledButton = styled('button')<ButtonProps>(({ theme, variant = 'contained', size = 'medium' }) => {
  const sizes = {
    small: theme.spacing(0.5, 1),
    medium: theme.spacing(1, 2),
    large: theme.spacing(1.5, 3),
  };
  
  const variants = {
    text: {
      backgroundColor: 'transparent',
      color: theme.palette.primary.main,
    },
    outlined: {
      backgroundColor: 'transparent',
      color: theme.palette.primary.main,
      border: `1px solid ${theme.palette.primary.main}`,
    },
    contained: {
      backgroundColor: theme.palette.primary.main,
      color: theme.palette.primary.contrastText,
    },
  };
  
  return {
    padding: sizes[size],
    borderRadius: theme.shape.borderRadius,
    border: 'none',
    cursor: 'pointer',
    ...variants[variant],
    
    '&:hover': {
      opacity: 0.9,
    },
    
    '&:disabled': {
      opacity: 0.5,
      cursor: 'not-allowed',
    },
  };
});

export function Button({ 
  primary, 
  secondary, 
  variant, 
  ...props 
}: ButtonProps) {
  // 处理已弃用的属性
  const actualVariant = variant || 
    (primary ? 'contained' : secondary ? 'outlined' : 'text');
  
  return <StyledButton variant={actualVariant} {...props} />;
}

---

迁移清单

每次组件迁移都使用此清单：

规划阶段

• 识别所有使用该组件的项目

• 记录当前属性和行为

• 定义迁移范围和时间线

• 获得相关方批准

实施阶段

• 按照标准创建 UI2 组件

• 保持属性兼容性

• 使用对象语法进行样式设置

• 仅使用主题值

• 实现所有状态（空闲、悬停、聚焦、禁用、错误）

• 添加完整的 Storybook stories

• 编写单元测试

• 记录可访问性特性

弃用阶段

• 为 UI1 组件添加弃用提示

• 更新 UI1 文档

• 为使用方创建迁移指南

• 发布 UI2 组件

采用阶段

• 更新新项目以使用 UI2

• 为现有项目创建迁移 PR

• 监控问题

• 收集反馈

• 规划 UI1 移除时间线

---

常见迁移模式

从 CSS 到 Styled Components

// UI1：CSS 文件
.dcl-card {
  background: #fff;
  padding: 16px;
  border-radius: 8px;
}

// UI2：样式组件
const Card = styled('div')(({ theme }) => ({
  backgroundColor: theme.palette.background.paper,
  padding: theme.spacing(2),
  borderRadius: theme.shape.borderRadius,
}));

从类名到属性

// UI1：基于类名的变体
<Button className={primary ? 'primary' : 'secondary'} />

// UI2：基于属性的变体
<Button variant={primary ? 'contained' : 'outlined'} />

从固定值到主题值

// UI1：固定值
const styles = {
  color: '#333',
  fontSize: '14px',
  padding: '8px 16px',
};

// UI2：主题值
const Component = styled('div')(({ theme }) => ({
  color: theme.palette.text.primary,
  fontSize: theme.typography.body2.fontSize,
  padding: theme.spacing(1, 2),
}));

---

破坏性变更

有时需要破坏性变更。请谨慎处理：

何时可接受破坏性变更

• 安全修复

• 严重漏洞

• 主版本更新

• 移除已弃用功能（附带通知）

如何处理破坏性变更

1. 尽早宣布 - 提前充分传达变更

2. 提供迁移路径 - 记录如何更新

3. 版本升级 - 遵循语义化版本控制

4. 弃用期 - 留出迁移时间

5. 代码转换工具 - 如果可能，提供自动化迁移工具

示例：移除已弃用的属性

// 版本 1.0：引入新 API，弃用旧 API
interface ButtonProps {
  /** @deprecated 请改用 variant="contained" */
  primary?: boolean;
  variant?: 'text' | 'outlined' | 'contained';
}

// 版本 1.5：提醒即将移除
interface ButtonProps {
  /** @deprecated 将在 2.0 中移除。请改用 variant */
  primary?: boolean;
  variant?: 'text' | 'outlined' | 'contained';
}

// 版本 2.0：移除已弃用的属性
interface ButtonProps {
  variant?: 'text' | 'outlined' | 'contained';
}

---

测试迁移

确保迁移后的组件正常工作：

视觉回归测试

以视觉方式比较 UI1 和 UI2 组件：

// 用于比较的 Storybook story
export const ComparisonStory: Story = {
  render: () => (
    <div style={{ display: 'flex', gap: '2rem' }}>
      <div>
        <h3>UI1</h3>
        <UI1Button primary>Click Me</UI1Button>
      </div>
      <div>
        <h3>UI2</h3>
        <UI2Button variant="contained">Click Me</UI2Button>
      </div>
    </div>
  ),
};

行为测试

确保属性的工作方式相同：

describe('Button migration', () => {
  it('应将 primary 属性（已弃用）与 variant="contained" 以相同方式处理', () => {
    const { container: ui1 } = render(<UI1Button primary>Test</UI1Button>);
    const { container: ui2 } = render(<UI2Button primary>Test</UI2Button>);
    
    // 比较渲染输出
    expect(ui1.textContent).toBe(ui2.textContent);
  });
});

---

文档更新

迁移后，更新文档：

更新 UI1 组件文档

# Button（UI1 - 已弃用）

> ⚠️ **此组件已迁移到 UI2。**
> 有关新版本，请参阅 [UI2 Button 文档](../ui2/button)。

此组件已弃用，并将在未来版本中移除。
请迁移到 UI2。

## 迁移指南

详情请参阅 [Migration Guide](./migration)。

创建 UI2 组件文档

# Button（UI2）

支持完整主题的现代按钮组件。

## 从 UI1 迁移

如果你正在从 UI1 迁移：

- `primary` 属性 → `variant="contained"`
- `secondary` 属性 → `variant="outlined"`
- CSS 类 → styled-components

详情请参阅完整的 [Migration Guide](./migration)。

---

下一步

• 回顾 自定义组件 用于创建 UI2 组件

• 查看 样式与主题 用于样式标准

• 检查 流程概览 完整工作流