在应用程序 Studio 中使用控件库Using the control library in App Studio

Microsoft 团队应用程序 Studio为你提供了一组可在你自己的应用程序中使用的控件。Microsoft Teams App Studio provides you with a set of controls that you can use in your own apps. 这些控件在应用程序 Studio 的 "控件库" 选项卡中提供。These controls are provided in the Control Library tab of App Studio.

这些控件由 Microsoft 团队设计人员创建,用于简化其自己的工作流,并对控件行为和支持团队的默认主题进行标准化。These controls were created by the Microsoft Teams designers to streamline their own workflows, standardize control behavior and support Team's default themes. 您可以在自己的应用程序中使用此库来实现统一的外观和感觉。You can use this library in your own apps to achieve a unified look and feel.

控件包括:Controls include:

  • 按钮Buttons
  • 下拉Dropdowns
  • 复选框Checkboxes
  • 单选按钮Radio Buttons
  • Toggles
  • 测试区域Test Areas
  • 链接Links
  • 选项卡Tabs
  • 表格Tables
  • 图标Icons

(可选)使用响应控件Optionally use React controls

完整的团队控制库使用对JAVASCRIPT UI 框架的响应,但它是构建的,因此不会绑定到特定的 UI 框架。The full Teams control library uses the React JavaScript UI framework however it is built so that it is not tied to a specific UI framework. 有四种不同的 npm 包:There are four different npm packages:

  • msteams-ui-样式-核心UI 组件的核心 CSS 样式。msteams-ui-styles-core The core CSS styles of UI components. 它独立于任何 UI 框架。It’s independent of any UI framework.
  • msteams-ui-图标-核心团队的核心图标集图标。msteams-ui-icons-core The core set of Teams icons.
  • msteams-组件-响应响应绑定库。msteams-ui-components-react The React binding library. 这取决于 msteams--核心。It depends on msteams-ui-styles-core.
  • msteams-ui-图标-响应团队图标集的响应绑定库。msteams-ui-icons-react The React binding library for the set of Teams icons. 这取决于 msteams-------图标-核心。It depends on msteams-ui-icons-core.

这些库都是开放源代码,您可以使用 msteams-ui-styles-core 和 msteams-ui-无响应的核心。These libraries are all open source, and you can use msteams-ui-styles-core and msteams-ui-icons-core without React.

添加控件库Adding the control library

安装控件库及其对等依赖项typestyleInstall the control library and its peer dependency typestyle:

npm install --save typestyle && npm install --save msteams-ui-components-react

可选: 安装团队图标。Optional: Install the Teams icons.

npm install --save msteams-ui-icons-react

查找并打开src/App.js它的内容并将其替换为以下代码:Find and open src/App.js and replace its content with following code:

import React, { Component } from ‘react’;
import { TeamsComponentContext, ThemeStyle, PrimaryButton } from ‘msteams-ui-components-react’

class App extends Component {
   render() {
      // Sets up the top-level context for the library. It accepts global
      // configurations such as font size and theme. fontSize is your page’s
      // default font size. We made it a parameter so that you could use this
      // library with CSS frameworks such as Bootstrap. Some CSS frameworks
      // set the default font size for the page; retrieve it and use it
      // instead of {16} in the block.
      // This library uses the power of CSS to do most of the work for you.
      // Instead of passing themes as a parameter to every UI component,
      // we set it on a parent HTML element. All HTML elements nested within
      // that parent will inherit these properties.

      return (
        <TeamsComponentContext
            fontSize={16}
            theme={ThemeStyle.Light}
        />
      );
   }
}
export default App;

运行应用Run the app

npm run start

导航到http://localhost:3000时,您应该会看到以下屏幕:When you navigate to http://localhost:3000, you should see the following screen:

动态处理主题更改Dynamically handling theme changes

您的应用程序需要在以下情况处理主题:Your app needs to handle themes when:

  • 最初加载该选项卡The tab is initially loaded
  • 用户在选项卡已加载之后更改主题A user changes the theme after the tab is already loaded

主题包含在选项卡的上下文中,可以在通过 URL 占位符值加载选项卡之前,也可以通过使用Microsoft 团队 JAVASCRIPT 客户端 SDK在任何时候进行检索。The theme is included in a tab’s Context, which can be retrieved before the tab is loaded via URL placeholder values, or at any time by using the Microsoft Teams JavaScript client SDK.

下面讨论了如何检索当前主题以及如何响应主题更改:获取你的 Microsoft 团队选项卡的上下文How the current theme is retrieved and how to respond to theme changes is discussed here: Get context for your Microsoft Teams tab.

此示例代码演示如何执行此操作。This sample code shows how this is done.

