1. 程式人生 > >ElementUI騰訊雲開發者開發指南

ElementUI騰訊雲開發者開發指南

原文地址:https://cloud.tencent.com/developer/chapter/18051

目錄

安裝

npm 安裝

CDN

Hello world

快速上手

使用 [email protected]

使用 Starter Kit

引入 Element

全域性配置

開始使用

使用 Nuxt.js

國際化

相容 [email protected]

相容其他 i18n 外掛

相容 [email protected]

按需載入裡定製 i18n

通過 CDN 的方式載入語言檔案

自定義主題

僅替換主題色

在專案中改變 SCSS 變數

命令列主題工具

內建過渡動畫

fade 淡入淡出

zoom 縮放

collapse 展開摺疊

按需引入


安裝

npm 安裝

推薦使用 npm 的方式安裝,它能更好地和 webpack 打包工具配合使用。

npm i element-ui -S

CDN

目前可以通過 unpkg.com/element-ui 獲取到最新版本的資源,在頁面上引入 js 和 css 檔案即可開始使用。

<!-- 引入樣式 -->
<link rel="stylesheet" href="https://unpkg.com/element-ui/lib/theme-chalk/index.css">
<!-- 引入元件庫 -->
<script src="https://unpkg.com/element-ui/lib/index.js"></script>

我們建議使用 CDN 引入 Element 的使用者在連結地址上鎖定版本,以免將來 Element 升級時受到非相容性更新的影響。鎖定版本的方法請檢視 unpkg.com

Hello world

通過 CDN 的方式我們可以很容易地使用 Element 寫出一個 Hello world 頁面。

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <!-- import CSS -->
  <link rel="stylesheet" href="https://unpkg.com/element-ui/lib/theme-chalk/index.css">
</head>
<body>
  <div id="app">
    <el-button @click="visible = true">Button</el-button>
    <el-dialog :visible.sync="visible" title="Hello world">
      <p>Try Element</p>
    </el-dialog>
  </div>
</body>
  <!-- import Vue before Element -->
  <script src="https://unpkg.com/vue/dist/vue.js"></script>
  <!-- import JavaScript -->
  <script src="https://unpkg.com/element-ui/lib/index.js"></script>
  <script>
    new Vue({
      el: '#app',
      data: function() {
        return { visible: false }
      }
    })
  </script>
</html>

如果是通過 npm 安裝,並希望配合 webpack 使用,請閱讀下一節:快速上手。

快速上手

本節將介紹如何在專案中使用 Element。

使用 [email protected]

我們為新版的 vue-cli 準備了相應的 Element 外掛,你可以用它們快速地搭建一個基於 Element 的專案。

使用 Starter Kit

我們提供了通用的專案模板,你可以直接使用。對於 Laravel 使用者,我們也準備了相應的模板,同樣可以直接下載使用。

如果不希望使用我們提供的模板,請繼續閱讀。

引入 Element

你可以引入整個 Element,或是根據需要僅引入部分元件。我們先介紹如何引入完整的 Element。

完整引入

在 main.js 中寫入以下內容:

import Vue from 'vue';
import ElementUI from 'element-ui';
import 'element-ui/lib/theme-chalk/index.css';
import App from './App.vue';

Vue.use(ElementUI);

new Vue({
  el: '#app',
  render: h => h(App)
});

以上程式碼便完成了 Element 的引入。需要注意的是,樣式檔案需要單獨引入。

按需引入

藉助 babel-plugin-component,我們可以只引入需要的元件,以達到減小專案體積的目的。

首先,安裝 babel-plugin-component:

npm install babel-plugin-component -D

然後,將 .babelrc 修改為:

{
  "presets": [["es2015", { "modules": false }]],
  "plugins": [
    [
      "component",
      {
        "libraryName": "element-ui",
        "styleLibraryName": "theme-chalk"
      }
    ]
  ]
}

接下來,如果你只希望引入部分元件,比如 Button 和 Select,那麼需要在 main.js 中寫入以下內容:

