1 meter介紹

lv_meter 是 LVGL v8 引入的一種圖形控件，用于創建儀表盤樣式的用戶界面元素，它可以模擬像速度表、電壓表、溫度表這類模擬表盤。它通過可視化刻度、指針、顏色弧線等來展示數值信息，是一種非常直觀的數據展示控件。

1.1 核心特性

1. 支持多個 刻度刻度表（scale）

2. 每個刻度表可以有多個 刻度（tick）

3. 每個刻度可以添加多個 指針（needle/arc/image）

4. 支持多種類型的指針：線針、弧線、圖像

5. 可以設置 最小值/最大值 和 角度范圍

6. 動態更新數據值，模擬實時儀表

1.2 lv_meter 的結構組成

在邏輯上，lv_meter 由三個核心部分組成：

1. 刻度盤（scale）
   是整個儀表盤的“底盤”。定義了儀表盤的 值范圍（例如 0 ~ 100）、顯示的角度范圍（如 270°）、以及 刻度線的數量和樣式。一個 lv_meter 對象可以擁有多個刻度盤（通常用一個就夠了）。

2. 刻度線（ticks）
   是刻度盤上的線條，包括 主刻度線（粗、帶標簽）和 次刻度線（細、不帶標簽）。它們用于可視化數據分布，幫助用戶讀數。可以自定義刻度數量、線寬、顏色、標簽間隔等。

3. 指示器（indicator）用于顯示當前值。

指示器有三種主要類型：

針狀指示器（needle）：像時鐘的指針一樣旋轉。

弧形指示器（arc）：顯示某一段范圍，常用于區域顯示。

圖像指針（image）：用圖像作為指針，更加美觀。

每個指示器都與某個刻度盤綁定，并根據數據自動旋轉或變化。

1.3 工作原理

1. 創建儀表：先創建 lv_meter 對象。

2. 添加刻度盤：定義刻度盤的數值范圍、角度范圍。

3. 設置刻度線：設置次刻度和主刻度的外觀。

4. 添加指示器：添加針或弧等指示器來展示當前值。

5. 設置指針值：調用函數實時更新指針的位置或弧度。

1.4 實際用途舉例

1. 電動車儀表盤：顯示速度、電量、溫度等。

2. 工業控制界面：如氣壓表、水溫表、轉速表。

3. 醫療設備 UI：心率儀、氧氣濃度計等。

4. 智能家居：如空調溫度、濕度顯示表盤。

2 常見函數介紹

2.1 創建儀表對象

lv_obj_t * meter = lv_meter_create(lv_scr_act());

2.2 添加刻度盤

lv_meter_scale_t * scale = lv_meter_add_scale(meter);

2.3 設置刻度盤范圍（數值范圍 & 角度范圍）

lv_meter_set_scale_range(meter, scale, min_value, max_value, angle_range, rotation_offset);

angle_range：刻度盤覆蓋的角度
rotation_offset：起始角度
angle = rotation_offset + (value - min) × (angle_range / (max - min))

2.4 設置刻度線

2.4.1 控制小刻度的數量和外觀

lv_meter_set_scale_ticks(meter,scale,tick_num,     // 🟡 刻度線總數（含起點和終點）tick_width,   // 🟢 每條刻度線的寬度（像素）tick_length,  // 🔵 每條刻度線的長度（像素）color         // 🔴 刻度線的顏色
);

tick_num = (max_value - min_value) / 間隔 + 1

2.4.2 控制主刻度（帶數字）的顯示

主刻度（Major Ticks），即那些更長、更粗、帶有標簽文字的刻度線。這類刻度通常用于強調關鍵數值，如 0、20、40 等。

lv_meter_set_scale_major_ticks(meter,scale,major_tick_every, // 🟡 每隔幾個 tick 出現一個主刻度（=多少小刻度間隔）width,             // 🟢 主刻度的線寬length,            // 🔵 主刻度的線長color,             // 🔴 主刻度顏色label_gap          // 🟣 標簽（數字）與線之間的像素間距
);

主刻度數 ≈ tick_num / major_tick_every
主刻度值 = min + i * (max - min) / (tick_num - 1) * major_tick_every

2.5 添加指針

2.5.1 創建一個線狀指針

lv_meter_indicator_t * lv_meter_add_needle_line(lv_obj_t *meter,             /* 表盤對象 */lv_meter_scale_t *scale,     /* 對應的刻度盤 */uint16_t width,              /* 指針的線寬，單位：像素 */lv_color_t color,            /* 指針的顏色 */int16_t r_mod                /* 指針的長度相對于半徑的比例，0-100 */
);

2.5.2 創建一個弧形指示器（可用于范圍值顯示）

lv_meter_indicator_t * arc = lv_meter_add_arc(meter, scale, thickness, color, r_mod);

2.6 設置指針值

lv_meter_set_indicator_value(meter, indicator, value);

3 簡單示例

3.1 溫度

3.1.1 數據標準

1. 溫度范圍：0°C ~ 100°C

2. 儀表角度范圍：270°（從左下到右下）

3. 主刻度每 10°C 一個，次刻度每 5°C 一個

4. 一個紅色針狀指針

5. 可以通過定時器或動畫更新溫度值

3.1.2 具體代碼

static lv_obj_t* meter;
static lv_meter_indicator_t* needle;/* 模擬溫度值更新的回調函數 */
static void update_temperature_cb(lv_timer_t* timer) {static int temp = 0;lv_meter_set_indicator_value(meter, needle, temp);temp = (temp + 1) % 101; // 循環 0 ~ 100
}void create_temperature_meter(void) {/* 創建儀表對象 */meter = lv_meter_create(lv_scr_act());/* 設置大小和位置 */lv_obj_set_size(meter, 200, 200);lv_obj_center(meter);/* 添加刻度盤 */lv_meter_scale_t* scale = lv_meter_add_scale(meter);///* 設置數值范圍 0~100°C，角度覆蓋 270°，從135°起始 */lv_meter_set_scale_range(meter, scale, 0, 100, 270, 135);/* 設置刻度線（小刻度） */lv_meter_set_scale_ticks(meter, scale, 21, 2, 10, lv_palette_main(LV_PALETTE_GREY));///* 設置主刻度線（帶數字標簽） */lv_meter_set_scale_major_ticks(meter, scale, 5, 4, 15, lv_color_black(), 10);/* 添加一個紅色指針（長度為90%） */needle = lv_meter_add_needle_line(meter, scale, 6, lv_palette_main(LV_PALETTE_RED), 1);lv_meter_indicator_t* arc_green = lv_meter_add_arc(meter, scale,6,lv_palette_main(LV_PALETTE_GREEN), 4); // 線寬6px，圓弧在刻度后面lv_meter_set_indicator_start_value(meter, arc_green, 0);lv_meter_set_indicator_end_value(meter, arc_green, 60);lv_meter_indicator_t* arc_orange = lv_meter_add_arc(meter, scale,6,lv_palette_main(LV_PALETTE_ORANGE), 4);lv_meter_set_indicator_start_value(meter, arc_orange, 60);lv_meter_set_indicator_end_value(meter, arc_orange, 80);lv_meter_indicator_t* arc_red = lv_meter_add_arc(meter, scale,6, lv_palette_main(LV_PALETTE_RED), 4);lv_meter_set_indicator_start_value(meter, arc_red, 80);lv_meter_set_indicator_end_value(meter, arc_red, 100);///* 初始溫度設為25°C */lv_meter_set_indicator_value(meter, needle, 25);///* 創建定時器，每500ms更新一次溫度 */lv_timer_create(update_temperature_cb, 500, NULL);
}