【Lively Wallpaper 】插件开发：LivelyProperties.json 全流程实战教程

文章目录

- [一、Lively Wallpaper 插件开发：LivelyProperties.json 全流程实战教程](#一、Lively Wallpaper 插件开发：LivelyProperties.json 全流程实战教程)
- - 配置文件位置
- [二、LivelyProperties.json 标准格式](#二、LivelyProperties.json 标准格式)
- - [2.1 整体结构](#2.1 整体结构)
  - [2.2 支持的配置类型及示例](#2.2 支持的配置类型及示例)
  - - 基础常用类型
    - 其他规范类型（进阶掌握）
  - [2.3 完整配置文件示例](#2.3 完整配置文件示例)
- [三、配置文件的读取与设置（核心 API 实战）](#三、配置文件的读取与设置（核心 API 实战）)
- - [3.1 初始化读取配置](#3.1 初始化读取配置)
  - [3.2 主动修改并保存配置](#3.2 主动修改并保存配置)
- 四、监听配置面板修改并响应更新
- - [4.1 核心监听逻辑](#4.1 核心监听逻辑)
  - [4.2 完整业务逻辑示例](#4.2 完整业务逻辑示例)
- 五、全流程调试与注意事项
- - [5.1 调试技巧](#5.1 调试技巧)
  - [5.2 常见坑点](#5.2 常见坑点)
- 六、总结

一、Lively Wallpaper 插件开发：LivelyProperties.json 全流程实战教程

本文所有配置均严格遵循 Lively 官方 JSON Schema 规范（官方文档链接）。

Lively Wallpaper 是一款开源的动态壁纸工具，LivelyProperties.json 是其插件配置面板的核心配置文件。本文将从配置文件格式 、配置读取/设置 、监听配置修改三个维度，完整讲解插件与配置文件交互的全流程，帮助你快速实现可配置化的 Lively 插件。

为直观理解插件与配置文件的交互全流程，结合官方规范及 API 用法，绘制核心流程图如下（清晰展示配置定义、读取、修改、保存的完整链路）：
方式一
方式二
定义LivelyProperties.json
插件加载初始化
调用lively.getProperty读取配置
应用配置到插件逻辑
配置修改方式
用户在Lively面板修改
触发propertyChanged事件
插件代码主动修改
调用lively.setProperty提交配置
Lively框架自动持久化
更新LivelyProperties.json
插件响应更新重新应用

流程图说明：插件无法直接操作配置文件，所有配置保存均需通过 Lively 提供的 API 及框架完成，确保配置同步生效。

LivelyProperties.json：定义插件配置面板 UI 组件（如滑块、复选框、颜色选择器）的 JSON 文件，同时也是配置值的持久化存储载体，需严格遵循官方 JSON Schema 规范编写。
双向交互逻辑：Lively 框架仅负责渲染配置面板，配置的读取、修改、保存、响应更新均需插件通过 API 手动实现，无自动双向绑定。
核心 API：lively.getProperty()（读）、lively.setProperty()（写）、propertyChanged 事件（监听修改）。

配置文件位置

Lively 加载插件后，核心配置文件 LivelyProperties.json 及插件相关配置的保存路径，与你提供的路径密切相关，具体分两类（对应你给出的路径场景），明确区分「插件本体配置」和「临时缓存配置」：

插件本体配置 ：对应路径 %USERPROFILE%\AppData\Local\Lively Wallpaper\Library\wallpapers\0wj1biqk.f41，该路径是当前加载插件（文件夹 0wj1biqk.f41 即为单个插件的存储目录）的根目录，LivelyProperties.json 直接保存在此文件夹内，插件的所有持久化配置（如你在配置面板修改的参数）均会写入此文件，关闭 Lively 后不会丢失，也是插件加载时优先读取配置的路径。
插件临时缓存配置 ：对应路径 %USERPROFILE%\AppData\Local\Lively Wallpaper\Library\SaveData\wptmp\ejfpwota.jcf，该路径是 Lively 加载插件时的临时缓存目录，其中 ejfpwota.jcf 为临时缓存文件（非标准 JSON 格式），仅用于插件加载时的临时配置缓存，关闭 Lively 后可能被清理，不建议手动修改此路径下的文件。

补充说明：每个插件对应 wallpapers 目录下一个独立的随机命名文件夹（如 0wj1biqk.f41），其内部的 LivelyProperties.json 是该插件的专属配置文件，与其他插件配置互不干扰；而 SaveData\wptmp 目录下的临时文件，会根据插件加载情况动态生成和清理，无需手动管理。

二、LivelyProperties.json 标准格式

2.1 整体结构

文件整体为 JSON 对象，每个键值对对应一个配置项（如开关、滑块），配置项在面板中的展示顺序可自定义。

核心规则：

必须是合法 JSON 格式（无注释、引号闭合、逗号规范），额外属性需符合官方 additionalProperties 定义；
每个配置项通过 type 字段指定 UI 类型，type 仅支持官方 enum 定义的 8 种类型；
配置项的键（JSON 对象的 key）为配置项唯一标识（插件通过此标识读写值，不可重复）；
text 为面板显示的配置名称（官方规范必填字段，部分类型除外）；
所有配置项必须包含 type 和 value 字段（官方强制必填），部分类型需补充专属必填字段。

2.2 支持的配置类型及示例

基础常用类型

类型（type）	用途	核心必填字段	规范示例
`slider`	数值滑块（调节连续数值）	type、value、text、min、max、step	`{"text":"透明度","type":"slider","value":1.0,"min":0,"max":1,"step":0.01}`
`dropdown`	下拉菜单（单选固定选项）	type、value、text、items	`{"text":"播放速度","type":"dropdown","value":0,"items":["慢速","正常"]}`
`color`	颜色选择器（选择十六进制颜色）	type、value、text	`{"text":"背景色","type":"color","value":"#000000"}`
`checkbox`	复选框（布尔值开关）	type、value、text	`{"text":"自动播放","type":"checkbox","value":true}`

其他规范类型（进阶掌握）

类型（type）	用途	核心必填字段	规范示例
`textbox`	文本输入框（输入自定义文本）	type、value、text	`{"text":"自定义文字","type":"textbox","value":"Hello Lively"}`
`folderDropdown`	文件夹下拉框（选择指定目录文件）	type、value、text、filter、folder	`{"text":"选择图片","type":"folderDropdown","value":"","filter":"*.jpg
`button`	按钮（触发自定义事件）	type、value、text	`{"text":"重置配置","type":"button","value":"重置"}`
`label`	标签（仅显示文本，无交互）	type、value（无额外必填字段）	`{"type":"label","value":"外观设置区域"}`

2.3 完整配置文件示例

JSON 复制代码

{
  "matrixColor": {
    "text": "字体颜色",
    "type": "color",
    "value": "#00FF46"
  },
  "isAutoPlay": {
    "text": "自动播放动画",
    "type": "checkbox",
    "value": true
  },
  "playSpeed": {
    "text": "播放速度",
    "type": "slider",
    "value": 1.0,
    "min": 0.5,
    "max": 2.0,
    "step": 0.1
  },
  "textAlign": {
    "text": "文字对齐",
    "type": "dropdown",
    "value": 1,
    "items": ["左对齐", "居中", "右对齐"]
  },
  "customText": {
    "text": "自定义文字",
    "type": "textbox",
    "value": "Hello Lively"
  },
  "bgImage": {
    "text": "背景图片",
    "type": "folderDropdown",
    "value": "",
    "filter": "*.jpg|*.png",
    "folder": "./images"
  },
  "resetBtn": {
    "text": "重置按钮",
    "type": "button",
    "value": "重置配置"
  },
  "settingTip": {
    "type": "label",
    "value": "文本"
  }
}

key 即 LivelyProperties.json 文件中，每个配置项对应的 JSON 对象的键（自定义命名），核心要求如下：

作用： 作为配置项的唯一标识，插件通过该 key 调用 lively.getProperty()/lively.setProperty() 读写配置值；

约束： 不可重复、需符合 JSON 键名规范（无特殊字符、不空格），无固定命名要求，建议语义化（如示例中的 matrixColor、playSpeed）；

示例： 配置

{"matrixColor": {"type": "color", "value": "#00FF46", "text": "字体颜色"}}

中，matrixColor 即为该配置项的 key。

三、配置文件的读取与设置（核心 API 实战）

插件通过 Lively 提供的 JavaScript API 实现配置的读写，以下是完整的代码示例及解析，API 调用与官方规范配置完全适配。

3.1 初始化读取配置

插件加载时，优先读取配置文件中的值（无值则使用默认值），并应用到插件逻辑中，默认值类型需与官方规范中value 类型一致。

JavaScript 复制代码

// 初始化读取配置
// 1. 读取单个配置项：lively.getProperty(key, defaultValue)
// 格式：getProperty(配置唯一标识, 默认值)，默认值类型与官方规范一致
const isAutoPlay = lively.getProperty("isAutoPlay", true); // checkbox 类型（布尔值）
const playSpeed = lively.getProperty("playSpeed", 1.0);   // slider 类型（数字）
const matrixColor = lively.getProperty("matrixColor", "#00FF46"); // color 类型（字符串）
const textAlign = lively.getProperty("textAlign", 1);    // dropdown 类型（数字，选项索引）

// 2. 应用配置到插件（示例：设置画布背景色、动画速度）
function applyConfig() {
  const canvas = document.getElementById("lively-canvas");
  if (canvas) {
    canvas.style.color = matrixColor; // 应用颜色配置
    // 结合其他配置实现业务逻辑
    console.log(`自动播放：${isAutoPlay}，播放速度：${playSpeed}x`);
  }
}

// 初始化时执行配置应用
applyConfig();

3.2 主动修改并保存配置

插件无法直接修改 LivelyProperties.json 文件本身，所有配置的保存均需通过 Lively 提供的 lively.setProperty() API 实现，调用该 API 后，Lively 框架会自动将修改后的配置持久化到对应路径的配置文件中，无需手动操作文件。

JavaScript 复制代码

// 主动修改并保存配置
// 示例：按钮点击后修改播放速度（slider 类型）
document.getElementById("speedUpBtn").addEventListener("click", () => {
  // 1. 获取当前值
  let currentSpeed = lively.getProperty("playSpeed", 1.0);
  // 2. 修改值（不超过最大值，符合 slider 类型的官方约束）
  currentSpeed = Math.min(currentSpeed + 0.1, 2.0);
  // 3. 保存到配置文件：lively.setProperty(key, value)
  lively.setProperty("playSpeed", currentSpeed);
  // 4. 重新应用配置
  applyConfig();
});

// 示例：修改 checkbox 类型配置（布尔值）
document.getElementById("togglePlayBtn").addEventListener("click", () => {
  const newState = !lively.getProperty("isAutoPlay", true);
  lively.setProperty("isAutoPlay", newState);
  applyConfig();
});

四、监听配置面板修改并响应更新

当用户在 Lively 配置面板手动修改配置时，插件需监听 propertyChanged 事件，实时响应更新，确保面板修改与插件逻辑同步。

4.1 核心监听逻辑

JavaScript 复制代码

// 监听配置修改事件
// 监听配置修改事件：lively.on("propertyChanged", 回调函数)
lively.on("propertyChanged", (e) => {
  // e.detail：包含修改的配置信息 { key: 配置标识, value: 新值 }
  const { key, value } = e.detail;
  
  // 方式1：针对性响应单个配置修改（适配各官方类型）
  switch (key) {
    case "isAutoPlay":
      // checkbox 类型，value 为布尔值
      togglePlay(value);       // 执行播放/暂停逻辑
      break;
    case "playSpeed":
      // slider 类型，value 为数字
      updateAnimationSpeed(value); // 更新动画速度
      break;
    case "matrixColor":
      // color 类型，value 为十六进制字符串
      updateTextColor(value); // 重新应用文字颜色
      break;
    case "textAlign":
      // dropdown 类型，value 为选项索引
      updateTextAlign(value); // 更新文字对齐方式
      break;
    default:
      applyConfig(); // 其他配置修改，统一重新应用
      break;
  }
  
  // 可选：主动保存修改（Lively 面板修改后会自动保存，此步骤可省略）
  // lively.setProperty(key, value);
});

4.2 完整业务逻辑示例

JavaScript 复制代码

// 完整业务逻辑
// 定义业务函数（适配各类型配置）
function togglePlay(isAutoPlay) {
  const anim = document.getElementById("animation");
  if (isAutoPlay) {
    anim.style.animationPlayState = "running";
  } else {
    anim.style.animationPlayState = "paused";
  }
}

function updateAnimationSpeed(speed) {
  const anim = document.getElementById("animation");
  anim.style.animationDuration = `${10 / speed}s`; // 速度越快，时长越短
}

function updateTextColor(color) {
  const text = document.getElementById("customText");
  text.style.color = color;
}

function updateTextAlign(alignIndex) {
  const text = document.getElementById("customText");
  const alignMap = [ "left", "center", "right" ]; // 与 dropdown items 顺序一致
  text.style.textAlign = alignMap[alignIndex];
}

// 初始化 + 监听完整流程
window.onload = () => {
  // 1. 初始化读取配置（适配所有官方类型）
  let isAutoPlay = lively.getProperty("isAutoPlay", true);
  let playSpeed = lively.getProperty("playSpeed", 1.0);
  let matrixColor = lively.getProperty("matrixColor", "#00FF46");
  let textAlign = lively.getProperty("textAlign", 1);
  
  // 2. 应用初始配置
  applyConfig();
  togglePlay(isAutoPlay);
  updateAnimationSpeed(playSpeed);
  updateTextColor(matrixColor);
  updateTextAlign(textAlign);
  
  // 3. 监听配置修改，实时响应
  lively.on("propertyChanged", (e) => {
    const { key, value } = e.detail;
    // 更新本地变量并响应修改
    if (key === "isAutoPlay") togglePlay(value);
    if (key === "playSpeed") updateAnimationSpeed(value);
    if (key === "matrixColor") updateTextColor(value);
    if (key === "textAlign") updateTextAlign(value);
    // 其他类型配置统一应用
    applyConfig();
  });
};

五、全流程调试与注意事项

5.1 调试技巧

配置文件位置：插件目录下直接放置 LivelyProperties.json，Lively 会自动识别，若识别失败，优先检查 JSON 格式和字段是否符合官方规范；
日志调试：使用 console.log() 打印配置值，重点排查配置值类型是否与官方要求一致；

5.2 常见坑点

JSON 格式错误：禁止添加注释（////* */）、确保引号/逗号规范，否则面板无法渲染；同时禁止添加官方规范中未定义的属性（官方 additionalProperties 约束）；
配置键重复：多个配置项使用相同的 key（JSON 对象的键）会导致读写混乱，需保证每个配置项 key 唯一；
未监听事件：用户修改面板配置后无响应，大概率是未绑定 propertyChanged 事件，或事件回调中未处理对应配置项；
类型不匹配：读取配置时默认值类型需与官方规范中 value 类型一致（如 slider 用数字，checkbox 用布尔值，dropdown 用数字索引）；
缺失必填字段：部分类型（如 slider、folderDropdown）缺失官方要求的专属必填字段（如 slider 缺失 min/max/step），会导致对应参数控件无法使用；
type 类型错误：使用官方 enum 之外的 type 值（如原文档的 combobox、file），会导致配置项无法识别，需严格使用 8 种官方标准类型。

六、总结

LivelyProperties.json 是"UI 定义 + 数据存储"双角色，整体为 JSON 对象，需严格遵循官方 JSON Schema 规范，type 仅支持 8 种官方类型；
所有配置项必须包含type 和 value 字段，部分类型需补充专属必填字段（如 slider 需 min/max/step），缺失会导致参数控件无法使用；
配置读取用 lively.getProperty(key, 默认值)，保存用 lively.setProperty(key, 新值)，默认值和修改后的值需符合对应类型的官方约束；
监听 propertyChanged 事件是实现"面板修改→插件响应"的核心，需在事件回调中更新插件逻辑；
无自动双向绑定，所有配置交互逻辑需插件手动实现。

掌握以上流程后，你可以轻松实现任意复杂度的可配置化 Lively 插件，比如动态调整动画参数、自定义外观、加载本地资源等。