配置

Ionic Config 提供了一种在应用中全局更改组件属性的方法。它可以设置应用模式、选项卡按钮布局、动画等。

¥Ionic Config provides a way to change the properties of components globally across an app. It can set the app mode, tab button layout, animations, and more.

全局配置

¥Global Config

可用的配置键可以在 IonicConfig 界面中找到。

¥The available config keys can be found in the IonicConfig interface.

以下示例禁用波纹效果并将模式默认为 Material Design：

¥The following example disables ripple effects and default the mode to Material Design:

JavaScript
Angular
Angular (Standalone)
React
Vue

example.js
window.Ionic = {
  config: {
    rippleEffect: false,
    mode: 'md',
  },
};

app.module.ts


import { IonicModule } from '@ionic/angular';



@NgModule({
  ...
  imports: [
    IonicModule.forRoot({
      rippleEffect: false,
      mode: 'md'
    })
  ],
  ...
})

main.ts


import { provideIonicAngular } from '@ionic/angular/standalone';



bootstrapApplication(AppComponent, {
  providers: [
    ...,
    provideIonicAngular({
      rippleEffect: false,
      mode: 'md'
    })
  ]
})

必须在渲染任何 Ionic 组件（包括 IonApp）之前调用 setupIonicReact 函数。

¥The setupIonicReact function must be called before rendering any Ionic components (including IonApp).

App.tsx

import { setupIonicReact } from '@ionic/react';

setupIonicReact({
  rippleEffect: false,
  mode: 'md',
});

main.ts

import { IonicVue } from '@ionic/vue';

import { createApp } from 'vue';

createApp(App).use(IonicVue, {
  rippleEffect: false,
  mode: 'md',
});

每个组件的配置

¥Per-Component Config

Ionic Config 不是反应性的。在组件渲染后更新配置的值将得到以前的值。当你需要反应性值时，建议使用组件的属性而不是更新配置。

¥Ionic Config is not reactive. Updating the config's value after the component has rendered will result in the previous value. It is recommended to use a component's properties instead of updating the config, when you require reactive values.

JavaScript
Angular
Angular (Standalone)
React
Vue

不建议

¥Not recommended

window.Ionic = {
  config: {
    // Not recommended when your app requires reactive values
    backButtonText: 'Go Back',
  },
};

推荐

¥Recommended

<ion-back-button></ion-back-button>

<script>
  const backButton = document.querySelector('ion-back-button');

  /**

   * The back button text can be updated

   * anytime the locale changes.
   */
  backButton.text = 'Go Back';
</script>

不建议

¥Not recommended

import { IonicModule } from '@ionic/angular';



@NgModule({
  ...
  imports: [
    IonicModule.forRoot({
      // Not recommended when your app requires reactive values
      backButtonText: 'Go Back'
    })
  ],
  ...
});

推荐

¥Recommended

<ion-back-button [text]="backButtonText"></ion-back-button>

@Component(...)
class MyComponent {
  /**

   * The back button text can be updated

   * anytime the locale changes.
   */
  backButtonText = 'Go Back';
}

不建议

¥Not recommended

import { provideIonicAngular } from '@ionic/angular/standalone';



bootstrapApplication(AppComponent, {
  providers: [
    ...,
    provideIonicAngular({
      // Not recommended when your app requires reactive values
      backButtonText: 'Go Back'
    })
  ]
})

推荐

¥Recommended

<ion-back-button [text]="backButtonText"></ion-back-button>

@Component(...)
class MyComponent {
  /**

   * The back button text can be updated

   * anytime the locale changes.
   */
  backButtonText = 'Go Back';
}

不建议

¥Not recommended

import { setupIonicReact } from '@ionic/react';



setupIonicReact({
  // Not recommended when your app requires reactive values
  backButtonText: 'Go Back',
});

推荐

¥Recommended

import { useState } from 'react';


import { IonBackButton } from '@ionic/react';



const ExampleComponent = () => {
  const [backButtonText, setBackButtonText] = useState('Go Back');
  return (
    {/*

     * The back button text can be updated

     * anytime the locale changes.
     */}
    <IonBackButton text={backButtonText}></IonBackButton>
  )
}

不建议

¥Not recommended

import { IonicVue } from '@ionic/vue';


import { createApp } from 'vue';

// Not recommended when your app requires reactive values
createApp(App).use(IonicVue, {
  backButtonText: 'Go Back',
});

推荐

¥Recommended

<template>
  <ion-back-button [text]="backButtonText"></ion-back-button>
</template>

