引言

一、技术背景

1.1 九宫格分割的核心思想

• 4 个角区域（不可拉伸）：左上、右上、左下、右下（保持原始像素，用于显示圆角、边框等细节）。
• 4 个边区域（单向拉伸）：上边、下边、左边、右边（沿水平或垂直方向拉伸，保持边线连续）。
• 1 个中心区域（双向拉伸）：中间部分（沿水平和垂直方向同时拉伸，填充剩余空间）。

1.2 Cocos2d 中的实现机制

二、应用使用场景

三、不同场景下的代码实现

3.1 场景1：基础按钮九宫格拉伸（Cocos Creator 3.x）

需求描述

代码实现

// Scale9Button.ets（Cocos Creator 3.x）
import { _decorator, Component, Node, Sprite, SpriteFrame, resources, UITransform, Label } from 'cc';
const { ccclass, property } = _decorator;

@ccclass('Scale9Button')
export class Scale9Button extends Component {
    @property
    buttonImagePath: string = 'button_bg'; // 九宫格背景图片路径（resources/button_bg.png）
    @property
    buttonText: string = '点击我';

    start() {
        // 1. 加载九宫格背景图片（需提前在图片导入设置中勾选“九宫格”并设置 capInsets）
        resources.load<SpriteFrame>(this.buttonImagePath, SpriteFrame, (err, spriteFrame) => {
            if (err) {
                console.error(`加载按钮背景失败: ${err}`);
                return;
            }

            // 2. 创建背景精灵（使用 Scale9Sprite）
            const background = new Node('ButtonBackground');
            const bgSprite = background.addComponent(Sprite);
            bgSprite.spriteFrame = spriteFrame;
            // 启用九宫格拉伸（通过 Sprite 的 sizeMode 和 capInsets 设置）
            bgSprite.type = Sprite.Type.SLICED; // 关键：设置为 SLICED 模式（即九宫格模式）
            background.setParent(this.node);

            // 3. 创建按钮文本
            const textLabel = new Node('ButtonText');
            const text = textLabel.addComponent(Label);
            text.string = this.buttonText;
            text.fontSize = 24;
            text.color = new Color(255, 255, 255);
            text.anchorX = 0.5;
            text.anchorY = 0.5;
            text.x = 0;
            text.y = 0;
            textLabel.setParent(background);

            // 4. 设置按钮整体大小（模拟动态调整，如根据文本长度）
            const uiTransform = background.getComponent(UITransform) || background.addComponent(UITransform);
            uiTransform.width = 200; // 初始宽度（可根据需求动态计算）
            uiTransform.height = 60; // 固定高度
            uiTransform.anchorX = 0.5;
            uiTransform.anchorY = 0.5;
        });
    }
}

关键点解释

• 九宫格模式设置：bgSprite.type = Sprite.Type.SLICED是核心，告诉引擎使用九宫格拉伸逻辑（需图片本身已配置 capInsets）。
• 图片导入配置：在 Cocos Creator 的 资源管理器​ 中选中背景图片（如 button_bg.png），在属性检查器中勾选 “九宫格”，并设置 “Cap Insets”（定义 4 个角的边界，如左上角 x=10, y=10, 宽度=20, 高度=20）。
• 动态尺寸：通过调整 UITransform的 width和 height，按钮背景会自动按九宫格规则拉伸（边角不变形）。

3.2 场景2：对话框面板九宫格拉伸（Cocos2d-x C++）

需求描述

代码实现

// DialogPanel.cpp（Cocos2d-x 4.x）
#include "DialogPanel.h"
#include "cocos2d.h"

USING_NS_CC;

Scene* DialogPanel::createScene() {
    return DialogPanel::create();
}

bool DialogPanel::init() {
    if (!Scene::init()) return false;

    auto visibleSize = Director::getInstance()->getVisibleSize();
    Vec2 origin = Director::getInstance()->getVisibleOrigin();

    // 1. 加载九宫格背景图片（需提前在 TexturePacker 或 Cocos Studio 中配置 capInsets）
    auto background = ui::Scale9Sprite::create("dialog_bg.png");
    if (!background) {
        CCLOG("加载对话框背景失败！");
        return false;
    }

    // 2. 设置九宫格的裁剪区域（capInsets：定义 4 个角的边界）
    // 假设 dialog_bg.png 的角区域为左上角 (20, 20) 宽高 (20, 20)
    background->setCapInsets(Rect(20, 20, 20, 20)); 

    // 3. 设置初始尺寸（模拟动态调整，如根据文本行数）
    background->setContentSize(Size(400, 200)); // 初始宽度 400，高度 200
    background->setPosition(Vec2(visibleSize.width / 2 + origin.x, visibleSize.height / 2 + origin.y));
    this->addChild(background, 0);

    // 4. 添加对话框文本（模拟动态内容）
    auto label = Label::createWithTTF("这是一段很长的对话内容，用于测试九宫格面板的拉伸效果！", "fonts/Marker Felt.ttf", 20);
    if (!label) {
        CCLOG("创建文本失败！");
        return false;
    }
    label->setPosition(Vec2(background->getContentSize().width / 2, background->getContentSize().height / 2));
    label->setTextColor(Color4B::WHITE);
    background->addChild(label);

    return true;
}

