NarraLeaf

useAvatar

useAvatar 钩子，返回当前对话行的头像可见性、图片地址、角色与立绘

useAvatar 返回当前 Say 台词下解析后的对话框头像信息：是否显示、图片地址、以及关联的 Character / 立绘 Image。须在 Dialog 子树内使用（与 useDialog 同源上下文）

用法

import { Avatar, Dialog, Nametag, Texts, useAvatar } from "narraleaf-react";

function GameDialog() {
    const avatar = useAvatar();

    return (
        <Dialog>
            <div
                style={{
                    display: "grid",
                    gridTemplateColumns: avatar.visible ? "120px 1fr" : "1fr",
                    gap: 16,
                }}
            >
                {avatar.visible && <Avatar style={{ width: 120, height: 120 }} />}
                <div>
                    <Nametag />
                    <Texts />
                </div>
            </div>
        </Dialog>
    );
}

返回值：DialogAvatarContext

  • visible: boolean — 当前行是否应显示头像图
  • src: string | null — 供 <img src> 使用的地址；无图时为 null
  • character: Character | null — 说话人角色（若有）
  • portrait: Image | null — 参与解析的舞台立绘 Image（若有）
  • alt: string — 建议的图片替代文本

visible 为 false 时，src 为 null。Avatar 内部使用本 Hook，无头像时不渲染任何节点

可见时的元数据

const avatar = useAvatar();

if (avatar.visible) {
    console.log(avatar.src);
    console.log(avatar.character?.state.name);
    console.log(avatar.portrait?.config.name);
}

与 <Avatar /> 的关系

Avatar 会调用 useAvatar() 并输出 <img>，默认尺寸 96×96、objectFit: "cover"、borderRadius: 6。可通过 className / style 覆盖

参见

  • Dialog — 解析顺序、Character / Sentence 配置
  • Character — setAvatar、addPortrait、setPortraits
  • 类型：DialogAvatarContext（自 narraleaf-react 导出）

本页目录

用法返回值：DialogAvatarContext可见时的元数据与 <Avatar /> 的关系参见