1. 为什么你的网站需要一点“诗意”不知道你有没有过这种感觉打开一个技术博客或者个人网站满屏都是代码、教程和干货虽然内容扎实但看久了总觉得有点“干”少了点温度和人情味。我自己做了这么多年开发也运营过几个技术站点深有体会。用户来你的网站除了获取信息其实也在感受你营造的氛围。一个恰到好处的诗词句子或者一句能引发共鸣的“每日一言”就像咖啡馆里背景播放的舒缓音乐不喧宾夺主却能瞬间提升整个空间的格调让访客停留的时间更长印象也更深刻。这可不是我瞎说。我自己的博客侧边栏就长期挂着“今日诗词”后台数据显示不少用户会特意刷新页面就为了看看今天换成了哪句诗。更有趣的是在文章评论区经常有读者就当天展示的诗词展开讨论无形中增加了社区的互动和粘性。对于内容创作者来说这简直是一个零成本提升用户体验和文化氛围的神器。那么怎么实现呢难道要我们手动每天去更新吗当然不用这就是“今日诗词”和“每日一言”这类API服务的魅力所在。它们提供了稳定、免费或带有免费额度的接口我们只需要写几行简单的JavaScript代码就能让网站自动展示每日更新的优美句子。无论你是前端新手还是资深全栈集成起来都毫无压力。接下来我就手把手带你用最直白的方式把这份“诗意”装进你的网站。2. 今日诗词API让古典之美自动绽放2.1 初识今日诗词不止是随机一句诗“今日诗词”的官网是www.jinrishici.com。初次接触你可能会觉得它就是一个随机返回古诗词句子的工具。但用久了你会发现它的“智能推荐”才是精髓。这个API并不是简单地从数据库里随机挑一句它会结合时间、季节、节日、甚至天气来进行推荐。举个例子中秋节那天它返回的很可能就是“但愿人长久千里共婵娟”下雨天你可能会看到“清明时节雨纷纷”清晨访问或许会是“一日之计在于晨”相关的诗句。这种应景的推送让展示的诗词不再是冰冷的文字而是有了生命力和场景感仿佛你的网站也在呼吸感知着时间的流转。它提供两种主要的调用方式直接生成图片和返回JSON数据。图片方式最简单适合纯展示而JSON方式则给了我们前端开发者最大的灵活性可以自定义样式、动画甚至做更复杂的交互。我们主要讲后者因为可控性更强更能融入网站的设计风格。2.2 五分钟快速集成基础版代码实战官方提供了超级方便的浏览器端SDK让我们能像引入jQuery一样轻松使用。下面这个例子是我在无数项目中验证过的最稳定、最基础的集成方案。首先在你的HTML页面中需要两个元素来承载诗词内容和出处信息比如两个p标签。然后引入SDK并写一个简单的回调函数。!-- 1. 在页面中预留显示位置 -- h2今日诗词/h2 p idjinrishici-sentence正在加载今日诗词.../p p idjinrishici-info/p !-- 2. 引入官方JS SDK -- script srchttps://sdk.jinrishici.com/v2/browser/jinrishici.js charsetutf-8/script !-- 3. 编写处理逻辑 -- script // 使用 jinrishici.load 方法它接收一个回调函数 jinrishici.load(function(result) { // 回调函数的参数 result 包含了完整的API返回数据 console.log(result); // 首次调试时建议打开控制台看看数据结构 // 提取诗词句子 var sentence result.data.content; // 提取出处信息朝代、作者、标题 var dynasty result.data.origin.dynasty; var author result.data.origin.author; var title result.data.origin.title; // 组合成我们想要的展示格式 var infoText 【${dynasty}】${author}《${title}》; // 将内容填充到页面元素中 document.getElementById(jinrishici-sentence).innerText sentence; document.getElementById(jinrishici-info).innerText infoText; }); /script把这段代码放到你的网站页面里刷新一下一句随机的古诗词就应该出现了。这个过程完全在浏览器端完成不依赖你的服务器对网站性能几乎没有影响。我建议你在第一次集成时务必打开浏览器的开发者工具F12查看console.log(result)的输出。这样你能清晰地看到API返回的完整JSON结构理解每个字段的含义未来做定制化开发就心里有底了。2.3 玩转高级配置样式、异步与错误处理基础功能实现了但我们肯定不满足于此。一个产品级的集成需要考虑加载状态、网络错误、样式美化等问题。下面我来分享几个实战中总结的进阶技巧。首先是样式美化。直接显示文字可能很单调。我们可以用CSS让它更出彩。比如给诗词句子加上优雅的字体、适当的阴影和动画。#jinrishici-sentence { font-family: STKaiti, 华文楷体, serif; /* 使用楷体更显古韵 */ font-size: 1.5rem; line-height: 1.8; color: #2c3e50; padding: 1rem; border-left: 4px solid #3498db; /* 左侧装饰竖线 */ background-color: #f8f9fa; border-radius: 4px; margin: 1rem 0; transition: all 0.3s ease; } #jinrishici-sentence:hover { background-color: #e8f4fc; /* 鼠标悬停微交互 */ border-left-color: #2980b9; } #jinrishici-info { font-size: 0.9rem; color: #7f8c8d; text-align: right; font-style: italic; }其次是处理异步加载与错误。网络请求总有失败的可能。一个好的用户体验是优雅地降级。我们可以改造之前的脚本增加加载中和失败的状态提示。div idpoem-container p idjinrishici-sentence 正在从古诗词库中寻觅佳句.../p p idjinrishici-info/p /div script srchttps://sdk.jinrishici.com/v2/browser/jinrishici.js charsetutf-8/script script // 设置一个超时定时器防止网络卡死 var loadTimer setTimeout(function() { var container document.getElementById(poem-container); container.innerHTML p stylecolor:#95a5a6;⏳ 诗词加载较慢请稍后刷新试试。/p; }, 5000); // 5秒超时 jinrishici.load(function(result) { // 成功收到数据清除超时定时器 clearTimeout(loadTimer); document.getElementById(jinrishici-sentence).innerText result.data.content; document.getElementById(jinrishici-info).innerText 【${result.data.origin.dynasty}】${result.data.origin.author}《${result.data.origin.title}》; }, function(err) { // 这里是失败回调函数官方SDK可能未显式提供我们可以用catch包装 clearTimeout(loadTimer); console.error(今日诗词加载失败:, err); document.getElementById(poem-container).innerHTML p stylecolor:#e74c3c; 很遗憾今日诗词暂不可用。推荐阅读静夜思 - 李白/p; }); /script注意官方SDK的jinrishici.load方法可能没有直接提供错误回调参数。更稳健的做法是用Promise或try...catch进行包装或者依赖上面的超时机制。这里展示的是一种思路你可以根据实际情况调整。3. 每日一言API注入一句触动心灵的话3.1 走进一言一句话的温暖力量如果说“今日诗词”带来的是古典的雅致那么“每日一言”Hitokoto注入的则是现代的温度。它的官网是hitokoto.cn。这个项目的初衷非常打动我“动漫也好、小说也好、网络也好不论在哪里我们总会看到有那么一两个句子能穿透你的心。”它收集的句子来源非常广泛包括动漫台词、小说摘录、网络金句甚至用户自己的投稿。每一句话都简短有力或励志或治愈或引人深思。把它放在博客的页脚、侧边栏或者文章结束的地方就像一位老朋友在轻声诉说能给偶然瞥见的访客带来一瞬间的共鸣或鼓励。从技术角度看它的API设计极其简洁友好返回格式支持JSON、JSONP、纯文本等多种方式对前端集成特别方便。而且它完全免费没有调用频率的严格限制当然我们作为开发者要自觉维护不要恶意刷接口。3.2 极简集成一行代码的魔法每日一言最简单的集成方式是使用它提供的JSONP格式的JS文件调用。这种方式可以绕过浏览器的跨域限制非常适合前端直接调用。!-- 在你想显示“一言”的位置放置一个容器 -- div idhitokoto-texti正在加载一句暖心的话.../i/div !-- 使用 script 标签调用API并将返回的句子写入指定ID的容器 -- script srchttps://v1.hitokoto.cn/?encodejsselect%23hitokoto-text defer/script没错就一行脚本src里的链接是它的API地址encodejs参数表示返回JS代码格式select%23hitokoto-text是一个CSS选择器告诉API将返回的句子直接插入到idhitokoto-text的元素内部。defer属性让脚本在页面解析完后执行不阻塞渲染。刷新页面你应该能看到一句随机的话出现在那个div里了。这种方式简单到不可思议但缺点是不够灵活我们无法控制返回数据的具体结构也无法在插入前进行额外的处理比如修改样式、添加动画。3.3 进阶掌控使用Fetch API进行自定义调用为了获得完全的控制权我强烈推荐使用现代的fetchAPI或axios等库来调用每日一言的JSON接口。这样我们能自己处理整个数据流。div idhitokoto-container blockquote idhitokoto-content心之所向素履以往。/blockquote p idhitokoto-from—— 来自网络/p /div script // 定义一个异步函数来获取一言 async function fetchHitokoto() { const container document.getElementById(hitokoto-container); const contentEl document.getElementById(hitokoto-content); const fromEl document.getElementById(hitokoto-from); // 先显示加载状态 contentEl.innerText 正在汲取智慧的能量...; fromEl.innerText ; try { // 调用API等待响应 const response await fetch(https://v1.hitokoto.cn); // 将响应解析为JSON对象 const data await response.json(); // 更新页面内容 contentEl.innerText data.hitokoto; // 句子内容 // 出处信息如果有作者和作品就拼接起来 let fromText data.from; if (data.from_who) { fromText ${data.from_who}《${data.from}》; } fromEl.innerText —— ${fromText}; // 可选根据句子类型data.type添加不同的图标或样式 // 例如励志、哲理、动漫、电影... container.dataset.type data.type; } catch (error) { // 如果请求失败显示备用内容 console.error(获取每日一言失败:, error); contentEl.innerText 旅途本身就是最美的风景。; fromEl.innerText —— 备用语录; } } // 页面加载完成后执行 window.addEventListener(DOMContentLoaded, fetchHitokoto); // 你也可以加一个按钮让用户手动刷新一言 // document.getElementById(refresh-btn).addEventListener(click, fetchHitokoto); /script通过这种方式我们拿到了完整的JSON数据里面包含句子hitokoto、出处from、作者from_who、类型type等字段。你可以尽情发挥创意比如根据type字段显示不同颜色的边框或者做一个“点击刷新”按钮让用户主动获取新句子。4. 双剑合璧打造网站的文化展示栏单独使用“今日诗词”或“每日一言”已经效果不错但如果把它们组合在一起交替显示或者并列展示就能打造一个更具吸引力的“文化角”或“灵感驿站”。这里我分享两种我实际用过的布局方案。4.1 方案一标签页切换式展示这种方案适合侧边栏空间有限的情况。通过标签页Tab切换让用户自主选择看诗词还是看一言。HTML结构div classculture-widget div classtab-header button classtab-btn active>.culture-widget { border: 1px solid #eee; border-radius: 8px; overflow: hidden; } .tab-header { display: flex; background: #f5f5f5; } .tab-btn { flex: 1; padding: 12px; border: none; background: none; cursor: pointer; } .tab-btn.active { background: white; font-weight: bold; } .tab-pane { display: none; padding: 20px; } .tab-pane.active { display: block; }JavaScript逻辑// 1. 标签切换逻辑 document.querySelectorAll(.tab-btn).forEach(btn { btn.addEventListener(click, function() { const tabId this.dataset.tab; // 切换按钮状态 document.querySelectorAll(.tab-btn).forEach(b b.classList.remove(active)); this.classList.add(active); // 切换内容面板 document.querySelectorAll(.tab-pane).forEach(pane pane.classList.remove(active)); document.getElementById(tab-${tabId}).classList.add(active); }); }); // 2. 分别调用两个API的函数 function loadPoem() { /* 复用之前今日诗词的fetch代码 */ } function loadHitokoto() { /* 复用之前每日一言的fetch代码 */ } // 3. 页面加载时初始化两个内容 window.addEventListener(DOMContentLoaded, () { loadPoem(); loadHitokoto(); });4.2 方案二自动轮播与动画效果如果你希望展示更动态可以做一个自动轮播组件每隔10秒或30秒在诗词和一言之间切换并加上淡入淡出的动画效果。class CultureCarousel { constructor(poemEl, hitokotoEl, interval 10000) { this.poemEl poemEl; this.hitokotoEl hitokotoEl; this.interval interval; // 轮播间隔单位毫秒 this.currentIndex 0; // 0代表诗词1代表一言 this.items [poemEl, hitokotoEl]; this.init(); } init() { // 先隐藏所有项目 this.items.forEach(el el.style.opacity 0); // 显示第一个项目 this.showItem(0); // 加载数据 this.loadAllData(); // 启动轮播定时器 this.startCarousel(); } async loadAllData() { // 并行加载诗词和一言数据 await Promise.all([this.fetchPoem(), this.fetchHitokoto()]); } async fetchPoem() { /* ... */ } async fetchHitokoto() { /* ... */ } showItem(index) { // 淡出当前项目 if (this.currentIndex ! null) { this.items[this.currentIndex].style.transition opacity 0.5s ease; this.items[this.currentIndex].style.opacity 0; } // 淡入新项目 this.currentIndex index; this.items[index].style.transition opacity 0.5s ease; this.items[index].style.opacity 1; } startCarousel() { setInterval(() { const nextIndex (this.currentIndex 1) % this.items.length; this.showItem(nextIndex); }, this.interval); } } // 使用 window.addEventListener(DOMContentLoaded, () { const poemBox document.getElementById(poem-box); const hitokotoBox document.getElementById(hitokoto-box); new CultureCarousel(poemBox, hitokotoBox, 15000); // 每15秒轮播一次 });这个轮播类封装了数据加载、显示切换和定时轮播的逻辑。你只需要提供两个容器元素它就能自动运行起来。通过CSS控制opacity过渡就能实现平滑的淡入淡出效果比生硬的显示隐藏要优雅得多。5. 避坑指南与性能优化实战集成第三方API看似简单但在实际生产环境中我踩过不少坑。这里把关键的经验教训分享给你希望能帮你绕过这些弯路。5.1 常见的“坑”与解决方案坑一API调用失败导致页面元素空白或错误。这是最常见的问题。网络不稳定、服务端临时故障、用户浏览器插件拦截等都可能导致请求失败。解决方案必须添加完善的错误处理。就像前面示例中做的使用try...catch包裹请求逻辑并在catch块中设置友好的降级内容如显示一句本地存储的默认句子。同时可以设置请求超时避免用户长时间等待。坑二页面加载闪烁FOUC。因为诗词/一言内容是异步加载的在JS执行前HTML容器可能是空的或有“加载中”文字JS执行后瞬间替换会造成视觉上的闪烁。解决方案使用CSS隐藏初始状态待数据加载完成后再显示。#poem-container, #hitokoto-container { opacity: 0; transition: opacity 0.3s ease; } #poem-container.loaded, #hitokoto-container.loaded { opacity: 1; }在JS中数据填充完毕后为容器加上loaded类。坑三影响页面核心内容的加载速度。虽然SDK脚本不大但如果放在HTML头部且网络慢仍可能阻塞渲染。解决方案使用async或defer属性异步加载脚本。更激进的做法是等页面核心内容加载完毕DOMContentLoaded事件甚至用户滚动到附近Intersection Observer API时再动态创建脚本标签去加载这些“装饰性”内容。坑四样式冲突。第三方SDK有时会自带一些基础样式可能和你网站的CSS产生冲突。解决方案将展示容器用一个有特定类名的div包裹起来并在你的CSS中使用足够具体的选择器来定义样式确保你的样式优先级更高。如果发现冲突可以用浏览器开发者工具的检查元素功能查看最终生效的CSS规则。5.2 性能优化与缓存策略对于个人博客或访问量不大的网站直接每次页面加载都请求API没问题。但如果你的网站流量较大或者你想追求极致的加载速度可以考虑以下缓存策略。1. 浏览器本地缓存LocalStorage思路是第一次请求API后将返回的句子和当前日期一起存入localStorage。下次用户访问时先检查缓存中是否有当天的数据如果有就直接使用无需网络请求。第二天再请求新的。async function getPoemWithCache() { const cacheKey jinrishici_cache; const today new Date().toDateString(); // 以日期作为缓存标识 const cached localStorage.getItem(cacheKey); if (cached) { const { date, data } JSON.parse(cached); if (date today) { // 缓存有效直接使用 renderPoem(data); return; } } // 缓存无效或没有缓存发起请求 const newData await fetchPoemFromAPI(); // 存储新缓存 localStorage.setItem(cacheKey, JSON.stringify({ date: today, data: newData })); renderPoem(newData); }注意localStorage有同源策略限制且容量有限通常5MB。对于诗词/一言这种文本数据完全够用。2. 服务端缓存推荐用于动态网站如果你的网站有后端如Node.js, PHP, Python可以在服务端调用这些API将结果缓存一段时间比如1小时然后前端从你自己的后端接口获取。这样做有几个好处屏蔽前端跨域问题如果API不支持CORS。统一错误处理和降级。大幅减少对原始API的调用次数更友好。提升前端加载速度因为你的服务器可能响应更快。一个简单的Node.jsExpress中间件示例const axios require(axios); const NodeCache require(node-cache); const poemCache new NodeCache({ stdTTL: 3600 }); // 缓存1小时 app.get(/api/daily-poem, async (req, res) { try { let poem poemCache.get(poem); if (!poem) { const response await axios.get(https://v2.jinrishici.com/sentence); poem response.data; poemCache.set(poem, poem); } res.json(poem); } catch (error) { // 从缓存中返回旧数据即使过期了也比报错好 const stalePoem poemCache.get(poem); if (stalePoem) { res.json(stalePoem); } else { res.status(500).json({ error: 无法获取诗词 }); } } });这样你的前端只需要调用自己的/api/daily-poem接口即可更稳定、更快速。把这些第三方服务集成到网站里技术上没有太高门槛真正的功夫在于细节的处理和对用户体验的考量。从简单的脚本引入到考虑加载状态、错误处理、缓存策略再到设计优雅的交互和动画每一步的打磨都能让这个小功能更好地服务于你的内容和用户。