搜索插件、代码仓与 APP 分类

kpostal 封面
插件详情v2.0.1

kpostal

Kpostal 包可通过 Kakao 邮政编码服务搜索韩国邮政地址。

AndroidiOS
近 30 天下载
2660
喜欢数
74
Pub 分数
160

安装插件

flutter pub add kpostal

插件介绍

基于插件公开信息、社区数据与项目使用情况整理的选型参考。

kpostal 包通过集成 Kakao Postcode 服务,使 Flutter 应用能够搜索韩国邮政地址。它为用户提供了一个简单、原生的界面,可从可搜索列表中选择地址,从而提高面向韩国的应用程序中地址输入的准确性和效率。该包支持 Android 和 iOS 平台,确保在不同设备上行为一致。它非常适合需要精确位置数据的表单,例如配送或注册系统。

适合场景

  • 移动应用中的韩文地址选择
  • 配送和运输表单输入
  • 用户资料注册带位置
  • 韩国的基于位置的服务
  • 电子商务应用中的地址自动补全

主要特点

  • 与 Kakao Postcode API 的集成
  • 对 Android 和 iOS 的支持
  • 简洁直观的地址搜索用户界面
  • 实时地址过滤
  • 轻量且易于实现

适合对象

  • 为韩国开发应用程序的开发者
  • 需要准确韩国邮政编码的应用程序
  • 电子商务和物流平台
  • 需要可靠地址输入的表单

使用建议

  • 需要互联网连接以进行邮编查询
  • 仅限韩国地址
  • 可能需要为非韩语用户进行额外的本地化
  • 取决于Kakao的服务可用性

原始 README

以下为关联源码仓库的 README 原文快照,最新内容请访问源码仓库。

kpostal — Korean postal address search for Flutter

pub version pub points pub likes downloads test license

English Korean


kpostal is a Korean postal address search widget for Flutter, powered by the Kakao (Daum) postcode service. Push a single widget, get a structured address (postcode, road/jibun address, building info, …) back — with optional latitude/longitude geocoding.

Inspired by the discontinued Kopo package.

Features

  • 🔎 Kakao postcode search as a ready-made KpostalView widget — zero configuration to get started.
  • 🌐 Multi-platform: Android, iOS, macOS, and Web, built on the official webview_flutter (iframe on Web).
  • 📍 Geocoding built in: latitude/longitude via free platform geocoding (Android/iOS/macOS), plus optional Kakao Maps API geocoding.
  • 🏠 Resilient hosting: uses a GitHub-hosted search page by default, with a local-server fallback (useLocalServer) in case of hosting issues.
  • 🎨 Customizable: custom AppBar, loading indicator, and result callback.

Platform Support

Android iOS macOS Web Windows Linux
✅ ✅ ✅ ✅ ❌ ❌
  • Requires Flutter 3.38+ / Dart 3.10+.
  • On Web, useLocalServer is ignored and platform geocoding is unavailable (latitude/longitude are null) — use kakaoKey geocoding instead.
  • Platform geocoding uses the free OS services with their own usage limits — see the Apple, Android, and geocoding docs.
kpostal screenshot

Quick Start

dependencies:
  kpostal:
import 'package:kpostal/kpostal.dart';

// Use callback.
await Navigator.push(context, MaterialPageRoute(
  builder: (_) => KpostalView(
    callback: (Kpostal result) {
      print(result.address);
      print(result.latitude);
    },
  ),
));

// Or receive the result as a return value.
Kpostal result = await Navigator.push(
  context, MaterialPageRoute(builder: (_) => KpostalView()));

Key fields on the Kpostal result: postCode, address, roadAddress, jibunAddress, buildingName, sido, sigungu, latitude/longitude, kakaoLatitude/kakaoLongitude, userSelectedAddress — see the API reference for the full list.

Setup

🧑🏻‍💻 With the default hosted page, Android and iOS need no extra setup.

Android — internet permission (release mode)
<!-- AndroidManifest.xml -->
<uses-permission android:name="android.permission.INTERNET"/>
macOS — network entitlements
<!-- macos/Runner/DebugProfile.entitlements & Release.entitlements -->
<key>com.apple.security.network.client</key>
<true/>
<!-- only if you use [useLocalServer] -->
<key>com.apple.security.network.server</key>
<true/>
Local server (optional, useLocalServer: true) — allow http traffic

The local server serves the search page over http://localhost, so cleartext traffic must be allowed.

Android — add android:usesCleartextTraffic="true" to <application> in AndroidManifest.xml:

<application
    android:label="[your_app]"
    android:usesCleartextTraffic="true"
    ...>

iOS — add NSAppTransportSecurity to Info.plist:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>
Kakao geocoding (optional, kakaoKey) — get kakaoLatitude/kakaoLongitude
  1. Go to the Kakao Developers site, register, and create an app.
  2. Add a Web platform: App – [Platform] – [Web Platform Registration].
  3. Register the site domain:
    • default hosting: https://tykann.github.io
    • local server: http://localhost:{your port, default 8080}
  4. Use the JavaScript key shown at the top of the page as kakaoKey.
KpostalView(
  kakaoKey: '{your kakao app JS key}',
  callback: (Kpostal result) {
    print(result.kakaoLatitude);
  },
)

Usage

KpostalView(
  useLocalServer: true,        // host the page on localhost (default: false)
  localPort: 8080,             // local server port (default: 8080)
  kakaoKey: '{JS key}',        // enable Kakao geocoding (optional)
  appBar: ...,                 // custom AppBar (optional)
  onLoading: ...,              // custom loading widget (optional)
  callback: (Kpostal result) { ... },
)

Migration from 1.x

Most apps need no code changes — v2 swaps the webview engine from flutter_inappwebview to the official webview_flutter and adds Web/macOS support.

  • Requires Flutter 3.38+ / Dart 3.10+.
  • On Web, latitude/longitude are null — use kakaoKey geocoding if you need coordinates.
  • macOS apps need the network entitlements above.

See the CHANGELOG for details.

Roadmap

  • [x] v2: migrate to official webview_flutter, Web & macOS support
  • [x] v2.0.0 stable release
  • [ ] Custom search page URL — self-host the postcode page on your own domain (also enables full control on Web, where a local server isn't possible)
  • [ ] Embeddable search widget (usable inside bottom sheets/dialogs without a Scaffold)
  • [ ] Windows/Linux support — blocked on webview_flutter desktop support

Have an idea or issue? Open an issue — contributions are welcome!

License

MIT

所属分类

依赖

依赖清单 4 项

源码仓库

使用此插件的项目

暂无相关数据。