Dart 原生範本
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
原生範本是附帶完整程式碼的檢視區塊，方便快速套用來顯示原生廣告，且易於修改。使用原生範本時，外掛程式會提供預先設計好的 Android 和 iOS 版面配置，您可以透過 Dart API 自訂原生素材資源的樣式。
本指南將示範如何用 Dart API 設定基礎平台檢視區塊的樣式，並顯示廣告。
必備條件
請務必使用測試廣告進行測試
建構及測試應用程式時，請務必使用測試廣告，而非實際的正式廣告；如要載入測試廣告，最簡單的方法是使用原生廣告專用的測試廣告單元 ID：
/21775744923/example/native
測試廣告單元經過設定，每次請求都會傳回測試廣告。在編寫程式碼、測試及偵錯階段，您可以自由在應用程式中使用這些廣告單元，但發布前記得要換成自己的廣告單元 ID。
載入廣告
以下是使用 medium 尺寸原生範本載入原生廣告的程式碼範例：
class NativeExampleState extends State<NativeExample> {
NativeAd? nativeAd;
bool _nativeAdIsLoaded = false;
// TODO: replace this test ad unit with your own ad unit.
final _adUnitId = '/21775744923/example/native';
/// Loads a native ad.
void loadAd() {
_nativeAd = NativeAd(
adUnitId: _adUnitId,
listener: NativeAdListener(
onAdLoaded: (ad) {
debugPrint('$NativeAd loaded.');
setState(() {
_nativeAdIsLoaded = true;
});
},
onAdFailedToLoad: (ad, error) {
// Dispose the ad here to free resources.
debugPrint('$NativeAd failed to load: $error');
ad.dispose();
},
),
request: const AdManagerAdRequest(),
// Styling
nativeTemplateStyle: NativeTemplateStyle(
// Required: Choose a template.
templateType: TemplateType.medium,
// Optional: Customize the ad's style.
mainBackgroundColor: Colors.purple,
cornerRadius: 10.0,
callToActionTextStyle: NativeTemplateTextStyle(
textColor: Colors.cyan,
backgroundColor: Colors.red,
style: NativeTemplateFontStyle.monospace,
size: 16.0),
primaryTextStyle: NativeTemplateTextStyle(
textColor: Colors.red,
backgroundColor: Colors.cyan,
style: NativeTemplateFontStyle.italic,
size: 16.0),
secondaryTextStyle: NativeTemplateTextStyle(
textColor: Colors.green,
backgroundColor: Colors.black,
style: NativeTemplateFontStyle.bold,
size: 16.0),
tertiaryTextStyle: NativeTemplateTextStyle(
textColor: Colors.brown,
backgroundColor: Colors.amber,
style: NativeTemplateFontStyle.normal,
size: 16.0)))
..load();
}
}
如要瞭解可用的樣式選項，請參考 NativeTemplateStyle和 NativeTemplateTextStyle。
自訂廣告
使用原生範本自訂原生廣告時，廣告的 UI 設定會存放在 NativeTemplateStyle 類別中，因此您能透過 Dart 程式碼，輕鬆設定整個原生廣告的樣式。
範本尺寸
Flutter 原生廣告範本有兩種尺寸：TemplateType.small 和 TemplateType.medium。小型範本用於 TableView 或 GridView 為佳，適合動態內廣告或需要細長矩形廣告檢視區塊的場景。中型範本約占半頁到四分之三頁，適合用於到達網頁或啟動頁面。
| 小型 |
Android
|
iOS
|
| 中型 |
Android
|
iOS
|
原生廣告事件
如要接收原生廣告互動相關的事件通知，請使用廣告的 listener 屬性，並實作 NativeAdListener 來接收廣告事件回呼。
class NativeExampleState extends State<NativeExample> {
NativeAd? _nativeAd;
bool _nativeAdIsLoaded = false;
// TODO: replace this test ad unit with your own ad unit.
final _adUnitId = '/21775744923/example/native';
/// Loads a native ad.
void loadAd() {
_nativeAd = NativeAd(
adUnitId: _adUnitId,
listener: NativeAdListener(
onAdLoaded: (ad) {
print('$NativeAd loaded.');
setState(() {
_nativeAdIsLoaded = true;
});
},
onAdFailedToLoad: (ad, error) {
// Dispose the ad here to free resources.
print('$NativeAd failedToLoad: $error');
ad.dispose();
},
// Called when a click is recorded for a NativeAd.
onAdClicked: (ad) {},
// Called when an impression occurs on the ad.
onAdImpression: (ad) {},
// Called when an ad removes an overlay that covers the screen.
onAdClosed: (ad) {},
// Called when an ad opens an overlay that covers the screen.
onAdOpened: (ad) {},
// For iOS only. Called before dismissing a full screen view
onAdWillDismissScreen: (ad) {},
// Called when an ad receives revenue value.
onPaidEvent: (ad, valueMicros, precision, currencyCode) {},
),
request: const AdManagerAdRequest(),
// Styling
nativeTemplateStyle: NativeTemplateStyle(
// Required: Choose a template.
templateType: TemplateType.medium,
// Optional: Customize the ad's style.
mainBackgroundColor: Colors.purple,
cornerRadius: 10.0,
callToActionTextStyle: NativeTemplateTextStyle(
textColor: Colors.cyan,
backgroundColor: Colors.red,
style: NativeTemplateFontStyle.monospace,
size: 16.0),
primaryTextStyle: NativeTemplateTextStyle(
textColor: Colors.red,
backgroundColor: Colors.cyan,
style: NativeTemplateFontStyle.italic,
size: 16.0),
secondaryTextStyle: NativeTemplateTextStyle(
textColor: Colors.green,
backgroundColor: Colors.black,
style: NativeTemplateFontStyle.bold,
size: 16.0),
tertiaryTextStyle: NativeTemplateTextStyle(
textColor: Colors.brown,
backgroundColor: Colors.amber,
style: NativeTemplateFontStyle.normal,
size: 16.0)))
..load();
}
}
顯示廣告
如要將 NativeAd 顯示為小工具，必須先呼叫 load()，再用支援的廣告例項化 AdWidget。雖然可以在呼叫 load() 前建立小工具，但必須呼叫 load() 後，才能將其加入小工具樹狀結構。
AdWidget 本身繼承自 Flutter 的 Widget 類別，可以像其他小工具一樣使用。在 iOS 平台上，請務必將小工具放在明確指定高度與寬度的容器中，否則廣告可能無法正常顯示。
// Small template
final adContainer = ConstrainedBox(
constraints: const BoxConstraints(
minWidth: 320, // minimum recommended width
minHeight: 90, // minimum recommended height
maxWidth: 400,
maxHeight: 200,
),
child: AdWidget(ad: _nativeAd!),
);
// Medium template
final adContainer = ConstrainedBox(
constraints: const BoxConstraints(
minWidth: 320, // minimum recommended width
minHeight: 320, // minimum recommended height
maxWidth: 400,
maxHeight: 400,
),
child: AdWidget(ad: _nativeAd!),
);
釋出廣告資源
不再需要使用 NativeAd 時，必須釋放相關資源。呼叫 dispose() 的最佳時機包括：與原生廣告相關聯的 AdWidget 從小工具樹狀結構中移除後，或在 AdListener.onAdFailedToLoad() 回呼中執行。
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：2025-08-31 (世界標準時間)。
[null,null,["上次更新時間：2025-08-31 (世界標準時間)。"],[[["\u003cp\u003eNative Templates offer pre-built layouts for Android and iOS, customizable through a Dart API, streamlining native ad implementation.\u003c/p\u003e\n"],["\u003cp\u003eFlutter provides two native ad template sizes, \u003ccode\u003esmall\u003c/code\u003e and \u003ccode\u003emedium\u003c/code\u003e, suitable for various ad placements, such as in-feed or landing pages.\u003c/p\u003e\n"],["\u003cp\u003eNative ad styling can be achieved using the \u003ccode\u003eNativeTemplateStyle\u003c/code\u003e and \u003ccode\u003eNativeTemplateTextStyle\u003c/code\u003e classes in Dart, offering granular control over visual elements.\u003c/p\u003e\n"],["\u003cp\u003eTo display the native ad, instantiate an \u003ccode\u003eAdWidget\u003c/code\u003e with the loaded \u003ccode\u003eNativeAd\u003c/code\u003e and place it within a \u003ccode\u003eConstrainedBox\u003c/code\u003e to define its dimensions.\u003c/p\u003e\n"],["\u003cp\u003eEnsure to dispose of the \u003ccode\u003eNativeAd\u003c/code\u003e using the \u003ccode\u003edispose()\u003c/code\u003e method when it's no longer needed, such as after removing the associated \u003ccode\u003eAdWidget\u003c/code\u003e from the widget tree.\u003c/p\u003e\n"]]],["Native templates provide prebuilt Android and iOS layouts for native ads, customizable via a Dart API. To use, load an ad with `NativeAd`, specifying an ad unit ID and listener for events. Customize the ad's appearance through `NativeTemplateStyle`, choosing from `small` or `medium` template sizes. Display the ad using an `AdWidget` within a `ConstrainedBox`. Ensure ads are tested with provided test ad unit IDs and disposed of properly after use to free up resources.\n"],null,["# Native templates in Dart\n\nSelect platform: [Android](/ad-manager/mobile-ads-sdk/android/native/templates \"View this page for the Android platform docs.\") [iOS](/ad-manager/mobile-ads-sdk/ios/native/templates \"View this page for the iOS platform docs.\") [Flutter](/ad-manager/mobile-ads-sdk/flutter/native/templates \"View this page for the Flutter platform docs.\")\n\n\u003cbr /\u003e\n\nNative templates are code-complete views for your native ads, designed for fast\nimplementation and easy modification. With native templates, the plugin provides\nprebuilt Android and iOS layouts for you, and you can customize the style of the\nnative assets using a Dart API.\n\nThis guide demonstrates how to use the Dart API to stylize the underlying\nplatform views and to render the ad.\n\nPrerequisites\n-------------\n\n- Flutter 2.4.0 or higher.\n\n\u003c!-- --\u003e\n\n- Complete the [Get started guide](/ad-manager/mobile-ads-sdk/flutter/quick-start).\n- Familiarize yourself with the [native ads options](/ad-manager/mobile-ads-sdk/flutter/native).\n\nAlways test with test ads\n-------------------------\n\nWhen building and testing your apps, make sure you use test ads rather than\nlive, production ads. The easiest way to load test ads is to use our dedicated\ntest ad unit ID for native ads:\n\n- `/21775744923/example/native`\n\nThe test ad units are configured to return test ads for every request, so\nyou can use them in your own apps while coding, testing, and\ndebugging---just make sure you replace them with your own ad unit IDs before\npublishing your app.\n\nLoad ad\n-------\n\nThe following example loads a native ad using the `medium` sized native\ntemplate: \n\n class NativeExampleState extends State\u003cNativeExample\u003e {\n NativeAd? nativeAd;\n bool _nativeAdIsLoaded = false;\n\n // TODO: replace this test ad unit with your own ad unit.\n final _adUnitId = '/21775744923/example/native';\n\n /// Loads a native ad.\n void loadAd() {\n _nativeAd = NativeAd(\n adUnitId: _adUnitId,\n listener: NativeAdListener(\n onAdLoaded: (ad) {\n debugPrint('$NativeAd loaded.');\n setState(() {\n _nativeAdIsLoaded = true;\n });\n },\n onAdFailedToLoad: (ad, error) {\n // Dispose the ad here to free resources.\n debugPrint('$NativeAd failed to load: $error');\n ad.dispose();\n },\n ),\n request: const AdManagerAdRequest(),\n // Styling\n nativeTemplateStyle: NativeTemplateStyle(\n // Required: Choose a template.\n templateType: TemplateType.medium,\n // Optional: Customize the ad's style.\n mainBackgroundColor: Colors.purple,\n cornerRadius: 10.0,\n callToActionTextStyle: NativeTemplateTextStyle(\n textColor: Colors.cyan,\n backgroundColor: Colors.red,\n style: NativeTemplateFontStyle.monospace,\n size: 16.0),\n primaryTextStyle: NativeTemplateTextStyle(\n textColor: Colors.red,\n backgroundColor: Colors.cyan,\n style: NativeTemplateFontStyle.italic,\n size: 16.0),\n secondaryTextStyle: NativeTemplateTextStyle(\n textColor: Colors.green,\n backgroundColor: Colors.black,\n style: NativeTemplateFontStyle.bold,\n size: 16.0),\n tertiaryTextStyle: NativeTemplateTextStyle(\n textColor: Colors.brown,\n backgroundColor: Colors.amber,\n style: NativeTemplateFontStyle.normal,\n size: 16.0)))\n ..load();\n }\n }\n\nSee\n[`NativeTemplateStyle`](//pub.dev/documentation/google_mobile_ads/latest/google_mobile_ads/NativeTemplateStyle-class.html)\nand\n[`NativeTemplateTextStyle`](//pub.dev/documentation/google_mobile_ads/latest/google_mobile_ads/NativeTemplateTextStyle-class.html)\nfor available styling options.\n\nCustomize ad\n------------\n\nWhen customizing a native ad using native templates, your ad's UI configuration\nwill live in the `NativeTemplateStyle` class, enabling you to style an entire\nnative ad in Dart code.\n\n### Template sizes\n\nFlutter native ad templates come in two types: `TemplateType.small` and\n`TemplateType.medium`. The small template is ideal for a `TableView` or\n`GridView`, for in-feed ads or anywhere you need a thin rectangular ad view. The\nmedium template is meant to be a half to three-quarters page view, which is\nideal for landing or splash pages.\n\n| Small |\n|-------------|---------|\n| **Android** | **iOS** |\n| **Android** | **iOS** |\n\nNative ad events\n----------------\n\nTo be notified of events related to the native ad interactions, use the\n[`listener`](//pub.dev/documentation/google_mobile_ads/latest/google_mobile_ads/NativeAd/listener.html)\nproperty of the ad. Then, implement\n[`NativeAdListener`](//pub.dev/documentation/google_mobile_ads/latest/google_mobile_ads/NativeAdListener-class.html)\nto receive ad event callbacks. \n\n class NativeExampleState extends State\u003cNativeExample\u003e {\n NativeAd? _nativeAd;\n bool _nativeAdIsLoaded = false;\n\n // TODO: replace this test ad unit with your own ad unit.\n final _adUnitId = '/21775744923/example/native';\n\n /// Loads a native ad.\n void loadAd() {\n _nativeAd = NativeAd(\n adUnitId: _adUnitId,\n listener: NativeAdListener(\n onAdLoaded: (ad) {\n print('$NativeAd loaded.');\n setState(() {\n _nativeAdIsLoaded = true;\n });\n },\n onAdFailedToLoad: (ad, error) {\n // Dispose the ad here to free resources.\n print('$NativeAd failedToLoad: $error');\n ad.dispose();\n },\n // Called when a click is recorded for a NativeAd.\n onAdClicked: (ad) {},\n // Called when an impression occurs on the ad.\n onAdImpression: (ad) {},\n // Called when an ad removes an overlay that covers the screen.\n onAdClosed: (ad) {},\n // Called when an ad opens an overlay that covers the screen.\n onAdOpened: (ad) {},\n // For iOS only. Called before dismissing a full screen view\n onAdWillDismissScreen: (ad) {},\n // Called when an ad receives revenue value.\n onPaidEvent: (ad, valueMicros, precision, currencyCode) {},\n ),\n request: const AdManagerAdRequest(),\n // Styling\n nativeTemplateStyle: NativeTemplateStyle(\n // Required: Choose a template.\n templateType: TemplateType.medium,\n // Optional: Customize the ad's style.\n mainBackgroundColor: Colors.purple,\n cornerRadius: 10.0,\n callToActionTextStyle: NativeTemplateTextStyle(\n textColor: Colors.cyan,\n backgroundColor: Colors.red,\n style: NativeTemplateFontStyle.monospace,\n size: 16.0),\n primaryTextStyle: NativeTemplateTextStyle(\n textColor: Colors.red,\n backgroundColor: Colors.cyan,\n style: NativeTemplateFontStyle.italic,\n size: 16.0),\n secondaryTextStyle: NativeTemplateTextStyle(\n textColor: Colors.green,\n backgroundColor: Colors.black,\n style: NativeTemplateFontStyle.bold,\n size: 16.0),\n tertiaryTextStyle: NativeTemplateTextStyle(\n textColor: Colors.brown,\n backgroundColor: Colors.amber,\n style: NativeTemplateFontStyle.normal,\n size: 16.0)))\n ..load();\n }\n }\n\nDisplay ad\n----------\n\nTo display a `NativeAd` as a widget, you must instantiate an\n[`AdWidget`](//pub.dev/documentation/google_mobile_ads/latest/google_mobile_ads/AdWidget-class.html)\nwith a supported ad after calling `load()`. You can create the widget before\ncalling `load()`, but `load()` must be called before adding it to the widget\ntree.\n\n`AdWidget` inherits from Flutter's `Widget` class and can be used like any other\nwidget. On iOS, make sure you place the widget in a container with a specified\nwidth and height. Otherwise, your ad may not be displayed. \n\n // Small template\n final adContainer = ConstrainedBox(\n constraints: const BoxConstraints(\n minWidth: 320, // minimum recommended width\n minHeight: 90, // minimum recommended height\n maxWidth: 400,\n maxHeight: 200,\n ),\n child: AdWidget(ad: _nativeAd!),\n );\n\n // Medium template\n final adContainer = ConstrainedBox(\n constraints: const BoxConstraints(\n minWidth: 320, // minimum recommended width\n minHeight: 320, // minimum recommended height\n maxWidth: 400,\n maxHeight: 400,\n ),\n child: AdWidget(ad: _nativeAd!),\n );\n\nDispose ad\n----------\n\nA\n[`NativeAd`](//pub.dev/documentation/google_mobile_ads/latest/google_mobile_ads/NativeAd-class.html)\nmust be disposed of when access to it is no longer needed. The best practice for\nwhen to call `dispose()` is after the `AdWidget` associated with the native ad\nis removed from the widget tree and in the `AdListener.onAdFailedToLoad()`\ncallback."]]