关键点解释

• capInsets 设置：setCapInsets(Rect(20, 20, 20, 20))定义了 4 个角区域的边界（左上角起始坐标 (20, 20)，宽度和高度均为 20 像素）。
• 动态尺寸调整：通过 setContentSize改变背景面板的大小，九宫格精灵会自动拉伸中间部分和边区域，保持角区域不变形。
• 文本适配：对话框文本居中显示在面板中央，面板高度可根据文本行数动态增加（如通过代码计算文本高度并调整 setContentSize）。

3.3 场景3：输入框九宫格拉伸（Cocos Creator 3.x + 动态输入）

需求描述

代码实现

// Scale9InputBox.ets（Cocos Creator 3.x）
import { _decorator, Component, Node, Sprite, SpriteFrame, resources, UITransform, EditBox, input } from 'cc';
const { ccclass, property } = _decorator;

@ccclass('Scale9InputBox')
export class Scale9InputBox extends Component {
    @property
    inputBoxImagePath: string = 'input_bg'; // 九宫格输入框背景图片路径
    private inputBox: Node = null!;
    private editBox: EditBox = null!;
    private uiTransform: UITransform = null?;

    start() {
        // 1. 加载九宫格背景图片
        resources.load<SpriteFrame>(this.inputBoxImagePath, SpriteFrame, (err, spriteFrame) => {
            if (err) {
                console.error(`加载输入框背景失败: ${err}`);
                return;
            }

            // 2. 创建输入框背景（九宫格模式）
            this.inputBox = new Node('InputBoxBackground');
            const bgSprite = this.inputBox.addComponent(Sprite);
            bgSprite.spriteFrame = spriteFrame;
            bgSprite.type = Sprite.Type.SLICED; // 关键：九宫格模式
            this.inputBox.setParent(this.node);

            // 3. 创建 EditBox（用户输入组件）
            this.editBox = this.inputBox.addComponent(EditBox);
            this.editBox.placeholderLabel.string = '请输入内容...';
            this.editBox.fontSize = 20;
            this.editBox.fontColor = new Color(0, 0, 0);
            this.editBox.backgroundColor = new Color(255, 255, 255, 0); // 透明背景（由九宫格背景显示）
            this.editBox.placeholderFontSize = 20;
            this.editBox.placeholderFontColor = new Color(128, 128, 128);

            // 4. 设置初始尺寸
            this.uiTransform = this.inputBox.getComponent(UITransform) || this.inputBox.addComponent(UITransform);
            this.uiTransform.width = 300;
            this.uiTransform.height = 50;
            this.uiTransform.anchorX = 0.5;
            this.uiTransform.anchorY = 0.5;
            this.inputBox.setPosition(0, 0, 0);

            // 5. 监听文本变化，动态调整输入框宽度（模拟根据输入内容长度）
            this.editBox.node.on(EditBox.EventType.TEXT_CHANGED, this.onTextChanged, this);
        });
    }

    private onTextChanged(text: string) {
        // 根据文本长度动态调整输入框宽度（简单示例：每 2 个字符增加 10 像素）
        const baseWidth = 200;
        const charWidth = 10;
        const newWidth = baseWidth + Math.min(text.length * charWidth, 200); // 限制最大宽度
        this.uiTransform!.width = newWidth;
    }
}

关键点解释

• 动态宽度调整：通过监听 EditBox的 TEXT_CHANGED事件，根据输入文本的长度动态调整输入框的 width（九宫格背景自动拉伸中间部分）。
• 用户交互：EditBox组件提供文本输入功能，背景通过九宫格精灵保持边框圆角不变形。
• 限制逻辑：示例中限制了输入框的最大宽度（避免过度拉伸），实际项目中可根据设计需求调整。

四、原理解释与核心特性

4.1 九宫格拉伸的工作流程

sequenceDiagram
    participant Developer as 开发者（代码/图片配置）
    participant Engine as Cocos2d 引擎
    participant Sprite as Sprite 组件
    participant Texture as 纹理（原始图片）
    participant Renderer as 渲染引擎

    Developer->>Engine: 加载图片并配置 capInsets（定义 4 个角边界）
    Developer->>Sprite: 设置 type = SLICED（九宫格模式）
    Engine->>Texture: 解码原始图片为纹理
    Engine->>Sprite: 根据 capInsets 将纹理切割为 9 个区域（4 角 + 4 边 + 1 中心）
    Developer->>Sprite: 调整节点尺寸（如 width/height 变化）
    Sprite->>Engine: 请求重新渲染
    Engine->>Renderer: 按九宫格规则拉伸中间和边区域，保持角区域不变
    Renderer-->>屏幕: 显示最终 UI 元素（边角无变形）

