设计系统前端开发工具UI组件【免费下载链接】LonaA tool for defining design systems and using them to generate cross-platform UI code, Sketch files, and other artifacts.项目地址https://gitcode.com/gh_mirrors/lo/Lona点击查看免费下载本篇技术指南围绕 Lona 仓库中 docs/file-formats 目录下的文件格式规范展开系统讲解 Lona 的核心载体——.component组件定义文件——以及配套的colors.json、textStyles.json、gradients.json、shadows.json、types.json等设计系统 Token 文件的字段结构、约束与真实工作区示例。读完本文你将掌握 Lona 工作区中每一类文件的完整 JSON 骨架能够手工编写或校验一套可被 Lona Studio 编辑、被 Lona Compiler 消费的跨平台设计系统。一、文件格式总览谁在读写这些文件Lona 的定位是定义设计系统并用它生成跨平台 UI 代码、Sketch 文件与其他产物。围绕这一目标文件格式被清晰地分成两类组件定义文件.componentLona 最主要的操作对象。Lona Studio 负责编辑这些文件Lona Compiler 负责从它们生成代码见 组件文件格式。设计系统 Token 文件用于支撑组件文件中的取值统一存放在工作区workspace的规范位置。docs/file-formats/README.md给出了 Token 文件的规范位置与对应规范文档类型文件名规范文档颜色Colorscolors.jsoncolors.md文本样式Text StylestextStyles.jsontext-styles.md渐变Gradientsgradients.jsongradients.md阴影Shadowsshadows.jsonshadows.md类型Typestypes.jsonREADME 中未单独展开见下文自定义类型一节一个值得注意的细节规范文档开头明确声明This specification may deviate slightly from what Lona actually uses. This specification is currently thegoal——即这套规范是 Lona 的目标形态实际实现可能略有偏差。阅读与使用时应以这套规范为主同时结合仓库源码与真实工作区文件交叉印证。从编译器源码可以印证这些 Token 文件的规范位置约定。在 config.re 中编译器通过findPathWithSuffix在workspacePath下查找colors.json、textStyles.json、shadows.json等文件若找不到则回退为路径指向工作区根目录、内容为空数组的默认配置。这说明Token 文件是可选但强约定的——缺失时编译器仍能运行只是设计系统没有对应的 Token 来源。二、组件定义文件.component规范.component文件用 JSON 编码是一个包含若干顶层字段的对象。规范目前列出的顶层字段包括metadata组件的文档与索引信息devices用于在 Lona Studio 中渲染组件的设备尺寸examples组件的示例/测试用例params组件的参数输入定义root图层layer层级树的根logic组件逻辑规范标注为即将推出privateLona Studio 内部使用的私有信息2.1 metadata文档与索引元数据metadata是包含以下可选字段的对象属性类型必填说明tagsstring[]否用于组件分类/索引的标签数组descriptionstring否组件描述用于文档化可包含 Markdown示例metadata: { description: My header component. Use it for displaying titles., tags: [Header] }2.2 devices设备尺寸列表devices是对象数组定义 Lona Studio 中用于渲染组件的各种设备尺寸。这些字段当前不生成任何代码但概念上可用于生成自动化测试。每个对象包含属性类型必填说明namestring是设备的人类可读名称widthnumber是设备宽度heightnumber是设备高度以密度无关像素dp为单位heightModeAt Least 或 Exactly是设备视口是否可随内容增长。At Least时视口可增长Exactly时视口恒为给定height底部组件会被裁剪visibleboolean是是否在屏幕上绘制该设备paramsJSON是供Logic使用的可选参数值exportScalenumber是产物导出倍率默认为1即1x分辨率backgroundColorColor是设备背景色显示于 Lona Studio 及导出产物中示例devices: [ { name: iPhone SE, width : 375, height : 100, heightMode : At Least, visible : true, params : {}, exportScale : 1, backgroundColor : white } ]真实工作区中的设备字段与此略有出入例如 ComponentParameterInstance.component 中的设备只给出了height、heightMode、name、width四项——这正是规范声明可能与实际使用略有偏差的体现规范是目标实现允许渐进对齐。2.3 examples组件的示例/测试用例examples是对象数组定义组件的示例或测试用例同样当前不生成代码但概念上可用于生成自动化测试。字段如下属性类型必填说明namestring是示例的人类可读名称typeentry 或 importedList否是显式定义的单个用例entry还是从 JSON 导入的用例列表importedList。默认为entryvisibleboolean否是否在屏幕上绘制该用例。默认为trueparamsJSON否供Logic使用的可选参数值。仅对type为entry的示例定义urlURL否以 JSON 定义的示例列表的 URL。仅对type为importedList的示例定义示例examples: [ { name : Default case, params : { title : Header sample text } } ]2.4 params组件参数定义params是组件对外暴露的参数输入列表也是代码生成的关键输入属性类型必填说明namestring是参数的代码友好名称。该名称会被直接翻译为变量名因此不应包含空格或特殊字符typeData Type是参数的数据类型defaultValueJSON否参数的默认值。若指定将在代码中使用示例params: [ { type : String, name : title }, { type : Boolean, name : large, defaultValue : true } ]这里的Data Type既可以指内置基础类型String、Boolean、Number等也可以指工作区types.json中定义的自定义类型。defaultValue对生成代码的调用方很有价值例如在 ComponentParameterInstance.component 中自定义组件ComponentParameterTemplate的实例通过params传入titleComponent、subtitleComponent等子组件值而这些值的类型正是Lona:Text。2.5 root图层层级树的根root是图层层级layer hierarchy的根。每个图层都是一个组件的实例——图层指定它代表哪个组件以及要传给该组件的参数。图层既可以是内置组件也可以是自定义组件。图层的字段属性类型必填说明idstring是图层的唯一 id用作逻辑logic中的键namestring是图层的人类可读名称。在 Lona Studio 中重命名图层默认会自动同步更新id字段typestring是内置组件的类型为Lona:View、Lona:Text、Lona:Image、Lona:Animation。自定义组件的 type 与其文件名相同去掉.component扩展名。另有特殊类型Lona:Children代表可在此组件内使用的子组件占位符paramsJSON是指定组件的输入参数。对自定义组件而言这些参数由该组件.component文件根级的params定义对内置类型而言参数定义见下文childrenComponent[]否内置的Lona:View与Lona:Image组件会在自身内部渲染子组件自定义组件可通过在children数组中放置Lona:Children占位符来渲染子组件以 ComponentParameterInstance.component 的真实结构为例其root是一个Lona:View图层内部children中放置了一个ComponentParameterTemplate自定义组件实例同时该实例的params中传入了type为Lona:Text的子组件定义。这种图层实例 参数注入 子组件占位的组合正是 Lona 组件可组合性的核心机制。规范中Built-in Component Params内置组件参数一节目前标注为Coming soon!即将推出Logic一节同样标注为 Coming soon!——这两个部分在现有规范中尚未展开细节。2.6 privateStudio 私有信息约定private对象存放 Lona Studio UI 内部使用的信息并有一条清晰的命名空间约定Lona Studio 只会写入以com.lonastudioapp为前缀的键若存在其他键Lona Studio 会原样保留、不修改外部工具可以写入private对象但不应使用或修改任何以com.lonastudioapp为前缀的键。这条约定保证了 Studio 与外部工具可以在同一文件中共存而不互相破坏是一种轻量的插件式扩展点。三、colors.json设计系统颜色colors.json定义设计系统的颜色。顶层是一个包含colors数组的对象数组中每个颜色对象包含属性类型必填说明idstring是颜色的唯一 id供 Lona Studio 内部及生成代码使用。应代码友好不能包含空格或异常字符因为它会作为变量名使用namestring是颜色的人类可读名称显示于 Lona Studio UI不会出现在生成代码中valuestring是颜色值采用 CSS 格式。任何合法 CSS 值均可如blue、fce、#ffccee、rgb(0,0,100)、rgba(255,255,255,0.3)commentstring否颜色的可选描述解释使用场景等上下文信息。可显示于 Lona Studio UI不会出现在生成代码中Color Type颜色引用约定颜色可以通过id字符串从其他文件引用——这是实现颜色单一事实来源single source of truth的关键机制。颜色也可以在其他文件中内联出现直接给出 CSS 颜色值但规范不鼓励这样做除非是black、white、transparent这类基础色。这一点在 text-styles.md 与 shadows.md 的color字段中反复出现它们都接受CSS 颜色值或colors.json中定义的id。完整示例文件colors.json{ colors: [ { id: lonaTeal, name: Lona Teal, value: #008080, comment: Teal color for backgrounds }, { id: lonaBlue, name: Lona Blue, value: #000080, comment: Blue accent color } ] }仓库中的真实工作区给出了更大规模的参考examples/test/foundation/colors.json是一份完整的 Material Design 色板覆盖 Red、Pink、Purple、Indigo、Blue、Teal、Green、Amber、Grey、Bluegrey 等色系的 50/100/200/…/900 及 a100–a700 阶梯字段严格遵循name/id/value部分条目带comment的三元组结构可直接作为团队搭建配色体系时的模板。四、textStyles.json文本样式textStyles.json定义设计系统的文本样式。顶层是包含styles数组的对象并可包含一个可选的defaultStyleName字符串。数组中的每个文本样式对象属性类型必填说明idstring是文本样式的唯一 id供 Lona Studio 内部及生成代码使用。应代码友好不能包含空格或异常字符因为它会作为变量名使用namestring是文本样式的人类可读名称显示于 Lona Studio UI不会出现在生成代码中commentstring否可选描述解释使用场景。可显示于 Lona Studio UI不会出现在生成代码中fontNamestring否字体名称fontFamilystring否字体族名称fontWeightstring否字重采用 CSS 值以 100 为步进的字符串范围 100 到 900fontSizenumber否字号单位像素lineHeightnumber否每行文本高度单位像素letterSpacingnumber否统一调整字符间距正数增加间距负数减少间距colorColor否CSS 颜色值或colors.json中定义的颜色的idextendsstring否要继承的另一个文本样式的id可选的defaultStyleName决定 Lona Studio 中新建文本时默认采用的样式其值应为styles数组中某个文本样式的id。该值不会用于代码。完整示例文件textStyles.json{ defaultStyleName: h2, styles: [ { id: h1, name: Heading 1, fontFamily: Helvetica Neue, fontWeight: 300, fontSize: 48, lineHeight: 56, letterSpacing: -0.3, color: lonaBlue }, { id: h2, name: Heading 2, fontFamily: Helvetica Neue, fontWeight: 500, fontSize: 32, lineHeight: 40, letterSpacing: -0.3, color: rgba(0,0,0,0.9) } ] }注意color字段的两种用法h1引用colors.json中的颜色idlonaBlueh2直接内联 CSS 颜色值rgba(0,0,0,0.9)——正好对应上文Color Type的引用约定。extends字段则允许基于已有样式做增量派生例如定义标题的强调色变体时只需覆盖color。从生成端看文本样式会落到具体平台的代码中例如 swiftTextStyle.re 中处理当textStyles.json未定义任何样式时打印通用默认样式的兜底逻辑说明编译器会为 Swift 输出生成对应的文本样式代码而defaultStyleName只影响 Studio 内的新建行为。五、shadows.json阴影定义shadows.json定义设计系统的阴影。顶层是包含shadows数组的对象并可包含可选的defaultShadowName字符串。数组中的每个阴影对象属性类型必填说明idstring是阴影的唯一 id供 Lona Studio 内部及生成代码使用。应代码友好不能包含空格或异常字符因为它会作为变量名使用namestring是阴影的人类可读名称显示于 Lona Studio UI不会出现在生成代码中commentstring否可选描述解释使用场景。可显示于 Lona Studio UI不会出现在生成代码中xnumber否阴影的水平偏移单位像素ynumber否阴影的垂直偏移单位像素blurnumber否阴影的模糊半径单位像素colorColor否CSS 颜色值或colors.json中定义的颜色的id可选的defaultShadowName决定 Lona Studio 中新建阴影时的默认样式其值应为shadows数组中某个阴影的id同样不会用于代码。完整示例文件shadows.json{ defaultShadowName: elevation1, shadows: [ { id: elevation1, name: Elevation 1, color: black, x: 0, y: 2, blur: 4 }, { id: elevation2, name: Elevation 2, color: red, x: 0, y: -2, blur: 4 }, { id: elevation3, name: Elevation 3, color: yellow, x: 0, y: -4, blur: 4 } ] }示例中的y取值有正有负说明阴影偏移允许向上负偏移或向下正偏移投射color也可以直接引用colors.json中的颜色id以保持与配色体系一致。六、gradients.json渐变定义gradients.json定义设计系统的渐变。顶层是包含gradients数组的对象。数组中的每个渐变对象属性类型必填说明idstring是渐变的唯一 id供 Lona Studio 内部及生成代码使用。应代码友好不能包含空格或异常字符因为它会作为变量名使用namestring是渐变的人类可读名称显示于 Lona Studio UI不会出现在生成代码中commentstring否可选描述解释使用场景。可显示于 Lona Studio UI不会出现在生成代码中colorStopsArray{ position: number, color: Color }是渐变的色标stop列表完整示例文件gradients.json{ gradients: [ { id: gradient1, name: Gradient 1, colorStops: [ { position: 0, color: black }, { position: 1, color: white } ] } ] }colorStops中的每个元素由position色标位置与color颜色组成color同样遵循 Color Type 约定可用 CSS 值或引用colors.json中的id。渐变文件目前没有defaultGradientName之类的默认值字段——这一点与文本样式、阴影的默认样式机制不同。七、types.json自定义数据类型README 的格式表中列出了types.json但未单独给出规范文档。从真实工作区文件 studio/workspace/types.json 可以看到其实际结构顶层是types数组每一项是一个类型定义对象核心形态包括别名/命名类型{ name: Named, alias: ..., of: ... }of可以是基础类型如SwiftColor、PickerShadow也可以是嵌套结构枚举类型of为{ name: Enum, cases: [...] }例如示例中的DimensionType定义了fitContent、fill、fixed三个 case后两者带Number/Unit载荷函数类型of为{ name: Function, parameters: [...] }例如ColorHandler、TextStyleHandler等带标签label与类型type的函数签名。这解释了 component.md 中params字段的Data Type它既可以指向内置类型也可以指向types.json中声明的自定义类型。自定义类型让组件的参数体系可以表达枚举选择、回调函数与别名而不只是基础标量。八、工作区组织与编译链路所有上述文件都被组织在一个 Lona 工作区中。工作区根目录的lona.json是工作区标记/配置文件例如 studio/workspace/lona.json 仅包含workspaceName: Lona Studio而 examples/test/lona.json 甚至可以是一个空对象{}。可见lona.json的必填内容极少主要用于标识工作区名称。在编译侧Token 文件与组件文件的消费路径如下Token 解析编译器在 config.re 中以工作区路径为基准按colors.json、textStyles.json、shadows.json等固定文件名定位并解析 Token文件缺失时回退为空配置组件编译.component文件中的root图层树、params参数定义与devices/examples等结构被解析后由编译器各平台模块如swift/、javaScript/目录下的生成器产出目标代码Token 代码生成命令行工具支持将 Token 文件生成为各平台代码commandLine.re中即有Generate legacy token files (e.g. colors.json colors.js)的说明。仓库中 examples/generated/tokens 下的swift/与react-dom/目录即展示了这类生成产物Swift 源码与 React/JS 模块的实际形态。因此一套完整的 Lona 设计系统工作区通常由以下文件构成lona.json工作区配置可只含workspaceNamecolors.json/textStyles.json/gradients.json/shadows.jsonToken 单一事实来源types.json自定义数据类型可选若干*.component文件组件定义可分层放置于子目录中。九、小结Lona 的文件格式体系可以用一句话概括.component文件描述界面长什么样、接收什么参数Token 文件描述设计系统的取值从哪来types.json描述参数能是什么类型lona.json描述这是哪个工作区。本文覆盖了规范中全部已展开的字段表格与示例metadata、devices、examples、params、root、private以及四种 Token 文件并补充了仓库源码与真实工作区文件中的实现证据。需要再次提醒的是官方规范在 README 中明确声明其是目标形态可能与 Lona 实际实现略有偏差——例如真实.component文件中的设备字段比规范更精简。因此在手工编写或迁移文件时建议以本文引用的规范文档为主体同时对照仓库中 examples/test 与 studio/workspace 下的真实文件做交叉校验。此外规范中Built-in Component Params与Logic两节仍标注为 Coming soon!相关字段如Lona:Text的具体参数目前以真实工作区文件的实际用法为准。赞分享设计系统前端开发工具UI组件【免费下载链接】LonaA tool for defining design systems and using them to generate cross-platform UI code, Sketch files, and other artifacts.项目地址https://gitcode.com/gh_mirrors/lo/Lona点击查看免费下载相关推荐KernelSU 安装实战指南LKM 与 GKI 双模式、KMI 匹配原理与 ksud boot-patch 详解KernelSU 安装实战指南LKM 与 GKI 双模式、KMI 匹配原理与 ksud boot patch 详解 本文基于 KernelSU 官方安装文档设计系统前端开发工具UI组件Lona 渐变色定义gradients.json文件格式规范与源码级解析Lona 渐变色定义gradients.json文件格式规范与源码级解析 本篇技术指南围绕 Lona 设计系统工作区中的 gradients.json 文件设计系统前端开发工具UI组件OpenRocket 文件格式完全指南.ork 设计文件与 .orc 组件文件规范详解OpenRocket 文件格式完全指南.ork 设计文件与 .orc 组件文件规范详解 本指南以 OpenRocket 官方开发文档 file_specifi桌面应用科学计算3D渲染上一篇psysh中的方法默认参数ClassMethodDefaultParametersMatcher实现下一篇Cycle.js开发环境问题排查解决响应式应用的环境问题创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考