@retractable and @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. 用户使用自定义布局

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

1. 使用默认布局时如何开启功能

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

var CustomAppearance= UIExtension.appearances.AdaptiveAppearance.extend({
    getDefaultFragments: function() {
        return [{
                target: '@gtab', // 选择所有 <gtab> components
                config: {
                    attrs: {
                        '@retractable': ''
                    }
                }
            }, {
                target: 'toolbar-tab-bodies', // 选择标签面板的容器
                config: {
                    attrs: {
                        '@retractable-body': ''
                    }
                }
            }];
    }
})
new PDFUI({
    // ...more options
    appearance: CustomAppearance
})

2. 使用自定义布局

自定义布局中，只要在 <gtab> 组件上添加 @retractable 指令即可， 而 @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', // 选择所有 <gtab> components
                config: {
                    attrs: {
                        '@retractable': ''
                    }
                }
            }, {
                target: 'toolbar-tab-bodies', // 选择标签面板的容器
                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 这些样式，目的是让面板宽度和父节点相同，并且不占用容器的高度，在实际应用场景可能因为父节点没有设置宽度和定位等等问题而无法正常显示，请用户根据具体应用场景调整此样式值。