★ FEATURED ARTICLE 后端前端企业应用【免费下载链接】cal.diyScheduling infrastructure for absolutely everyone.项目地址https://gitcode.com/GitHub_Trending/ca/cal.diy点击查看免费下载导读本文以 cal.diyCal.com 开源调度基础设施仓库中 Skype 集成应用 的DESCRIPTION.md为切入点深入剖析应用商店详情页描述文件的 YAML frontmatter 结构、{DESCRIPTION}占位符替换机制、图片轮播渲染管线以及配套的config.json静态视频链接配置与声明式安装处理器。读完本文你将掌握如何在 cal.diy 中为任意集成应用编写符合规范的描述文件并理解其从文件系统到前端页面的完整渲染链路。一、DESCRIPTION.md 是什么应用商店详情页的骨架文件在 cal.diy 的 monorepo 结构中每个位于packages/app-store/slug/目录下的集成应用都携带一个DESCRIPTION.md文件。以 Skype 应用为例其完整内容如下--- items: - 1.jpeg - 2.jpeg - 3.jpeg --- {DESCRIPTION}这个文件看似简单实则承担着两个关键职责YAML frontmatter 声明展示图片items字段按顺序列出该应用在商店详情页轮播展示的截图文件名正文占位符承载应用简介{DESCRIPTION}是一个占位符在页面构建阶段会被替换为config.json中的description字段内容。这一设计并非 Skype 应用独有而是所有应用通用的规范模板。在 app-store 模板目录 中存在完全相同的文件骨架Skype 应用正是基于该模板生成的其config.json中记录了__template: event-type-location-video-static。二、frontmatter 规范图片列表的书写约定根据仓库 packages/app-store/CONTRIBUTING.md 中 App Contribution Guidelines 对DESCRIPTION.md的明确要求图片数量建议至少包含 4 张图片用于展示应用的使用场景和/或安装步骤Skype 应用当前提供了 3 张只写文件名不写路径items中仅填写文件名例如1.jpeg而不是/app-store/skype/1.jpeg。系统会根据应用目录自动补全资源路径描述内容要求正文应说明该集成允许用户在 cal.diy 中做什么例如允许你将 Cal 预订与你的 Zoho 日历同步这类功能性描述。这一只写文件名的约定由渲染管线负责兑现在 apps/web/lib/apps/[slug]/getStaticProps.ts 中每个items条目都会经过getAppAssetFullPath(item, { dirName, isTemplate })转换为完整的静态资源 URL最终落到packages/app-store/skype/static/目录下的实际文件如 1.jpeg、2.jpeg、3.jpeg。三、{DESCRIPTION} 占位符构建期的二次注入{DESCRIPTION}是模板系统的关键记号它存在两层替换逻辑3.1 应用生成时的首次替换当开发者通过 app-store-cli 脚手架创建新应用时CLI 在 core.ts 中执行如下替换fs.writeFileSync( ${appDirPath}/DESCRIPTION.md, fs .readFileSync(${appDirPath}/DESCRIPTION.md) .toString() .replace(/_DESCRIPTION_/g, description) .replace(/_APP_DIR_/g, slug) );即把模板文件中形如{DESCRIPTION}的占位符替换为开发者填写的应用描述。同时在 AppCreateUpdateForm.tsx 中该描述被标注为 A detailed description of your app后续还可以扩展为DESCRIPTION.mdx以支持更丰富的 Markdown 语法。3.2 页面构建时的二次替换在应用商店详情页的构建阶段getStaticProps.ts 会读取该文件并再次执行source.replace(/{DESCRIPTION}/g, appMeta.description)将占位符替换为从_appRegistry元数据中取到的应用描述该描述源自config.json的description字段。如果文件缺失则回退到appMeta.description并在服务端打印日志No DESCRIPTION.md provided for: appDirname四、渲染管线从 frontmatter 到 Glide 轮播4.1 解析与校验getStaticProps.ts 使用自实现的parseFrontmatter基于js-yaml4.x采用yaml.loadJSON_SCHEMA并配合FRONTMATTER_REGEX正则提取---包裹的 YAML 块解析描述文件随后通过sourceSchemazod校验content与data.items的结构export const sourceSchema z.object({ content: z.string(), data: z.object({ description: z.string().optional(), items: z.array( z.union([ z.string(), z.object({ iframe: z.object({ src: z.string() }) }), ]) ).optional(), }), });值得注意items数组除了字符串形式的本地图片还支持iframe对象用于嵌入外部页面这为描述文件提供了灵活的内容扩展能力。4.2 前端轮播呈现解析结果通过source.data?.items传给 slug-view.tsx最终由 Slider.tsx 渲染为基于 Glide.js 的轮播图组件。Slider组件接收泛型items数组与renderItem渲染函数内部通过data-glide-eltrack和glide__slides结构实现图片滑动展示并自带左右箭头控制ArrowLeftIcon/ArrowRightIcon。至此DESCRIPTION.md中的每一张截图都会成为商店详情页轮播中的一帧直观地向用户展示该应用的实际使用效果。五、配套 config.json静态视频链接的声明式配置DESCRIPTION.md只负责展示层真正决定应用行为的是同目录下的 config.json。Skype 应用的关键配置如下配置项值说明nameSkype应用展示名称slugskype应用唯一标识官方注释提示不要修改 slug如确需修改应使用 CLI 的 edit 命令typeskype_conferencing应用类型标识用于关联 Credential 记录variantconferencing应用变体归类为视频会议类categories[conferencing]应用商店分类logoicon.svg图标文件名需存放在static/目录不写路径appData.location.typeintegrations:{SLUG}_video事件类型位置的集成标识{SLUG}会被替换为skypeappData.location.linkTypestatic链接类型为静态 URL用户手动粘贴appData.location.organizerInputPlaceholderhttps://join.skype.com/组织者在表单中输入位置的占位提示appData.location.urlRegExphttps://join\\.skype\\.com/[a-zA-Z0-9]*位置 URL 的正则校验规则这套配置完整继承了 event-type-location-video-static 模板 的结构与 Whereby、Around 等静态链接型视频应用属于同一实现范式不需要 OAuth 授权只要求预约双方提供一个静态的视频会议链接。description字段同时承担双重角色既作为应用商店卡片上的简介CONTRIBUTING.md 建议不超过 10 个单词避免在商店中被截断又在构建期被注入DESCRIPTION.md的正文占位符。六、安装处理器声明式的 AppDeclarativeHandlerSkype 应用无需编写任何 OAuth 回调或授权逻辑其安装入口 api/add.ts 全部由声明式处理器完成import { createDefaultInstallation } from calcom/app-store/_utils/installation; import type { AppDeclarativeHandler } from calcom/types/AppHandler; import appConfig from ../config.json; const handler: AppDeclarativeHandler { appType: appConfig.type, variant: appConfig.variant, slug: appConfig.slug, supportsMultipleInstalls: false, handlerType: add, createCredential: ({ appType, user, slug, teamId }) createDefaultInstallation({ appType, user: user, slug, key: {}, teamId }), }; export default handler;其核心机制在 packages/app-store/_utils/installation.ts 的createDefaultInstallation中实现直接在prisma.credential表中写入一条记录type为skype_conferencing、appId为skype、key为空对象{}因为静态链接应用无需存储任何密钥。supportsMultipleInstalls: false表示同一用户只能安装一次安装时会调用checkInstalled校验并返回 422 Already installed 错误。这正体现了 CONTRIBUTING.md 中所有应用都应使用AppDeclarativeHandler见 types/AppHandler.d.ts的架构约定——对于无认证要求的静态视频应用声明式处理足以覆盖全部安装逻辑。七、从模板到上架DESCRIPTION.md 的完整生命周期综合仓库实现一个DESCRIPTION.md的完整生命周期可以归纳为生成app-store-cli将模板如event-type-location-video-static复制到packages/app-store/slug/并把描述写入占位符core.ts编写按 CONTRIBUTING.md 规范补充items截图清单只写文件名与正文功能描述注册generateAppFiles执行yarn ts-node --transpile-only src/build.ts生成apps.*.generated.ts等元数据文件使应用进入商店注册表构建详情页getStaticProps读取文件完成 frontmatter 解析、{DESCRIPTION}替换与图片路径补全getStaticProps.ts渲染slug-view.tsx与Slider.tsx将描述与截图以轮播形式呈现给用户安装用户点击安装后api/add.ts声明式处理器在数据库中创建 Credential完成接入。八、小结DESCRIPTION.md是 cal.diy 应用商店体系中小而关键的规范文件它以极简的 YAML frontmatter 声明展示素材以{DESCRIPTION}占位符实现描述信息的构建期注入配合config.json的静态链接配置与AppDeclarativeHandler声明式安装构成了一条从脚手架生成、页面渲染到用户安装的完整闭环。对于想要为 cal.diy 贡献新集成应用的开发者而言理解这一文件机制是快速上手的必经之路——它决定了你的应用在商店中如何被展示、如何被描述、以及如何被安装。赞分享后端前端企业应用【免费下载链接】cal.diyScheduling infrastructure for absolutely everyone.项目地址https://gitcode.com/GitHub_Trending/ca/cal.diy点击查看免费下载相关推荐Monobot CX 应用集成解析基于 cal.diy 应用商店的 DESCRIPTION.md 与配置机制详解Monobot CX 应用集成解析基于 cal.diy 应用商店的 DESCRIPTION.md 与配置机制详解 Monobot 是 cal.diyCal.后端前端企业应用Symfony Console Markdown 描述器解析以 input_definition_2 快照为例读懂参数文档生成机制Symfony Console Markdown 描述器解析以 input_definition_2 快照为例读懂参数文档生成机制 本篇文章以 Symfony后端Web框架Cal.diy 怎么配置 Google Calendar 集成OAuth 凭证、重定向 URI 与应用商店Cal.diy 怎么配置 Google Calendar 集成OAuth 凭证、重定向 URI 与应用商店 自托管的 Cal.diy 实例默认不会直接连通 G后端前端企业应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
