ARTICLE DETAIL

资讯详情

深耕网站建设、视觉设计与SEO优化的一线实战洞察。

GrapesJS 插件工程化:从 grapesjs-cli 脚手架模板 README 看插件的开发、使用与发布全流程

GrapesJS 插件工程化:从 grapesjs-cli 脚手架模板 README 看插件的开发、使用与发布全流程 GrapesJS 插件工程化从 grapesjs-cli 脚手架模板 README 看插件的开发、使用与发布全流程【免费下载链接】grapesjsFree and Open source Web Builder Framework. Next generation tool for building templates without coding项目地址: https://gitcode.com/GitHub_Trending/gr/grapesjs导读在 GrapesJS 生态中插件Plugin是扩展编辑器的标准方式而grapesjs-cli脚手架会在初始化时为你生成一份结构完整、可直接填写的插件 README 模板即本文剖析的packages/cli/src/template/README.md。本文以该模板为骨架逐段讲解在线 Demo、Summary、Options、Download、Usage、Development 等章节的撰写方法与背后的代码机制并联动 init.ts、模板插件源码 等仓库实现帮助你从零产出一个可直接发布到 NPM 的生产级 GrapesJS 插件。一、模板 README 在插件脚手架中的定位1.1 它是什么、从哪里来grapesjs-cli的init命令会在当前目录生成一个可运行的插件工程其中就包含一份 README。这份 README 并不是普通的静态文档而是一份Lodash 模板文件位于 packages/cli/src/template/README.md其中的% name %、% rName %、% user %等占位符会在脚手架执行时被替换为真实项目信息。从 init.ts 可以看到模板的读取方式const getTemplateFileContent (pth: string) { const pt path.resolve(__dirname, ${tmpPath}/${pth}); return fs.readFileSync(pt, utf8); };随后在createSourceFiles中模板内容通过lodash.template渲染后写入当前工作目录的README.mdinit.ts// Write README.md fs.writeFileSync(rdmDst, template(rdmSrc)(opts));1.2 三个核心占位符占位符含义来源% name %插件的展示名称如 Grapesjs My Plugin由目录名自动转换而来init交互提问或--name参数% rName %仓库名同时用作 NPM 包名与注册到编辑器时的插件名init交互提问或--rName参数% user %仓库所属用户名GitHub/Bitbucket 等init交互提问或--user参数其中name的自动生成逻辑见 init.ts将目录名中的下划线替换为连字符按-分词后把每个词首字母大写并用空格连接。例如目录grapesjs-my-plugin会生成Grapesjs My Plugin。1.3 脚手架还生成了哪些文件除了 READMEinit任务init.ts还会按需生成src/index.js—— 插件入口文件必生成模板见 src/index.jssrc/components.js—— 自定义组件类型选择components时生成src/blocks.js—— 自定义块选择blocks时生成src/locale/en.js—— i18n 翻译结构选择i18n时生成package.json、tsconfig.json、.gitignore、.npmignore、_index.html、LICENSE等也就是说写好 README 各章节的过程就是明确插件对外契约的过程——下面按模板章节顺序逐一展开。二、Live Demo为插件创建在线可玩示例模板 README 的第一部分建议在 README 顶部放置一个Live Demo链接让潜在用户无需安装即可体验插件效果。模板原文的建议是使用 JSFiddle、CodeSandbox 或 CodePen 等在线工具创建一个简单示例把 Demo 链接放进 README并附上截图或 GIF 作为加分项。为了降低操作成本模板已经准备好了一份可直接复制到上述工具中的 HTML、CSS、JavaScript 代码演示完成后删除本节、并将顶部链接替换为你的 Demo 地址即可。HTMLlink hrefhttps://unpkg.com/grapesjs/dist/css/grapes.min.css relstylesheet / script srchttps://unpkg.com/grapesjs/script script srchttps://unpkg.com/% rName %/script div idgjs/div三点值得注意依次加载 GrapesJS 样式、GrapesJS 核心库、你的插件 UMD 包% rName %会被替换为真实插件名div idgjs是编辑器挂载容器container配置与之对应依赖 unpkg CDN 分发意味着发布前必须保证插件包已成功构建并上传 NPM。JSconst editor grapesjs.init({ container: #gjs, height: 100%, fromElement: true, storageManager: false, plugins: [% rName %], });各配置项含义配置项作用container编辑器挂载的选择器对应 HTML 中的#gjsheight编辑器可视高度Demo 中取100%铺满视口fromElement是否从容器内已有 DOM 解析组件结构便于预置初始内容storageManager设为false关闭本地存储避免 Demo 环境出现存储副作用plugins以字符串数组形式声明要加载的插件字符串即rNameCSSbody, html { margin: 0; height: 100%; }这段 CSS 用于去掉浏览器默认边距并撑满视口保证编辑器在 Demo 容器中全屏呈现不出现滚动条错位。三、Summary向用户展示插件能力清单Demo 之后是插件的“能力摘要”采用嵌套列表呈现Plugin name:% rName %Componentscomponent-id-1component-id-2...Blocksblock-id-1block-id-2...撰写时应把插件通过DomComponents.addType注册的自定义组件类型 id、通过BlockManager.add注册的块 id逐一列出。这既是用户快速判断“这个插件能不能满足我需求”的入口也是插件可发现性SEO/搜索的重要载体建议使用插件名做前缀如my-plugin-*避免与其他插件冲突。四、Options插件配置项速查表模板预留了一张 Markdown 表格作为配置项文档骨架OptionDescriptionDefaultoption1Description optiondefault value插件作者需要将占位符替换为真实配置项并标注默认值。这张表与插件入口的选项合并逻辑一一对应——模板入口 src/index.js 中的做法是export default (editor, opts {}) { const options { ...{ // default options }, ...opts }; // ... };即“内置默认值 用户传入选项”的浅合并策略用户通过pluginsOpts传入的配置会覆盖默认值。因此 Options 表格中的 Default 列应当与src/index.js中默认值对象保持一致避免文档与实现脱节。若开启了 i18n模板还会额外暴露i18n: {}选项用于让用户覆盖插件自带的翻译消息见下文第八节。五、Download三种安装方式模板为发布准备了三种获取渠道分别面向不同使用场景CDN浏览器直引UMD 包https://unpkg.com/% rName %NPM模块化安装npm i % rName %GIT源码开发git clone https://github.com/% user %/% rName %.git三个地址均由脚手架占位符自动渲染无需手动维护仓库地址。其中 NPM 渠道要求包名与rName一致——这一点由 模板 package.json 的name: % rName %保证同时main字段指向构建产物dist/index.js。六、Usage两种使用方式详解模板给出了插件被消费的两种典型场景这是 README 中最需要“可复制可运行”的部分。6.1 直接在浏览器中使用script 标签link hrefhttps://unpkg.com/grapesjs/dist/css/grapes.min.css relstylesheet / script srchttps://unpkg.com/grapesjs/script script srcpath/to/% rName %.min.js/script div idgjs/div script typetext/javascript var editor grapesjs.init({ container: #gjs, // ... plugins: [% rName %], pluginsOpts: { % rName %: { /* options */ }, }, }); /script要点通过 CDN 引入% rName %.min.js后插件自动注册到全局grapesjs命名空间plugins数组里填插件名字符串即可加载插件专属配置统一放在pluginsOpts下以插件名为 key 的对象中编辑器会将其作为opts传入插件工厂函数。6.2 现代 JavaScript模块化引入import grapesjs from grapesjs; import plugin from % rName %; import grapesjs/dist/css/grapes.min.css; const editor grapesjs.init({ container : #gjs, // ... plugins: [plugin], pluginsOpts: { [plugin]: { /* options */ } } // or plugins: [ editor plugin(editor, { /* options */ }), ], });两种写法等价plugins: [plugin]pluginsOpts是声明式写法与 CDN 场景语义一致plugins: [editor plugin(editor, { /* options */ })]是命令式写法直接在数组里调用插件工厂函数并传入配置适合需要按条件动态传参的场景。无论哪种写法插件工厂函数签名都是(editor, opts {}) {...}见 src/index.js这正是模板入口导出的默认函数形态。七、Development本地开发与构建流程模板为插件开发者提供了从克隆到构建的完整命令序列$ git clone https://github.com/% user %/% rName %.git $ cd % rName %npm inpm startnpm run build其中npm start与npm run build由 模板 package.json 的 scripts 映射到grapesjs-cliscripts: { start: grapesjs-cli serve, build: grapesjs-cli build, bump: npm version patch -m Bump v%s }serve启动webpack-dev-server开发服务器默认地址http://localhost:8080浏览器打开后即可在真实编辑器中调试插件cli README需要换端口时用grapesjs-cli serve -p 8081需要透传 devServer 配置时可用 JSON 参数例如grapesjs-cli serve --devServer{https: true}build生成生产环境的压缩产物dist/发布 NPM 前必须执行bump以 patch 级别递增版本号并自动提交Bump v%s提交信息方便按语义化版本管理发布节奏。7.1 定制构建webpack.config.js如果默认打包配置无法满足需求grapesjs-cli支持在项目根目录创建webpack.config.js导出一个接收默认config并返回新配置的函数详见 cli README 的 Customization 章节// YOUR-PROJECT-DIR/webpack.config.js // config is the default configuration export default ({ config }) { // This is how you can distinguish the build command from the serve const isBuild config.mode production; return { ...config, module: { rules: [ { /* extra rule */ }, ...config.module.rules, ], }, }; };可通过config.mode production区分build与serve两种运行模式从而在开发与生产环境应用不同的 loader 规则。7.2 脚手架生成的工程约束脚手架还会生成 tsconfig.jsonES5 目标、开启严格模式、include: [src]以及.gitignore忽略node_modules、dist、_index.html、日志等与.npmignore发布时排除源码与配置文件。init命令支持-y跳过全部交互提问或通过--user、--name、--rName、--components、--blocks、--i18n、--license等参数直接指定见 cli README 与 init.ts 的 InitOptions 定义。八、从模板到实现脚手架生成的插件源码骨架README 中的各章节承诺最终要由src/下的真实代码兑现。理解这几份模板源码能让 README 的填写更有依据。8.1 插件入口src/index.jsexport default (editor, opts {}) { const options { ...{ // default options }, ...opts }; // Add components loadComponents(editor, options); // Add blocks loadBlocks(editor, options); // Load i18n files editor.I18n editor.I18n.addMessages({ en, ...options.i18n, }); // TODO Remove editor.on(load, () editor.addComponents( div stylemargin:100px; padding:25px; Content loaded from the plugin /div, { at: 0 } )) };完整的条件编译版本见 模板 index.js其中components/blocks/i18n的 import 与调用会按脚手架提问结果决定是否保留。结构要点工厂函数签名(editor, opts {})与 README Usage 章节的两种调用方式严格对应loadComponents/loadBlocks分别把组件与块的注册逻辑拆分到独立文件职责清晰i18n 分支通过editor.I18n.addMessages合并默认翻译en与用户自定义options.i18neditor.on(load, ...)这段是脚手架预置的演示代码在编辑器顶部注入一段示例内容README 发布前应将其删除正如模板注释// TODO Remove所示。8.2 自定义组件类型src/components.jsexport default (editor, opts {}) { const domc editor.DomComponents; domc.addType(MY-COMPONENT, { model: { defaults: { // Default props }, }, view: {}, }); };通过DomComponents.addType注册新组件类型model.defaults声明默认属性对应 README Summary 中列出的 Components id。完整的组件扩展通常还包括可编辑 trait、样式属性等可参考仓库中 dom_components 模块 的既有类型实现。8.3 自定义块src/blocks.jsexport default (editor, opts {}) { const bm editor.BlockManager; bm.add(MY-BLOCK, { label: My block, content: { type: MY-COMPONENT }, // media: svg.../svg, }); };通过BlockManager.add注册块label是块在侧边栏的显示名content指定插入到画布的内容——这里直接引用上一节注册的MY-COMPONENT类型形成“块 → 组件”的联动media可提供块预览图SVG 等被注释掉时使用默认占位。8.4 i18n 结构src/locale/en.js启用 i18n 后脚手架会在src/locale/下生成默认语言文件入口文件通过I18n.addMessages加载。这与 核心 i18n 模块 的消息合并机制一致用户可用options.i18n覆盖默认文案实现插件多语言。九、发布前检查清单综合模板与脚手架实现发布前应完成以下事项删除演示代码移除 src/index.js 中TODO Remove标注的editor.on(load, ...)示例注入完善 README用真实 Demo 链接替换顶部占位在 Live Demo 节删除模板示例代码、在 Summary 节列出真实 Components/Blocks id、在 Options 节用真实配置项含默认值替换option1占位行验证构建执行npm run build确认dist/产物正常生成对应main: dist/index.js版本与许可用npm run bump维护版本号模板默认声明MIT许可证init.ts 默认license: MITinit会依据 SPDX 列表生成对应 LICENSE 文件并在 README 末尾标注。完成上述步骤后一个「README 说明完整、源码可运行、构建可发布」的 GrapesJS 插件就准备就绪了。这份模板 README 既是面向用户的说明书也是插件工程的验收清单——两者通过 init.ts 的模板渲染机制天然绑定从工程化层面保证了文档与实现的同步更新。【免费下载链接】grapesjsFree and Open source Web Builder Framework. Next generation tool for building templates without coding项目地址: https://gitcode.com/GitHub_Trending/gr/grapesjs创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表