Microsoft PXT 扩展开发：如何为自定义块添加帮助文档

在 Microsoft PXT 开发环境中，扩展作者经常需要为自定义块添加帮助文档。当用户点击扩展块并选择"帮助"时，理想情况下应该显示该块的专用参考文档，就像主程序块那样。然而，目前许多扩展会将用户重定向到扩展的 README 文件，这并非最佳用户体验。

当前问题分析

许多扩展开发者发现，他们的块帮助功能无法像预期那样工作。点击帮助按钮后，用户会被带到扩展的README页面，而不是特定块的文档。这主要是因为帮助系统的配置方式不够直观，现有文档也没有明确说明如何正确设置。

解决方案：使用代码托管平台前缀

PXT 实际上提供了一个优雅的解决方案，通过在 jsDoc 的 %help 属性中使用 代码托管平台: 前缀。这个功能允许开发者直接链接到托管在代码托管平台上的特定文档文件。例如：

//% help=代码托管平台:arcade-character-animations/docs/set-character-state

这种语法告诉 PXT 系统，该块的帮助文档位于代码托管平台仓库的指定路径下。当用户点击帮助按钮时，系统会直接加载这个特定文件，而不是整个 README。

实现步骤

1. 在你的扩展项目中创建一个专门的文档目录（如 /docs）
2. 为每个需要文档的块创建单独的 Markdown 文件
3. 在块的 jsDoc 注释中添加 help 属性，使用 代码托管平台: 前缀指向对应文档
4. 确保文档文件随扩展一起提交到代码托管平台仓库

最佳实践建议

• 保持文档简洁明了，专注于块的特定功能
• 包含使用示例和常见问题解答
• 定期更新文档以反映功能变更
• 考虑为复杂块添加多个使用场景示例

未来展望

随着 PXT 生态系统的成熟，扩展开发者应该更加重视文档质量。良好的块级文档不仅能提升用户体验，还能降低扩展的使用门槛，促进更广泛的采用。

通过采用这种文档方法，扩展开发者可以提供与核心块一致的用户体验，使他们的扩展更加专业和易用。