# 類星體 Quasar(V1)
### 參考連結
* 官方網站
*https://quasar.dev/*
* 討論區
*https://forum.quasar-framework.org/*
* [Vue] 使用 Quasar 輕鬆打造 Material 及 iOS 風格的響應式網站 系列
*https://ithelp.ithome.com.tw/users/20111805/ironman/1731?page=1*
* Lodash(JS套件包，上面網站中範例會使用到)
*https://lodash.com/*
* 類星體I18N檔案集中
*https://github.com/quasarframework/quasar/tree/dev/ui/lang*
* VUE路由
*https://quasar.dev/quasar-cli/cli-documentation/routing*
* 類星體路由文件
*https://quasar.dev/layout/routing-with-layouts-and-pages*
* 類星體樣板
*https://quasar.dev/layout-builder*
* 類星體中文文檔(應該是非官方)
*http://www.quasarchs.com/*
* 類星體外部拓展元件(表單拖拉/進階表單功能)
*https://quasar-qgrid.netlify.com/examples*
---
### 入門
https://quasar.dev/start/pick-quasar-flavour
選擇一個安裝方式，本篇所選擇的安裝方式採用Quasar CLI
可以查看並比較需要使用的情境在選擇用何種方式進行安裝。
---
### 類星體 Quasar-安裝
首先要先檢查node版本是否符合
```bash=
$ node --version
```
~~Vue-cli (可略，視情況安裝)~~
~~$ npm install -g vue-cli~~
Quasar-cli
~~$ npm install -g quasar-cli~~
```bash=
$npm install -g @quasar/cli
```
檢查版本
```bash=
$ quasar -v
```
佈署環境
~~$ quasar init <folder name>~~
```bash=
$quasar create <folder name>
```
專案建立引導(很長)
```bash=
Project name (internal usage for dev)
//給你確認專案名字 `注意 這邊只能小寫`
Project product name
(must start with letter if building mobile apps) (Quasar App)
//填上專案的產品名稱 (這邊會寫進 package.json)
Project description
//填上專案的敘述 (這邊會寫進 package.json)
Author
//作者 有git會自動放git的使用者帳號
Pick your favorite CSS preprocessor: (can be changed later) (Use arrow keys)
//選擇樣式語言（以後可以更改）
Sass with indented syntax (recommended)//帶有縮排語法的Sass(推薦)
> Sass with SCSS syntax (recommended)//SCSS與Sass(推薦)
Stylus
None (the others will still be available)
Pick a Quasar components & directives import strategy
(can be changed later) (Use arrow keys)
//選擇導入策略（以後可以更改）
* Auto-import in-use Quasar components & directives
- slightly higher compile time; next to minimum bundle size;
most convenient
//自動-自動導入使用中的Quasar組件和指令，編譯略慢但方便使用
> * Manually specify what to import
- fastest compile time; minimum bundle size; most tedious
//手動-手動導入使用中的Quasar組件和指令，編譯時間最快，但繁瑣
* Import everything from Quasar
- not treeshaking Quasar; biggest bundle size; convenient
//所有內容-從Quasar導入所有內容，檔案最大
Check the features needed for your project:
(Press <space> to select, <a> to toggle all, <i> to invert selection)
//選擇要一起安裝的插件，空白鍵選擇，A鍵全選，I鍵反轉選項
( ) ESLint //用來維護程式碼品質的 好(煩人?!)東西
(*) Vuex //前端倉儲
(*) Axios //主要拿來接API
(*) Vue-i18n //多國語系
(*) IE11 support //IE11 支援
Cordova id (disregard if not building mobile apps)
//如果有要轉Cordova可以填 沒有的話直接跳過也可以
Should we run `npm install` for you after the project has been created?
(recommended) (Use arrow keys)
//自動執行 npm install(推薦)
Yes, use Yarn (recommended)//Yarn(推薦)
> Yes, use NPM //NPM
No, I will handle that myself
```
**修改package.json(重點)**
```json=
// package.json
"scripts": {
"dev": "quasar dev",
"build": "quasar build",
"build:pwa": "quasar build -m pwa"
}
```
#### 版本升級語法
```
quasar upgrade --install
```
單純升級套件可以使用
```
npm install --save quasar@^1.8.5
```
---
### I18N設定
(以繁體中文為例)
(!!!!新版設定-改一行就好了!!!)
(!!!舊版設定!!!)
先去以下網址，或是需要使用的語言的頁面
https://github.com/quasarframework/quasar/blob/dev/ui/lang/zh-hant.js
繁體中文: zh-hant.js
```json=
//quasar.conf.
boot: ['i18n','axios',...]
...
framework: {lang: 'zh-hant',...}
```
建立語言資料夾(請把I18N文檔放進資料夾內的index.js中)
修改i18n>index.js
修改boot>i18n.js
I18N成功後畫面
---
### Qicon
```json=
//quasar.conf.js
extras: [
'material-icons'
]
//類星體支援的Icon
extras: [
'material-icons',
'material-icons-outlined',
'material-icons-round',
'material-icons-sharp',
'mdi-v3',
'ionicons-v4',
'eva-icons',
'fontawesome-v5',
'themify'
]
```
引用方法-[官方文件Qicon](https://quasar.dev/options/quasar-icon-sets)
#### 常見問題：q-icon 無法正常顯示
請把字型排除類星體q-icon的Class
更動字型會導致q-icon無法正常顯示
詳細解決方案[請查看此](https://hackmd.io/hyEM2XFwT_2d6gg1lKHmKA?both#Q-icon-%E7%84%A1%E6%B3%95%E6%AD%A3%E5%B8%B8%E9%A1%AF%E7%A4%BA)
---
### 配置quasar.conf.js
很多重要的檔案設定都會放在這個檔案中，包含組件的引用。
詳細可以[查看此](https://ithelp.ithome.com.tw/articles/10202367)，或[官方設定文件說明](https://quasar.dev/quasar-cli/quasar-conf-js)
---
### 結構目錄
照搬，正確版本還是須看官方文件
https://ithelp.ithome.com.tw/articles/10201701
官方文件說明
https://quasar.dev/quasar-cli/cli-documentation/directory-structure
```
.
├── src/
│ ├── assets/
│ ├── statics/ # 給你放圖片的
│ ├── components/ # 給你放component的
│ ├── css/
| ├── app.styl |
| --------------------------------------------------------------------------
| ------------ |
| │ └── themes
| │ ├── variables.mat.styl # Material 主題的變數
| │ └── variables.ios.styl # iOS 主題的變數 |
| │ ├── common.variables.styl # 在這邊寫的CSS能蓋掉Quasar自己元件預設的CSS |
│ ├── layouts/ # 內建的layout頁面會放這裡
│ ├── pages/ # 內建的頁面也都在這
│ ├── plugins/ # 之後自己新增的插件會放這邊
│ ├── router/ # 放Vue Router的東西 這邊就不多介紹
| | ├── index.js
| │ └── routes.js
│ ├── store/ # 放Vuex Store的東西 這邊也不多介紹
| | ├── index.js
| │ ├── <folder>
| │ └── <folder>
│ ├── App.vue # 最起始的 Vue component
│ └── index.template.html # index.html 的模板
├── src-ssr/ # 有使用 SSR 功能才會有這個
├── src-pwa/ # 有使用 PWA 功能才會有這個
├── src-cordova/ # 有使用 Cordova 功能才會有這個
├── src-electron/ # 有使用 Electron 功能才會有這個
├── dist/ # 當你 build 你的專案時會放這裡
│ ├── spa-mat/ # 資料夾名稱會依照你的<功能>跟<主題>來定義
│ ├── spa-ios/
│ ├── electron-mat/
│ └── ....
└── quasar.conf.js # Quasar 的 Config 資料夾(非常重要 大部份東西都會在這邊改)
```
---
### 路由
* “ /src/router/index.js”保存Vue路由器的初始化代碼
* “ /src/router/routes.js”保存您的網站/應用程序的路由
請詳讀
[VUE官方文件](https://router.vuejs.org/)
及
[類星體官方文件](https://quasar.dev/layout/routing-with-layouts-and-pages)
---
### Vuex使用
[請查看此](https://quasar.dev/quasar-cli/cli-documentation/vuex-store#Adding-a-Vuex-Module )
---
#### Sass&SCSS 注意事項
> Quasar CLI會檢測該文件是否至少包含一個'$'字符，如果是，它將自動導入Quasar Sass / SCSS變量。
但是，如果您有一個使用到的import語句，並且要從中導入的文件不包含任何'$'字符，則此操作將無效。在這種情況下，您需要添加一個簡單的註釋（// $），以便Quasar可以檢測至少一個'$'字符：
```sass=
<style lang="sass">
// $
@import 'some-file.sass'
// now some-file.sass can benefit
// from Quasar Sass variables too
// due to comment above
</style>
```
quasar.conf.js> CSS中包含的.sass / .scss文件也需要相同的內容。
---
## 類星體 輸入框
#### 輸入框樣式補充
官方文件沒有將去除所有邊框的選項寫進Q-input文件中，但在驗證表單的文件中有寫到，可以透過**borderless**屬性將邊框去除
---
## 類星體 驗證方法
>1. 如果需要驗證失敗聚焦在QField組件上，需製作Method去處發focus ()
* [驗證說明](https://quasar.dev/vue-components/input)
於官方文件-表單元素>輸入框>最尾端
* [表單驗證](https://quasar.dev/vue-components/form)
於官方文件-表單
* [區域](http://www.quasarchs.com/vue-components/field)
除了輸入框及下拉選單以外提供其他表單組件的驗證方式
> 請注意輸入框及下拉選單都預設了區域的作用方式，請勿重複套用
### 類星體提供的驗證模式
1. [內部驗證](https://quasar.dev/vue-components/input#Internal-validation)
Qinput組件中，有提供:rules 的prop屬性提供驗證，可以使定規則或是以第三方驗證進行驗證，設定的自定義驗證將會是一個函數，結果為True時驗證成功傳值，否則將回傳錯誤訊息(字串方式)
```
ref="驗證用變數(VUE控制DOM的使用項，必須為唯一值)"
value="驗證用變數"
rules=> 驗證條件 || 錯誤訊息
```
例如：
```
value => value.includes('Hello') || '該字串必須包含Hello'
```
Qinput上需編寫成
```
:rules="[val => !!val || '此項為必填項']"
:rules="[ val => val.length <= 3 || '不得超過3個字元']"
```
(0413補充 類星體也有提供error插槽，只要觸發:error事件，就會啟用)
也可以透過 resetValidation() 重置表單及驗證。
此外，官方也提供了部分驗證規則的範本檔案，可以[去此查看](https://github.com/quasarframework/quasar/blob/dev/ui/src/utils/patterns.js)
2. [被動驗證](https://quasar.dev/vue-components/input#Example--Lazy-rules)
設置 lazy-rules 屬性即可啟用被動驗證
被動驗證的用意是，在第一次使用者輸入完畢(或失去焦點)後才進行驗證，而不是在輸入進行時就提供驗證。
主要是為了ux上能給使用者更好的體驗，如果使用者再輸入的過程一直被錯誤訊息干擾，可能會影響使用上的觀感。
3. [表單驗證](https://quasar.dev/vue-components/input#Example--Form-validation)
標題連結為不使用Q-form範例。
以ref屬性進行驗證
Q-form的部分請[參考此處提供的官方頁面](https://quasar.dev/vue-components/form)
4. [異步驗證](https://quasar.dev/vue-components/input#Async-rules)
簡單講述異部驗證，舉例如使用者註冊帳戶時，會去驗證資料庫是否有重複帳號，如果有，將回傳訊息並顯示該使用者名稱已被註冊。
> 官方提示：
請考慮將異步驗證與[事件延遲](https://homura0731.github.io/post/2018/09/lodash-debounce/)一同使用，以避免每次點擊按鈕時就立刻使用異步驗證，這樣可能會對效能造成不好的影響。
> * 其他文件參考
https://mropengate.blogspot.com/2017/12/dom-debounce-throttle.html
5. [外部驗證(第三方驗證)](https://quasar.dev/vue-components/input#External-validation)
透過第三方驗證套件，連結到Qinput組件，如官方推薦的[Vuelidate](https://vuelidate.js.org/)
可使用屬性：error/error-message/bottom-slots(顯示錯誤訊息處)
### 表單驗證方式
>注意事項：
>1. QForm掛勾到QInput、QSelect或QField的組件中
>2. QForm中的組件必須使用內部驗證(而非外部驗證)
>3. 如要使用表單重置(reset)功能，請確保同時捕捉到QForm事件的@reset，並使用它處理重置組件模型
>4. 使用正則表達式時後面需加.test(val)
>注意如果該驗證項有驗證長度，那不得給予NULL值，會發生錯誤
### 對話框驗證方式
v1.8版提供
---
## 類星體 選擇框
>如果選擇框要以物件型式傳入，必須要有label跟vaule屬性！
>改變選項時應使用@input，而非@chang
---
## 類星體 表格使用
> 如果需要更多表格說明，可以去官方文件查看詳細
### [格式說明](https://quasar.dev/vue-components/table#Defining-the-columns)
```
columns：表頭
{
name："識別項，唯一值(ID)"
required："可見"
label："顯示文字"
align："對其方式"
field：使對象屬性確認該列的值
format：自定義函數格式化
sortable：排序
//td
style：樣式
classes：類名稱
//header
headerStyle：樣式
headerClasses：類名稱
}
```
一般我們建議會將表頭的JSON部分統一存放在一個JS檔集中管理，以利程式碼維護
### 單項表頭值插入
以插入表單方式進行表格內自定義需添加 slot:body-cell-{table's name} 屬性
這邊的table's name 是指 columns中的name
### 加載狀態
v1.8.版提供
```html
<q-table :loading="loading" .... >
<template v-slot:loading>
<q-inner-loading showing color="primary" />
</template>
</q-table>
```
---
## 類星體列表使用
###
#### q-item-label
##### ：lines =“ 2” 可控制渲染行數
---
## 類星體 預載器
v1.6.版提供
QSkeleton是一個組件，用於在加載實際頁面數據之前顯示內容的佔位符預覽。這是一種在頁面完全加載並提高感知性能之前通知用戶頁面期望的好方法。它可用於在獲取數據時在屏幕上逐步顯示信息。
---
## 類星體 外部擴展
https://quasar.dev/app-extensions/discover
有針對類星體所開發的外部套件，如 @quasar/qcalendar (類星曆)
要使用外部套件請參考以下步驟
> 1.輸入外部擴展指令 quasar ext add <ext-id>
> 2.確認安裝成功後 到quasar.conf.js 於該區塊中添加你的套件
```
extendWebpack(cfg) {
// do something with Electron main process Webpack cfg
// chainWebpack also available besides this extendWebpack
qcalendar
//如類星曆就要寫qcalendar，取決於取名名稱
}
```
>官方的外部套件命名與其他使用者開發套件命名會不同
>官方命名會帶有@quasar 字樣
>而其他開發者就會依下面方式取名，
>如果quasar ext add 指令失敗，也可以透過NPM全名來添加該外部擴展套件
>
---
## 類星體插件使用-LocalStorage
>注意如果使用類星體的LocalStorage SET 那GET也要使用類星體，否則會有前綴字樣
---
## 類星體 注意事項
(05/07更新)
### 版本更新頻繁
做為一個正在成長的框架，類星體版本更新的速度相當的快，所以請時常注意官方文件版本及自己開發的版本型號
### Q-icon 無法正常顯示
請把字型排除類星體q-icon的Class
更動字型會導致q-icon無法正常顯示
### Enter自動送出表單
請將表單多設置一個v-on:keydown.enter.prevent事件
以防再輸入框按Enter鍵時執行送出表單事件
### 檔案位置不能隨意擺放
必須遵照官方文件嚴格的規範
* 照片就放置在statics資料夾(如果需靜態引入需給相對屬性?)
* 頁面就放在page
* 框架就放在Layout
* 本地化控制檔 boot>i18n
隨意擺放會造成類星體編譯時產生問題
### [Sass&SCSS 注意事項](https://hackmd.io/hyEM2XFwT_2d6gg1lKHmKA?both#SassampSCSS-%E6%B3%A8%E6%84%8F%E4%BA%8B%E9%A0%85)
該項已有區塊做說明，在此不贅述。
### Flex需額外開啟
如果需要斷點
quasar.conf > framework > cssAddon: true
設定開啟
https://quasar.dev/layout/grid/introduction-to-flexbox#Flex-Addons
### q-page預設大小
https://quasar.dev/layout/page#Style-fn
### 手機查看功能
quasar dev --play
會產生一個QR CODE 可以用手機查看
Sign in with Wallet
Connect another wallet