import Vue from 'vue';
import { Button, Select } from 'element-ui';
import App from './App.vue';

Vue.component(Button.name, Button);
Vue.component(Select.name, Select);
/* 或寫為
 * Vue.use(Button)
 * Vue.use(Select)
 */

new Vue({
  el: '#app',
  render: h => h(App)
});

完整元件列表和引入方式(完整元件列表以 components.json 為準)

import Vue from 'vue';
import {
  Pagination,
  Dialog,
  Autocomplete,
  Dropdown,
  DropdownMenu,
  DropdownItem,
  Menu,
  Submenu,
  MenuItem,
  MenuItemGroup,
  Input,
  InputNumber,
  Radio,
  RadioGroup,
  RadioButton,
  Checkbox,
  CheckboxButton,
  CheckboxGroup,
  Switch,
  Select,
  Option,
  OptionGroup,
  Button,
  ButtonGroup,
  Table,
  TableColumn,
  DatePicker,
  TimeSelect,
  TimePicker,
  Popover,
  Tooltip,
  Breadcrumb,
  BreadcrumbItem,
  Form,
  FormItem,
  Tabs,
  TabPane,
  Tag,
  Tree,
  Alert,
  Slider,
  Icon,
  Row,
  Col,
  Upload,
  Progress,
  Badge,
  Card,
  Rate,
  Steps,
  Step,
  Carousel,
  CarouselItem,
  Collapse,
  CollapseItem,
  Cascader,
  ColorPicker,
  Transfer,
  Container,
  Header,
  Aside,
  Main,
  Footer,
  Loading,
  MessageBox,
  Message,
  Notification
} from 'element-ui';

Vue.use(Pagination);
Vue.use(Dialog);
Vue.use(Autocomplete);
Vue.use(Dropdown);
Vue.use(DropdownMenu);
Vue.use(DropdownItem);
Vue.use(Menu);
Vue.use(Submenu);
Vue.use(MenuItem);
Vue.use(MenuItemGroup);
Vue.use(Input);
Vue.use(InputNumber);
Vue.use(Radio);
Vue.use(RadioGroup);
Vue.use(RadioButton);
Vue.use(Checkbox);
Vue.use(CheckboxButton);
Vue.use(CheckboxGroup);
Vue.use(Switch);
Vue.use(Select);
Vue.use(Option);
Vue.use(OptionGroup);
Vue.use(Button);
Vue.use(ButtonGroup);
Vue.use(Table);
Vue.use(TableColumn);
Vue.use(DatePicker);
Vue.use(TimeSelect);
Vue.use(TimePicker);
Vue.use(Popover);
Vue.use(Tooltip);
Vue.use(Breadcrumb);
Vue.use(BreadcrumbItem);
Vue.use(Form);
Vue.use(FormItem);
Vue.use(Tabs);
Vue.use(TabPane);
Vue.use(Tag);
Vue.use(Tree);
Vue.use(Alert);
Vue.use(Slider);
Vue.use(Icon);
Vue.use(Row);
Vue.use(Col);
Vue.use(Upload);
Vue.use(Progress);
Vue.use(Badge);
Vue.use(Card);
Vue.use(Rate);
Vue.use(Steps);
Vue.use(Step);
Vue.use(Carousel);
Vue.use(CarouselItem);
Vue.use(Collapse);
Vue.use(CollapseItem);
Vue.use(Cascader);
Vue.use(ColorPicker);
Vue.use(Container);
Vue.use(Header);
Vue.use(Aside);
Vue.use(Main);
Vue.use(Footer);

Vue.use(Loading.directive);

Vue.prototype.$loading = Loading.service;
Vue.prototype.$msgbox = MessageBox;
Vue.prototype.$alert = MessageBox.alert;
Vue.prototype.$confirm = MessageBox.confirm;
Vue.prototype.$prompt = MessageBox.prompt;
Vue.prototype.$notify = Notification;
Vue.prototype.$message = Message;

全域性配置