• capInsets 定义：通过 Rect参数指定 4 个角区域的起始坐标和尺寸（如左上角 x=10, y=10, 宽度=20, 高度=20），引擎据此将纹理划分为 9 块。
• 拉伸规则：当节点尺寸变化时，引擎仅对中间区域（双向拉伸）和边区域（单向拉伸）进行调整，角区域（如左上、右下）始终保持原始像素。
• 模式切换：通过 Sprite.Type.SLICED（九宫格模式）告诉引擎启用该逻辑（对比 SIMPLE模式为直接拉伸，TILED模式为平铺）。

4.2 核心特性

五、环境准备

5.1 开发工具与项目配置

• 引擎：Cocos Creator 3.x（推荐，内置九宫格模式支持）或 Cocos2d-x 4.x（需使用 ui::Scale9Sprite）。
• 图片配置：
  • Cocos Creator：在资源管理器中选中图片，勾选 “九宫格”​ 并设置 “Cap Insets”（定义 4 个角边界）。
  • Cocos2d-x：通过 TexturePacker 等工具导出带九宫格信息的图片，或在代码中通过 setCapInsets设置。
• 依赖库：Cocos2d-x 需包含 ui模块（如 #include "ui/CocosGUI.h"）。

5.2 实际应用示例（完整可运行）

场景：动态按钮（宽度随文本变化）

1. 资源准备：准备一张带圆角的按钮背景图片（如 button_bg.png），在 Cocos Creator 中配置 capInsets（如角区域为左上角 (10, 10) 宽高 (10, 10)）。
2. 代码实现：参考 场景1​ 的代码，动态调整按钮的 UITransform.width（如根据用户输入的文本长度）。
3. 运行结果：按钮背景的边角圆润不变形，中间部分随宽度增加无缝拉伸。

六、测试步骤与详细代码

测试1：验证边角不变形

1. 步骤：运行按钮场景，将按钮的 width调整为远大于原始尺寸（如 500 像素）。
2. 预期：按钮的 4 个角（如圆角）保持原始形状，中间部分拉伸填充，无变形。

测试2：验证动态适配

1. 步骤：在输入框场景中输入长文本（如 50 个字符），观察输入框宽度是否动态增加。
2. 预期：输入框背景的边角不变形，中间部分随宽度拉伸，文本始终居中显示。

测试3：验证多场景复用

1. 步骤：将同一张九宫格图片（如 panel_bg.png）用于按钮和对话框，检查是否均能正确拉伸。
2. 预期：不同 UI 元素（按钮、对话框）通过调整 capInsets 和尺寸，均能实现预期的拉伸效果。

七、部署场景

• 移动端游戏：适配不同分辨率的手机屏幕（如 iPhone 14 和 Android 平板），确保 UI 元素（如按钮、面板）在所有设备上显示一致。
• PC 端游戏：支持窗口大小调整（如用户拖拽窗口边缘），九宫格 UI 元素自动适配新尺寸。
• Web 游戏：通过动态调整九宫格背景，兼容不同浏览器的窗口缩放比例。

八、疑难解答

8.1 常见问题

8.2 调试技巧

• 可视化 capInsets：在 Cocos Creator 的资源管理器中选中图片，通过 “九宫格预览”​ 查看角区域的划分是否合理。
• 日志输出：在代码中打印 UITransform的尺寸变化（如 console.log(uiTransform.width)），确认动态调整逻辑是否生效。
• 工具辅助：使用 TexturePacker预生成带九宫格信息的图片，避免手动配置错误。

九、未来展望与技术趋势

1. 自动九宫格生成：工具链（如 TexturePacker）可能集成 AI 算法，自动识别图片的角区域并生成最优 capInsets，减少手动配置。
2. 动态九宫格参数：支持运行时动态调整 capInsets（如根据 UI 元素的形状变化实时修改拉伸规则）。
3. 跨引擎兼容：九宫格格式（如 capInsets 数据）可能成为通用标准，被 Unity、Godot 等引擎支持，实现资源复用。
4. 3D UI 扩展：九宫格拉伸逻辑延伸至 3D UI 元素（如 3D 按钮的贴图拉伸），提升全场景游戏的 UI 一致性。

十、总结

• 原理：通过将图片划分为 9 个区域（4 角 + 4 边 + 1 中心），仅拉伸中间和边区域，保持角区域原始形状。
• 应用：广泛应用于按钮、对话框、输入框等需要动态调整尺寸的 UI 元素，提升多分辨率设备的视觉一致性。
• 优势：无需为不同尺寸设计多张图片，减少资源数量，同时保证 UI 的精致细节（如圆角、边框）。