---
tags: 網頁開發, ECentury
---

# 故宮主題網公版 v1.1.0 使用說明文件

這邊說明一下故宮主題網的公版使用方式

## 一、建立使用環境

### 1-1 安裝 node.js

先確認自己的電腦是否有安裝 node.js

1. 在電腦左下角「**開啟**」點擊右鍵選擇「**執行**」
2. 輸入 `cmd` 後會出現一個黑視窗，這個東西叫做**終端機（Terminal）**

在終端機輸入：

node -v

:::info
:::

輸入後會出現 node.js 的版本編號。

如果沒有顯示版本編號的話，就代表你的電腦沒有安裝 node.js，沒有安裝的話就去[官網](https://nodejs.org/en/)下載安裝，建議下載 LTS 版本（穩定版本，左邊的那一個）。

:::warning
如果你的 node.js 版本小於 10.0 以下的話，也請重新安裝最新版本的 node.js。
:::

### 1-2 安裝 SASS/SCSS

如果已經有安裝過 SASS 這段可以直接省略

安裝 SASS 的方式可以參考 [這篇文章](http://blog.shihshih.com/installing-the-sass-and-compass/) 或是去看公司買的 [六角學院 SASS課程](http://www.hexschool.com/courses/sass.html) ，這邊就不再多做說明。

Windows 環境上基本上就是以下流程：

1. 安裝 Ruby（sass 是用 Ruby 寫的，所以要裝 Ruby）
2. 使用 Command Prompt with Ruby
3. 安裝 sass、系統更新
4. 使用

:::warning
一些比較舊的教學會叫你安裝 compass，但是 compass 已經被棄用了，所以可以不用安裝。
:::

### 1-3 在全域安裝 Gulp

電腦如果沒有安裝過 Gulp 的話需要在終端機安裝 Gulp，這個基本上只要安裝一次就可以了。

打開終端機輸入：

npm install gulp -g

### 1-4 下載 Visual Studio Code

下載 [VScode](https://code.visualstudio.com/) 編輯器

VScode 跟別的編輯器最大的優勢在於他整合了許多網頁開發所需的工具（終端機、GIT...等等），安裝擴充外掛也非常的容易，而且也有提供中文版本的介面。

打開 VScode 後，點選左邊的方塊圖示可以切換到擴充工具清單，上面的搜尋欄位可以搜尋你想裝的外掛，並點選安裝。

:::info
:::

這邊需要安裝以下幾個需要用到的外掛：

#### 1. [中文版本介面](https://marketplace.visualstudio.com/items?itemName=MS-CEINTL.vscode-language-pack-zh-hant)

如果你想看英文介面的話就不用裝。


#### 2. [Live Sass Compiler](https://marketplace.visualstudio.com/items?itemName=ritwickdey.live-sass)

這個外掛可以幫你把 SASS/SCSS 即時編譯成 CSS 檔。


#### 3. [Live Server](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer)

這個外掛可以幫你在本機端建立一個模擬 Server 的環境，讓你可以在模擬網路的環境下檢視你的 HTML 檔案。


#### 4. [Gulp Task](https://marketplace.visualstudio.com/items?itemName=nickdodd79.gulptasks)

這個外掛可以幫你管理/執行自動化工具 Gulp 的任務。


## 二、主題網公版

故宮主題網的公版放在公司 Git Server 的這個位置，遇到任何問題的修正或是有擴充功能，我都會更新至這個 Git 資料庫。

http://git.dc1.ec-media.com.tw:3000/NPM/M-Theme

### 2-1 下載主題網公版

點選右上角的下載圖示可以下載檔案，請下載 **ZIP** 檔。

:::info
:::

解壓縮打開資料夾後可以看到這些檔案：

:::info
:::

:::warning
下載下來的資料夾名稱叫做「M-Theme」，這是 GIT 資料庫的名字。
這邊你可以改成專案資料夾的名稱或是你自己要的名稱。
:::

### 2-2 打開編輯器，建立專案開發環境

打開 VScode，點選左上角，上方工具欄的「檔案」，選擇「開啟資料夾」。

開啟至剛剛下載下來的公版資料夾的位置：

:::info
:::

開啟後可以看到我們剛剛下載的檔案。

:::info
:::

接著選擇上方工具欄的「終端機」，新增一個終端機。

:::info
:::

接著下方會出現 VScode 的終端機視窗，終端機的預設路徑會是你專案資料夾的位置。

:::warning
如果看不到路徑，對著終端機視窗按幾下 Enter 應該就會有了。
:::

:::info
:::

然後在終端機輸入 **`npm install`**，專案資料夾就會開始安裝我預先設定的開發環境。

:::info
:::

這邊的安裝會安裝以下幾個開發用的套件：

- gulp（自動化工具 Gulp）
- gulp-html-extend（做 HTML 區塊模組的 Gulp 套件）
- gulp-babel（Babel，可以把 ES6 的 JavaScript 轉換成 ES5 版本工具）
- gulp-uglify（把 JS 檔案壓縮且醜化）
- gulp-concat（合併 JS 檔案）
- gulp-rename（把檔案重新命名）
- gulp-replace（把檔案內容做替換修改）
- gulp-htmlmin（把 HTML 檔案壓縮）
- del（刪除舊的編譯檔案）

安裝完成之後，專案資料夾會出現一包名為 **node_modules** 的資料夾。

:::info
:::

:::danger
node_modules 是 node.js 的工具包，基本上非常大一包，所以千萬不要把 node_modules 加入 GIT，不然資料庫容量會爆炸。
:::

:::danger
:exclamation: **上傳、複製你的專案時也千萬不要 copy 這包資料夾，千萬不要！！**
**（做任何調整、修改、移動檔案都不要去動 node_modules 就是了）**
:::

基本上到這裡專案開發環境就差不多了。

### 2-3 如何使用 Gulp

要執行 Gulp 的話只要從 VScode 左下角的 Gulp Tasks 視窗

- 選擇 default
- 按下右上的綠色開始按鈕

:::info
:::

這個動作會幫我們完成幾件事情：

- 刪除/建立 dist 資料夾
- HTML 區塊模組的載入拼湊，並把 HTML 檔案壓縮輸出至 dist 資料夾
- JS 檔案做 Babel 的編譯、壓縮、醜化，並輸出至 dist/common/js 資料夾
- 把 css、images 資料夾複製移動至 dist/common 資料夾

## 三、主題網公版使用規則說明

不論是 HTML、CSS、JavaScript，現在都是建議把「開發用的檔案」和「輸出後的檔案」做分離，對於檔案的模組化來說這是必要的架構。編輯完開發用的檔案之後，利用一些自動化工具或是後處理器，把檔案做輸出。

:::danger
:exclamation: 所有的檔案都應該在「開發用的檔案」上做編輯，千萬不要去編輯「輸出後的檔案」，因為這是沒有任何意義的！
:::

### 3-1 HTML 檔案說明

HTML 檔案依照不同語言分別放在不同的資料夾，如 ch（中文）、en（英文）、jp（日文）。

每個資料夾底下會有 **`assets`** 和 **`layout`** 這二個資料夾，assets 資料夾是放置開發用的 HTML 檔案，layout 資料夾是放置共用區塊模組。

由於每個網站都要有一個進入點，所以中文版的「page-1.html」會被輸出至上層並且改名為 index.html。

:::warning
這邊 Gulp 會幫我們做的事情是幫我們把 HTML 做區塊模組的載入拼湊。
:::

#### 3-1-1 HTML 的區塊模組設定

打開 `assets` 資料夾裡的 HTML 檔，可以發現一些 `<!-- @@include -->` 開頭的標籤，這是用來做區塊引入用的，後面填入的則是欲載入的 HTML 檔的路徑位置。

:::info
:::

**範例說明：**

假如你想把 Header 區塊獨立出來，就可以利用這種方式把 `header.html` 引入至 `#header ` 裡面。這些區塊的檔案都是統一放在 layout 資料夾，檔名一律是`_`開頭，這樣比較好辨認。

<header id="header">
    <!-- @@include ../header.html -->
</header>

### 3-2 JavaScript 檔案說明

在 `common/js` 資料夾裡面放的是「開發用的 JS 檔案」，這些檔案經過 Gulp 編譯後會輸出至 `dist/common/js` 資料夾裡面，並合併成一隻「main.js」。

:::warning
這邊 Gulp 會幫我們做的事情是幫我們把 JS 轉換成 ES5 版本以及做壓縮、合併、醜化。

由於這邊有使用到 Babel，所以開發用 JS 檔可以使用一些 ES6 提供的語法。因為現在大家都寫 ES6 了，所以在網路上參考其他開發者的寫法時，也可以不用擔心 IE 相容的問題。
:::

### 3-3 CSS 檔案說明

CSS 的部分是使用 SCSS 來撰寫，編譯的部分並不是使用 Gulp 而是使用 VScode 的 Live Sass Compiler 外掛，寫好後的 SCSS 檔則會輸出至 CSS 資料夾。

#### 3-3-1 如何使用 Live Sass Compiler

點擊 VScode 右下角的 `watch sass` 即可開始編譯 SASS/SCSS 檔。

:::info
:::

Live Sass Compiler 的設定是寫在 `.vscode` 資料夾裡的 `settings.json`。

SCSS 檔編譯後會輸出至 common/css 以及 dist/common/css 資料夾內，輸出的格式是壓縮（compressed）。

:::info
:::

### 3-4 Gulpfile.js

Gulpfile.js 是 gulp 指令的設定檔。

如果你要修改檔案輸出的位置或是設定其他 Gulp 外掛的功能需要在這個檔案做修改。

### 3-5 Package.json

`package.json` 和 `package-lock.json` 是 npm 用來紀錄專案安裝了那些套件的檔案。

我們安裝的這些 Gulp 外掛都是用 node.js 寫的套件，而 npm 則是 node.js 的套件管理工具，package.json 就是 npm 的所產生的紀錄檔。

如果專案要沿用，這個檔案非常重要，當我們在終端機輸入 npm install 時，電腦就是去下載安裝 package.json 裡面寫的套件。

:::warning
只要你的專案資料夾裡面有 package.json 和 package-lock.json 這兩個檔案，你只要在終端機輸入 npm install，這些套件和開發環境就能一次全部安裝完成，不需要一個一個重新安裝。
:::

### 3-6 READMEmd

`README.md` 是 Git 上的說明文件，在專案中完全不會用到，可以把它刪掉沒關係。

除非你想在 Git Server 上寫說明文件。

## 四、如何瀏覽我的網站

如果要使用 Live Server 瀏覽網站需依照以下步驟：

1. 選擇 dist 資料夾裡面的 HTML 檔
2. 在 HTML 介面按右鍵
3. 點選 open with live server 即可

:::info
:::

他就能以模擬網路環境的方式瀏覽你的 HTML 檔案。

:::warning
以本機端點兩下開啟 HTML 檔和模擬網路環境開啟 HTML 檔，這兩種方式所呈現的畫面其實是**完全不一樣的！！**

在做網頁開發時建議以模擬網路環境所呈現的畫面為主，這樣才能確保的你網站畫面跟未來上線後不會有誤差。
:::

## 五、專案完成後

專案完成後只需要把 dist 資料夾裡面的檔案給故宮，或是丟上測試網位置即可。

:::info
:::

### 5-1 如果我想沿用現在這個專案

如果想要沿用現在這個專案，你就在新增一個資料夾，把 node_modules 以外的全部檔案複製過去。然後按照一開始的步驟，打開 VScode 開啟終端機，輸入 npm install 即可。

:::warning
這邊最重要的就是 package.json 和 package-lock.json 這兩個檔案，如果沒有這兩個檔案，輸入 npm install 是沒有用的。
:::