配置报告设置

项目
01/18/2024

通过使用 Power BI 客户端 API，可以在应用程序中嵌入 Power BI 分析。使用此客户端库嵌入 Power BI 报表时，需向 API 提供有关该报表的信息。

可以使用配置对象来存储有关 Power BI 报表的信息。嵌入报表时，然后将该对象传递给 API。

除了向 API 授予对报表的访问权限外，还可以使用配置对象来自定义报表的外观和行为。例如，可以在配置对象中调整筛选器可见性、导航访问和位置设置。

以下部分介绍如何嵌入和配置 Power BI 内容。

提供配置信息

IReportLoadConfiguration 接口显示配置对象可以提供给 Power BI 客户端 API 的有关报表的属性：

interface IReportLoadConfiguration {
    embedUrl: string;
    accessToken: string;
    id: string;
    groupId?: string;
    settings?: ISettings;
    bookmark?: IApplyBookmarkRequest;
    pageName?: string;
    filters?: ReportLevelFilters[];
    slicers?: ISlicer[];
    theme?: IReportTheme;
    contrastMode?: ContrastMode;
    datasetBinding?: IDatasetBinding;
    permissions?: Permissions;
    viewMode?: ViewMode;
    tokenType?: TokenType;
}

有关此接口的必需参数的说明和显示如何嵌入报表的代码示例，请参阅嵌入报表。

自定义设置

以下部分介绍如何使用 settings 属性调整嵌入式 Power BI 报表的外观和行为。若要在已加载报表时更新报表设置，请使用 report.updateSettings 方法。有关详细信息，请参阅在运行时更新报表设置。

窗格

使用单个 panes 属性控制 Power BI 报表中所有窗格的外观，如以下代码所示：

let embedConfig = {
    ...
    settings: {
        panes: {
            bookmarks: {
                visible: true
            },
            fields: {
                expanded: false
            },
            filters: {
                expanded: false,
                visible: true
            },
            pageNavigation: {
                visible: false
            },
            selection: {
                visible: true
            },
            syncSlicers: {
                visible: true
            },
            visualizations: {
                expanded: false
            }
        }
    }
};

从下表中，可以看到每个 panes 属性支持哪些值：

属性	可见	展开
`bookmarks`	✔	❌
`fields`	✔	✔
`filters`	✔	✔
`pageNavigation`	✔	❌
`selection`	✔	❌
`syncSlicers`	✔	❌
`visualizations`	✔	✔

“筛选器”窗格

默认情况下，筛选器窗格可见。如果要隐藏此窗格，请使用 filterPaneEnabled 属性，如以下代码所示：

let embedConfig = {
    ...
    settings: {
        filterPaneEnabled: false
    }
};

注意

panes 属性替换属性filterPaneEnabled。为了保持向后兼容性，属性 filterPaneEnabled 仍然存在。但是，应避免同时使用这两个属性。

默认情况下，页面导航箭头在嵌入的报表上可见。若要隐藏这些箭头，请使用 navContentPaneEnabled 属性，如以下代码所示：

let embedConfig = {
    ...
    settings: {
        navContentPaneEnabled: false
    }
};

注意

panes 属性替换属性navContentPaneEnabled。为了保持向后兼容性，属性 navContentPaneEnabled 仍然存在。但是，应避免同时使用这两个属性。

页面导航窗格显示在报表底部，若要使用新的垂直页面窗格， position 可以设置属性：

let embedConfig = {
    ...
    settings: {
        panes:{
            pageNavigation: {
                visible: true,
                position: PagesPosition.Left
            }
        }    
    }
};

注意

不能使用 updateSettings更改页面导航窗格的位置。

Bars

使用属性设置操作栏和状态栏的 bars 可见性。

“操作”栏

以下代码使操作栏可见：

let embedConfig = {
    ...
    settings: {
        bars: {
            actionBar: {
                visible: true
            }
        }
    }
};

或者，在视图模式下，也可以使用 actionBarEnabled URL 参数：

let embedConfig = {
   ...
   embedUrl: embedUrl + "&actionBarEnabled=true"
};

注意

在视图模式下，仅 组织方案的嵌入 支持操作栏。

对于视图模式下的操作栏，建议为 Azure AD 应用程序启用 UserState.ReadWrite.All 权限。需要此权限才能允许最终用户将报表添加到其收藏夹，以及启用个人书签和持久筛选器。

状态栏

状态栏包含画布缩放控制器，该控制器提供在画布上缩放的功能。

以下代码使状态栏可见：

let embedConfig = {
    ...
    settings: {
        bars: {
            statusBar: {
                visible: true
            }
        }
    }
};

区域设置

localeSettings使用属性指定嵌入报表的语言和格式：

中的 languagelocaleSettings 属性由两个字母组成的两个部分，每个部分由连字符分隔：

语言定义 Power BI 用于本地化的语言。语言示例包括 en (English) 、 es (spanish) 和 tr (土耳其语) 。
locale 定义 Power BI 用于日期、货币和其他相关内容的文本格式。区域设置的示例包括美国 (英语) 、 ES (西班牙) 和 TR (Türkiye) 。

