素材库

文档版本: v1.1.2页面更新: 2026-08-20

素材库用于创建可调整尺寸和颜色的像素按钮、边框或面板。素材不是整张图片缩放，而是将 PNG 按 JSON 的四边切片规则重新拼接，因此四个角会保持原始像素风格。

使用方式#

在像素编辑器上方点击“素材库”。
选择内置素材，或导入一份 JSON 配置文件。
插入后，在右侧“素材图层”中调整 X/Y、宽高和主体色。
需要直接使用画笔修改时，先点击“栅格化素材图层”。栅格化后不能再修改该图层的素材参数。

素材图层会随 .kmstudio 工程保存，工程中会内嵌其源 PNG，不依赖原始素材目录。

可视化创建素材#

不需要手写 JSON。打开“素材库”后点击“新建素材”，按以下方式完成：

选择一张 PNG 源图。
在左侧拖动四条蓝色切片线，分别确定左、上、右、下的固定边缘。中间区域至少保留 1px。
在中间设置预览尺寸，检查角落是否保持原样、边缘和中心是否按预期循环。
设置各区域的填充方式、最小尺寸及内容安全边距。
对需要随主体色改变的轮廓、阴影、主体和高光，勾选对应角色后，从源图取色或打开调色板填写模板色。
保存后会在用户素材目录自动生成 <素材 ID>.png 和 <素材 ID>.material.json，可立即插入像素编辑器。

素材 ID 只能包含字母、数字、下划线和连字符；使用相同 ID 保存会更新同一份用户素材。

素材文件#

一份外部素材由同目录下的 PNG 和 JSON 组成：

stone_button.png
stone_button.material.json

JSON 中的 image 必须是相对 PNG 路径，不能指向 JSON 目录以外的位置。首版只支持 PNG 源图。

{
  "format": "kamenu-ui-material",
  "version": 1,
  "id": "stone_button",
  "name": "石质按钮",
  "image": "stone_button.png",
  "category": "buttons",
  "slice": { "left": 4, "top": 3, "right": 5, "bottom": 4 },
  "regions": {
    "top": "tileX",
    "bottom": "tileX",
    "left": "tileY",
    "right": "tileY",
    "center": "tile"
  },
  "minimumWidth": 16,
  "minimumHeight": 12,
  "contentPadding": { "left": 5, "top": 4, "right": 6, "bottom": 5 },
  "defaultPrimaryColor": "#4C8BFFFF",
  "palette": [
    { "sourceColor": "#202020", "role": "outline", "transform": "darken", "amount": 0.78 },
    { "sourceColor": "#606060", "role": "shadow", "transform": "darken", "amount": 0.44 },
    { "sourceColor": "#A0A0A0", "role": "body", "transform": "primary" },
    { "sourceColor": "#E0E0E0", "role": "highlight", "transform": "lighten", "amount": 0.38 }
  ]
}

left、top、right、bottom 可以分别设置，不要求相等，也不固定为 3px。四角保持原大小；上、下仅横向循环；左、右仅纵向循环；中心默认横纵循环。目标尺寸无法容纳完整循环时，最后一块会被像素级裁剪，不会被模糊拉伸。

颜色规则#

palette 只替换明确声明的模板 RGB 色值，透明度保留原像素的透明度。常用规则为：

primary：直接使用用户选择的主体色。
darken：主体色向黑色混合，用于轮廓和阴影。
lighten：主体色向白色混合，用于高光。
fixed：使用 fixedColor，不随主体色改变。

同一个模板 RGB 色不能在 palette 中重复。需要保持不变的装饰不要使用已声明的模板色。

区域模式#

fixed：固定显示一次。
tile：横纵循环。
tileX：仅横向循环。
tileY：仅纵向循环。
fill：使用区域左上像素填充。
stretch：最近邻拉伸。仅在素材明确需要时使用。
none：不绘制该区域。

像素按钮通常应使用 tile、tileX 和 tileY，避免 stretch。