<script setup lang="ts">
  import { IonBackButton } from '@ionic/vue';
  import { ref } from 'vue';

  /**

   * The back button text can be updated

   * anytime the locale changes.
   */
  const backButtonText = ref('Go Back');
</script>

每个平台的配置

¥Per-Platform Config

Ionic Config 也可以基于每个平台进行设置。例如，如果应用在速度可能较慢的设备上的浏览器中运行，这允许你禁用动画。开发者可以利用平台实用程序来完成此任务。

¥Ionic Config can also be set on a per-platform basis. For example, this allows you to disable animations if the app is being run in a browser on a potentially slower device. Developers can take advantage of the Platform utilities to accomplish this.

在以下示例中，仅当 Ionic 应用在移动 Web 浏览器中运行时，我们才会禁用该应用中的所有动画。

¥In the following example, we are disabling all animations in our Ionic app only if the app is running in a mobile web browser.

Angular
Angular (Standalone)
React
Vue

注意

由于配置是在运行时设置的，因此你将无权访问平台依赖注入。相反，你可以使用提供者直接使用的底层函数。

¥Since the config is set at runtime, you will not have access to the Platform Dependency Injection. Instead, you can use the underlying functions that the provider uses directly.

请参阅 Angular 平台文档了解你可以检测的平台类型。

¥See the Angular Platform Documentation for the types of platforms you can detect.

app.module.ts


import { isPlatform, IonicModule } from '@ionic/angular';



@NgModule({
  ...
  imports: [
    IonicModule.forRoot({
      animated: !isPlatform('mobileweb')
    })
  ],
  ...
})

注意

由于配置是在运行时设置的，因此你将无权访问平台依赖注入。相反，你可以使用提供者直接使用的底层函数。

¥Since the config is set at runtime, you will not have access to the Platform Dependency Injection. Instead, you can use the underlying functions that the provider uses directly.

请参阅 Angular 平台文档了解你可以检测的平台类型。

¥See the Angular Platform Documentation for the types of platforms you can detect.

main.ts


import { isPlatform, provideIonicAngular } from '@ionic/angular/standalone';



bootstrapApplication(AppComponent, {
  providers: [
    ...,
    provideIonicAngular({
      animated: !isPlatform('mobileweb')
    })
  ]
})

注意

请参阅 React 平台文档了解你可以检测的平台类型。

¥See the React Platform Documentation for the types of platforms you can detect.

App.tsx

import { isPlatform, setupIonicReact } from '@ionic/react';

setupIonicReact({
  animated: !isPlatform('mobileweb'),
});

注意

请参阅 Vue 平台文档了解你可以检测的平台类型。

¥See the Vue Platform Documentation for the types of platforms you can detect.

main.ts

import { IonicVue, isPlatform } from '@ionic/vue';

createApp(App).use(IonicVue, {
  animated: !isPlatform('mobileweb'),
});

后备措施

¥Fallbacks

下一个示例允许你根据平台设置完全不同的配置，如果没有平台匹配，则回退到默认配置：

¥The next example allows you to set an entirely different configuration based upon the platform, falling back to a default config if no platforms match:

Angular
Angular (Standalone)
React
Vue

app.module.ts


import { isPlatform, IonicModule } from '@ionic/angular';



const getConfig = () => {
  let config = {
    animated: false
  };

  if (isPlatform('iphone')) {
    config = {
      ...config,
      backButtonText: 'Previous'
    }
  }

  return config;
}
@NgModule({
  ...
  imports: [
    IonicModule.forRoot(getConfig())
  ],
  ...
});

main.ts


import { isPlatform, provideIonicAngular } from '@ionic/angular/standalone';



const getConfig = () => {
  let config = {
    animated: false
  };

  if (isPlatform('iphone')) {
    config = {
      ...config,
      backButtonText: 'Previous'
    }
  }

  return config;
}

bootstrapApplication(AppComponent, {
  providers: [
    ...,
    provideIonicAngular(getConfig())
  ]
})

App.tsx


import { isPlatform, setupIonicReact } from '@ionic/react';



const getConfig = () => {
  let config = {
    animated: false,
  };

  if (isPlatform('iphone')) {
    config = {
      ...config,
      backButtonText: 'Previous',
    };
  }

  return config;
};

setupIonicReact(getConfig());

main.ts


import { IonicVue, isPlatform } from '@ionic/vue';



const getConfig = () => {
  let config = {
    animated: false,
  };

  if (isPlatform('iphone')) {
    config = {
      ...config,
      backButtonText: 'Previous',
    };
  }

  return config;
};

createApp(App).use(IonicVue, getConfig());

覆盖

¥Overrides