有关可用语言和区域的列表，请参阅支持的语言。

以下代码将特定值分配给这些 localeSettings：

let embedConfig = {
    ...
    settings: {
        localeSettings: {
            language: "en-us"
        }
    }
};

注意

加载报表后，区域设置无法更改。若要更改报表区域设置，请通过调用 powerbi.reset(element)重置 iframe，然后再次嵌入报表。

透明背景

默认情况下，嵌入内容的背景为白色，边距为灰色。如果需要，可以为嵌入内容提供透明背景。然后，可以将所需的样式应用于包含嵌入内容的 HTML div 元素。元素 div 的样式随后变为可见。

使用此代码使嵌入内容的背景透明：

let embedConfig = {
    ...
    settings: {
        background: models.BackgroundType.Transparent
    }
};

超链接单击行为

可以控制表中超链接的行为，也可以控制矩阵现成的视觉对象。默认情况下，超链接将打开一个新窗口。

下面列出了可用的行为模式：

enum HyperlinkClickBehavior {
    Navigate,
    NavigateAndRaiseEvent,
    RaiseEvent
}

Navigate - URL 将加载到新的浏览上下文中。
NavigateAndRaiseEvent - URL 将加载到新的浏览上下文中，并引发事件 dataHyperlinkClicked 。
RaiseEvent - 阻止 URL 单击的默认行为并引发 dataHyperlinkClicked 事件。

使用此代码更改链接的行为以引发事件：

let embedConfig = {
    ...
    settings: {
        hyperlinkClickBehavior: HyperlinkClickBehavior.RaiseEvent
    }
};

dataHyperlinkClicked单击现成的表或矩阵视觉对象上的超链接并且行为为 NavigateAndRaiseEvent 或 RaiseEvent时，将触发事件。

report.on('dataHyperlinkClicked', () => {
    ...
});

有关处理事件的详细信息，请参阅如何处理事件。

可视化呈现的事件

可以侦听每个呈现视觉对象的事件。默认情况下，视觉对象呈现的事件处于禁用状态。

使用以下代码触发 visualRendered 事件：

let embedConfig = {
    ...
    settings: {
        visualRenderedEvents: true
    }
};

呈现 visualRendered 视觉对象并在 visualRenderedEvents 报表设置上启用时触发事件。

report.on('visualRendered', () => {
    ...
});

有关处理事件的详细信息，请参阅如何处理事件。

注意

由于视觉对象可能由于用户交互而呈现，因此建议仅在需要时才启用此事件。

错误消息

如果要在嵌入式报表中显示自定义错误消息，请使用 hideErrors 属性隐藏默认的 Power BI 嵌入错误消息。然后，代码可以采用适合你的应用设计的方式处理错误事件。有关替代默认错误的详细信息，请参阅替代默认错误消息。

使用此代码隐藏默认错误消息：

let embedConfig = {
    ...
    settings: {
        hideErrors: true
    }
};

自定义选项

以下部分介绍如何使用其他属性进一步自定义嵌入式 Power BI 报表的外观和行为。

默认页

您可以控制嵌入报表的哪个页面最初显示。默认情况下，初始页是最近修改的页面，这是上次保存报表时的活动页。可以通过使用 pageName 属性并为其提供要显示的页面的名称来替代此行为。但是，如果 Power BI 中不存在具有该名称的页面，则打开该页面的请求将失败。

以下代码演示如何将应用配置为显示特定页面：

let embedConfig = {
    ...
    pageName: 'ReportSection3'
};

负载筛选器时

可以控制应用应用于嵌入报表的筛选器。默认情况下，报表最初使用保存到报表中的筛选器。但是，如果要调整筛选器，有两个选项：

配置要与保存的筛选器一起使用的其他筛选器。以下代码演示如何使用 filters 属性追加其他筛选器：
```
let embedConfig = {
    ...
    filters: [...]
};
```
将保存的筛选器替换为新集。方法 setFilters 提供了一种动态更改报表筛选器的方法。如果在分阶段嵌入期间使用此方法，则可以替代报表最初应用的筛选器。有关构造筛选器和使用 setFilters 方法的详细信息，请参阅控制报表筛选器。

加载切片器时

可以控制应用应用于嵌入报表的切片器的状态。默认情况下，API 使用保存到报表的切片器。但是，可以使用 slicers 属性修改现有切片器的状态，如以下代码所示：

embedConfig = {
    ...
    slicers: slicerArray,
};

有关修改切片器状态的详细信息，请参阅控制报表切片器。

加载书签时

通过使用 bookmark 属性，可以将书签应用于嵌入的报表。有关使用书签捕获当前配置的报表页视图的详细信息，请参阅书签。

可以通过提供书签名称或状态来指定要使用的书签。如果提供书签名称，Power BI 报表需要包含具有该名称的已保存书签。

属性 bookmark 的类型 IApplyBookmarkRequest. 以下代码显示了此类型的定义：