在引入 Element 時,可以傳入一個全域性配置物件。該物件目前支援 sizezIndex 欄位。size 用於改變元件的預設尺寸,zIndex 設定彈框的初始 z-index(預設值:2000)。按照引入 Element 的方式,具體操作如下:

完整引入 Element:

import Vue from 'vue';
import Element from 'element-ui';
Vue.use(Element, { size: 'small', zIndex: 3000 });

按需引入 Element:

import Vue from 'vue';
import { Button } from 'element-ui';

Vue.prototype.$ELEMENT = { size: 'small', zIndex: 3000 };
Vue.use(Button);

按照以上設定,專案中所有擁有 size 屬性的元件的預設尺寸均為 'small',彈框的初始 z-index 為 3000。

開始使用

至此,一個基於 Vue 和 Element 的開發環境已經搭建完畢,現在就可以編寫程式碼了。各個元件的使用方法請參閱它們各自的文件。

使用 Nuxt.js

我們還可以使用 Nuxt.js

國際化

Element 元件內部預設使用中文,若希望使用其他語言,則需要進行多語言設定。以英文為例,在 main.js 中:

// 完整引入 Element
import Vue from 'vue'
import ElementUI from 'element-ui'
import locale from 'element-ui/lib/locale/lang/en'

Vue.use(ElementUI, { locale })

// 按需引入 Element
import Vue from 'vue'
import { Button, Select } from 'element-ui'
import lang from 'element-ui/lib/locale/lang/en'
import locale from 'element-ui/lib/locale'

// 設定語言
locale.use(lang)

// 引入元件
Vue.component(Button.name, Button)
Vue.component(Select.name, Select)

如果使用其它語言,預設情況下中文語言包依舊是被引入的,可以使用 webpack 的 NormalModuleReplacementPlugin 替換預設語言包。

webpack.config.js

{
  plugins: [
    new webpack.NormalModuleReplacementPlugin(/element-ui[\/\\]lib[\/\\]locale[\/\\]lang[\/\\]zh-CN/, 'element-ui/lib/locale/lang/en')
  ]
}

相容 [email protected]

Element 相容 [email protected],搭配使用能更方便地實現多語言切換。

import Vue from 'vue'
import VueI18n from 'vue-i18n'
import Element from 'element-ui'
import enLocale from 'element-ui/lib/locale/lang/en'
import zhLocale from 'element-ui/lib/locale/lang/zh-CN'

Vue.use(VueI18n)
Vue.use(Element)

Vue.config.lang = 'zh-cn'
Vue.locale('zh-cn', zhLocale)
Vue.locale('en', enLocale)

相容其他 i18n 外掛

如果不使用 [email protected],而是用其他的 i18n 外掛,Element 將無法相容,但是可以自定義 Element 的 i18n 的處理方法。

import Vue from 'vue'
import Element from 'element-ui'
import enLocale from 'element-ui/lib/locale/lang/en'
import zhLocale from 'element-ui/lib/locale/lang/zh-CN'

Vue.use(Element, {
  i18n: function (path, options) {
    // ...
  }
})

相容 [email protected]

預設不支援 6.x 的 vue-i18n,你需要手動處理。

import Vue from 'vue'
import Element from 'element-ui'
import VueI18n from 'vue-i18n'
import enLocale from 'element-ui/lib/locale/lang/en'
import zhLocale from 'element-ui/lib/locale/lang/zh-CN'

Vue.use(VueI18n)

const messages = {
  en: {
    message: 'hello',
    ...enLocale // 或者用 Object.assign({ message: 'hello' }, enLocale)
  },
  zh: {
    message: '你好',
    ...zhLocale // 或者用 Object.assign({ message: '你好' }, zhLocale)
  }
}
// Create VueI18n instance with options
const i18n = new VueI18n({
  locale: 'en', // set locale
  messages, // set locale messages
})

Vue.use(Element, {
  i18n: (key, value) => i18n.t(key, value)
})

new Vue({ i18n }).$mount('#app')

按需載入裡定製 i18n

