ElementUI騰訊雲開發者開發指南
原文地址:https://cloud.tencent.com/developer/chapter/18051
目錄
安裝
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 時,可以傳入一個全域性配置物件。該物件目前支援 size
與 zIndex
欄位。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-linear
和 el-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-center
,el-zoom-in-top
和 el-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)