小部件文档
完整指南，教您如何在网站上嵌入和自定义 Currency.Wiki 货币转换器小部件。
目录
1 快速入门
为您的网站添加货币转换器小部件非常简单。请按照以下步骤操作：
- 进入小部件生成器页面，自定义小部件外观
- 选择您喜欢的小部件样式、货币和主题
- 复制生成的嵌入代码（脚本或 Iframe）
- 将代码粘贴到您网站的 HTML 中，您希望小部件显示的位置
提示： 在小部件生成器中使用快速预设，快速开始配置小部件。
2 嵌入方式
脚本嵌入（推荐）
脚本嵌入方式会将小部件直接注入您的页面。货币下拉菜单将在周围内容上方显示，便于选择。
<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>
- 完全与页面样式隔离
- 支持严格内容安全策略
- 实现简单且安全
注意： 如需完整交互（下拉菜单悬浮显示），请用脚本嵌入。如需隔离或有 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 参数自定义您的小部件。这些参数适用于脚本和 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 | 强调色（十六进制，不含#） |
| 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 中。若为脚本嵌入，请确保容器 div 存在且 ID 正确。检查浏览器控制台是否有 JavaScript 错误。
下拉菜单无法使用
若使用 Iframe 嵌入，下拉菜单将在小部件区域内滚动。如需完整下拉悬浮功能，请使用脚本嵌入方式。
样式冲突
若您网站的 CSS 影响了小部件外观，请尝试使用 Iframe 嵌入方式，将小部件样式与页面隔离。
内容安全策略（CSP）问题
如有严格 CSP，需将 currency.wiki 添加到允许的 script-src 和 frame-src。示例：script-src 'self' currency.wiki; frame-src 'self' currency.wiki;
