Element Plus 升级与最佳实践规范

本文档记录了 Element Plus 从 v2.x 向 v3.0 过渡期间的废弃 API 替换方案及常见 Vue 渲染警告的修复规范。

1. Button 按钮

变更原因：type="text" 已在 v3.0 中废弃，文字按钮应使用独立的 link 属性。

• ❌ 废弃写法 (Deprecated)

  <el-button type="text">操作</el-button>
  <el-button type="text" icon="el-icon-edit">编辑</el-button>

• ✅ 推荐写法 (Recommended)

  <!-- 基础文字按钮 -->
  <el-button link>操作</el-button>
  
  <!-- 带颜色的文字按钮 (通常替代 type="text") -->
  <el-button link type="primary">操作</el-button>
  <el-button link type="danger">删除</el-button>

2. Radio 单选框 / Checkbox 多选框

变更原因：label 属性不仅作为显示文本，也作为值（value）的行为容易引起混淆。新版 API 明确区分了 value（数据值）和 label（显示文本/旧版兼容）。

• ❌ 废弃写法 (Deprecated)

  <el-radio-group v-model="radio">
    <!-- label 既充当 value 又充当显示的文本（如果没有默认 slot） -->
    <el-radio label="1">选项1</el-radio>
    <el-radio label="2">选项2</el-radio>
  </el-radio-group>

• ✅ 推荐写法 (Recommended)

  <el-radio-group v-model="radio">
    <!-- 显式使用 value 属性 -->
    <el-radio value="1">选项1</el-radio>
    <el-radio :value="2">选项2</el-radio>
  </el-radio-group>

3. Link 链接

变更原因：underline 属性由布尔值变更为枚举字符串，以提供更精细的控制。

• ❌ 废弃写法 (Deprecated)

  <el-link :underline="false">无下划线链接</el-link>

• ✅ 推荐写法 (Recommended)

  <el-link underline="never">无下划线链接</el-link>
  <el-link underline="hover">悬停显示下划线</el-link>
  <el-link underline="always">总是显示下划线</el-link>

4. Vue 渲染警告修复

问题描述：当模板中包含类似 的文本，但这不是 Vue 变量而是需要原样显示的静态文本时，Vue 会尝试解析并报 "Property accessed during render but is not defined" 警告。

• ❌ 问题代码

  <span>请使用 {{name}} 格式作为变量名</span>

• ✅ 修复方案 使用 v-pre 指令告诉 Vue 跳过该元素及其子元素的编译。

  <span v-pre>请使用 {{name}} 格式作为变量名</span>