type IApplyBookmarkRequest = IApplyBookmarkStateRequest | IApplyBookmarkByNameRequest;

interface IApplyBookmarkStateRequest {
    state: string;
}

interface IApplyBookmarkByNameRequest {
    name: string;
}

此代码演示如何按名称指定书签：

let embedConfig = {
    ...
    bookmark: {
        name: "Bookmark4f76333c3ea205286501"
    }
};

此代码演示如何按状态指定书签：

let embedConfig = {
    ...
    bookmark: {
        state: bookmarkState
    }
};

主题和高对比度模式

可以控制嵌入内容使用的主题和对比度级别。默认情况下，嵌入的任何内容都以默认主题和零对比度显示。可以通过配置特定主题或对比度级别来替代此行为。有关主题的详细信息，请参阅应用报表主题。

下面列出了可用的对比度模式：

enum ContrastMode {
    None = 0,
    HighContrast1 = 1,
    HighContrast2 = 2,
    HighContrastBlack = 3,
    HighContrastWhite = 4
}

使用类似于以下行的代码配置特定主题：

let embedConfig = {
    ...
    theme: {themeJson: ...}
};

以下代码演示如何替代默认对比度级别 None：

let embedConfig = {
    ...
    contrastMode: models.contrastMode.HighContrast1
};

注意

API 无法同时应用主题和对比度级别。如果同时配置这两个属性，API 将使用你指定的对比度级别，但会忽略该 theme 设置。

缩放级别

若要详细了解如何调整报表缩放级别，检查辅助功能文档。

在编辑模式下打开

默认情况下，嵌入的报表以视图模式显示。但是，可以重写此行为以在编辑模式下打开报表。还可以在模式之间切换。

配置编辑模式

若要在编辑模式下打开嵌入报表，请将 viewMode 属性与 permissions 属性一起使用。

可以为属性分配 viewMode 以下值：

View - 在视图模式下打开报表。
Edit - 在编辑模式下打开报表。

可以为属性分配 permissions 以下值：

Read - 用户可以查看报表。
ReadWrite - 用户可以查看、编辑和保存报表。
Copy - 用户可以使用 “另存为”保存报表的副本。
Create - 用户可以创建新报表。
All - 用户可以创建、查看、编辑、保存和保存报表的副本。

将内容配置为在编辑模式下打开时，请 permissions 为属性分配一个适合编辑的值，如以下代码所示：

let embedConfig = {
    ...
    permissions: models.Permissions.All
    viewMode: models.ViewMode.Edit
};

注意

permissions仅当获取的嵌入令牌具有足够的权限时，配置的值才有效。有关嵌入令牌的详细信息，请参阅创建嵌入令牌。

在编辑模式和视图模式之间切换

除了为嵌入内容指定启动模式外，还可以在编辑模式和查看模式之间动态切换。

如果内容处于编辑模式，并且你想要切换到查看模式，请使用以下 JavaScript 代码：

// Embed the content.
let embeddedContent = powerbi.embed(container, embedConfiguration);

...

// Switch to view mode.
embeddedContent.switchMode("view");

如果内容处于视图模式，并且你想要切换到编辑模式，请使用以下 JavaScript 代码：

// Embed the content.
let embeddedContent = powerbi.embed(container, embedConfiguration);

...

// Switch to edit mode.
embeddedContent.switchMode("edit");

注意事项和限制

配置嵌入内容时，请考虑以下几点：

当操作栏可见时，无法更改页面导航位置。详细了解操作栏。
在属性中使用 barssetting 属性（如 “条形图”中所述）时，仅当嵌入内容处于编辑模式时，API 才会应用配置。如果内容处于查看模式，API 将忽略设置 bars 。
使用 viewMode 属性在编辑模式下显示内容时，需要执行两个附加步骤：
- 使用 permissions 属性配置权限级别。该权限级别需要为用户提供修改内容的适当访问权限。例如，如果分配值permissionsRead,，用户将无法编辑内容。
- 确保生成的嵌入令牌具有支持编辑的权限。例如，如果获取值为 API 的view,令牌accessLevel，将无法在编辑模式下显示内容。
panes 属性替换以下settings属性：
- filterPaneEnabled
- navContentPaneEnabled
如果使用 panes 属性来配置筛选器或页面导航可见性，请不要在应用中使用 filterPaneEnabled 或 navContentPaneEnabled 属性。
API 无法同时对嵌入内容应用主题和对比度级别。如果使用和 contrastMode 属性配置这两个选项theme，API 会将你的contrastMode值与嵌入内容一起使用。但是，API 会忽略该 theme 设置。
如果要将书签应用于嵌入报表，可以使用 bookmark 属性。如果提供具有该属性的书签名称，则 API 只能使用该书签（如果存在具有该名称的书签）。同样，如果使用 pageName 属性指定打开页，则 API 只能显示该页面（如果存在具有给定名称的页面）。在配置名称之前，请考虑使用访问器方法（如 Report getPages 方法）来检查是否存在具有该名称的组件。