CountryPickerModal

CountryPickerModal 是 iOS 应用中选择国家的简单、可定制的视图。

您可以克隆/下载该仓库并运行 示例项目 来查看 CountryPickerModal 的效果。首先从 CountryPickerModalDemo 目录中运行 pod install。

安装

注意，2.x 版本与 Swift 4 兼容。为与 Swift 3 兼容，请使用 1.x 版本。

Cocoapods

CountryPickerModal 通过 CocoaPods 提供。只需将以下内容添加到您的 Podfile 中

use_frameworks!

target '<Your Target Name>' do
  pod 'CountryPickerModal'
end

Carthage

Carthage 是一个去中心化的依赖管理器，可以构建您的依赖项并为您提供二进制框架。

要通过 Carthage 安装 CountryPickerModal，只需将以下内容添加到您的 Cartfile 中

github "aeke/CountryPickerModal"

手册

1. 将 CountryPickerModal 仓库放置在您的项目目录中的某个位置。
2. 在 Xcode 中，将 CountryPickerModal.xcodeproj 添加到您的项目中。
3. 在您的应用程序目标上，将 CountryPickerModal 框架添加为嵌入的二进制文件，在“常规”选项卡上。
   1. 在“构建阶段”选项卡上将 CountryPickerModal 框架作为一个目标依赖项。
   2. （可选）在“构建阶段”选项卡上将 CountryPickerModal 框架作为一个目标依赖项。

使用情况

如果您使用 Storyboards/Interface Builder，可以通过将 UIView 添加到 Storyboard 并然后在实用工具面板（右侧面板）“身份检查器”选项卡的“自定义类”字段中手动更改视图的类为 CountryPickerModal 来创建 CountryPickerModal 实例。

您也可以通过编程方式创建 CountryPickerModal 实例。

import CountryPickerModal

let cpv = CountryPickerModal(frame: /**Desired frame**/)

要获取从您的 CountryPickerModal 实例在任何时候所选的国家，请使用 selectedCountry 属性。

let country = cpv.selectedCountry
print(country)

此属性不是可选的，默认值是用户的当前国家，来源于设备的当前地区设置。

自定义

可以通过 CountryPickerModal 实例直接访问自定义视图的选项，而内部 CountryPicker 表视图的选项可以通过 CountryPickerModalDataSource 协议来访问。如果您希望在被用户从列表中选择国家时收到通知，则还需要设置 CountryPickerModalDelegate 协议。

import CountryPickerModal

class DemoViewController: UIViewController, CountryPickerModalDelegate, CountryPickerModalDataSource {

    @IBOutlet weak var countryPickerModal: CountryPickerModal!

    override func viewDidLoad() {
        super.viewDidLoad()

        countryPickerModal.delegate = self
        countryPickerModal.dataSource = self

        /*** Direct customizations on CountryPickerModal instance ***/

        // Show the selected country's phone(e.g +234) code on the view
        countryPickerModal.showPhoneCodeInView = true

        // Show the selected country's iso code(e.g NG) on the view
        countryPickerModal.showCountryCodeInView = true
    }

}

CountryPickerModalDelegate

• 当用户从列表中选择国家或您手动设置 CountryPickerModal 的 selectedCountry 属性时调用。

  func countryPickerModal(_ countryPickerModal: CountryPickerModal, didSelectCountry country: Country)

• 在 CountryPickerModalController 被呈现或推入之前调用。CountryPickerModalController 是 UITableViewController 的子类。

  func countryPickerModal(_ countryPickerModal: CountryPickerModal, willShow viewController: CountryPickerModalController)

• 在 CountryPickerModalController 被呈现或推入之后调用。CountryPickerModalController 是 UITableViewController 的子类。

  func countryPickerModal(_ countryPickerModal: CountryPickerModal, didShow viewController: CountryPickerModalController)

注意：如果您已在项目中已经有 Country 类或结构体，实现 didSelectCountry 代理方法可能会导致编译错误，并显示消息说您的符合类不遵循 CountryPickerModalDelegate 协议。这是因为在方法中 Xcode 无法弄清楚要使用哪个 Country 模型。解决方案是用别名 CPVCountry 替换方法签名中的 Country，那么您的委托方法现在应该看起来像这样

func countryPickerModal(_ countryPickerModal: CountryPickerModal, didSelectCountry country: CPVCountry)

您也可以在其他部分的项目中使用 CPVCountry 作为框架中 Country 模型的替代。

此外，willShow 和 didShow 代理方法都是可选的。如果 CountryPickerModalController 显示（不是推送），它将被嵌入到 UINavigationController 中。提供 CountryPickerModalController 类，以便您根据需要自定义其外观。您还可以在 CountryPickerModalController 中访问公共的 searchController(UISearchController) 属性进行自定义。

CountryPickerModalDataSource

数据源方法定义内部（国家列表）ViewController 的行为。运行示例项目，尝试不同的选项。所有方法都是可选的。

