dynamic-cms-sdk

Dynamic CMS SDK for Next.js and React applications - 让前端接入 CMS 变得简单！

🚀 快速开始

安装

npm install dynamic-cms-sdk
# 或
yarn add dynamic-cms-sdk

基础配置

// lib/cms.ts
import { initCMS } from '@dynamic-cms/sdk';

export const cms = initCMS({
  baseURL: 'https://your-cms-api.com/functions/v1',
  apiKey: 'your-api-key',
  websiteId: 'your-website-id',
  webhookSecret: 'your-webhook-secret', // 可选
});

📖 使用方法

1. React Hooks 方式

import { useArticles, useArticle } from '@dynamic-cms/sdk';

// 文章列表
function BlogList() {
  const { articles, loading, error } = useArticles({
    status: 'published',
    limit: 10,
  });

  if (loading) return <div>加载中...</div>;
  if (error) return <div>错误: {error.message}</div>;

  return (
    <div>
      {articles.map(article => (
        <div key={article.id}>
          <h2>{article.content.title}</h2>
          <p>{article.content.excerpt}</p>
        </div>
      ))}
    </div>
  );
}

// 单篇文章
function ArticlePage({ slug }: { slug: string }) {
  const { article, loading, error } = useArticle(slug);

  if (loading) return <div>加载中...</div>;
  if (error) return <div>错误: {error.message}</div>;
  if (!article) return <div>文章不存在</div>;

  return (
    <article>
      <h1>{article.content.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: article.content.content }} />
    </article>
  );
}

2. 组件方式

import { ArticleList, SearchBox } from '@dynamic-cms/sdk';

function BlogPage() {
  const { articles, loading, error } = useArticles();

  return (
    <div>
      <SearchBox onSearch={(query) => console.log(query)} />
      <ArticleList 
        articles={articles}
        loading={loading}
        error={error}
        cardProps={{
          showExcerpt: true,
          showImage: true,
          onTitleClick: (article) => {
            window.location.href = `/blog/${article.slug}`;
          }
        }}
      />
    </div>
  );
}

3. Next.js 静态生成

// pages/blog/index.tsx
import { createGetStaticProps } from '@dynamic-cms/sdk/nextjs';
import { cms } from '@/lib/cms';

export const getStaticProps = createGetStaticProps(cms, {
  status: 'published',
  limit: 20,
});

// pages/blog/[slug].tsx
import { createGetStaticProps, createGetStaticPaths } from '@dynamic-cms/sdk/nextjs';

export const getStaticProps = createGetStaticPropsForArticle(cms);
export const getStaticPaths = createGetStaticPaths(cms);

4. Webhook 处理

// pages/api/webhook/cms.ts
import { createWebhookHandler } from '@dynamic-cms/sdk/nextjs';
import { cms } from '@/lib/cms';

export default createWebhookHandler(cms, process.env.CMS_WEBHOOK_SECRET!, {
  onArticlePublished: async (article) => {
    console.log('文章发布:', article.title);
  },
  onArticleUpdated: async (article) => {
    console.log('文章更新:', article.title);
  },
  onArticleDeleted: async (article) => {
    console.log('文章删除:', article.title);
  },
});

🎨 样式定制

SDK 提供了基础的 CSS 类名，你可以自定义样式：

/* 文章卡片 */
.cms-article-card {
  border: 1px solid #e5e7eb;
  border-radius: 8px;
  padding: 1rem;
  margin-bottom: 1rem;
}

.cms-article-title {
  font-size: 1.25rem;
  font-weight: 600;
  margin-bottom: 0.5rem;
}

.cms-article-excerpt {
  color: #6b7280;
  margin-bottom: 1rem;
}

/* 分页 */
.cms-pagination {
  display: flex;
  gap: 0.5rem;
  justify-content: center;
  margin-top: 2rem;
}

.cms-pagination button {
  padding: 0.5rem 1rem;
  border: 1px solid #d1d5db;
  background: white;
  cursor: pointer;
}

.cms-pagination button.active {
  background: #3b82f6;
  color: white;
}

🔧 API 参考

Hooks

• useArticles(params) - 获取文章列表
• useArticle(slug) - 获取单篇文章
• useSearchArticles(query, params) - 搜索文章
• useWebsite() - 获取网站配置
• useRelatedArticles(articleId, limit) - 获取相关文章
• usePagination(total, pageSize) - 分页逻辑

组件

• <ArticleCard /> - 文章卡片
• <ArticleList /> - 文章列表
• <Pagination /> - 分页组件
• <SearchBox /> - 搜索框

工具函数

• generateExcerpt() - 生成摘要
• calculateReadingTime() - 计算阅读时间
• formatDate() - 格式化日期
• generateSlug() - 生成 URL 别名
• verifyWebhookSignature() - 验证 Webhook 签名

📝 TypeScript 支持

SDK 完全使用 TypeScript 编写，提供完整的类型定义：

import { Article, CMSConfig, ArticleListParams } from '@dynamic-cms/sdk';

const config: CMSConfig = {
  baseURL: 'https://api.example.com',
  apiKey: 'your-key',
  websiteId: 'your-id',
};

const params: ArticleListParams = {
  status: 'published',
  limit: 10,
  category: 'tech',
};

🌟 特性

• ✅ 零配置 - 开箱即用
• ✅ TypeScript - 完整类型支持
• ✅ React Hooks - 现代化 API
• ✅ Next.js 优化 - SSG/ISR 支持
• ✅ 缓存优化 - 基于 SWR
• ✅ Webhook 支持 - 实时更新
• ✅ SEO 友好 - Sitemap/RSS 生成
• ✅ 可定制 - 灵活的样式和配置

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📞 支持

• 文档: 查看完整文档
• Issues: 提交问题
• 邮箱: [email protected]