import Vue from 'vue'
import DatePicker from 'element/lib/date-picker'
import VueI18n from 'vue-i18n'

import enLocale from 'element-ui/lib/locale/lang/en'
import zhLocale from 'element-ui/lib/locale/lang/zh-CN'
import ElementLocale from 'element-ui/lib/locale'

Vue.use(VueI18n)
Vue.use(DatePicker)

const messages = {
  en: {
    message: 'hello',
    ...enLocale
  },
  zh: {
    message: '你好',
    ...zhLocale
  }
}
// Create VueI18n instance with options
const i18n = new VueI18n({
  locale: 'en', // set locale
  messages, // set locale messages
})

ElementLocale.i18n((key, value) => i18n.t(key, value))

通過 CDN 的方式載入語言檔案

<script src="//unpkg.com/vue"></script>
<script src="//unpkg.com/element-ui"></script>
<script src="//unpkg.com/element-ui/lib/umd/locale/en.js"></script>

<script>
  ELEMENT.locale(ELEMENT.lang.en)
</script>

搭配 vue-i18n 使用

<script src="//unpkg.com/vue"></script>
<script src="//unpkg.com/vue-i18n/dist/vue-i18n.js"></script>
<script src="//unpkg.com/element-ui"></script>
<script src="//unpkg.com/element-ui/lib/umd/locale/zh-CN.js"></script>
<script src="//unpkg.com/element-ui/lib/umd/locale/en.js"></script>

<script>
  Vue.locale('en', ELEMENT.lang.en)
  Vue.locale('zh-cn', ELEMENT.lang.zhCN)
</script>

目前 Element 內建了以下語言:

  • 簡體中文(zh-CN)
  • 英語(en)
  • 德語(de)
  • 葡萄牙語(pt)
  • 西班牙語(es)
  • 丹麥語(da)
  • 法語(fr)
  • 挪威語(nb-NO)
  • 繁體中文(zh-TW)
  • 義大利語(it)
  • 韓語(ko)
  • 日語(ja)
  • 荷蘭語(nl)
  • 越南語(vi)
  • 俄語(ru-RU)
  • 土耳其語(tr-TR)
  • 巴西葡萄牙語(pt-br)
  • 波斯語(fa)
  • 泰語(th)
  • 印尼語(id)
  • 保加利亞語(bg)
  • 波蘭語(pl)
  • 芬蘭語(fi)
  • 瑞典語(sv-SE)
  • 希臘語(el)
  • 斯洛伐克語(sk)
  • 加泰羅尼亞語(ca)
  • 捷克語(cs-CZ)
  • 烏克蘭語(ua)
  • 土庫曼語(tk)
  • 泰米爾語(ta)
  • 拉脫維亞語(lv)
  • 南非荷蘭語(af-ZA)
  • 愛沙尼亞語(ee)
  • 斯洛維尼亞語(sl)
  • 阿拉伯語(ar)
  • 希伯來語(he)
  • 立陶宛語(lt)
  • 蒙古語(mn)
  • 哈薩克語(kz)
  • 匈牙利語(hu)
  • 羅馬尼亞語(ro)
  • 庫爾德語(ku)
  • 維吾爾語(ug-CN)
  • 高棉語(km)

如果你需要使用其他的語言,歡迎貢獻 PR:只需加一個語言配置檔案即可。

自定義主題

Element 預設提供一套主題,CSS 命名採用 BEM 的風格,方便使用者覆蓋樣式。我們提供了三種方法,可以進行不同程度的樣式自定義。

僅替換主題色

如果僅希望更換 Element 的主題色,推薦使用線上主題生成工具。Element 預設的主題色是鮮豔、友好的藍色。通過替換主題色,能夠讓 Element 的視覺更加符合具體專案的定位。

使用上述工具,可以很方便地實時預覽主題色改變之後的視覺,同時它還可以基於新的主題色生成完整的樣式檔案包,供直接下載使用(關於如何使用下載的主題包,請參考本節「引入自定義主題」和「搭配外掛按需引入元件主題」部分)。