componentWillMount() {
    // If you are deploying your site as a MS Teams static or configurable tab,
    // you should add “?theme={theme}” to your tabs URL in the manifest.
    // That way you will get the current theme before it’s loaded; getContext()
    // is called only after the tab is loaded, which will cause the tab to flash
    // if the current theme is different than the default.
    this.updateTheme(this.getQueryVariable('theme'));
    this.setState({
        fontSize: this.pageFontSize(),
    });

    // If you are not using the MS Teams Javascript SDK, you can remove this entire
    // if block, but if you want theme changes in the MS Teams client to propagate
    // to the tab, leave it here.
    microsoftTeams.initialize();
    microsoftTeams.registerOnThemeChangeHandler(this.updateTheme);
}

将您自己的组件连接到 TeamsComponentContextConnect your own component to the TeamsComponentContext

如果您想要使用自己的 CSS 代码,您仍可以响应主题更改,并使用工作组定义的颜色。If you want to use your own CSS code you can still respond to theme changes and use colors defined by teams. TeamsComponentContext 允许您执行此操作。TeamsComponentContext allows you to do this.

再次编辑您src/App.js的文件并将其内容替换为以下代码:Once again, edit your src/App.js file and replace its content with following code:

import React, { Component } from ‘react’;
import { TeamsComponentContext, ThemeStyle, ConnectedComponent } from ‘msteams-ui-components-react’

class App extends Component {
    render() {
        return (
            <TeamsComponentContext
                fontSize={16}
                theme={ThemeStyle.HighContrast}>
                <MyComponent />
            </TeamsComponentContext>
        );
    }
}

class MyComponent extends Component {
    render() {
        return (
            <ConnectedComponent render={(props) => {
                const context = props.context;

                switch (context.style) {
                case ThemeStyle.Dark:
                    return <div style={{ color: context.colors.dark.brand00 }}>Dark theme!</div>;
                case ThemeStyle.HighContrast:
                    return <div style={{ color: context.colors.highContrast.black }}>High Contrast theme!</div>;
                case ThemeStyle.Light:
                    return <div style={{ color: context.colors.light.brand00 }}>Light theme!</div>;
                }
            }} />
        );
    }
}

export default App;

在此代码中,定义了名为 MyComponent 的新组件。In this code, a new component is defined called MyComponent. 然后,添加名为 ConnectedComponent 的控件库中的特殊组件。Then a special component from the control library called ConnectedComponent is added. ConnectedComponent 具有一个名render为的属性,该属性采用函数作为参数。ConnectedComponent has a property called render which takes a function as a parameter. 在呈现时,将使用您的选项卡的相应上下文调用此函数。上下文包括呈现页面的主题,以及可用于将团队颜色应用于选项卡的全局颜色对象。正如您在switch语句中所看到的那样<div> ,将根据主题选择相应的。At render time this function will be called with the appropriate context for your tab. The context includes the theme that the page is being rendered in as well as the global color object that you can use to apply Teams colors to your tab. As you can see in the switch statement, the appropriate <div> is chosen based on the theme.

若要更改主题,我们需要将根级别的 TeamsComponentContext 传递给不同的主题。To change themes, we need to pass the root-level TeamsComponentContext a different theme. 当主题发生更改时,将重新呈现 ConnectedComponent 中包装的所有子元素。When a theme changes, all the child elements wrapped in ConnectedComponent will be re-rendered. 请参阅上一节 "动态处理主题更改"。See previous section “Dynamically Handle Theme Changes.”

可以通过其他方式将组件连接到 TeamsComponentContext。There are other ways to connect your component to TeamsComponentContext. 如果你熟悉Redux,则可能更喜欢以下模式:If you’re familiar with Redux, you may prefer the following pattern:

import React, { Component } from ‘react’;
import { TeamsComponentContext, ThemeStyle, connectTeamsComponent } from ‘msteams-ui-components-react’

class App extends Component {
    render() {
        return (
            <TeamsComponentContext
                fontSize={16}
                theme={ThemeStyle.HighContrast}>
                <MyComponent />
            </TeamsComponentContext>
        );
    }
}

class MyComponentInner extends Component {
    render() {
        const context = this.props.context;
        switch (context.style) {
            case ThemeStyle.Dark:
                return <div style={{ color: context.colors.dark.brand00 }}>Dark theme!</div>;
            case ThemeStyle.HighContrast:
                return <div style={{ color: context.colors.highContrast.black }}>High Contrast theme!</div>;
            case ThemeStyle.Light:
                return <div style={{ color: context.colors.light.brand00 }}>Light theme!</div>;
        }
    }
}

const MyComponent = connectTeamsComponent(MyComponentInner);

export default App;

在此方法中,不使用 ConnectedComponent,而是使用 connectTeamsComponent 函数。In this method, instead of using ConnectedComponent, you use the connectTeamsComponent function. ConnectTeamsComponent 函数将使用当前组件,并返回一个新组件,其中插入了 context 对象。The connectTeamsComponent function takes your current component and returns a new component with the context object injected.

后续步骤Next steps

指向团队应用程序 Studio,并查看我们提供的所有控件以及如何使用它们的示例代码。Head to Teams App Studio and check out all the controls we offer and sample code of how to use them. 不要忘记在不同主题中浏览它们。Don’t forget to explore them in different themes.