设计系统前端开发工具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/component.md结合仓库内真实组件文件与编译器实现系统讲解.component文件的顶层结构、七大字段metadata、devices、examples、params、root、logic、private的完整属性定义、JSON 编码方式与实战写法。读完本文你将掌握手写或理解 Lona 组件定义文件的全套能力能够独立阅读 examples/test/components 下的真实组件、并据此搭建可被 Lona Studio 编辑、被 Lona Compiler 编译生成多端代码的设计系统组件。一、.component文件在 Lona 生态中的定位Lona 是一个用于定义设计系统并生成跨平台 UI 代码、Sketch 文件与其他产物的工具链由Lona Studio图形化设计 工程工具与Lona Compiler代码生成器两大部分组成。根据 docs/file-formats/README.md 的说明Lona 的核心操作对象就是.component文件即组件定义文件Lona Studio 负责编辑这些文件图形界面 代码编辑Lona Compiler 负责从这些文件生成代码。与此同时设计系统中的其他资源颜色、文本样式、渐变、阴影、类型也以 JSON 形式存放在工作区的固定位置与组件文件协同工作类型文件名Colors颜色colors.jsonText Styles文本样式textStyles.jsonGradients渐变gradients.jsonShadows阴影shadows.jsonTypes类型types.json需要注意的是该格式规范文档本身在开头就声明此规范可能与 Lona 实际使用的略有出入目前这份规范是目标goal。因此在阅读真实组件文件时你会发现某些字段的实践用法比规范更丰富例如examples条目中额外的id字段、层上的metadata字段这些差异我们会在后文结合仓库实例逐一指出。二、编码方式Encoding为什么选择 JSON当前组件数据以JSON编码。规范文档指出 JSON 的一个核心痛点它不易于合并、不易于人工编辑。因此文档设想了一种更易合并供人类或机器操作的存储格式数据在被任何工具消费之前再转换为 JSON——这属于对未来演进的规划当前仓库实际仍以 JSON 作为唯一编码。从仓库实例看.component文件即为一个完整的 JSON 对象例如 examples/test/components/NestedButtons.component 就是典型的、可被解析的真实文件。JSON 的优点是解析简单、生态完善编译器、Studio、Sketch 插件都能直接消费缺点是手写时对格式敏感、多人协作时 diff 冲突多。三、文件顶层结构Outline.component文件是一个 JSON 对象包含以下顶层字段metadata组件元数据文档、索引用devices用于在 Studio 中渲染组件的设备尺寸列表examples组件的示例/测试用例params组件的对外参数定义root图层层级结构的根节点logic组件逻辑交互、条件、赋值private仅供 Studio 内部使用的私有信息其中metadata、devices、examples、params、root是构成一个可用组件的核心logic在规范中标记为 Coming soon但仓库的真实组件如 examples/test/interactivity/Button.component已包含完整的逻辑结构private则是 Studio 内部使用的约定命名空间。下面逐字段详解。四、metadata组件元数据metadata用于组件文档、索引等杂项用途是一个包含以下可选字段的对象属性类型必填描述tagsstring[]否用于对组件分类/索引的标签数组descriptionstring否组件描述用于文档用途可包含 Markdown规范给出的示例metadata: { description: My header component. Use it for displaying titles., tags: [Header] }从仓库实例来看metadata不仅出现在顶层描述整个组件也出现在单个图层上在 examples/test/interactivity/Button.component 中根Lona:View图层带有backingElementClass: { reactdom: button }指定 React DOM 后端生成button元素Lona:Text图层带有accessLevel: { ios: public }指定 iOS 生成的访问级别。这说明metadata的杂项用途定位是准确的——不同工具可以在其中写入平台相关的额外信息。五、devices设备尺寸列表devices是 Lona Studio 中用于将组件渲染到不同尺寸设备的列表。规范明确指出这些设备当前不生成任何代码尽管概念上它们未来可能用于生成自动化测试。它是一个对象数组每个对象包含以下字段属性类型必填描述namestring是设备的人类可读名称widthnumber是设备的宽度heightnumber是设备的高度以密度无关像素为单位heightModeAt Least 或 Exactly是当被组件填满时设备视口是否可增长At Least视口会增长Exactly视口始终是给定的精确height底部组件会被裁剪visibleboolean是是否在屏幕上绘制此设备paramsJSON是供logic使用的可选参数值exportScalenumber是导出产物的缩放比例默认1即1x分辨率backgroundColorColor是设备背景色显示在 Studio 中并出现在导出产物里规范示例devices: [ { name: iPhone SE, width : 375, height : 100, heightMode : At Least, visible : true, params : {}, exportScale : 1, backgroundColor : white } ]仓库实例对照真实组件文件中的devices通常会省略可选字段、只保留最小集。例如 examples/test/components/NestedButtons.component 定义了三个宽度递增的设备devices : [ { name : iPhone SE, height : 100, heightMode : At Least, width : 320 }, { name : iPhone 7, height : 100, heightMode : At Least, width : 375 }, { name : iPhone 7, height : 100, heightMode : At Least, width : 414 } ]这里heightMode均为At Least表示视口高度可以随组件内容增长组件很高时不会裁剪visible、params、exportScale、backgroundColor均未给出Lona Studio 会按默认值处理。backgroundColor的类型引用自 colors.md 的 Color Type 小节——颜色既可以引用colors.json中定义的id也可以内联 CSS 色值如white但规范建议除black、white、transparent外的颜色尽量走引用以保证单一事实来源。六、examples组件的示例 / 测试用例examples是组件的示例test cases。与devices一样规范说明它们当前不生成代码但概念上可用于生成自动化测试。它是一个对象数组每个对象字段如下属性类型必填描述namestring是示例的人类可读名称typeentry 或 importedList否该示例是显式定义的单个用例还是从 JSON 导入的示例列表默认entryvisibleboolean否是否在屏幕上绘制此测试用例默认trueparamsJSON否供logic使用的可选参数值仅当type为entry时定义urlURL否以 JSON 定义的示例列表的 URL仅当type为importedList时定义规范示例examples: [ { name : Default case, params : { title : Header sample text } } ]仓库实例对照真实组件的examples通常会为每个参数组合建一个命名用例。例如 examples/test/interactivity/Button.component 定义了主按钮与次按钮两个用例examples : [ { id : Default, name : Default, params : { label : Primary Button } }, { id : Secondary, name : Secondary, params : { label : Secondary Button, secondary : true } } ]注意这里出现了规范表格之外的id字段实践用法比规范更丰富并且params与组件params定义一一对应label、secondary。type默认即entry所以未显式声明若要使用外部 JSON 示例列表则需声明type: importedList并提供url。七、params组件的参数定义params定义组件对外暴露的参数——这些参数会显示在 Lona Studio 的检查器中并在生成代码时作为组件函数/类的入参。每个参数对象字段如下属性类型必填描述namestring是参数的代码友好名称会直接被翻译为变量名因此不能包含空格或特殊字符typeData Type是参数的数据类型defaultValueJSON否参数默认值若指定将在生成代码时使用规范示例params: [ { type : String, name : title }, { type : Boolean, name : large, defaultValue : true } ]仓库实例对照真实组件展示了更丰富的数据类型。以 examples/test/interactivity/Button.component 为例params : [ { name : label, type : String }, { name : onTap, type : { name : Function } }, { name : secondary, type : Boolean } ]其中onTap是函数类型参数回调用于把点击事件从父组件传入type在此时是一个对象{ name: Function }说明Data Type在序列化时既可以是字符串如String、Boolean也可以是带name键的对象如函数、复合类型这与 studio/workspace/types.json 中的自定义类型体系相呼应。另外参数类型还支持Component在 examples/test/components/ComponentParameterTemplate.component 中params : [ { name : titleComponent, type : Component }, { name : subtitleComponent, type : Component } ]这表示组件可以接收另一个组件作为参数即插槽/模板配合下文root中的Lona:Children占位符使用。可选参数当参数未提供值时调用方可以传入null见 examples/test/components/NestedOptionals.component 中boolParam : null的用法。八、root图层层级结构的根root是图层层级的根节点。图层Layer定义了 UI 层级每个图层都是一个组件的实例instance图层声明它代表哪个组件以及传递给该组件的参数。图层可以代表内置组件或自定义组件。图层包含以下属性属性类型必填描述idstring是图层的唯一 id在逻辑中作为键使用namestring是图层的人类可读名称。在 Lona Studio 中重命名图层时默认会自动同步更新id字段typestring是内置组件的类型为Lona:View、Lona:Text、Lona:Image、Lona:Animation。自定义组件的类型与其文件名一致去掉.component后缀。另有特殊类型Lona:Children代表可在该组件内使用的子组件的占位符paramsJSON是指定组件的输入参数。自定义组件的参数由该.component文件根层的params定义内置类型的参数由本规范下文定义childrenComponent[]否内置的Lona:View与Lona:Image组件可在自身内部渲染子组件自定义组件可通过在其children数组中放置Lona:Children占位符来渲染子组件8.1 内置组件参数Built-in Component Params规范中该小节标注为Coming soon!待完善。不过从仓库真实组件文件可以观察到实际使用的内置组件参数这些参数与 docs/file-formats 下的布局、样式概念一致常见的有Lona:View布局与样式参数如alignSelfstretch、paddingTop/Bottom/Left/Right、backgroundColor颜色 id 或 CSS 色值如blue100、#D8D8D8、height、width、marginTop等Lona:Text文本与排版参数如text字符串内容、font引用textStyles.json中的文本样式 id如button、headline、subheading2。例如 examples/test/components/NestedComponent.component 中的文本图层{ id : Text, params : { font : subheading2, marginBottom : 8, text : Example nested component }, type : Lona:Text }以及根视图图层{ id : View, params : { alignSelf : stretch, paddingBottom : 10, paddingLeft : 10, paddingRight : 10, paddingTop : 10 }, type : Lona:View }8.2 内置组件与自定义组件的组合以 examples/test/components/NestedButtons.component 为例其根Lona:View内嵌了两个自定义组件type为Button与按钮组件文件Button.component同名以及一个用于分隔的Lona:Viewroot : { id : View, type : Lona:View, params : { paddingTop : 24, alignSelf : stretch, paddingBottom : 24, paddingLeft : 24, paddingRight : 24 }, children : [ { id : Button, type : Button, params : { label : Button 1 } }, { id : View 1, type : Lona:View, params : { height : 8, alignSelf : stretch } }, { id : Button2, type : Button, params : { label : Button 2 } } ] }可见自定义组件的type即其文件名去掉扩展名Button.component→Button传参直接对应其params定义label。这也解释了为何规范要求参数名代码友好——label会被翻译为生成代码中的变量名。8.3Lona:Children子组件占位符与组件插槽Lona:Children是自定义组件中放置外部传入子组件的占位符。在 examples/test/components/ComponentParameterTemplate.component 中组件声明了两个Component类型参数并在图层树中通过Lona:Children引用它们{ id : titleComponent, params : { parameterName : titleComponent }, type : Lona:Children }, { id : subtitleComponent, params : { parameterName : subtitleComponent }, type : Lona:Children }而调用方examples/test/components/ComponentParameterInstance.component在传参时以内联组件对象形式给出包含type如Lona:Text与parameters如{text: Title, textStyle: headline}params : { titleComponent : { type : Lona:Text, parameters : { text : Title, textStyle : headline } }, subtitleComponent : { type : Lona:Text, parameters : { text : Subtitle, textStyle : subheading2 } } }这正是组件模板 插槽的完整链路Component类型参数 Lona:Children占位符 调用方内联组件对象三者共同实现组合式 UI。九、logic组件逻辑规范中该小节标注为Coming soon!但仓库真实组件已经使用了完整的逻辑结构。从 examples/test/interactivity/Button.component 可以看到logic是表达式对象数组包含赋值与条件两类核心表达式AssignExpr赋值表达式——把参数值赋给图层属性例如把label参数赋给Text图层的text{ assignee : [ layers, Text, text ], content : [ parameters, label ], type : AssignExpr }IfExpr条件表达式——按条件给图层属性赋值例如按悬停/按压状态切换背景色{ condition : { left : [ layers, View, hovered ], op : , right : { type : LitExpr, value : { data : true, type : Boolean } }, type : BinExpr }, body : [ { assignee : [ layers, View, backgroundColor ], content : { type : LitExpr, value : { data : blue200, type : Color } }, type : AssignExpr } ], type : IfExpr }这里的寻址语法揭示了逻辑的取值模型parameters.name读取组件参数如parameters.label、parameters.secondarylayers.layerId.property读取/写入图层属性如layers.Text.text、layers.View.backgroundColor、layers.View.hovered、layers.View.pressed、layers.View.onPressLitExpr字面量表达式value.data为值、value.type为类型Boolean、Color等。更多逻辑示例见 examples/test/logic 目录下的If.component、Assign.component、Optionals.component等文件。可以推断编译器的 compiler/core/src/logic 模块负责将这些表达式解析、求值并翻译为各目标语言的代码Swift / JavaScript 等。十、private私有信息命名空间private对象保存 Lona Studio UI 内部使用的信息。关键约定是Lona Studio 只会写入以com.lonastudioapp为前缀的键Lona Studio 会保留其他已有键且不做改动即外部工具可以向该对象写入内容Lona Studio 不会使用或修改它们反过来外部工具不应使用或修改任何以com.lonastudioapp为前缀的键。这是一个典型的命名空间隔离协议以官方前缀开头的键归 Studio 所有其余键归第三方工具所有双方互不干扰。十一、组装一个完整的最小组件综合以上各节我们可以把规范示例与仓库实践合并得到一个可直接对照学习的完整组件骨架{ metadata: { description: A reusable header component. Use it for displaying titles., tags: [Header] }, devices: [ { name: iPhone SE, width: 320, height: 100, heightMode: At Least }, { name: iPhone 7, width: 375, height: 100, heightMode: At Least } ], examples: [ { name: Default, params: { title: Header sample text } } ], params: [ { type: String, name: title }, { type: Boolean, name: large, defaultValue: true } ], logic: [], root: { id: View, type: Lona:View, params: { alignSelf: stretch, paddingLeft: 16, paddingRight: 16 }, children: [ { id: Title, type: Lona:Text, params: { text: Text goes here, font: headline } } ] } }要点回顾metadata描述组件devices控制 Studio 中的预览画布尺寸examples提供命名用例可被 Studio 逐个预览未来可用于生成自动化测试params声明对外接口logic表达交互与条件root描述 UI 树private留给工具间隔离私有数据。十二、从规范到代码与 Lona 工具链的关系.component文件是 Lona 的单一事实来源Lona Studiostudio/LonaStudio直接读写这些文件其Models目录下的CSComponent.swift、CSComponentLayer.swift、CSParameter.swift等模型类与本文描述的字段一一对应编辑器的每个改动最终都会序列化回 JSONLona Compilercompiler/core负责把组件定义编译为多端代码仓库中的 examples/generated/react-dom、examples/generated/react-native、examples/generated/swift、examples/generated/sketchJs 等目录即为从组件文件生成的产物可直观对比一个.component文件、多端代码输出的效果与组件配套的colors.json、textStyles.json等资源文件定义了params与图层属性中可引用的颜色 id如blue100和文本样式 id如headline、button完整的颜色文件格式见 docs/file-formats/colors.md。需要注意的是docs/file-formats/README.md 明确声明规范是目标状态可能与 Lona 实际行为略有偏差本文已尽量同时给出规范定义与仓库真实文件对照阅读真实组件时请以仓库实际文件为准。若想快速上手可以直接在 Lona Studio 中打开 examples/test 或 examples/material-design 工作区观察并编辑其中的.component文件体会设计工具 工程工具一体化的组件定义流程。赞分享设计系统前端开发工具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 设计系统工作流用 .component 文件驱动跨平台 UI 代码生成Lona Studio 与 Lona Compiler 实战指南Lona 设计系统工作流用 .component 文件驱动跨平台 UI 代码生成Lona Studio 与 Lona Compiler 实战指南 导读 L设计系统前端开发工具UI组件5分钟快速上手MediaCrawler新媒体数据采集工具完整指南5分钟快速上手MediaCrawler新媒体数据采集工具完整指南 你是不是经常需要从社交媒体平台收集数据却被复杂的登录验证和反爬机制困扰MediaCraw设计系统前端开发工具UI组件uv-ui跨平台Vue组件库深度解析与实战应用uv ui跨平台Vue组件库深度解析与实战应用 在当今多端融合的开发浪潮中如何选择一款既能提升开发效率又能确保跨平台一致性的跨平台Vue组件库成为开发者面临的前端UI组件跨平台上一篇Tabulator 数据过滤终极指南10个高级多条件查询技巧下一篇Lens-Turbo-3.8B-8bit批量生图工作流搭建本地AI绘图流水线的完整方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考