DataCards 项目设置参数完全指南：从基础配置到高级技巧

前言

DataCards 是一款功能强大的数据可视化工具，它能够将结构化数据以精美的卡片形式呈现。本文将全面解析 DataCards 的各项设置参数，帮助用户从入门到精通地掌握配置技巧。

配置方式概述

DataCards 提供了两种灵活的配置方式：

1. 全局配置：适用于所有数据卡片的默认设置
2. 区块级配置：针对特定代码块的个性化设置

全局配置详解

全局配置是所有数据卡片的默认行为，建议将最常用的配置项设置在此处：

1. 打开应用设置面板
2. 在插件列表中找到 DataCards 选项
3. 根据需求调整各项参数

区块级配置详解

区块级配置允许针对特定查询进行个性化定制，语法规则为：

TABLE 字段1, 字段2 FROM 数据源
SORT 排序字段

// Settings
参数名: 参数值
参数名: 参数值

参数分类详解

预设样式参数

preset 是最核心的样式参数，决定了卡片的整体布局风格：

• grid：网格布局（默认）
• portrait：纵向布局，适合展示图片
• square：方形布局
• compact：紧凑布局
• dense：高密度布局

图像显示参数

图像相关参数控制着卡片中图片的展示方式：

• imageProperty：指定使用哪个元数据字段作为图片源
• imageHeight：图片高度（支持CSS单位）
• imageFit：图片填充方式（cover/contain）

内容显示参数

内容参数决定了卡片中信息的呈现方式：

• properties：指定显示的字段（all或字段列表）
• exclude：排除不显示的字段
• scrollableProperties：是否启用内容滚动
• contentHeight：可滚动区域的高度

布局控制参数

精细控制卡片布局的高级参数：

• columns：固定列数
• dynamicColumns：是否启用动态列数
• minCardWidth：卡片最小宽度（动态布局时有效）

移动端适配参数

专为移动设备优化的参数：

• mobilePreset：移动端预设样式
• mobileColumns：移动端列数（通常设为1-3）
• mobileContentHeight：移动端内容区域高度

实用配置示例

基础配置示例

TABLE 文件链接, 作者, 评分 FROM #书籍
SORT 评分 DESC

// Settings
preset: portrait
imageProperty: 封面

高级配置示例

TABLE 文件链接, 作者, 评分, 类型, 封面 FROM #书籍
SORT 评分 DESC

// Settings
preset: grid
imageProperty: 封面
columns: 8
fontSize: small
showLabels: true

响应式布局示例

TABLE 文件链接, 作者, 评分, 类型, 封面 FROM #书籍
SORT 评分 DESC

// Settings
preset: grid
imageProperty: 封面
dynamicColumns: true
minCardWidth: 280px

参数优先级规则

当同一参数在多处设置时，系统遵循以下优先级：

1. 区块级设置（最高优先级）
2. 全局设置
3. 预设默认值
4. 移动端特殊设置（在移动设备上自动生效）

特别提示：对于列数设置，固定列数参数会覆盖动态列数设置，这在需要精确控制布局时非常有用。

最佳实践建议

1. 性能优化：对于包含大量图片的数据集，建议启用enableLazyLoading参数
2. 移动端适配：始终测试移动端显示效果，必要时使用mobilePreset单独配置
3. 内容溢出处理：长文本内容建议启用truncateText或scrollableProperties
4. 布局一致性：在全局设置中定义基础样式，在区块级设置中仅覆盖必要参数

通过合理组合这些参数，您可以创建出既美观又实用的数据卡片展示效果。建议从简单配置开始，逐步尝试更复杂的参数组合，以找到最适合您需求的展示方式。