• 您希望在列表顶部显示的国家数组。这对于针对特定国家人群的应用很有用。

  func preferredCountries(in countryPickerModal: CountryPickerModal) -> [Country]

• 首选部分的预期标题。

  func sectionTitleForPreferredCountries(in countryPickerModal: CountryPickerModal) -> String?

  注意：如果您希望在列表上显示首选国家，您必须从 preferredCountries(in countryPickerModal: CountryPickerModal) 返回非空国家数组和此部分标题。仅返回数组或标题将不起作用。

• 仅显示列表上的 首选项 国家部分。默认值为 false

  func showOnlyPreferredSection(in countryPickerModal: CountryPickerModal) -> Bool

  返回 true 以隐藏内部列表，这样用户就只能从首选国家列表中进行选择。

• 列表中部分标题的期望字体。可用于配置文本大小。

  func sectionTitleLabelFont(in countryPickerModal: CountryPickerModal) -> UIFont

• 列表中部分标题标签的期望文本颜色。

  func sectionTitleLabelColor(in countryPickerModal: CountryPickerModal) -> UIColor?

• 列表中单元格标签的期望字体。可用于配置文本大小。

  func cellLabelFont(in countryPickerModal: CountryPickerModal) -> UIFont

• 列表中国家名的期望文本颜色。

  func cellLabelColor(in countryPickerModal: CountryPickerModal) -> UIColor?

• 列表中国家旗图像的期望大小。

  func cellImageViewSize(in countryPickerModal: CountryPickerModal) -> CGSize

• 列表中国家旗图像的期望圆角。

  func cellImageViewCornerRadius(in countryPickerModal: CountryPickerModal) -> CGFloat

• 将内部 ViewController 推送/显示时的导航项标题。默认值是 nil

  func navigationTitle(in countryPickerModal: CountryPickerModal) -> String?

• 如果内部 ViewController 显示（不是推送），则使用此导航项按钮。如果返回 nil，则使用默认的 "关闭" 按钮。此方法仅允许您返回自定义按钮。默认值是 nil

  func closeButtonNavigationItem(in countryPickerModal: CountryPickerModal) -> UIBarButtonItem?

  注意：与此按钮关联的任何 target 或 action 都将被替换，因为此按钮的唯一目的是关闭内部 ViewController。

• 搜索栏的期望位置。默认值是 .tableViewHeader

  func searchBarPosition(in countryPickerModal: CountryPickerModal) -> SearchBarPosition

  可能的值：.tableViewHeader、.navigationBar 和 .hidden

• 在列表上显示国家名称旁边的电话区号。例如，尼日利亚 (+234)。默认值是 false

  func showPhoneCodeInList(in countryPickerModal: CountryPickerModal) -> Bool

使用 CountryPickerModal 与 UITextField

将 CountryPickerModal 用作电话号码输入字段的左侧视图是一个很好的用例。

class DemoViewController: UIViewController {

    @IBOutlet weak var phoneNumberField: UITextField!

    override func viewDidLoad() {
        super.viewDidLoad()

        let cpv = CountryPickerModal(frame: CGRect(x: 0, y: 0, width: 120, height: 20))
        phoneNumberField.leftView = cpv
        phoneNumberField.leftViewMode = .always
    }
}

这意味着您的用户无需在文本字段中输入国家的电话区号。这也确保您从 CountryPickerModal 获取有效的电话区号，而不是依赖您的用户。

独立使用内部选择器

如果您出于任何原因不希望显示默认视图或有自己的实现来显示国家信息，您仍然可以使用内部选择器，通过在 CountryPickerModal 实例上调用方法 showCountriesList(from: UIViewController)，让您的用户从列表中选择国家。

保持对 CountryPickerModal 实例的字段引用是非常重要的，否则它将被垃圾回收，并尝试使用它将导致崩溃。

class DemoViewController: UIViewController {

    // Keep a field reference
    let countryPickerModal = CountryPickerModal()

    override func viewDidLoad() {
        super.viewDidLoad()
    }

    @IBAction func buttonPressed(_ sender: Any) {
        countryPickerModal.showCountriesList(from: self)
    }
}

在上面的示例中，调用 countryPickerModal.showCountriesList(from: self) 将导致内部选择器视图控制器在其自己的导航堆栈中呈现，因为 DemoViewController 不是一个导航控制器。

如果您已经有一个导航堆栈，您可以通过调用 countryPickerModal.showCountriesList(from: self.navigationController!) 将内部选择器视图控制器推送到该堆栈，或者以安全的方式进行操作

if let nav = self.navigationController {
	countryPickerModal.showCountriesList(from: nav)
}

别忘了设置一个代理，以便在用户从列表中选择国家时被通知。内部选择器视图控制器的使用示例包含在演示项目中。

许可

CountryPickerModal 按照MIT许可证分发。有关详情，请参阅 LICENSE。