Kodi插件开发：如何用xbmcplugin.addDirectoryItems与ListItem正确设置URL

我正在为Kodi 19（Python3环境）更新一款插件，但是Kodi的官方文档十分混乱，互联网上能搜索到的相关代码大多已经过时，我无法理解如何使用xbmcplugin.addDirectoryItems正确创建包含条目的虚拟目录。
以下是我的简化代码：

我的KODI菜单函数 #

def menu_live():
  # 这里从网络获取数据
  datas = api.get_live_videos()
  
  listing = datas_to_list(datas)

  sortable_by = (xbmcplugin.SORT_METHOD_DATE,
                 xbmcplugin.SORT_METHOD_DURATION)

  xbmcplugin.addDirectoryItems(common.plugin.handle, listing, len(listing))
  xbmcplugin.addSortMethod(common.plugin.handle, xbmcplugin.SORT_METHOD_LABEL)
  xbmcplugin.endOfDirectory(common.plugin.handle)

虚拟目录条目列表构建函数 #

def datas_to_list(datas):
    list_items = []

    if datas and len(datas):
        for data in datas:
            li = data_to_listitem(data)
            url = li.getPath()
            list_items.append((url, li, True))

    return list_items

ListItem对象创建函数 #

def data_to_listitem(data):
    # 解析数据构造xbmcgui.ListItem
    label = ...
    url = ...
    ...

    list_item = xbmcgui.ListItem(label)
    list_item.setPath(url)

    return list_item

我的疑问 #

我不太清楚媒体URL的交互逻辑：看起来可以通过list_item.setPath(url)的方式在xbmcgui.ListItem中定义URL，这种方式在我看来是合理的，直接给条目本身设置URL。但后续往列表中添加条目时，似乎还需要再次设置URL：

li = data_to_listitem(data)
list_items.append((url, li, True))

这看起来很奇怪，因为这意味着你需要在构建条目的函数外部也获取到URL值。我目前的临时解决方案是：

li = data_to_listitem(data)
url = li.getPath() # 从ListItem中读取之前定义的URL
list_items.append((url, li, True))

这段代码可以正常运行，但我的疑问是：既然我可以通过setPath()给ListItem定义URL，为什么还要在往列表追加ListItem时重复填写该URL？

问题解答 #

这个重复传URL的设定是Kodi Python API的历史遗留设计，核心逻辑如下：

• 早期Kodi版本的xbmcgui.ListItem没有setPath()/getPath()接口，所有条目关联的跳转、播放URL只能通过addDirectoryItems接收的三元组第一个参数传递，后续版本新增ListItem的path属性后，为了兼容存量的旧版本插件代码，官方没有修改addDirectoryItems的参数规则
• 实际运行时Kodi会优先读取三元组里的URL值，只有当三元组的URL为空时，才会 fallback 读取ListItem内部设置的path属性。你现在用li.getPath()获取URL再填到三元组的写法是完全符合规范的，不存在性能或者逻辑问题，属于Kodi插件开发社区通用的标准写法
• 补充说明：如果你的插件不需要兼容Kodi 18及更早版本，也可以直接给三元组第一个参数传空字符串''，实测Kodi 19+会正常读取ListItem内部的path，不过还是推荐你目前的写法，兼容性更好

内容的提问来源于stack exchange，提问作者gordie