# # @retractable 和 @retractable-body

## # 简介

`@retractable` 和 `@retractable-body` 是两个自定义指令，需要结合使用，用于实现标签页面板的可收缩（浮动）和可固定功能。这两个指令可以在应用程序中帮助您创建具有可收缩和可固定功能的标签页，从而提供更好的用户体验。

## # 用法

### # 基本用法

要创建具有可收缩和可固定功能的标签页，请结合使用 `@retractable` 和 `@retractable-body` 指令。以下是一个基本用法示例：

    <gtab name="home-tab" group="tabs" body="home-tab-body" @retractable></gtab>
    <gtab name="edit-tab" group="tabs" body="edit-tab-body" @retractable></gtab>
    <div name="home-tab-body" @retractable-body style="position: relative"></div>
    <div name="edit-tab-body" @retractable-body style="position: relative"></div>

使用 `@retractable` 和 `@retractable-body` 指令后，您的标签页面板将具有可收缩和可固定的功能，用户可以点击标签或按钮来展开或折叠页面内容。

### # 开启 `@retractable` 功能

由于默认布局模板没有集成该指令，因此要开启相关功能，就需要用户做进一步处理。目前用户可能出现的场景：

1. 用户使用默认内置布局
2. 用户使用自定义布局

下面，我们针对这两个场景说明其用法。

### # 使用默认内置布局时如何开启功能

可以使用 Fragment 配置 开启该功能：

    var CustomAppearance= UIExtension.appearances.AdaptiveAppearance.extend({
        getDefaultFragments: function() {
            return [{
                    target: '@gtab', // Select all <gtab> components
                    config: {
                        attrs: {
                            '@retractable': ''
                        }
                    }
                }, {
                    target: 'toolbar-tab-bodies', // Select the container of the tab panel

                    config: {
                        attrs: {
                            '@retractable-body': ''
                        }
                    }
                }];
        }
    })
    new PDFUI({
        // ...more options
        appearance: CustomAppearance
    })

### # 使用自定义布局时如何开启功能

在自定义布局中，您只需将 `@retractable` 指令添加到 `<gtab>` 组件中即可。`@retractable-body` 指令可以添加到每个标签页面板上或标签页面板的容器上，前提是标签页面板都放置在同一个容器组件下。但是，前一种方法更繁琐，我们不推荐使用。以下是在容器组件中使用 `@retractable-body` 指令的示例：

    var CustomAppearance= UIExtension.appearances.AdaptiveAppearance.extend({
        getLayoutTemplate: function(){
            return `
                <webpdf @aria:circular-focus>
                    <toolbar name="toolbar" class="fv__ui-toolbar-scrollable" @aria:role="navigation" @aria:label="aria:labels.toolbar.nav-title">
                        <div class="fv__ui-tab-nav" name="toolbar-tabs" @alt.menu=">::activated()" @aria:toolbar.tablist>
                            <gtab @retractable name="home-tab" group="toolbar-tab" body="fv--home-tab-paddle" text="toolbar.tabs.home.title" @aria:toolbar.tab active @portfolio.deactive></gtab>
                            <gtab @retractable name="comment-tab" group="toolbar-tab" body="fv--comment-tab-paddle" text="toolbar.tabs.comment.title" @aria:toolbar.tab @portfolio.unsupport></gtab>
                        </div>
                        <div class="fv__ui-toolbar-tab-bodies" name="toolbar-tab-bodies" @retractable-body>
                            <paddle exclude-devices="tablet" name="fv--home-tab-paddle" @portfolio.unsupport @aria:toolbar>
                                <group-list name="home-toolbar-group-list">
                                    <group name="home-tab-group-hand" retain-count="3">
                                        <hand-ribbon-button></hand-ribbon-button>
                                        <selection-ribbon-dropdown></selection-ribbon-dropdown>
                                        <snapshot-ribbon-button @hide-on-sr></snapshot-ribbon-button>
                                    </group>
                                    <group name="home-tab-group-io" retain-count="1" shrink-title="toolbar.more.document.title">
                                        <open-file-ribbon-dropdown></open-file-ribbon-dropdown>
                                        <download-file-ribbon-button></download-file-ribbon-button>
                                        <print:print-ribbon-button></print:print-ribbon-button>
                                    </group>
                                    <!-- ... more components -->
                                </group-list>
                            </paddle>
                            <paddle exclude-devices="tablet" name="fv--comment-tab-paddle" @portfolio.unsupport @aria:toolbar visible="false" @lazy.idle>
                                <group-list name="comment-toolbar-group-list">
                                    <group name="comment-tab-group-hand" retain-count="3">
                                        <hand-ribbon-button></hand-ribbon-button>
                                        <selection-ribbon-dropdown></selection-ribbon-dropdown>
                                        <zoom-ribbon-dropdown></zoom-ribbon-dropdown>
                                    </group>
                                    <group name="comment-tab-group-note" retain-count="3">
                                        <create-note-ribbon-button></create-note-ribbon-button>
                                        <create-attachment-ribbon-button></create-attachment-ribbon-button>
                                    </group>
                                    <!-- ... more components -->
                                </group-list>
                            </paddle>
                        </div>
                    </toolbar>
                    <!-- ... more components -->
                </webpdf>
            `;
        }
    })
    new PDFUI({
        // ...more options
        appearance: CustomAppearance
    })

## # 示例

以下是一个完整的示例，演示了如何使用 `@retractable` 和 `@retractable-body` 指令创建一个具有可收缩标签页面的简单应用程序。请点击 `run` 按钮运行。

    <style>
        .my-layer {
            width: 400px;
            height: 300px;
        }
        .flex-container {
            display: flex;
            justify-content: space-between;
        }
    </style>
    <script>
        var CustomAppearance = UIExtension.appearances.AdaptiveAppearance.extend({
            getDefaultFragments: function() {
                debugger;
                return [{
                    target: '@gtab', // Select all <gtab> components
                    config: {
                        attrs: {
                            '@retractable': ''
                        }
                    }
                }, {
                    target: 'toolbar-tab-bodies', // Select the container of the tab panel

                    config: {
                        attrs: {
                            '@retractable-body': ''
                        }
                    }
                }];
            }
        });
        var libPath = window.top.location.origin + '/lib';
        var pdfui = new UIExtension.PDFUI({
                viewerOptions: {
                    libPath: libPath,
                    jr: {
                        licenseSN: licenseSN,
                        licenseKey: licenseKey
                    }
                },
                renderTo: document.body,
                appearance: CustomAppearance,
                addons: []
        });
    </script>

    {
        "iframeOptions": {
            "style": "height: 500px"
        }
    }

## # 注意事项

1. `@retractable` 指令会在标签页面板中插入一个按钮组件，该组件显示在标签页面板的右下角。这是通过使用绝对定位 (`position: absolute`) 来实现的。因此，您需要确保标签页面板的 `position` CSS 属性值不能设置为 `static`。

2. `@restractable-body` 指令的作用是在用户收起标签页面板时，向组件的 className 中加入 `fv__ui-retractable-floating-bar`。其默认设置了 `position: absolute;left:0;right:0` 样式，目的是使面板宽度和父节点相同，并且不占用容器的高度。在实际应用场景中，可能因为父节点没有设置宽度和定位等问题，面板无法正常显示。用户应根据其特定的应用场景调整此样式值。