最后一个示例允许你根据不同的平台要求累积配置对象。

¥This final example allows you to accumulate a config object based upon different platform requirements.

Angular
Angular (Standalone)
React
Vue

app.module.ts


import { isPlatform, IonicModule } from '@ionic/angular';



const getConfig = () => {
  if (isPlatform('hybrid')) {
    return {
      tabButtonLayout: 'label-hide'
    }
  }

  return {
    tabButtonLayout: 'icon-top'
  };
}
@NgModule({
  ...
  imports: [
    IonicModule.forRoot(getConfig())
  ],
  ...
});

main.ts


import { isPlatform, provideIonicAngular } from '@ionic/angular/standalone';



const getConfig = () => {
  if (isPlatform('hybrid')) {
    return {
      tabButtonLayout: 'label-hide'
    }
  }

  return {
    tabButtonLayout: 'icon-top'
  };
}

bootstrapApplication(AppComponent, {
  providers: [
    ...,
    provideIonicAngular(getConfig())
  ]
})

App.tsx


import { isPlatform, setupIonicReact } from '@ionic/react';



const getConfig = () => {
  if (isPlatform('hybrid')) {
    return {
      tabButtonLayout: 'label-hide',
    };
  }

  return {
    tabButtonLayout: 'icon-top',
  };
};

setupIonicReact(getConfig());

main.ts


import { IonicVue, isPlatform } from '@ionic/vue';



const getConfig = () => {
  if (isPlatform('hybrid')) {
    return {
      tabButtonLayout: 'label-hide',
    };
  }

  return {
    tabButtonLayout: 'icon-top',
  };
};

createApp(App).use(IonicVue, getConfig());

读取配置（Angular）

¥Reading the Config (Angular)

Ionic Angular 提供了一个 Config 提供程序来访问 Ionic Config。

¥Ionic Angular provides a Config provider for accessing the Ionic Config.

get

描述	返回 `any` 形式的配置值。如果未定义配置，则返回 `null`。
签名	`get(key: string, fallback?: any) => any`

示例

¥Examples

Angular
Angular (Standalone)

import { Config } from '@ionic/angular';



@Component(...)
class AppComponent {
  constructor(config: Config) {
    const mode = config.get('mode');
  }
}

import { Config } from '@ionic/angular/standalone';



@Component(...)
class AppComponent {
  constructor(config: Config) {
    const mode = config.get('mode');
  }
}

getBoolean

描述	返回 `boolean` 形式的配置值。如果未定义配置，则返回 `false`。
签名	`getBoolean(key: string, fallback?: boolean) => boolean`

示例

¥Examples

Angular
Angular (Standalone)

import { Config } from '@ionic/angular';



@Component(...)
class AppComponent {
  constructor(config: Config) {
    const swipeBackEnabled = config.getBoolean('swipeBackEnabled');
  }
}

import { Config } from '@ionic/angular/standalone';



@Component(...)
class AppComponent {
  constructor(config: Config) {
    const swipeBackEnabled = config.getBoolean('swipeBackEnabled');
  }
}

getNumber

描述	返回 `number` 形式的配置值。如果未定义配置，则返回 `0`。
签名	`getNumber(key: string, fallback?: number) => number`

接口

¥Interfaces

IonicConfig

以下是 Ionic 使用的配置选项。

¥Below are the config options that Ionic uses.

