Skip to content

面板布局

Jump to bottom
ESLyric edited this page Jan 5, 2025 · 15 revisions

面板布局

当前ESLyric面板布局处于开发过程中，内容可能更改

ESLyric支持自定义歌词面板元素布局。

布局文件

ESLyric使用XML作为布局文件格式。所有配置内容不区分大小写。
布局文件位置: %fb2k_profile%/eslyric-data/layout，布局xml文件可直接放置在该目录下，也可以新建目录放置，但插件仅加载Layout目录第一层级子目录下的xml文件。

布局由不同功能的布局元素组成。

元素类型

当前支持的布局元素:

名称 说明
container 容器类型布局元素，用于容纳其他布局元素，类似与DUI中的分离器
label 标签布局元素，用于显示文本，支持格式化标题表达式、自定义字体及执行命令等
albumart 封面图片布局元素，用于显示封面图片
button 按钮布局元素，用于显示按钮控件
lyric 歌词布局元素，用于显示歌词内容

此外, panel元素为特殊的container类型，行为及属性与container一致，仅作为布局根节点使用:

<panel ...>
 <!--elements-->
</panel>

元素属性

通用属性

所有布局元素支持的属性

属性 值 说明
name 任意值 元素的名称panel元素名称用于布局名称
其他元素名称在设置面板勾选显示元素标识时显示
anchor left top right bottom
hfill vfill hcenter vcenter
center fill 		锚点
left 以左侧元素或父元素左侧为锚点
top以上侧元素或父元素上侧为锚点
right以右侧元素或父元素右侧为锚点
bottom以下侧元素或父元素下侧为锚点
hfill以左右侧元素或父元素左右侧为锚点
vfill以上下侧元素或父元素上下侧为锚点
hcenter水平居中，左边距偏移
vcenter垂直居中，上边距偏移
center居中，左/上边距偏移
fill以四侧为描点
margin l l,t l,t,r,b格式数值
数值可为固定数值或百分比数值或混合使用
 边距
l 四侧边距为相同值
l，t 左右边距为l，上下边距为t
l，t，r，b分别设置左，上，右，下边距
固定数值: 边距为固定值
百分比数值: l，r为父元素宽度百分占比， t，b为父元素高度百分占比
margin-left 固定数值，如80
百分比数值，如80% 		左边距
固定数值: 左边距为固定值
百分比数值: 左边距占父元素宽度百分比
margin-top 固定数值，如80
百分比数值，如80% 		右边距
固定数值: 右边距为固定值
百分比数值: 右边距占父元素宽度百分比
margin-right 固定数值，如80
百分比数值，如80% 		上边距
固定数值: 上边距为固定值
百分比数值: 左边距占父元素高度百分比
margin-bottom 固定数值，如80
百分比数值，如80% 		下边距
固定数值: 下边距为固定值
百分比数值: 左边距占父元素高度百分比
left 同 margin-left 同 margin-left
top 同 margin-top 同 margin-top
width 固定数值， 如80
百分比数值， 如80%
自适应 *
自动 auto 		宽度
固定数值: 固定宽度
百分比数值: 占用父元素宽度的比例
自适应: 根据父元素剩余宽度自动计算，仅在stack容器内生效(实验性质，某些情况下表现可能非预期)
自动: 自动计算高度，当前仅以下布局元素支持
① label 根据绘制文本高度设置
② container 根据子布局元素高度设置
height 同 width 同 width，但针对高度
min-width 固定数值，如80 最小宽度当设置最小宽度后，且未设置小于最小宽度时隐藏(hide-min=0或未设置)，则元素宽度不小于该值
max-width 固定数值，如80 最大宽度
min-height 固定数值，如80 最小高度，行为同 min-width但针对高度
max-height 固定数值，如80 最大高度
visibility 格式化标题表达式 布局元素显示条件，设置后执行表达式后返回1则显示，否则隐藏元素
hide-min boolean 设置 min-width 或 min-height 后，当设置为true时且元素当前宽高小于对应值则隐藏该元素
hide-empty boolean 布局元素内容为空时是否隐藏该元素
label: 显示文本为空
albumart: 无专辑图片
lyric: 无歌词
container: 无子布局元素
overflow hide 布局元素尺寸超出父元素时:
hide: 隐藏该元素
aspect-ratio float 布局元素宽高比, 宽高皆有效时优先参考宽度
1.0 宽高一致

特有属性

除通用属性外，各布局元素支持的属性。

panel

<panel>为布局根节点(容器)，与container属性与行为一致(见container一节说明), 但包含额外属性:

属性 值 说明
features 位标记 声明布局支持的特性，为以下标记的或组合: 0x01: 始终显示布局，未指定时播放停止后将不绘制布局

container

<container>用于定义容器类型元素:

属性 值 说明
layout stack free 布局类型
stack: 支持左右或上下排布元素(默认)
free: 自由排布元素，元素间可重叠
orientation vertical horizonal layout设置为stack时子布局元素的排布方向
vertical: 垂直排布(默认)
horizonal: 水平排布
justify start middle end justify layout设置为stack时子布局元素对齐方式
start: 从起始位置对齐
middle: 从中间对齐(默认)
end: 从末尾位置对齐
justify: 插入空白空间以填充区域

label

<label>用于定义标签类型元素:

属性 值 说明
caption 任意值，支持格式化标题表达式 文本内容
text-align left center right 文本对齐方式，默认为center
text-color #rrggbb
rgb(r，g，b) r,g,b [0,255]
rgba(r,g,b,a), r,g,b [0,255], a [0,1.0]		 文本颜色，如#112233 rgb(11,22,33) rgba(11,22,33,0.5)。 默认为面板设置值
highlight-color 同 text-color 高亮色，配置command后悬浮鼠标显示，默认为面板设置值
font-family 字体名称 字体名称。默认为面板设置值
font-size 数值 文本字体点数大小。默认为面板设置值
bold boolean 设置粗体风格
italic boolean 设置斜体风格
nowrap boolean 是否换行，默认为false
line-space 数值 换行时多行文本间的间距，默认为1
command 见command格式 鼠标左键单击时执行的命令
loop cycle shuttle 文本绘制超出元素宽度后滚动
cycle: 循环滚动
shuttle: 左右来回滚动
loop-speed 数值 文本滚动速度，默认为20
loop-padding 数值 文本循环滚动时，前后文本间距，默认为80
always-eval boolean 始终计算caption标题表达式而不依赖当前是否正在播放。注:标题表达式需要与音轨无关，否则将出现非预期行为

command格式

插件当前支持以下类型的命令:

命令前缀 说明
mm:// 执行主菜单命令，如mm://Playback/Play or pause
cm:// 执行当前播放音轨上下文命令，如cm://Properties
lib:// 查询媒体库，如lib://%%artist%% IS %artist%
esl:// 执行内置命令，如esl://OpenFiles

当前自带命令

命令 说明
OpenFiles 打开文件
Preferences 参数选项
Next 下一首
Previous 上一首
Random 随机播放
Pause 暂停
Play 播放
PlayOrPause 播放或暂停
Stop 停止
Mute 静音开/关
AddFiles 添加文件
AddDirectory 添加目录
Properties 当前播放音轨属性
PlaybackOrderDefault 播放次序-默认
PlaybackOrderRepeatPlaylist 播放次序-重复播放列表
PlaybackOrderRepeatTrack 播放次序-重复音轨
PlaybackOrderRandom 播放次序-随机
PlaybackOrderShuffleTracks 播放次序-乱序音轨
PlaybackOrderShuffleAlbums 播放次序-乱序专辑
PlaybackOrderShuffleFolders 播放次序-乱序目录

为支持多语言的foobar2000, 在布局中指定命令时可以引入多语言配置。 配置文件固定为布局xml文件同目录下的locales.xml文件，文件格式:

<?xml version="1.0" encoding="UTF-8"?>
<locales>
    <locale type="en_US">
        <string key="PlayOrPause">Playback/Play or pause</string>
    </locale>
    <locale type="zh_CN">
        <string key="PlayOrPause">播放/播放或暂停</string>
    </locale>
</locales>

其中key为字符串标识。放置该xml文件后，插件在加载布局时会同时加载该xml文件。此时使用${key}形式指定命令，如:

mm://${PlayOrPause}

注: 布局基于ESLyric高级设置中配置的语言选取locales.xml中的本地化文本，因此当插件语言与播放器语言不一致时可能出现无法执行的情况。

自定义字体

label支持font-family属性指定不同的字体，同时插件会加载布局文件同目录下的fonts目录，该目录下字体无需手动安装，正确指定名称后即可使用。

目录结构示意:

├───layout
│   │   Layout.xsd
│   │   readme.txt
│   │
│   └───Style1
│       │   locales.xml <-- 本地化文件
│       │   main.xml <-- 布局文件
│       │
│       ├───fonts <-- 字体目录，自动加载
│       │       xxxxx.ttf

albumart

<albumart> 用于定义封面图片类型元素:

属性 值 说明
album-art front artist back disc 封面类型，默认为front
follow-background boolean 封面图片跟随面板设置，注意：当同时设置album-art后且封面存在时将忽略该值
use-stub boolean 封面不存在时是否获取stub封面，与面板设置独立
fitness fill fit stretch center 封面显示契合度
radius float 封面显示圆角半径
radius-x float 封面显示圆角x半径
radius-y float 封面显示圆角y半径
stub 相对路径 当无封面时显示的图片相对路径

button

<button> 用于定义按钮控件元素:

属性 值 说明
background 相对路径 图片相对路径
同名同格式但带有_hover后缀的图片自动作为悬浮状态图片
如指定images/play.png则images/play_hover.png为悬浮状态图片
command 命令 参考label部分command格式说明

插件获取图片时的搜索顺序:

  1. 相对于xml布局文件相对路径
  2. 相对于xml布局文件同目录下images目录的相对路径

因此对于配置background="images/play.png"，假设当前布局文件路径为c:\path\to\layout.xml

  1. 搜索c:\path\to\images\play.png，存在时使用
  2. 搜索c:\path\to\images\images\play.png，存在时使用

lyric

<lyric> 用于定义歌词类型元素:

属性 值 说明
banner-text 任意值 设置未播放时的banner文本，与高级设置用的banner文本独立。同时需要设置panel的features属性包含位0x01以始终显示布局元素
fallback 格式化标题文本 与插件面板设置独立

seekbar

<seekbar> 用于定义音轨进度条:

属性 值 说明
background-color 颜色 背景颜色
foreground-color 颜色 前景颜色
thumb-color 颜色 滑块颜色
thumb-width 数值 滑块宽度，方形滑块时有效
thumb-height 数值 滑块高度，方形滑块时有效
thumb-radius 数值 滑块半径,设置时滑块为圆形，否则为方形滑块
track-width 数值 进度轨道宽度，垂直方向时有效
track-height 数值 进度轨道高度，水平方向时有效
always-show-thumb boolean 总是显示滑块，默认为true
vertical boolean 是否为竖向滑块，默认为false
radius 数值 圆角半径

volume

<volume> 用于定义音量滑块，属性与<seekbar>一致。

扩展标题字段

字段 说明
%esl_search_progress% 当前歌词搜索进度
%esl_search_service% 当前歌词搜索服务
%esl_has_playing_lyric% 当前是否有播放歌词 [0,1]
%fb2k_playback_order% 播放次序
%fb2k_volume% 当前音量dB
%fb2k_volume_scaled% 当前音量dB*100, 整数值
%fb2k_volume_level_5% 当前音量等级, 整数值 [0-4]
%fb2k_volume_level_7% 当前音量等级, 整数值 [0-6]

布局示例

<layout xmlns="https://github.com/ESLyric/layout" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://github.com/ESLyric/layout ./Layout.xsd">
    <panel layout="stack" name="Sample layout" orientation="horizontal" features="1">
        <container name="left-panel" anchor="vfill" width="44%" min-width="600" hide-min="1">
            <albumart anchor="right" margin-right="18%" width="60%" min-width="360" aspect-ratio="1.0" radius="10" stub="images/default.png" follow-background="1" />
            <container name="meta-info" anchor="right" margin-right="18%" width="60%" height="auto" justify="start">
                <label name="title" margin="0,20,0,0" caption="%title%" command="cm://{Properties}" text-align="left" text-color="rgb(255,255,255)" highlight-color="rgb(0,160,0)" font-size="14" width="100%" height="auto" loop="cycle" nowrap="1"/>
                <label name="artist" margin="0,14,0,0" caption="[%artist%]" text-align="left" text-color="rgb(200,200,200,0.8)" font-size="14" width="100%" height="auto" hide-empty="1"/>
                <label name="album" margin="0,14,0,0" caption="[%album% ]$if(%date%, © %date% )" text-align="left" text-color="rgb(200,200,200,0.8)" font-size="12" width="100%" height="auto" loop="cycle" hide-empty="1"/>
                <label name="tech-info" margin="0,14,0,0" caption="%codec% / %bitrate%kbps / $ifgreater($mod(%samplerate%,1000),0,$insert($div(%samplerate%,100),'.',$sub($len($div(%samplerate%,100)),1)) kHz,$div(%samplerate%,1000) kHz)" text-align="left" text-color="rgb(200,200,200,0.8)" font-size="12" loop="shuttle" width="100%" height="auto" />
            </container>
        </container>
        <container name="right-panel" anchor="vfill" width="*">
            <lyric margin="0,60,0,60" text-align="left" anchor="fill" banner-text="Style for foobar2000"/>
        </container>
    </panel>
</layout>
Clone this wiki locally