/**
* Blog Post object toolkit for CMS forms, preview, and local-storage sync.
* - ES2020+ compatible, browser-first.
* - Provides: factory, validation, update helpers, preview, and draft storage.
*/
/**
* @typedef {Object} BlogPost
* @property {string} title // 文章标题
* @property {string} slug // URL 友好的标识符（根据标题生成，或手动设置）
* @property {string} content // 正文（纯文本/Markdown/HTML）
* @property {string} summary // 摘要（若为空则从 content 推导）
* @property {string[]} tags // 标签（去重、裁剪空白）
* @property {string} authorName // 作者显示名
* @property {string} authorId // 作者唯一标识
* @property {string} coverUrl // 封面图 URL
* @property {boolean} published // 是否发布
* @property {string} createdAt // ISO 8601 创建时间
* @property {string} updatedAt // ISO 8601 更新时间
*/
// -------------------- Utilities --------------------
const toISO = (date = new Date()) => new Date(date).toISOString();
/**
* Create a URL-friendly slug from title or input.
* - lowercases, trims, removes diacritics, keeps a-z0-9 and hyphens.
*/
function slugify(input, maxLength = 80) {
const s = String(input ?? '')
.trim()
.toLowerCase()
.normalize('NFKD') // split diacritics
.replace(/[\u0300-\u036f]/g, '')// remove diacritics marks
.replace(/[^a-z0-9]+/g, '-') // non-alnum => hyphen
.replace(/^-+|-+$/g, '') // trim hyphens
.slice(0, maxLength);
return s || 'untitled';
}
/**
* Strip HTML to plain text (safe in browser using DOMParser; falls back to regex).
*/
function stripHTML(html) {
if (typeof window !== 'undefined' && typeof DOMParser !== 'undefined') {
const doc = new DOMParser().parseFromString(String(html ?? ''), 'text/html');
return doc.body.textContent || '';
}
// Fallback (non-browser)
return String(html ?? '').replace(/<[^>]*>/g, ' ');
}
/**
* Derive a summary from summary/content with max length and ellipsis.
*/
function deriveSummary({ summary, content }, maxLen = 160) {
if (typeof summary === 'string' && summary.trim()) return summary.trim();
const text = stripHTML(content).replace(/\s+/g, ' ').trim();
if (!text) return '';
return text.length > maxLen ? text.slice(0, maxLen - 1).trimEnd() + '…' : text;
}
/**
* Normalize tags: trim, remove empty, de-duplicate, optional limit.
*/
function normalizeTags(tags = [], max = 50) {
const out = [];
const seen = new Set();
for (const t of tags) {
if (typeof t !== 'string') continue;
const v = t.trim();
if (!v || seen.has(v)) continue;
out.push(v);
seen.add(v);
if (out.length >= max) break;
}
return out;
}
/**
* Quick word count-based reading time (optional helper for UI).
*/
function estimateReadingTime(text, wordsPerMin = 250) {
const words = String(stripHTML(text)).trim().split(/\s+/).filter(Boolean).length;
const mins = Math.max(1, Math.ceil(words / Math.max(100, wordsPerMin)));
return { minutes: mins, words };
}
// -------------------- Factory & Validation --------------------
/**
* Create a new BlogPost with sane defaults and normalization.
* @param {Partial<BlogPost>} initial
* @returns {BlogPost}
*/
function createBlogPost(initial = {}) {
const now = toISO();
const title = String(initial.title ?? '').trim();
const createdAt = (typeof initial.createdAt === 'string' && !Number.isNaN(Date.parse(initial.createdAt)))
? new Date(initial.createdAt).toISOString()
: now;
const content = String(initial.content ?? '');
const post = {
title,
slug: slugify(initial.slug || title),
content,
summary: deriveSummary({ summary: initial.summary, content }),
tags: normalizeTags(initial.tags),
authorName: String(initial.authorName ?? ''),
authorId: String(initial.authorId ?? ''),
coverUrl: String(initial.coverUrl ?? ''),
published: Boolean(initial.published),
createdAt,
updatedAt: now,
};
return post;
}
/**
* Validate a BlogPost object. Returns {valid, errors[]}
* - Type checks, ISO date checks, basic slug rules.
*/
function validateBlogPost(post) {
const errors = [];
const isString = (v) => typeof v === 'string';
const mustString = ['title', 'slug', 'content', 'summary', 'authorName', 'authorId', 'coverUrl', 'createdAt', 'updatedAt'];
for (const k of mustString) {
if (!isString(post[k])) errors.push(`"${k}" must be a string`);
}
if (!Array.isArray(post.tags)) errors.push('"tags" must be an array');
else if (!post.tags.every((t) => typeof t === 'string')) errors.push('"tags" must be string[]');
if (typeof post.published !== 'boolean') errors.push('"published" must be a boolean');
const isoFields = ['createdAt', 'updatedAt'];
for (const f of isoFields) {
if (isString(post[f]) && Number.isNaN(Date.parse(post[f]))) {
errors.push(`"${f}" must be a valid ISO 8601 date string`);
}
}
// basic slug sanity
if (isString(post.slug) && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(post.slug)) {
errors.push('"slug" should be lower-case alphanumerics separated by hyphens');
}
return { valid: errors.length === 0, errors };
}
/**
* Functional update: returns a new BlogPost with normalized fields and updatedAt bumped.
* - If title is changed and slug not explicitly provided, regenerate slug from title.
* - Summary is rederived when summary not provided or empty string.
* - Tags are normalized.
*/
function updateBlogPost(post, patch = {}) {
const merged = { ...post, ...patch };
// Handle slug regeneration rules
const titleChanged = typeof patch.title === 'string' && patch.title !== post.title;
const slugProvided = Object.prototype.hasOwnProperty.call(patch, 'slug');
if (titleChanged && !slugProvided) {
merged.slug = slugify(merged.title);
} else if (slugProvided) {
merged.slug = slugify(patch.slug);
}
// Normalize tags and summary
merged.tags = normalizeTags(patch.tags ?? post.tags);
merged.summary = deriveSummary({ summary: merged.summary, content: merged.content });
// Bump updatedAt
merged.updatedAt = toISO();
return merged;
}
// -------------------- Serialization & Storage --------------------
/**
* Serialize BlogPost to JSON string (stable keys for readability).
*/
function serializeBlogPost(post) {
const ordered = {
title: post.title,
slug: post.slug,
content: post.content,
summary: post.summary,
tags: post.tags,
authorName: post.authorName,
authorId: post.authorId,
coverUrl: post.coverUrl,
published: post.published,
createdAt: post.createdAt,
updatedAt: post.updatedAt,
};
return JSON.stringify(ordered);
}
/**
* Parse JSON or plain object into a normalized BlogPost.
*/
function parseBlogPost(input) {
const obj = typeof input === 'string' ? JSON.parse(input) : input;
return createBlogPost(obj);
}
/**
* Generate a stable draft storage key for localStorage.
*/
function draftKey(post) {
return `cms:draft:${post.slug || 'untitled'}`;
}
/**
* Save draft to localStorage. Returns the storage key or null on failure.
*/
function saveDraft(post, key = draftKey(post)) {
try {
localStorage.setItem(key, serializeBlogPost(post));
return key;
} catch (err) {
// Optionally surface error to caller
return null;
}
}
/**
* Load draft from localStorage. Returns BlogPost or null if not found/invalid.
*/
function loadDraft(key) {
try {
const raw = localStorage.getItem(key);
if (!raw) return null;
return parseBlogPost(raw);
} catch {
return null;
}
}
/**
* Remove draft from localStorage. Returns true if removed.
*/
function clearDraft(key) {
try {
localStorage.removeItem(key);
return true;
} catch {
return false;
}
}
// -------------------- Preview Helper --------------------
/**
* Build a lightweight preview DTO for UI rendering (no HTML).
*/
function getPreview(post, maxSummaryLen = 160) {
return {
title: post.title || '未命名',
slug: post.slug,
summary: deriveSummary({ summary: post.summary, content: post.content }, maxSummaryLen),
coverUrl: post.coverUrl || '',
tags: post.tags,
published: post.published,
updatedAt: post.updatedAt,
readingTime: estimateReadingTime(post.content).minutes,
};
}
// Example export (if using modules)
// export {
// createBlogPost,
// updateBlogPost,
// validateBlogPost,
// serializeBlogPost,
// parseBlogPost,
// saveDraft,
// loadDraft,
// clearDraft,
// getPreview,
// };
对象结构说明
- 采用工厂函数创建对象，提供可靠的默认值与规范化处理，便于在表单中直接绑定。
- 提供函数式更新方法 updateBlogPost，避免副作用并自动维护 updatedAt。
- 内置 slug 生成、摘要推导、标签归一化、ISO 时间戳、草稿本地存储支持。
- 提供 getPreview 生成轻量预览数据用于卡片/列表展示。
属性详细说明表
| 属性名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---:|---|---|
| title | string | 否 | '' | 文章标题；用于生成 slug |
| slug | string | 否 | 由 title 推导或 'untitled' | URL 标识，lowercase-hyphen |
| content | string | 否 | '' | 正文（纯文本/Markdown/HTML） |
| summary | string | 否 | 从 content 推导 | 摘要；若提供空串，将重新推导 |
| tags | string[] | 否 | [] | 标签，自动去重与裁剪空白 |
| authorName | string | 否 | '' | 作者显示名 |
| authorId | string | 否 | '' | 作者唯一标识（建议必填） |
| coverUrl | string | 否 | '' | 封面图 URL |
| published | boolean | 否 | false | 是否发布 |
| createdAt | string(ISO) | 否 | 创建时刻 | ISO 8601 时间字符串 |
| updatedAt | string(ISO) | 否 | 创建/更新时刻 | ISO 8601 时间字符串 |
使用示例代码
// 1) 一键生成表单初始对象
let post = createBlogPost({
title: '用现代 JavaScript 写出更好的代码',
authorName: 'Jane Doe',
authorId: 'user_123',
tags: ['JavaScript', 'Web', ' JavaScript '], // 会去重 -> ['JavaScript', 'Web']
});
console.log(post.slug); // yong-xian-dai-javascript-xie-chu-geng-hao-de-dai-ma（示例）
// 2) 表单编辑：内容或标题变化时进行函数式更新
post = updateBlogPost(post, { content: '# 正文内容\n更多文本...' });
// 标题变化时，若未手动提供 slug，将自动重算 slug
post = updateBlogPost(post, { title: '新标题' });
// 3) 校验（用于提交前）
const { valid, errors } = validateBlogPost(post);
if (!valid) {
console.error('校验失败：', errors);
}
// 4) 预览卡片数据（摘要、阅读时长）
const preview = getPreview(post);
console.log(preview);
// 5) 本地存储草稿
const key = saveDraft(post); // cms:draft:<slug>
const loaded = loadDraft(key); // 读取并自动规范化
clearDraft(key); // 清除草稿
最佳实践建议
- Slug 稳定性：文章发布后建议固定 slug，不要因标题变更自动更新，以避免链接失效。可在 UI 上提供“锁定 slug”的开关。
- 安全渲染：content 若包含 HTML/Markdown，请在渲染时使用可靠库进行解析与消毒（如 DOMPurify），切勿直接注入未消毒的 HTML。
- ISO 时间：持久化与接口交互统一使用 ISO 8601 字符串，便于跨时区与后端协作。
- 函数式更新：通过 updateBlogPost 返回新对象，便于在状态管理库（如 React/Redux/Zustand）中追踪变更。
- 标签规范：保持标签数组小而精（如 ≤ 50 个），避免大小写或前后空白导致的重复。
- 校验扩展：根据业务规则可扩展 validateBlogPost（例如要求 authorId 必填、coverUrl 合法性校验等）。
- 本地存储命名空间：使用明确前缀（如 cms:draft:）避免与其他存储键冲突，并考虑配合用户 ID 做多账号隔离。
