Marketch 插件版本演进全解读:从 CHANGELOG 看功能迭代、图层命名约定与 Sketch 兼容性策略
Marketch 插件版本演进全解读:从 CHANGELOG 看功能迭代、图层命名约定与 Sketch 兼容性策略
本文以 Marketch 仓库根目录的 CHANGELOG.md 为骨架,逐条还原 v1.0.0 至 v1.0.24 各版本的功能新增、缺陷修复与兼容性决策,并结合 export.cocoascript、util.cocoascript 等源码给出底层实现证据。读完你将掌握该插件的两条"魔法命名前缀"(svg、-)、Symbol 与切片导出机制、Sketch 版本适配的演进脉络,以及 v1.0.24 中针对 Sketch v52 API 变更的变通方案与已知限制,能够据此正确使用插件并理解导出行为背后的代码依据。
一、为什么读 CHANGELOG:Marketch 的能力演进脉络
Marketch 是一个 Sketch 3 插件,核心能力是从 Sketch 文件自动生成一个可直接在浏览器打开的 HTML 预览页,在该页面中可以直接测量任意图层的尺寸与间距,并复制其 CSS 样式(见 README.md)。插件本体由四个 cocoascript 脚本与一个预览页组成:
- manifest.json:注册两条命令——
Export as zipFile(快捷键command shift m,入口 zip.cocoascript)与Get New Version(入口 checkupdate.cocoascript); - export.cocoascript:负责从 Sketch 文档中采集画板、图层数据并导出图片;
- util.cocoascript:提供图层数据序列化、CSS 过滤、多语言、打包等工具函数;
- index.html:预览页面,实现测量标尺、间距标注、切片展示与图层导出交互。
CHANGELOG 正是理解这套插件"今天长什么样、为什么长这样"的入口:版本号背后是功能主线的不断叠加(切片、多圆角 CSS、SVG 导出、Symbol 导出),也是与 Sketch 自身 API 变更长期博弈的实录(从 Sketch 3.4 一路适配到 v52、macOS 10.13)。
二、版本时间线总览
将 CHANGELOG.md 全部条目按时间倒序整理如下,后续章节将逐条展开:
| 版本 | 类型 | 核心内容 |
|---|---|---|
| v1.0.24 | fix | 通过移除 sharedObject 查询绕过 Sketch v52 API 破坏性变更;导出功能恢复;右侧面板不再显示文本/形状的共享样式信息,长期方案仍在探索 |
| v1.0.23 | fix | 支持 Sketch 46.2 与 macOS 10.13 |
| v1.0.22 | fix | 修复多行文字只显示第一行的问题 |
| v1.0.21 | fix | 支持 Sketch 4.1 |
| v1.0.21 | update | Symbol 导出可用 |
| v1.0.19 | update | 支持 Sketch 3.7+ |
| v1.0.18 | update | 新界面 |
| v1.0.13 | update | 支持 Sketch 3.5 |
| v1.0.10 | new | 图层名以 svg 为前缀时,导出为 SVG 文件 |
| v1.0.6 | update | 支持 Sketch 3.4.4 |
| v1.0.5 | new | 页面名/画板名以 - 为前缀时跳过导出;\- 转义为字面 -,\\ 转义为字面 \ |
| v1.0.4 | update | 支持 Sketch beta 3.4 |
| v1.0.0 | add | 支持导出 slice;CSS 支持多圆角;导出 CSS 属性与 Sketch 保持一致;修复画板截图异常 |
可以看出,v1.0.0 确立了插件的基础能力框架,v1.0.4~v1.0.23 的主体工作是 Sketch 版本适配,v1.0.5 与 v1.0.10 则沉淀为影响设计稿命名规范的两条约定——这正是本文要重点展开的部分。
三、命名约定:两条影响导出行为的"魔法前缀"
3.1 svg 前缀:让图层以 SVG 格式导出(v1.0.10)
CHANGELOG v1.0.10 记录:图层名以 svg 为前缀时,Marketch 会额外将该图层导出为 SVG 文件。在 export.cocoascript 的 exportLayerAsImage 中可以看到完整实现:每个非画板图层默认导出 @0.5x、@1x、@2x、@3x 四张 PNG,随后判断图层名是否匹配 /^svg/i:
if(/^svg/i.test(layer.name())){
slice = [[MSExportRequest exportRequestsFromExportableLayer:layer] firstObject];
slice.format = 'svg';
// 图层名以"svg"开头时,作为svg导出
[doc saveArtboardOrSlice:slice toFile:exportName +'.svg'];
}
匹配成功后会将导出格式切换为 svg 并额外输出一份 .svg 文件。同时在预览页 index.html 中,右侧面板的图层导出区块会根据图层名决定格式下拉框内容:
var formatType = '<option value="png">png</option>';
if(/^svg/.test(layerData.name)){
formatType += '<option value="svg">svg</option>'
}
即:普通图层导出面板只有 png 选项,svg 前缀图层则额外提供 svg 格式,且选择 svg 后尺寸下拉框会被禁用(SVG 为矢量格式,无倍率概念)。这条约定让设计稿中"需要矢量交付"的图标类图层可以通过命名直接指定导出格式,无需额外手工处理。
3.2 - 前缀:让页面/画板跳过导出(v1.0.5)
CHANGELOG v1.0.5 记录:页面名或画板名以 - 为前缀时,将不会被导出。在 export.cocoascript 中,"导出全部画板"分支对页面与画板分别执行了同样的正则过滤:
// 不导出以"-"开头的页面
if(!/^-{1}[^-]*?.*$/.test(loopVar.name())){
var artloops = loopVar.artboards().objectEnumerator();
while(artboard = artloops.nextObject()){
if(artboard.className() == 'MSArtboardGroup' && !/^-{1}[^-]*?.*$/.test(artboard.name())){
this.allArtboards.addObject(artboard);
}
}
}
正则 ^-{1}<a href="https://link.gitcode.com/i/5caddf50fc5d87d2acb09ff7055b404d" target="_blank">^-]*?.*$ 的含义是:以单个 - 开头、其后为任意字符的页面/画板名,命中即跳过。预览页 [index.html 的左侧页面/画板列表构建逻辑(buildList)也使用同一正则过滤,保证"跳过"在预览页同样生效。
需要注意一个例外:Symbol Master(MSSymbolMaster)在 export.cocoascript 中会无条件收集进待处理画板列表(注释明确写着"不导出前缀为 - 且不为 symbol 的图层"),这与 v1.0.21 加入的 Symbol 导出能力有关(见 4.3 节)。
3.3 转义规则:\- 与 \\
如果确实希望页面/画板名以字面 - 开头,CHANGELOG 给出的写法是 \-。对应实现位于 util.cocoascript 的 toJSString:当配置 escapeLine 为 true 时,会先把 \- 还原为 -,再做 URI 编码:
if(config && config.escapeLine){
str = str.replace(/\\-/g, '-');
}
if(config && config.encode){
str = encodeURIComponent(str);
}
escapeLine: true 仅用于页面名与画板名的序列化(export.cocoascript 与 util.cocoascript 中 config.type == 'artboard' 的分支)。这样在 Sketch 中命名为 \-首页 的页面,导出阶段原始名以反斜杠开头不会命中排除正则,而进入预览数据后会被还原为 -首页 显示。同理,CHANGELOG 还约定了用 \\ 表示一个真正的反斜杠。
四、核心功能演进:从 v1.0.0 到 v1.0.21
4.1 v1.0.0:切片导出、多圆角 CSS 与导出一致性
v1.0.0 一次性确立了三个基础能力,全部可以在当前源码中找到对应实现:
切片(slice)导出。 export.cocoascript 中 MSSliceLayer 分支会把切片数据写入 artboardData.slice,并在画板目录下创建 slice 子目录导出图片。预览页 index.html 顶部提供"显示切片"开关,开启后切片以虚线框呈现,并可通过 @1x、@2x 链接拖拽保存(index.html)。
CSS 多圆角支持。 util.cocoascript 在处理形状图层时,会把 CSS 中的 border-radius 单独提取出来供设计查看,并将多值圆角转换为更紧凑的展示格式:
if(layerData.style['border-radius']){
layerData.radius = layerData.style['border-radius'];
if(layerData.radius.split('px').length > 2){
layerData.radius = layerData.radius.replace(/px\s?/gi, '/');
}else{
layerData.radius = layerData.radius.replace('px', '');
}
}
即 10px 20px 30px 40px 会显示为 10/20/30/40;另外对于长宽误差 2px 以内的正圆(MSOvalShape),会自动补充 border-radius: 100%(util.cocoascript)。
导出 CSS 与 Sketch 保持一致。 filterSketchCss(util.cocoascript)负责清洗 Sketch 系统生成的 CSS:过滤 border: 0px 之类的无效参数、统一属性值小写(font-family 除外)。同时 getLayerData 会对带边框的形状/位图按边框位置(center/inside/outside)补偿坐标与尺寸,使导出的 CSS 与 Sketch 中的视觉效果一致(util.cocoascript)。
4.2 v1.0.18:新界面
v1.0.18 的"新界面"即当前 index.html 的三栏布局:左侧为页面/画板导航列表,中间为画布(选中图层显示尺寸标注 sketch-marker 与虚线灯塔 lighthouse,悬停另一图层时显示间距标尺 skm-r-*),右侧为属性面板(位置尺寸、边框、填充色、圆角、图层内容、字号、CSS 代码、共享样式与导出入口)。界面还内置了单位换算下拉框(index.html),支持 Standard(px)、pt 系列(@1x/@2x/@3x)与 dp 系列(LDPI 0.75x 至 XXXHDPI 4x),换算逻辑见 getScale(index.html):
var scales = {
px: pixelNum + 'px',
pt: pixelNum * 0.75 / this.unit.factor + 'pt',
dp: pixelNum / this.unit.factor + 'dp'
}
4.3 v1.0.21:Symbol 导出
v1.0.21 让 Symbol 进入导出范围。源码中 Symbol 支持体现在三个层面:
- Symbol Master 采集:
run阶段会遍历所有页面,将MSSymbolMaster无条件加入待处理画板列表(export.cocoascript); - Symbol 标识:画板为
MSSymbolMaster时记录symbolId(util.cocoascript),MSSymbolInstance实例同样记录symbolId并导出图片(export.cocoascript); - 预览页渲染:
buildSymbolArtboard(index.html)根据symbolId在symbols映射中取出 Symbol Master 的图层数据,将其子图层按相对坐标递归渲染到实例位置;右侧面板也会展示 Symbol 缩略图,双击可跳转到对应画板(index.html)。
五、Sketch 与 macOS 兼容性演进
5.1 版本支持时间线
从 CHANGELOG 可以梳理出 Marketch 的适配轨迹:v1.0.4 支持 Sketch beta 3.4 → v1.0.6 支持 3.4.4 → v1.0.13 支持 3.5 → v1.0.19 支持 3.7+ → v1.0.21 支持 4.1 → v1.0.23 支持 Sketch 46.2 与 macOS 10.13 → v1.0.24 应对 Sketch v52 的 API 破坏性变更。这条时间线说明:Sketch 插件必须持续跟随宿主应用的 API 演进,兼容性修复在 CHANGELOG 中占据了近半篇幅。
5.2 Sketch 41 API 变更的适配
export.cocoascript 与 util.cocoascript 中留下了多处针对 Sketch 41 的适配注释,是"跟随 API 变更"的直观证据:
var layerFrame = layer.frame(); //Sketch 41 Fix: frameInArtboard() = > frame()
var layerSize = theLayer.frame().size; //Sketch 41 Fix: frameInArtboard() = > frame()
x: Math.ceil(layer.absoluteRect().x()), //Sketch 41 Fix: origin.x = > absoluteRect().x()
即:从 Sketch 41 起,frameInArtboard() 被替换为 frame(),origin.x/y 被替换为 absoluteRect().x()/y(),代码中以注释形式保留了替换痕迹,方便后续版本对照。
5.3 v1.0.24:Sketch v52 sharedObject 变通方案与已知限制
v1.0.24 是 CHANGELOG 中最新的修复条目,背景是 Sketch v52 对 sharedObject 相关 API 做了破坏性变更。官方变更说明为:通过移除 sharedObject 查询作为变通方案,导出功能得以恢复;代价是此版本中文本与形状的共享样式(shared style)信息不再显示在右侧面板,长期修复方案仍在探索中。
这条变更与源码完全对应。在 util.cocoascript 的 getLayerData 中,文本与形状分支仍会正常采集图层数据,但 sharedObjectId 被初始化为 null 且全程不再赋值,导致后续 if(sharedObjectId != null) 分支(shared style 名称查询)成为死代码:
var sharedObjectId = null; // v1.0.24 移除 sharedObject lookup 后不再赋值
// ...
if(sharedObjectId != null){
sharedStyle = util.getSharedStyleFromID(sharedObjectId, 'text');
// ...
}
对应预览页 index.html 中,共享样式信息块仅在 layerData.sharedStyle != '' 时才渲染,因此面板不再出现"文字样式/图层样式"条目。需要澄清的是:这里的"不显示"仅指共享样式信息,文本与形状图层本身的测量、CSS 导出与图片导出功能不受影响(MSTextLayer、MSShapeGroup 分支依然完整,见 export.cocoascript)。getSharedStyleFromID 函数仍保留在工具库中(util.cocoascript),只是当前版本不再调用,为后续长期方案预留了位置。
六、问题修复记录
6.1 画板截图异常(v1.0.0)
v1.0.0 修复了画板截图异常。对应实现见 exportLayerAsImage 的画板分支(export.cocoascript):画板按 1x 或 2x(勾选"画板导出2倍大小"时)导出 artboard.png,作为预览页画布背景图(index.html 中 background: 'url(.../artboard.png)')。
6.2 多行文本只显示第一行(v1.0.22)
v1.0.22 修复了多行文本只显示第一行的问题。文本内容在序列化时经 toJSString(layer.stringValue(), {encode: true}) 处理(util.cocoascript),encodeURIComponent 会把换行符编码为 %0A,预览页通过 decode 还原后在面板"图层内容"区块展示(index.html)。该修复保证了多行文本的换行信息在 Sketch → 数据 → 预览页的链路中不被截断。
6.3 macOS 10.13 与 Sketch 46.2(v1.0.23)
v1.0.23 的适配没有在源码中留下明显的分支注释(从当前代码看,版本相关判断仅剩 util.cocoascript 中 getFontWeight 对 Sketch 3.3 及以下的旧版字体加粗兼容分支),因此这条更多属于发布层面的兼容性声明,代表该版本在当时最新的 Sketch 46.2 与 macOS 10.13 环境下完成了回归验证。
七、从源码验证:一条完整的导出流水线
结合 zip.cocoascript 与 export.cocoascript,Marketch 的"Export as zipFile"(快捷键 command shift m)完整流程如下:
- 导出选项:
getExportConfig弹出COSAlertWindow,提供画板范围下拉框(选中画板/当前页全部画板/全部画板,默认"全部画板",见 zip.cocoascript)以及三个开关:画板按 2x 导出、每个图层导出为图片、保存 Sketch 源文件; - 保存路径:
getSavePath通过NSSavePanel选择 zip 输出位置,默认文件名为 Sketch 文档名(未保存的文档为Untitled.zip,见 zip.cocoascript); - 延迟执行:
coscript.scheduleWithInterval延迟 1 秒启动导出以释放 UI(zip.cocoascript); - 数据采集:
Marketch.run按选项收集画板(含 Symbol Master)、初始化临时目录NSTemporaryDirectory()/com.sketch.cosa/<时间戳>,若勾选"保存 Sketch 源文件"则复制当前.sketch文件(export.cocoascript、L158-L209); - 逐画板处理:
collectArtboard遍历画板,导出artboard.png(按 1x/2x)、按类型采集图层数据(文本/切片/位图/形状/Symbol,小尺寸组合并按组导出,见 export.cocoascript),并处理蒙版关系; - 产出预览页:
saveDataFile将全部数据序列化为data.js(var pageData = {...}),copyHtmlFile把插件内置的 index.html 复制进临时目录(export.cocoascript); - 打包:
util.zipFile调用系统/usr/bin/ditto(参数-c -k -X --rsrc)打包为 zip,成功后通过NSWorkspace在 Finder 中高亮 zip 文件(util.cocoascript、zip.cocoascript)。
预览页加载时通过 data.js 注入数据并执行 new Marketch({sketchData: pageData}).render()(index.html),前端据此完成页面/画板列表渲染、测量标尺与面板展示。理解这条流水线,就能明白 CHANGELOG 中"导出功能恢复"(v1.0.24)这类修复为什么属于关键性问题——任何一步采集失败都会导致整条链路中断。
八、版本号核对与更新检测机制
仓库中有两个版本号来源:插件清单 manifest.json 的 version: "1.0.24",以及根目录 package.json 的 version: "1.0.24",两者与 CHANGELOG 最新条目一致。
Get New Version 命令(checkupdate.cocoascript)的检测逻辑是:读取插件目录下 manifest.json 的版本号,通过 util.getJSON 拉取远端 package.json 的版本号,再用 convertVersion 将形如 1.0.24 的版本号转换为纯数字(parseFloat(version.match(/\d/gi).join(''), 10),结果为 1024)后比较大小,据此弹出"发现新版本/已是最新版本/网络异常"的提示(提示文案见 util.cocoascript 的 I18N 配置,支持中英文按系统语言自动切换)。
九、小结
Marketch 的 CHANGELOG 虽然只有十几个条目,却完整记录了一个 Sketch 插件从 v1.0.0 打基础(切片、多圆角、CSS 一致性、画板截图修复)到沉淀命名规范(svg 前缀、- 前缀与转义规则),再到 Symbol 导出、新界面与持续跟随 Sketch/macOS 版本演进的完整历程。对照源码可以看到,每一条变更都对应着 export.cocoascript、util.cocoascript、index.html 中可验证的具体实现;而 v1.0.24 的 sharedObject 变通方案与已知限制,则提醒使用者当前版本中文本/形状的共享样式信息暂不可见,安装使用时需留意这一限制。如需在自己的 Sketch 环境中使用,可 clone 本仓库(git clone https://gitcode.com/gh_mirrors/ma/marketch),将 marketch.sketchplugin 目录解压后双击安装(前提是 Sketch 3.4+ 且以画板为工作单元,见 README.md)。