配置	类型	描述
`actionSheetEnter`	`AnimationBuilder`	为所有 `ion-action-sheet` 提供自定义进入动画，覆盖默认的 "animation"。
`actionSheetLeave`	`AnimationBuilder`	为所有 `ion-action-sheet` 提供自定义离开动画，覆盖默认的 "animation"。
`alertEnter`	`AnimationBuilder`	为所有 `ion-alert` 提供自定义进入动画，覆盖默认的 "animation"。
`alertLeave`	`AnimationBuilder`	为所有 `ion-alert` 提供自定义离开动画，覆盖默认的 "animation"。
`animated`	`boolean`	如果 `true`，Ionic 将启用应用中的所有动画和过渡。
`backButtonDefaultHref`	`string`	覆盖所有 `<ion-back-button>` 组件中 `defaultHref` 属性的默认值。
`backButtonIcon`	`string`	覆盖所有 `<ion-back-button>` 组件中的默认图标。
`backButtonText`	`string`	覆盖所有 `<ion-back-button>` 组件中的默认文本。
`innerHTMLTemplatesEnabled`	`boolean`	相关组件：`ion-alert`、`ion-infinite-scroll-content`、`ion-loading`、`ion-refresher-content`、`ion-toast`。如果是 `true`，传递给相关组件的内容将被解析为 HTML 而不是纯文本。默认为 `false`。
`hardwareBackButton`	`boolean`	如果是 `true`，Ionic 将响应 Android 设备中的硬件后退按钮。
`infiniteLoadingSpinner`	`SpinnerTypes`	覆盖所有 `<ion-infinite-scroll-content>` 组件中的默认加载控件类型。
`loadingEnter`	`AnimationBuilder`	为所有 `ion-loading` 提供自定义进入动画，覆盖默认的 "animation"。
`loadingLeave`	`AnimationBuilder`	为所有 `ion-loading` 提供自定义离开动画，覆盖默认的 "animation"。
`loadingSpinner`	`SpinnerTypes`	覆盖所有 `ion-loading` 叠加层的默认加载控件。
`menuIcon`	`string`	覆盖所有 `<ion-menu-button>` 组件中的默认图标。
`menuType`	`string`	覆盖所有 `<ion-menu>` 组件的默认菜单类型。
`modalEnter`	`AnimationBuilder`	为所有 `ion-modal` 提供自定义进入动画，覆盖默认的 "animation"。
`modalLeave`	`AnimationBuilder`	为所有 `ion-modal` 提供自定义离开动画，覆盖默认的 "animation"。
`mode`	`Mode`	该模式决定整个应用使用哪种平台样式。
`navAnimation`	`AnimationBuilder`	覆盖整个应用中所有 `ion-nav` 和 `ion-router-outlet` 的默认 "animation"。
`pickerEnter`	`AnimationBuilder`	为所有 `ion-picker` 提供自定义进入动画，覆盖默认的 "animation"。
`pickerLeave`	`AnimationBuilder`	为所有 `ion-picker` 提供自定义离开动画，覆盖默认的 "animation"。
`platform`	`PlatformConfig`	覆盖默认的平台检测方法。
`popoverEnter`	`AnimationBuilder`	为所有 `ion-popover` 提供自定义进入动画，覆盖默认的 "animation"。
`popoverLeave`	`AnimationBuilder`	为所有 `ion-popover` 提供自定义离开动画，覆盖默认的 "animation"。
`refreshingIcon`	`string`	覆盖所有 `<ion-refresh-content>` 组件中的默认图标。
`refreshingSpinner`	`SpinnerTypes`	覆盖所有 `<ion-refresh-content>` 组件中的默认加载控件类型。
`rippleEffect`	`boolean`	如果是 `true`，将在整个应用中启用 Material Design 涟漪效果。
`sanitizerEnabled`	`boolean`	如果是 `true`，Ionic 将对接受自定义 HTML 的组件属性启用基本 DOM 清理程序。
`spinner`	`SpinnerTypes`	覆盖所有 `<ion-spinner>` 组件中的默认加载控件。
`statusTap`	`boolean`	如果是 `true`，单击或点击状态栏将导致内容滚动到顶部。
`swipeBackEnabled`	`boolean`	如果 `true`，Ionic 将在应用中启用 "swipe-to-go-back" 手势。
`tabButtonLayout`	`TabButtonLayout`	覆盖整个应用中所有 `ion-bar-button` 的默认 "layout"。
`toastDuration`	`number`	覆盖所有 `ion-toast` 组件的默认 `duration`。
`toastEnter`	`AnimationBuilder`	为所有 `ion-toast` 提供自定义进入动画，覆盖默认的 "animation"。
`toastLeave`	`AnimationBuilder`	为所有 `ion-toast` 提供自定义离开动画，覆盖默认的 "animation"。
`toggleOnOffLabels`	`boolean`	覆盖所有 `ion-toggle` 组件中的默认 `enableOnOffLabels`。
`experimentalCloseWatcher`	`boolean`	实验：如果是 `true`，则密切观察者 API 将用于处理所有 Escape 键和硬件后退按钮按下操作，以关闭菜单和覆盖并进行导航。请注意，`hardwareBackButton` 配置选项也必须是 `true`。
`focusManagerPriority`	`FocusManagerPriority[]`	实验：定义后，Ionic 会在每次页面转换后将焦点移动到适当的元素。这可确保在发生页面转换时通知依赖辅助技术的用户。默认禁用。

全局配置​

每个组件的配置​

每个平台的配置​

后备措施​

覆盖​

读取配置（Angular）​

get​

示例​

getBoolean​

示例​

getNumber​

接口​

IonicConfig​

目录

全局配置

每个组件的配置

每个平台的配置

后备措施

覆盖

读取配置（Angular）

get

示例

getBoolean

示例

getNumber

接口

IonicConfig