图像 | NarraLeaf-React

用于角色与背景美术的 `Image` 元素，涵盖标签式、分层与直接资源图片、穿戴物与变暗

此类继承自 Displayable

Image 用于控制角色的外观显示。它只负责外观，不处理对话——对话由 Character 负责

公共方法

构造函数

一个 Image 只能使用标签模式、图层模式或 src 模式中的一种，不能混用

config: Partial<IImageUserConfig> - 参见 IImageUserConfig

标签模式（Tag-based）

适用于带有表情、服装等标签的立绘组合：

const image = new Image({
    src: {
        groups: [
        ["happy", "sad", "angry"],
        ["shirt", "jacket", "t-shirt"],
        ["trousers", "skirt", "shorts"],
        ],
        defaults: ["happy", "shirt", "trousers"],
        resolve: (emotion, top, bottom) => `https://你的/图片/路径/${emotion}_${top}_${bottom}.png`
    } as const,
});
// 默认图片为 `https://你的/图片/路径/happy_shirt_trousers.png`

同一组或不同组中不能有重复标签：

const image = new Image({
    src: {
        groups: [
        ["a", "b", "c"],
        ["1", "2", "3"],
        ["a"], // 无效，标签 "a" 已存在
        ["x", "y", "y"], // 无效，标签 "y" 重复
        ],
        defaults: ["a"], // 无效，默认值必须包含完整标签集
    } as const,
    /* ... */
});

图层模式（Layered）

适用于按部件导出的美术资源。5 种表情 + 4 套服装只需 5 + 4 个文件，而非 5 × 4 张合成图：

const yuko = new Image({
    src: {
        // 从底到顶
        layers: [
            "yuko/body.png",                                              // 常驻层
            {uniform: "yuko/uniform.png", casual: "yuko/casual.png"},     // 服装组
            {uniform: null, casual: "yuko/jacket.png"},                   // 跟随服装组
            {happy: "yuko/brows_happy.png", sad: "yuko/brows_sad.png"},   // 表情组
            {happy: "yuko/mouth_happy.png", sad: "yuko/mouth_sad.png"},   // 跟随表情组
            {happy: null, sad: "yuko/tears.png"},                         // null 表示不绘制
        ],
        defaults: ["uniform", "happy"],
    },
});

层叠图像由 char() 方法驱动。一个组由它的标签集合标识，提供同一组标签的每一层都由同一个组驱动：

yuko.char(["sad"]);                    // 眉毛、嘴巴、眼泪一起改变
yuko.char(["casual"]);                 // 服装和外套一起改变
yuko.char(["casual", "sad"]);          // 一次改变多个组
yuko.char(["sad"], new Dissolve({ duration: 300 })); // 带转场

layers 的每一项可以是：

字符串 — 常驻层，始终绘制
变体映射 — 以标签为键的互斥 src，null 表示该标签下不绘制
函数 — LayerResolver，根据当前标签派生 src（预加载器不可见，优先使用变体映射）
null — 不绘制

数组顺序即叠放顺序。defaults 为每个组指定一个默认标签

同一图像的所有层应共用一张画布，通过居中对齐。作用于整个图像的效果（转场、darken、opacity 等）会整体施加到图层栈上

跟随一个组的层必须重复该组的完整标签集合。只提供部分标签会声明一个新组，导致冲突。每个组都必须在 defaults 中列出一个标签

源文件模式（Src-based）

无标签时直接指定图片路径：

const image = new Image({
    src: "https://你的/图片/路径.png",
});

可穿戴模式（Wearable）

为图像添加附属物品，随主图像一起变换：

const child = new Image({
    /* ... */
});
const parent = new Image({
    /* ... */
}).wear(child);

注意： 一个图像只能有一个父图像

useLayer

为图像指定 Layer：

const layer = new Layer(/* ... */);

image.useLayer(layer);

链式方法

char

切换角色形象：

src: ImageSrc | Color | SelectElementFromEach<Tags> | FlexibleTuple<SelectElementFromEach<Tags>> | LayerTagsOf<Layers>[] - 图像源
transition?: ImageTransition - 转场效果，参见 Transition

image.char("你的/图片/路径", new Dissolve({ duration: 1000 }));

标签模式示例：

// happy, shirt, trousers
const image = new Image({
    src: {
        groups: [
            ["happy", "sad", "angry"],
            ["shirt", "jacket", "t-shirt"],
            ["trousers", "skirt", "shorts"],
        ],
        defaults: ["happy", "shirt", "trousers"],
        /* ... */
    } as const,
});

image.char(["jacket", "t-shirt"], new Dissolve({ duration: 1000 }));
image.char(["angry"], new Dissolve({ duration: 1000 }));

图层模式示例：

const yuko = new Image({
    src: {
        layers: [
            "yuko/body.png",
            {uniform: "yuko/uniform.png", casual: "yuko/casual.png"},
            {uniform: null, casual: "yuko/jacket.png"},
            {happy: "yuko/brows_happy.png", sad: "yuko/brows_sad.png"},
            {happy: "yuko/mouth_happy.png", sad: "yuko/mouth_sad.png"},
        ],
        defaults: ["uniform", "happy"],
    },
});

yuko.char(["sad"], new Dissolve({ duration: 300 }));
yuko.char(["casual"]);

darken

调整图像明暗：

darkness: number - 暗度，0（全亮）到 1（全黑）
duration?: number - 过渡时长（ms），不传则立即生效
easing?: TransformDefinitions.EasingDefinition - 缓动函数

image.darken(0.5, 500, "easeIn");
image.darken(0.5, 500); // 默认缓动
image.darken(0.5);      // 立即生效

公共方法

addWearable

添加可穿戴物品：

children: Image | Image[] - 可穿戴图像或数组
返回 this

const childImage = new Image(/* ... */);

image.addWearable(childImage);

wear

addWearable 的别名

bindWearable

将此图像绑定为父图像的可穿戴物品：

parent: Image - 父图像
返回 this

childImage.bindWearable(parentImage);

asWearableOf

bindWearable 的别名

图像

本页目录