在專案中改變 SCSS 變數

Element 的 theme-chalk 使用 SCSS 編寫,如果你的專案也使用了 SCSS,那麼可以直接在專案中改變 Element 的樣式變數。新建一個樣式檔案,例如 element-variables.scss,寫入以下內容:

/* 改變主題色變數 */
$--color-primary: teal;

/* 改變 icon 字型路徑變數,必需 */
$--font-path: '~element-ui/lib/theme-chalk/fonts';

@import "~element-ui/packages/theme-chalk/src/index";

之後,在專案的入口檔案中,直接引入以上樣式檔案即可(無需引入 Element 編譯好的 CSS 檔案):

import Vue from 'vue'
import Element from 'element-ui'
import './element-variables.scss'

Vue.use(Element)

需要注意的是,覆蓋字型路徑變數是必需的,將其賦值為 Element 中 icon 圖示所在的相對路徑即可。

命令列主題工具

如果你的專案沒有使用 SCSS,那麼可以使用命令列主題工具進行深層次的主題定製:

安裝工具

首先安裝「主題生成工具」,可以全域性安裝或者安裝在當前專案下,推薦安裝在專案裡,方便別人 clone 專案時能直接安裝依賴並啟動,這裡以全域性安裝做演示。

npm i element-theme -g

安裝白堊主題,可以從 npm 安裝或者從 GitHub 拉取最新程式碼。

# 從 npm
npm i element-theme-chalk -D

# 從 GitHub
npm i https://github.com/ElementUI/theme-chalk -D

初始化變數檔案

主題生成工具安裝成功後,如果全域性安裝可以在命令列裡通過 et 呼叫工具,如果安裝在當前目錄下,需要通過 node_modules/.bin/et 訪問到命令。執行 -i 初始化變數檔案。預設輸出到 element-variables.scss,當然你可以傳引數指定檔案輸出目錄。

et -i [可以自定義變數檔案]

> ✔ Generator variables file

如果使用預設配置,執行後當前目錄會有一個 element-variables.scss 檔案。內部包含了主題所用到的所有變數,它們使用 SCSS 的格式定義。大致結構如下:

$--color-primary: #409EFF !default;
$--color-primary-light-1: mix($--color-white, $--color-primary, 10%) !default; /* 53a8ff */
$--color-primary-light-2: mix($--color-white, $--color-primary, 20%) !default; /* 66b1ff */
$--color-primary-light-3: mix($--color-white, $--color-primary, 30%) !default; /* 79bbff */
$--color-primary-light-4: mix($--color-white, $--color-primary, 40%) !default; /* 8cc5ff */
$--color-primary-light-5: mix($--color-white, $--color-primary, 50%) !default; /* a0cfff */
$--color-primary-light-6: mix($--color-white, $--color-primary, 60%) !default; /* b3d8ff */
$--color-primary-light-7: mix($--color-white, $--color-primary, 70%) !default; /* c6e2ff */
$--color-primary-light-8: mix($--color-white, $--color-primary, 80%) !default; /* d9ecff */
$--color-primary-light-9: mix($--color-white, $--color-primary, 90%) !default; /* ecf5ff */

$--color-success: #67c23a !default;
$--color-warning: #e6a23c !default;
$--color-danger: #f56c6c !default;
$--color-info: #909399 !default;

...

修改變數

直接編輯 element-variables.scss 檔案,例如修改主題色為紅色。

$--color-primary: red;

編譯主題

儲存檔案後,到命令列裡執行 et 編譯主題,如果你想啟用 watch 模式,實時編譯主題,增加 -w 引數;如果你在初始化時指定了自定義變數檔案,則需要增加 -c 引數,並帶上你的變數檔名

et

> ✔ build theme font
> ✔ build element theme

引入自定義主題

預設情況下編譯的主題目錄是放在 ./theme 下,你可以通過 -o 引數指定打包目錄。像引入預設主題一樣,在程式碼裡直接引用 theme/index.css 檔案即可。

