🚚 安装

npm install remark-tweet-card

或

yarn add remark-tweet-card

🔦 使用方法

1. 导入

   和一般的 remark 插件一样，这里以 Astro 为例：

   // astro.config.js
   import { unified } from '@astrojs/markdown-remark';
   import remarkTweetCard from 'remark-tweet-card';
   
   export default defineConfig({
     markdown: {
       processor: unified({
         remarkPlugins: [remarkTweetCard],
       }),
     },
   });

2. 引入全局样式

   @import 'remark-tweet-card/style.css';

3. 在 Markdown 中使用

   [$tweet](1654079444816936969)
   
   或
   
   [$tweet](https://x.com/github/status/1654079444816936969)

   即可渲染一个包括头像、正文、媒体、引用推文、互动数据的推文卡片。

🔧 配置项

remarkTweetCard({
  // CSS 类名前缀（默认 'tweet-card'）
  prefix: 'tweet-card',

  // API 请求超时时间，单位毫秒（默认 10000）
  timeout: 10000,

  // 自定义缓存实例，需实现 get/set/has（默认使用内部 Map）
  cache: new Map(),

  // 自定义推文数据获取器
  fetchTweet: async (id, { timeout, cache }) => {
    /* ... */
  },

  // 自定义完整推文卡片 HTML 渲染
  renderTweet: (tweet, { prefix, text }) => {
    /* 返回 HTML 字符串 */
  },

  // 自定义错误降级 HTML 渲染
  renderError: (url, { prefix, text }) => {
    /* 返回 HTML 字符串 */
  },

  // 本地化文本标签
  text: {
    replies: 'Replies',
    reposts: 'Reposts',
    quotes: 'Quotes',
    likes: 'Likes',
    viewOnX: 'View on X',
    notFound: 'Tweet not available.',
  },
});

本地化配置

通过 text 选项可将推文卡片的界面文本本地化为任意语言。例如，配置为中文：

remarkTweetCard({
  text: {
    replies: '回复',
    reposts: '转发',
    quotes: '引用',
    likes: '喜欢',
    viewOnX: '在 X 上查看',
    notFound: '推文不可用。',
  },
});

🎨 自定义样式

提供了一份默认样式表，所有颜色通过 CSS 自定义属性控制。你只需覆盖以下变量即可实现一定程度的客制化：

深色模式

默认不提供深色样式，取决于项目的具体实现，你需要手动配置：

@media (prefers-color-scheme: dark) {
  :root {
    --tc-bg: #16181c;
    --tc-border: #2f3336;
    --tc-text: #e7e9ea;
    --tc-text-muted: #71767b;
  }
}

或

.dark {
  --tc-bg: #16181c;
  --tc-border: #2f3336;
  --tc-text: #e7e9ea;
  --tc-text-muted: #71767b;
}

😎 高阶用法

自定义数据获取

如果你需要代理请求或添加额外的错误处理：

import remarkTweetCard from 'remark-tweet-card';
import { fetchTweetData } from 'remark-tweet-card/api';

function myFetcher(id, { timeout, cache }) {
  // 通过你自己的代理获取数据
  const res = await fetch(`/api/tweet?id=${id}`);
  return res.ok ? res.json() : null;
}

remarkTweetCard({ fetchTweet: myFetcher })

自定义渲染

完全控制 HTML 输出：

remarkTweetCard({
  renderTweet(tweet, { prefix, text }) {
    // 使用你自己的模板生成 HTML
    return `<blockquote class="${prefix}">${tweet.text}</blockquote>`;
  },
});

复用子模块

插件的内部模块也单独导出，方便复用：

import {
  extractTweetId,
  fetchTweetData,
  clearCache,
} from 'remark-tweet-card/api';
import { buildTweetHTML, buildErrorHTML } from 'remark-tweet-card/html';
import { formatCount } from 'remark-tweet-card/utils';

const id = extractTweetId('https://x.com/user/status/123456');
const tweet = await fetchTweetData(id, { timeout: 5000 });
const html = tweet ? buildTweetHTML(tweet, { prefix: 'tweet-card' }) : '';