/** * Custom Component Creation Guide * 自定义组件创建指南 */ const customComponentGuide = { description: "创建自定义命令组件的完整流程", important: "创建过程中严禁删除、修改任何已有的函数或对象", steps: { "1. Backend Interface": { location: "plugin/lib/quickcomposer/xxx/yyy.js", description: "创建具体功能实现", requirements: { functionDefinition: "使用独立函数而非对象方法", asyncHandling: "使用 async/await 处理异步操作", errorHandling: "合理的错误捕获和提示", paramValidation: "检查必要参数是否存在", }, }, "2. Interface Export": { location: "plugin/lib/quickcomposer/xxx/index.js", description: "导出接口给quickcomposer使用", examples: { singleFunction: "module.exports = { operation }", multipleFunctions: "module.exports = { ...encoder, ...hash }", }, }, "3. Interface Registration": { location: "plugin/lib/quickcomposer.js", description: "将接口注册到quickcomposer对象", format: "quickcomposer.xxx = require('./quickcomposer/xxx')", }, "4. Component Development": { location: "src/components/composer/xxx/YourComponent.vue", basicStructure: { template: "组件模板，使用quasar组件库", script: "组件逻辑，使用Vue3 defineComponent", style: "组件样式，建议使用scoped", }, keyPoints: { props: { modelValue: { description: "必需的属性，包含组件的完整配置", type: "Object", required: true, structure: { value: "组件对应的函数名", code: "生成的代码字符串", argvs: "解析后的参数对象", }, }, }, computed: { argvs: { description: "处理参数的计算属性", implementation: ` return this.modelValue.argvs || this.parseCodeToArgvs(this.modelValue.code) || this.defaultArgvs; `, }, }, data: { defaultArgvs: { description: "定义组件的默认参数结构", example: `{ key: "", modifiers: { control: false, alt: false, shift: false, command: false, } }`, }, }, methods: { generateCode: { description: "生成代码字符串的方法", parameters: "argvs - 当前参数对象", implementation: { simpleCase: ` // 简单参数的情况 const args = [value, ...modifiers]; return \`functionName("\${args.join('","')})\`; `, objectCase: ` // 对象参数的情况 const formattedConfig = stringifyArgv(config); return \`functionName(\${formattedConfig})\`; `, }, }, parseCodeToArgvs: { description: "解析代码字符串为参数对象，严禁使用eval", parameters: "code - 要解析的代码字符串", implementation: { steps: [ "1. 检查代码是否存在", "2. 定义需要使用variable格式的路径", "3. 使用parseFunction解析代码", "4. 处理解析结果并返回参数对象", ], example: ` // 定义需要使用variable格式的路径 const variableFormatPaths = [ 'arg0', // url参数 'arg*.headers.**', // 所有headers字段 '!arg*.headers.Content-Type' // 排除Content-Type ]; // 解析代码 const result = parseFunction(code, { variableFormatPaths }); if (!result) return this.defaultArgvs; // 处理解析结果 const [url, config] = result.argvs; // 返回处理后的参数对象 return { ...this.defaultArgvs, url, ...config }; `, }, }, getSummary: { description: "生成命令的简短描述，用于在命令列表中显示", parameters: "argvs - 当前参数对象", implementation: { simpleCase: ` // 返回操作类型的标签 return this.operations.find(op => op.value === argvs.operation).label; `, complexCase: ` // 返回关键参数的值 return argvs.command.value; `, }, notes: [ "返回值应该简洁明了，帮助用户快速识别命令的功能", "对于复杂命令，应该返回最关键的参数信息", "返回的文本长度应该适中，避免过长", ], }, updateModelValue: { description: "更新组件的值并触发更新事件", parameters: "argvs - 当前参数对象", implementation: ` this.$emit("update:modelValue", { ...this.modelValue, summary: this.getSummary(argvs), code: this.generateCode(argvs), argvs, }); `, notes: [ "必须保留原有的 modelValue 属性", "必须包含 summary、code 和 argvs 三个字段", "summary 用于在命令列表中显示", "code 是生成的代码字符串", "argvs 是当前的参数对象", ], usage: [ "在 mounted 钩子中初始化组件值", "在 argvs setter 中更新组件值", "在任何需要更新组件值的地方调用", ], }, }, mounted: { description: "组件初始化时的处理", implementation: ` // 如果没有 argvs 和 code，使用默认值初始化 if (!this.modelValue.argvs && !this.modelValue.code) { this.$emit("update:modelValue", { ...this.modelValue, argvs: this.defaultArgvs, code: this.generateCode(this.defaultArgvs) }); } `, }, stringHandling: { stringifyArgv: { description: "将对象转换为代码字符串", usage: "用于生成包含对象参数的代码", example: "将 {key: 'value'} 转换为 '{key:\"value\"}'", }, parseFunction: { description: "解析函数调用代码为对象", usage: "用于解析函数调用代码，支持变量格式的路径匹配", parameters: { functionStr: "要解析的函数调用代码字符串", options: { variableFormatPaths: "需要使用variable格式的路径模式数组", }, }, pathPatterns: { paramPosition: { description: "参数位置匹配", examples: [ "arg0 - 第一个参数", "arg1 - 第二个参数", "arg* - 任意参数", ], }, objectProps: { description: "对象属性匹配", examples: [ "arg0.headers - 精确匹配", "arg1.data.* - 直接子属性", "arg2.params.** - 所有嵌套属性", ], }, wildcards: { description: "通配符使用", examples: [ "* - 单层匹配", "** - 多层匹配", "Accept* - 前缀匹配", ], }, exclusions: { description: "排除规则", examples: [ "!arg*.headers.Content-Type", "!arg*.headers.Cookie", ], }, }, example: ` const result = parseFunction( 'axios(url, { headers: { "User-Agent": ua } })', { variableFormatPaths: [ 'arg0', 'arg*.headers.**', '!arg*.headers.Content-Type' ] } ); `, returns: { functionName: "函数名称", args: "解析后的参数数组，根据路径规则处理变量格式", }, }, parseToHasType: { description: "将字符串解析为带类型的值", usage: "用于解析 VariableInput 类型的值", example: "将 '\"text\"' 解析为 newVarInputVal('str', 'text')", }, }, }, }, "5. Component Registration": { location: "src/js/composer/cardComponents.js", description: "使用defineAsyncComponent注册组件", format: "export const YourComponent = defineAsyncComponent(() => import('path/to/component'))", }, "6. Command Configuration": { location: "src/js/composer/commands/xxxCommands.js", requiredFields: { value: "quickcomposer.xxx.yyy", label: "显示名称", component: "组件名称", }, optionalFields: { desc: "命令描述", isAsync: "是否异步命令", isControlFlow: "是否控制流命令", }, }, }, notes: { variableHandling: { description: "VariableInput 值的处理方式取决于参数类型", cases: { objectCase: "当值在对象中时，使用 formatJsonVariables 处理，如 AxiosConfigEditor", simpleCase: "当值是直接参数时，直接使用值本身，如 MultiParams", }, tips: "formatJsonVariables 主要用于处理对象中的变量，避免对简单参数使用，以免产生不必要的引号", }, commonComponents: { description: "常用组件的使用说明", components: { VariableInput: { description: "变量输入组件", usage: "用于输入可能包含变量的字符串", props: [ "model-value - 输入值，需要包含 value、isString、__varInputVal__ 属性, 通过 varInputValManager 的 newVarInputVal 创建", "label - 输入框标签", "icon - 输入框图标", ], }, DictEditor: { description: "键值对编辑组件", usage: "用于编辑对象类型的配置，如 headers、env 等", features: [ "自带添加/删除按钮", "支持键值对编辑", "值部分默认使用 VariableInput", "支持下拉选项（通过 options.items 配置）", ], notes: [ "初始值应该是一个对象，如 {}", "支持通过 options 属性配置下拉选项", ], }, NumberInput: { description: "数字输入组件", usage: "用于输入数字类型的配置", props: [ "model-value - 数字值", "label - 输入框标签", "icon - 输入框图标", ], }, }, }, dataFlow: { description: "数据流转说明", patterns: { modelValue: { description: "组件数据结构", structure: { value: "函数名，来自命令配置", code: "生成的代码字符串", argvs: "解析后的参数对象", }, }, updateFlow: { description: "数据更新流程", steps: [ "1. 用户输入触发 update:model-value 事件", "2. 组件内部更新 argvs", "3. argvs 更新触发 generateCode", "4. 发送完整的 modelValue 给父组件", ], }, }, }, bestPractices: { description: "最佳实践", tips: [ "使用现有组件而不是重新开发", "参考 axios 等成熟组件的实现", "保持数据流的清晰和一致", "合理使用计算属性和方法", "避免直接修改 props", "正确处理默认值", ], }, commonPitfalls: { description: "自定义组件开发中的常见错误和最佳实践", componentRegistration: { description: "组件注册相关注意事项", tips: [ "组件名使用 PascalCase 命名，如 SystemCommandEditor", "在 cardComponents.js 中注册时使用字符串形式，如 component: 'SystemCommandEditor'", "不要在配置文件中导入组件", "不要在配置文件中定义 defaultArgvs，这应该只在组件内部定义", ], }, codeGeneration: { description: "代码生成相关注意事项", tips: [ "使用 modelValue.value 获取函数名，避免硬编码", "在 generateCode 中正确处理默认值的移除", "正确定义 variableFormatPaths 以处理变量格式", ], }, dataManagement: { description: "数据管理相关注意事项", tips: [ "使用 updateArgvs(key, value) 方法显式更新数据", "在模板中使用 :model-value 和 @update:model-value 而不是 v-model", "在 emit 时不需要提交 value 字段，因为这在 command 配置里已定义", "使用 getter/setter 形式的 argvs 计算属性", "在 mounted 和 updateArgvs 中保留原始字段 ...this.modelValue", "处理嵌套对象更新时需要正确处理路径，如 'options.encoding' 需要分别更新 options 对象", "更新嵌套对象时要保持对象的响应性，使用解构运算符复制对象", ], }, performance: { description: "性能优化相关注意事项", tips: [ "避免使用过多的 watch 属性，容易造成性能问题", "使用 computed 代替复杂的 watch", "减少不必要的数据更新和重渲染", "保持简单的 getter/setter 模式，避免复杂的嵌套对象更新", ], }, componentStructure: { description: "组件结构相关注意事项", tips: [ "使用 data() 而不是 setup 来定义组件数据", "在配置文件中的 value 应该包含完整路径，如 quickcomposer.system.exec", "组件内部保持简单清晰的结构，避免过度复杂的逻辑", ], }, }, }, examples: { simpleComponent: "RegexEditor - 单一功能的组件", complexComponent: "AxiosConfigEditor - 多功能、多配置的组件", controlComponent: "ConditionalJudgment - 流程控制组件", }, };