import '../theme/index.css'
import ElementUI from 'element-ui'
import Vue from 'vue'

Vue.use(ElementUI)

搭配外掛按需引入元件主題

如果是搭配 babel-plugin-component 一起使用,只需要修改 .babelrc 的配置,指定 styleLibraryName 路徑為自定義主題相對於 .babelrc 的路徑,注意要加 ~

{
  "plugins": [["component", [
    {
      "libraryName": "element-ui",
      "styleLibraryName": "~theme"
    }
  ]]]
}

如果不清楚 babel-plugin-component 是什麼,請閱讀 快速上手 一節。更多 element-theme 用法請參考專案倉庫。

內建過渡動畫

Element 內應用在部分元件的過渡動畫,你也可以直接使用。在使用之前請閱讀 transition 元件文件

fade 淡入淡出

 

 

提供 el-fade-in-linearel-fade-in 兩種效果。

<template>
  <div>
    <el-button @click="show = !show">Click Me</el-button>

    <div style="display: flex; margin-top: 20px; height: 100px;">
      <transition name="el-fade-in-linear">
        <div v-show="show" class="transition-box">.el-fade-in-linear</div>
      </transition>
      <transition name="el-fade-in">
        <div v-show="show" class="transition-box">.el-fade-in</div>
      </transition>
    </div>
  </div>
</template>

<script>
    export default {
    data: () => ({
      show: true
    })
  }
</script>

<style>
  .transition-box {
    margin-bottom: 10px;
    width: 200px;
    height: 100px;
    border-radius: 4px;
    background-color: #409EFF;
    text-align: center;
    color: #fff;
    padding: 40px 20px;
    box-sizing: border-box;
    margin-right: 20px;
  }
</style>

zoom 縮放

 

 

提供 el-zoom-in-centerel-zoom-in-topel-zoom-in-bottom 三種效果。

<template>
  <div>
    <el-button @click="show2 = !show2">Click Me</el-button>

    <div style="display: flex; margin-top: 20px; height: 100px;">
      <transition name="el-zoom-in-center">
        <div v-show="show2" class="transition-box">.el-zoom-in-center</div>
      </transition>

      <transition name="el-zoom-in-top">
        <div v-show="show2" class="transition-box">.el-zoom-in-top</div>
      </transition>

      <transition name="el-zoom-in-bottom">
        <div v-show="show2" class="transition-box">.el-zoom-in-bottom</div>
      </transition>
    </div>
  </div>
</template>

<script>
    export default {
    data: () => ({
      show2: true
    })
  }
</script>

<style>
  .transition-box {
    margin-bottom: 10px;
    width: 200px;
    height: 100px;
    border-radius: 4px;
    background-color: #409EFF;
    text-align: center;
    color: #fff;
    padding: 40px 20px;
    box-sizing: border-box;
    margin-right: 20px;
  }
</style>

collapse 展開摺疊

使用 el-collapse-transition 元件實現摺疊展開效果。

 

 

<template>
  <div>
    <el-button @click="show3 = !show3">Click Me</el-button>

    <div style="margin-top: 20px; height: 200px;">
      <el-collapse-transition>
        <div v-show="show3">
          <div class="transition-box">el-collapse-transition</div>
          <div class="transition-box">el-collapse-transition</div>
        </div>
      </el-collapse-transition>
    </div>
  </div>
</template>

<script>
    export default {
    data: () => ({
      show3: true
    })
  }
</script>

<style>
  .transition-box {
    margin-bottom: 10px;
    width: 200px;
    height: 100px;
    border-radius: 4px;
    background-color: #409EFF;
    text-align: center;
    color: #fff;
    padding: 40px 20px;
    box-sizing: border-box;
    margin-right: 20px;
  }
</style>

按需引入

// fade/zoom 等 
import 'element-ui/lib/theme-chalk/base.css'; 
// collapse 展開摺疊 
import CollapseTransition from 'element-ui/lib/transitions/collapse-transition'; 
import Vue from 'vue' 

Vue.component(CollapseTransition.name, CollapseTransition)