NMLocalizedPhoneCountryView 1.0.9

NMLocalizedPhoneCountryView 1.0.9

×

由 Namshi LLC 维护。

NMLocalizedPhoneCountryView 1.0.9

NMLocalizedPhoneCountryView

Platform Version License

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

您可以通过克隆/下载仓库并运行 示例项目 来查看 NMLocalizedPhoneCountryView 的实际应用。首先，在 NMLocalizedPhoneCountryViewDemo 目录中运行 pod install。

安装

仅支持 Swift 4.2 兼容版本。

CocoaPods

NMLocalizedPhoneCountryView 通过 CocoaPods 提供。只需在 Podfile 中添加以下内容

use_frameworks!

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

手动

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

使用方法

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

您还可以通过编程方式创建 NMLocalizedPhoneCountryView 的实例。

import NMLocalizedPhoneCountryView

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

所选国家

要获取 NMLocalizedPhoneCountryView 实例在任何时刻所选的国家，请使用 selectedCountry 属性。

let country = cpv.selectedCountry
print(country)

该属性不是可选的，默认值是用户当前所在国家，由设备的当前区域设置推导而来。

所选国家各州

您还可以查看所选国家的各州清单。

let statesCount = cpv.selectedCountry.states.count
print("statesCount \(statesCount)")

所选国家的运营商代码

您还可以查看所选国家的运营商代码（如果有）。默认是空运营商代码数组。

let carrierCodesCount = cpv.selectedCountry.carrierCodes.count
print("carrierCodesCount \(carrierCodesCount)")

所选国家的邮政编码

如果有的话，您还可以查看所选国家的邮政编码格式。默认值为空字符串。

let postalCodeFormat = cpv.selectedCountry.postalCode
print("postalCodeFormat \(postalCodeFormat)")

更改国家视图的本地化设置

使用以下方法更改您的应用本地化语言

cpvMain.localeSetup = NMLocaleSetup(baseLocale: sender.isOn ? "ar" : "Base", isRTL: sender.isOn)

并在不同的本地化设置下看到相同的国家列表。在我们的示例项目中，我们使用了阿拉伯语本地化，而我们的基本本地化为英语。

为国家视图添加新的本地化设置

如果您想使用这个库支持新的本地化设置，有以下两种方法

1. 在 CountryCodes.json 中添加新的本地化设置

创建一个新合并请求并添加库原始 json 文件中的新国家本地化设置。

例如：

{
    "name": "United Arab Emirates",
    "name_ar": "الإمارات",
    "name_fr" : "Emirats Arabes Unis",  ---->> New locale
    "dial_code": "+971",
    "code": "AE",
    "postal_code": "",
    "carrier_codes": [],
    "states": []
}

2. 使用您自己的国家列表

您可以使用自己的国家列表（无论是在本地还是从任何 API 响应中），并在将其用于 CountryView 之前使用该列表。注意：确保响应格式与当前格式相同，因为这种结构对于库的正常工作来说是必需的。如果您的自定义-countries-API 的响应格式不正确，或者它包含错误/空数据，NMLocalizedPhoneCountryView 将回退到我们本地的 CountryCodes.json 文件。

{
"name": "United Arab Emirates",
"name_ar": "الإمارات",
"dial_code": "+971",
"code": "AE",
"postal_code": "",
"carrier_codes": [],
"states": []
}

注意：如果您未对任何国家添加该语言的翻译，它将显示默认的英语名称。

排除主列表中的某些国家

您可以通过以下方式排除您不想在主列表中显示的国家

cpvMain.excludedCountriesList = ["AE", "QA", "SA", "OM", "KW", "BH"]

您必须将排除国家的国家代码列表传递到 countryView 的 excludedCountriesList 属性中。

自定义

自行调整视图本身的自定义选项通过NMLocalizedPhoneCountryView实例直接访问，而内部国家视图表的自定义选项则通过NMLocalizedPhoneCountryViewDataSource协议访问。如果您希望收到用户从列表中选择国家的通知，也需要设置NMLocalizedPhoneCountryViewDelegate协议。

import NMLocalizedPhoneCountryView

class DemoViewController: UIViewController, NMLocalizedPhoneCountryViewDelegate, NMLocalizedPhoneCountryViewDataSource {

    @IBOutlet weak var localizedPhoneCountryView: NMLocalizedPhoneCountryView!

    override func viewDidLoad() {
        super.viewDidLoad()
    
        localizedPhoneCountryView.delegate = self
        localizedPhoneCountryView.dataSource = self
        
        /*** Direct customizations on NMLocalizedPhoneCountryView instance ***/
        
        // Show the selected country's phone(e.g +234) code on the view
        localizedPhoneCountryView.showPhoneCodeInView = true
        
        // Show the selected country's iso code(e.g NG) on the view
        localizedPhoneCountryView.showCountryCodeInView = true
    }
    
}

