AnalogJS中injectContentFiles方法的问题分析与解决方案

问题背景

在AnalogJS框架中，injectContentFiles方法被设计用来获取内容文件列表，但开发者发现该方法返回的ContentFile对象中并未包含实际的Markdown内容。这导致在使用MarkdownComponent渲染内容时，会出现"marked(): input parameter is undefined or null"的错误。

问题分析

1. 类型定义与实际行为不符
   injectContentFiles的类型定义表明它会返回包含内容的ContentFile对象，但实际上该方法仅返回文件的基本信息（如文件名、路径等），而不包含文件内容。

2. 与injectContent方法的区别
   injectContent方法确实会获取并返回文件内容，但它是以Observable形式返回的，这表明内容获取是一个异步过程。而injectContentFiles是同步的，这解释了为什么它不包含实际内容。

3. 使用场景差异
   设计上，injectContentFiles主要用于获取内容文件列表（如博客文章列表），通常只需要显示标题、日期等元数据；而injectContent则用于获取单个文件的完整内容。

解决方案

临时解决方案

对于需要同时获取文件列表和内容的场景，可以结合使用两个方法：

export function injectBlogPosts() {
  const contentFiles = injectContentFiles<PostAttributes>();
  const contentStream = contentFiles.map((contentFile) => {
    const parts = contentFile.filename.split('/');
    const filename = parts[4];
    const subdirectory = parts[3];
    return injectContent({
      customFilename: `${subdirectory}/${filename}`
    });
  });
  return forkJoin(contentStream);
}

长期改进建议

1. 类型定义修正
   应该明确区分仅包含元数据的ContentFile和包含完整内容的ContentFile类型。

2. 方法行为明确化
   在文档中明确说明injectContentFiles仅返回文件元数据，不包含实际内容。

3. 新增方法选项
   可以考虑为injectContentFiles添加一个选项参数，允许开发者选择是否同时获取内容。

最佳实践

1. 列表页面
   仅使用injectContentFiles获取文件列表，展示元数据。

2. 详情页面
   使用injectContent获取单个文件的完整内容。

3. 特殊场景
   如需同时获取多个文件的完整内容，可采用上述forkJoin方案。

总结

这个问题反映了API设计时对使用场景考虑的不同。虽然当前行为与类型定义存在不一致，但通过理解框架的设计意图和正确使用方法，开发者可以有效地实现各种内容展示需求。未来版本可能会对此进行改进，使API更加清晰和一致。