插件开发-在活字格中快速开发一个自己的插件
本帖最后由 Grayson.Shang 于 2023-10-8 13:40 编辑低代码给我们的项目开发带来了很大的便利，比如缩短我们的开发的周期，降低开发的成本，为我们应用开发降本增效。当然这也一直是我们公司的目标，赋能开发者。
对于初步接触开发，之前一直使用低代码开发的格友们，深入的了解了活字格的功能之后，相信有一些感觉活字格的基础功能+已有插件已经可以满足大家的日常项目需求了。（若是没有，那可能是你对活字格了解的不够深入;P）
当然活字格不是万能的，也有一些定制化需求和之前使用代码开发的格友们，对于自己熟悉的算法和功能，发现在活字格中找不到，从而导致项目的开发陷入瓶颈，停滞不前，最后选择停用活字格。那么今天的这个帖子，就来帮助大家解决遇到的这类问题。
适用群体：
1. 需要的功能，活字格中暂时没有提供完整的方案，比如某一种算法加密，需要用到代码来实现
2. 对于项目开发中使用的功能，有更好的方案，比如页面上给单元格增加更加个性化更加美观的角标
3. 对于第三方一些功能的集成，想要包装成完整且可用性好的功能，而不想要通过零散请求方式来对接
插件案例：
对象与集合操作 命令、服务端命令
可交互页面容器（IFrame） 单元格
打开方式：
1. 打开Visual Studio，不打开任何项目，然后点击克隆存储库
2. 输入前面的连接，就可以打开了
课程大纲：
1. 获取插件开发的文档
2. 查看文档，生成一个最简单插件（单元格类型插件，前端命令插件，服务端命令插件）
3. 插件开发基础篇
a) 如何完成一个自定义的插件开发
[*]i. 公式类型属性
[*]ii. 支持返回结果（命令、服务端命令）
[*]iii. combo选择框
[*]iv. 属性可见性
[*]v. 子命令（命令、服务端命令）
[*]vi. JS-C#互相传值（单元格、命令）
[*]vii. 引用外部第三方JS文件（单元格、命令）
[*]viii. 动态修改命令名称（命令、服务端命令）
b) 代码调试
c) 修改插件信息，并将插件发布到葡萄城市场
1. 获取插件开发的文档
插件开发有两个文档
a) 我们最容易找到的文档就是，在帮助手册9.0版本中，倒数第二个版块，插件开发，这个是我们官方对外提供的文档，会随时更新
第五十四章 活字格插件开发 - 活字格V9帮助手册 - 葡萄城产品文档中心 (grapecity.com.cn)
b) 还有一个查看文档我们官方提供的一个语雀文档，不需要用户登录，我更喜欢使用这个文档，因为其中的代码更加清晰分明，可以更方便理解，不过当语雀信息是插件开发文档最初的一个版本，因为精力有限，官方主要支持帮助手册的内容更新。所以当语雀文档内容和帮助手册不一致时，以帮助手册的信息为准
快速开始 (yuque.com)
2. 根据文档生成一个简单的插件，这个照着文档就可以快速生成简单的插件了，讲的很详细，我就不做过多赘述了
快速开始 - 活字格V9帮助手册 - 葡萄城产品文档中心 (grapecity.com.cn)
3. 插件开发基础篇
a) 完成一个自定义插件的开发
[*] i. 公式类型属性
创建公式属性
[*]在插件中增加一个公式类型的属性（单元格、命令、服务端命令），在使用中，这一步的操作都是一样的// 这样就可以增加一个公式类型的属性了，具体结果可以参考帮助手册插件开发文档
public object MyFormulaProperty{ get; set; }
[*]支持换行输入（单元格、命令、服务端命令）// 运行用户输入的时候，可以按住Alt+Enter换行输入
public object MyFormulaProperty{ get; set; }
[*]支持输入只能选择一个页面上的单元格（命令）// 前端命令中，可以引用页面上一些单元格的位置，我们可以通过这个属性，让输入只能是页面上某一个单元格，而是不一个复杂的公式，或者一块区域
public object MyFormulaProperty{ get; set; }
使用公式属性
[*]单元格插件和命令插件的公式的计算是一样的// 都是在JS文件中的使用的，通过继承类的evaluateFormula函数来计算公式的值
const result = this.evaluateFormula(formula);
[*]服务端命令的公式计算有些区别，是在C#（也就是CS文件）中计算的// 首先计算公式时，需要函数中传递一个参数（IServerCommandExecuteContext dataContext），需要通过参数的一个函数来执行，而参数的来源就是服务端命令中ExecuteAsync，示例中是直接在服务端命令执行过程中调用的
public async Task<ExecuteResult> ExecuteAsync(IServerCommandExecuteContext dataContext)
{
// 这里await是异步执行，可以不做理解，照这样子使用即可
// 其他地方若是想要调用计算公式的函数，需要将IServerCommandExecuteContext dataContext作为函数的一个参数，在调用的时候将dataContext传入
var propCalcedValue = await dataContext.EvaluateFormulaAsync(this.MyFormulaProperty);
}
[*]有一点需要注意，单元格插件和命令插件的公式执行虽然一样，但是获取属性函数是不一样的// 这个是单元格插件获取属性值
const formula = this.CellElement.CellType.MyFormulaProperty;
// 这个是命令插件获取属性值
const formula = this.CommandParam.MyFormulaProperty;
[*]ii. 支持返回结果（命令、服务端命令）
创建对应属性
命令插件和服务端命令插件创建返回结果的属性是一样的
public string Result { get; set; } = "结果";
给返回结果属性赋值
命令插件和服务端命令插件赋值方式不一样，命令插件的功能都是JS文件中完成，服务端名功能都是CS文件中完成// 命令插件赋值给变量是在JS文件中，通过活字格提供的函数给对应的变量“Result”赋值
Forguncy.CommandHelper.setVariableValue(this.CommandParam.Result, value);
// 服务端命令赋值是在CS文件中，仍然是通过dataContext这个变量给对应的变量命令“Result”赋值
dataContext.Parameters = value;
[*]iii. combo选择框使用
combo选择框属性的使用是比较常见的，但是这个功能的使用没有什么需要特别注意的，可以参考帮助手册
下拉列表 属性 - 活字格V9帮助手册 - 葡萄城产品文档中心 (grapecity.com.cn)
[*]iv. 属性可见性
这个功能使用也比较频繁，但是有些同学找不到，还有一些其他相关的属性设置，具体可以参考帮助手册，我这边就贴一样帮助手册链接
单元格Attribute索引 - 活字格V9帮助手册 - 葡萄城产品文档中心 (grapecity.com.cn)
命令Attribute索引 - 活字格V9帮助手册 - 葡萄城产品文档中心 (grapecity.com.cn)
服务端命令Attribute索引 - 活字格V9帮助手册 - 葡萄城产品文档中心 (grapecity.com.cn)
属性校验
属性校验是我们在定义属性的中一个不可获取的一环，比如必填，数据范围等
属性校验 - 活字格V9帮助手册 - 葡萄城产品文档中心 (grapecity.com.cn)// 标注Required属性，该属性在用户输入中，就是必填的，当然这个属性不限制属性的类型，所有的属性都是可以标注的
public string Name { get; set; }
// 字符串类型的属性，可以通过下面属性定义最大长度和最小长度
public string Name { get; set; }
// 整数或者小数类型的属性，可以通过下面的属性定义可填的返回
public double Money { get; set; }温馨提示：帮助手册中关于属性校验的文档比较少，不过活字格中属性校验引用的是System.ComponentModel.DataAnnotations，大家有需要的话，可以参考相关的文档
C# 特性 System.ComponentModel 命名空间属性方法大全，System.ComponentModel 命名空间的特性 - 痴者工良 - 博客园 (cnblogs.com)
[*]v. 子命令（命令、服务端命令）
这个功能，大家用到的可能性比较少，不过还是有用到的可能，所起到的作用和服务端命令中“条件”和“循环命令”下增加命令是一样的，这里主要告诉应该在哪里查看这个功能的使用，大家需要的话自行了解使用
添加 子命令 - 活字格V9帮助手册 - 葡萄城产品文档中心 (grapecity.com.cn) （命令）
添加 子命令 - 活字格V9帮助手册 - 葡萄城产品文档中心 (grapecity.com.cn) （服务端命令）
[*]vi. JS-C#互相传值（单元格、命令）
了解了这么多功能了，不知道大家是否有这样一个认知，无论是单元格类型的插件，还是命令类型的插件，即使几乎所有的逻辑都是在JavaScript命令中完成的，但是属性的定义，却还都是在CS（C#）中做的。那么，咱们是否清楚，两者之间（Js文件，cs文件）的值互通呢
[*]JS文件获取用户输入的属性值，其实这个功能我们在前面的公式属性获取中有提到，这里就专门说一下，当然不只是公式，其他的所有属性都可以通过这样的方式来获取，只需要将MyProperty改成对应的属性名就可以了// 单元格类型的命令，一般是在onPageLoaded()函数中执行的
onPageLoaded() {
const formula = this.CellElement.CellType.MyProperty;
const result = this.evaluateFormula(formula)
}
// 命令类型的命令，一般是在execute()函数中执行的
execute() {
const formula = this.CommandParam.MyProperty;
const result = this.evaluateFormula(formula);
}
[*]JS文件将计算后的结果返回（命令）// 命令类型的插件，在执行完对应的逻辑之后，会有一个执行结果数据，需要将这个执行结果返回给用户
Forguncy.CommandHelper.setVariableValue(this.CommandParam.Result, res);
[*]vii. 引用外部第三方JS文件（单元格、命令）
在我们开发前端插件时，我们有时也会引用一些外部的JavaScript或者CSS文件，而我们如何在活字格中使用这些文件
快速开始，添加Tinymce单元格插件 - 活字格V9帮助手册 - 葡萄城产品文档中心 (grapecity.com.cn)
1. 将我们需要的JavaScript和CSS文件拷贝到我们插件中Resources目录下
2. 然后在我们PluginConfig.json文件中，引用这个文件就可以正常使用了
这样，我们就可以在我们的单元格JS文件和命令JS文件中使用这些外部引用的文件了
[*]viii. 动态修改命令名称（命令、服务端命令）
我们在日常开发中，有些命令因为对功能的开发有着至关重要的作用，但是单从命令本身阅读起来，又特别的麻烦，而我们只需要一些小小的技巧就可以让我们命令在使用中有着更高的可阅读性，以设置变量命令来举例
以前我们的插件中的ToString是这样的
现在我们只需要做这样的修改就可以让我们的插件名称变成动态的，可以根据我们用户对于某一个属性输入的值来设置不同的名称
b) 代码调试
关于代码的调试，我们一般有时比较简单，我们会采用日志输出的形式，比如前面命令的开发，我们可以采用alert，或者console.log打印日志来检查，不过若是命令比较复杂，或者像服务端命令的插件，并不能很好的查看日志，那么调试就必不可少了
前端代码调试
[*]前端代码调试比较简单，当活字格安装好插件之后，直接在活字格运行应用就可以调试，而调试工具就是浏览器
[*]在活字格页面执行完插件命令之后，在浏览器源代码里，找到Forguncy，下的Plugin对应插件名称下的JS文件，就可以直接打断点调试了
后端代码调试
[*]后端代码调试，比前端代码调试复杂一些，调试的工具是Visual Studio，需要在活字格中将应用Run起来，Run起来之后我们可以看到应用的访问地址：http://localhost:11574/Forguncy，我们需要先记住这个地址
[*]在Visual Studio中操作如下（首先得有对应插件源代码），点击菜单栏的调试，找到附加到进程
[*]点击进去，然后在搜索栏，输入Forguncy，就可以看到和活字格相关的所有进程信息了，然后在命令行一列找到我们前面记录有对应的端口号的URL，然后点击附加，就可以正常调试了
温馨提示：若是点击之后，有看到下面的信息很大的可能是，附加的进程选择错了，再重新按照上面的步骤重复一下操作
c) 修改插件信息，并将插件发布到葡萄城市场
关于插件的发布，我也不做过多的讲解，大家有需要可以参考帮助手册，我这边主要讲解一下，如何更换我们插件的图标（初始的图标确实有些丑）
1. 首先需要下载我们想要的图标，一般我会在这个网站中下载想要的图标iconfont-阿里巴巴矢量图标库，这个网站可以生成对应大小，指定颜色的png，也有海量的资源，我的插件图标基本上都是从这里获取的
2. 和前面提到的JS文件一样，将我们的图标拷贝到Resources目录下
3. 设置资源属性，这一步很关键，很多人说我明明拷贝的图片，并且也修改了对应命令的目录，但是就是不生效，这一步需要将生成操作设置成资源
4. 修改命令的Icon图标成自己的图片名称
相信通过上面的相关学习，你已经了解了活字格的插件开发，其实关于插件开发，我们不需要知道所有的知识，只需要在用的时候，知道在哪里可以找到我们想要的信息，就是本节课想要说的内容了
页:
[1]