NMLocalizedPhoneCountryViewDelegate

当用户从列表中选择一个国家或者手动设置NMLocalizedPhoneCountryView的selectedCountry属性时，将调用代理函数。

func localizedPhoneCountryView(_ localizedPhoneCountryView: NMLocalizedPhoneCountryView, didSelectCountry country: NMCountry) { 
	print(country)
}

NMLocalizedPhoneCountryViewDataSource

定义内部（国家列表） ViewController 行为的数据源函数。运行示例项目来试玩不同的选项。

  • 显示在列表顶部的国家数组。如果您的应用程序针对特定国家的人们，这将很有用。

      func preferredCountries(in localizedPhoneCountryView: NMLocalizedPhoneCountryView) -> [NMCountry]

  • 偏好部分的期望标题。

      func sectionTitleForPreferredCountries(in localizedPhoneCountryView: NMLocalizedPhoneCountryView) -> String?

    注意：如果要在列表上显示偏好国家，除了从这个 preferredCountries(in localizedPhoneCountryView: NMLocalizedPhoneCountryView) 返回非空国家数组以及该部分标题外，返回数组或标题本身是不起作用的。

  • 仅显示列表上的偏好国家部分。默认值是false。

      func showOnlyPreferredSection(in localizedPhoneCountryView: NMLocalizedPhoneCountryView) -> Bool

    返回true以隐藏内部列表，使您的用户只能从偏好国家列表中进行选择。

  • 内部视图控制器被推送/显示时的导航项标题。默认值为 nil。

      func navigationTitle(in localizedPhoneCountryView: NMLocalizedPhoneCountryView) -> String?

  • 如果内部视图控制器被显示（而不是被推送），将用来使用的导航项按钮。如果返回 nil，将使用默认的“关闭”按钮。此函数仅允许您返回自定义的按钮。默认值是 nil。

      func closeButtonNavigationItem(in localizedPhoneCountryView: NMLocalizedPhoneCountryView) -> UIBarButtonItem?

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

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

      func searchBarPosition(in localizedPhoneCountryView: NMLocalizedPhoneCountryView) -> SearchBarPosition

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

  • 在列表上显示国家名称旁边的电话代码。例如，尼日利亚（+234）。默认值是 false。

      func showPhoneCodeInList(in localizedPhoneCountryView: NMLocalizedPhoneCountryView) -> Bool

    FontTrait

    为您的 NMLocalizedPhoneCountryView 定义正常字体族，并在 NMLocalizedPhoneCountryView 和 NMLocalizedPhoneCountryViewController 的行内定义 FontTrait。分别简化 NMLocalizedPhoneCountryView 和 NMLocalizedPhoneCountryViewController 的 selectedCountryFontTrait 和 countriesListFontTrait 的值。

    FontTrait 的可能值

  public enum FontTrait {
    case normal, bold, italic
  }

在 UITextField 中使用 NMLocalizedPhoneCountryView

当将 NMLocalizedPhoneCountryView 用作电话号码输入字段左侧视图时，这是一个很好的用例。

class DemoViewController: UIViewController {

    @IBOutlet weak var phoneNumberField: UITextField!

    override func viewDidLoad() {
        super.viewDidLoad()
        
        let cpv = NMLocalizedPhoneCountryView(frame: CGRect(x: 0, y: 0, width: 120, height: 20))
        phoneNumberField.leftView = cpv
        phoneNumberField.leftViewMode = .always
    }
}

这意味着用户无需担心在文本字段中输入国家的电话区号。这也确保您从 NMLocalizedPhoneCountryView 而非依赖于用户获得有效的电话区号。

独立使用内部选择器

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

请保持对 NMLocalizedPhoneCountryView 实例的字段引用，否则它将被回收，任何尝试使用它的操作都将导致崩溃。

class DemoViewController: UIViewController {

    // Keep a field reference
    let localizedPhoneCountryView = NMLocalizedPhoneCountryView()

    override func viewDidLoad() {
        super.viewDidLoad()
    }
    
    @IBAction func buttonPressed(_ sender: Any) {
        localizedPhoneCountryView.showCountriesList(from: self)
    }
}

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

如果您已经有了导航堆栈，您可以通过调用 localizedPhoneCountryView.showCountriesList(from: self.navigationController!) 或以更安全的方式将其推送到该堆栈上。

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

别忘了设置一个代理以在其他用户从列表中选择国家时收到通知。如何在示例项目中使用内部选择器视图控制器的示例已包含在项目中。

许可

NMLocalizedPhoneCountryView 采用 MIT 许可证进行分发。有关详细信息，请参阅 LICENSE。最初灵感来源于 CountryPickerView。