小工具文件
完整指南，教您如何在網站嵌入並自訂 Currency.Wiki 貨幣換算小工具。
目錄
1 快速開始
將貨幣換算小工具加入您的網站很簡單，請依照以下步驟：
- 前往小工具建構器頁面，自訂小工具外觀
- 選擇偏好的樣式、貨幣與主題
- 複製產生的嵌入碼（Script 或 Iframe）
- 將程式碼貼到您網站 HTML 中要顯示小工具的位置
小提示： 在小工具建構器中使用快速開始預設，立即套用預設組合。
2 嵌入方式
Script 嵌入（推薦）
Script 嵌入法會直接將小工具注入您的頁面。貨幣下拉選單會浮現在周圍內容上方，方便選擇。
<div id="currency-wiki-widget"></div>
<script src="https://widget.currency.wiki/v3/script.js?style=compact&theme=light&from=USD&to=EUR"></script>
- 下拉選單顯示於小工具外部
- 適合互動式貨幣切換
- 與頁面無縫整合
Iframe 嵌入
Iframe 嵌入法會為小工具建立隔離容器。此方法安全，適用於內容安全政策嚴格的環境。
<iframe src="https://widget.currency.wiki/v3/embed?style=compact&theme=light&from=USD&to=EUR"
width="300" height="180" frameborder="0"></iframe>
- 完全與頁面樣式隔離
- 支援嚴格內容安全政策
- 簡單且安全的實作
注意： 如需完整互動（下拉選單浮於內容上方），建議用 Script 嵌入。如需隔離或有 CSP 限制，請用 Iframe 嵌入。
3 小工具樣式
我們提供 11 種不同小工具樣式，讓您的網站設計更契合。每種樣式都針對不同用途與顯示尺寸最佳化。
mini
250x140px
精簡單行換算器。適合頁首或空間有限處。
square
250x250px
1:1 比例含切換按鈕。適合側邊欄。
compact
300x180px
小巧但功能齊全的換算器。
inline
480x56px
橫向排列。適合嵌入內容或導覽列。
tall
200x280px
垂直側邊欄樣式，含經典標籤。
mini-chart
250x260px
精簡換算器，含迷你匯率走勢圖。
multi-expandable
300x320px
多貨幣換算器。使用者可新增/移除貨幣。
multi-fixed
300x300px
固定匯率清單。適合顯示特定匯率。
rates-compact
250x320px
精簡匯率清單，含最後更新時間。
rates-viewer
300x500px
完整圖表檢視，含詳細匯率資訊。
rates-viewer-compact
300x400px
圖表檢視的精簡版。
4 URL 參數
可用 URL 參數自訂小工具。Script 與 Iframe 嵌入法皆適用。
| 參數 | 預設值 | 說明 |
|---|---|---|
| style | compact | 小工具樣式（mini、square、compact、inline、tall、mini-chart、multi-expandable、multi-fixed、rates-compact、rates-viewer、rates-viewer-compact） |
| theme | light | 顏色主題（light、dark 或 auto） |
| from | USD | 來源貨幣代碼（如 USD、EUR、GBP） |
| to | EUR | 目標貨幣代碼（如 EUR、USD、JPY） |
| amount | 1000 | 預設換算金額 |
| accent | #2563eb | 強調色（16 進位，不含 #） |
| lang | en | 小工具語言代碼（如 en、es、fr、de） |
| flags | 1 | 顯示國旗（1=顯示，0=隱藏） |
| display | iso | 貨幣顯示格式（iso=USD，symbol=$） |
| lock | 0 | 鎖定貨幣（1=鎖定，0=不鎖定） |
| currencies | EUR,GBP,JPY | 多貨幣小工具的貨幣清單（以逗號分隔） |
| dropdown | all | 下拉選單貨幣（all、top10、top20 或自訂清單） |
| branding | 1 | 顯示品牌（1=顯示，0=隱藏） |
| brandinglink | 1 | 品牌可點擊（1=連結，0=僅文字） |
| format | auto | 數字格式（auto、us、eu、french、indian） |
| decimals | 2 | 小數位數（0-6） |
| chart | 0 | 啟用圖表（1=啟用，0=停用） |
| chartperiod | 7d | 圖表期間（7d、14d、30d、90d） |
範例
深色主題精簡換算器：
?style=compact&theme=dark&from=USD&to=EUR
多貨幣匯率：
?style=multi-fixed&from=USD¤cies=EUR,GBP,JPY,CAD
含 30 天圖表的迷你換算器：
?style=mini-chart&from=EUR&to=USD&chartperiod=30d
以貨幣符號顯示：
?style=compact&display=symbol&from=USD&to=EUR
鎖定貨幣並自訂金額：
?style=compact&from=GBP&to=USD&lock=1&amount=100
5 自訂選項
主題選項
- light - 淺色背景搭配深色文字
- dark - 深色背景搭配淺色文字
- auto - 自動配合使用者系統偏好
貨幣顯示格式
- iso - 顯示 ISO 代碼，如 USD、EUR、GBP
- symbol - 顯示貨幣符號，如 $、€、£
數字格式
- auto - 自動偵測訪客瀏覽器設定
- us - 美式格式：1,234.56
- eu - 歐式格式：1.234,56
- french - 法式格式：1 234,56
- indian - 印度格式：1,23,456.78
下拉選單貨幣選項
- all - 全部 170+ 支援貨幣
- top10 - 前 10 名最受歡迎貨幣
- top20 - 交易量前 20 名貨幣
- USD,EUR,GBP,... - 自訂特定貨幣清單
小提示： 建議使用小工具建構器，視覺化設定所有選項並自動產生嵌入碼。
6 疑難排解
小工具未顯示
請確認嵌入碼正確放在 HTML 中。Script 嵌入時，請確保容器 div 存在且 ID 正確。請檢查瀏覽器主控台是否有 JavaScript 錯誤。
下拉選單無法使用
若使用 Iframe 嵌入，下拉選單會在小工具區塊內滾動。若需完整下拉選單功能，請改用 Script 嵌入。
樣式衝突
若您網站的 CSS 影響小工具外觀，請改用 Iframe 嵌入，將小工具樣式與頁面隔離。
內容安全政策（CSP）問題
若您的 CSP 設定嚴格，請將 currency.wiki 加入允許的 script-src 與 frame-src。範例：script-src 'self' currency.wiki; frame-src 'self' currency.wiki;
