适用于 iOS 的可访问且可定制的购物⻋风格步进器。

许可

Y—Stepper 采用 Apache 2.0 许可证。

文档

文档自动从源代码注释生成，并呈现为托管在 GitHub Pages 上的静态⽹站：https://yml-org.github.io/ystepper-ios/

用法

`StepperControl` (UIKit)

StepperControl 是 UIControl 的⼦类，具有类似于 UIStepper 的 API。

`Stepper` (SwiftUI)

Stepper 是⼀个符合 SwiftUI View 协议的结构体。

初始化器

StepperControl 和 Stepper 都可以使⽤相同的五个参数初始化 (StepperControl 在内部使⽤ Stepper)

init(
    appearance: StepperControl.Appearance = .default,
    minimumValue: Double = 0,
    maximumValue: Double = 100,
    stepValue: Double = 1,
    value: Double = 0
)

标准初始化器允许您指定外观、最小值、最大值、步进值和当前值，尽管它为所有这些值提供了合理的默认值。

StepperControl 有⼀个额外的初始化器

init?(coder: NSCoder)

用于 Interface Builder 或 Storyboards (虽然我们建议您在代码中构建 UI)。

以这种方式创建的步进器以默认外观开始，但您可以通过更新其 appearance 属性在运行时对其进行自定义。

自定义

StepperControl 和 Stepper 都具有类型为 Appearance 的 appearance 属性。

Appearance 允许您自定义步进器的外观。您可以完全控制所使用的颜色、排版和图像。默认外观与深色模式兼容，并且符合 WCAG 2.0 AA 颜色对比度标准。

/// Appearance for stepper that contains typography and color properties
    public struct Appearance {
        /// Typography of stepper value label
        public var textStyle: (textColor: UIColor, typography: Typography)
        /// Background color for stepper view
        public var backgroundColor: UIColor
        /// Border color for stepper view
        public var borderColor: UIColor
        /// Border width for stepper view
        public var borderWidth: CGFloat
        /// Delete button image
        public var deleteImage: UIImage
        /// Increment button image
        public var incrementImage: UIImage
        /// Decrement button image
        public var decrementImage: UIImage
        /// Stepper's layout properties such as spacing between views. Default is `.default`.
        public var layout: Layout
        /// Whether to show delete image or not
        public var showDeleteImage: Bool
}

Appearance 具有 layout 属性，可用于自定义内容的布局。

/// A collection of layout properties for the `StepperControl`
    public struct Layout: Equatable {
        /// The content inset from edges. Stepper "content" consists of the two buttons and the text label between them.
        /// Default is `{8, 16, 8, 16}`.
        public var contentInset: NSDirectionalEdgeInsets
        /// The horizontal spacing between the stepper buttons and label. Default is `8.0`.
        public var gap: CGFloat
        /// Stepper's shape. Default is `.capsule`.
        public var shape: Shape

        /// Default stepper control layout.
        public static let `default` = Layout()
}

在 layout 中，有一个 shape 属性，可帮助确定 StepperControl 和 Stepper 的形状

/// Stepper's shape.
    public enum Shape: Equatable {
        /// None
        case none
        /// Rectangle
        case rectangle
        /// Rounded rectangle
        case roundRect(cornerRadius: CGFloat)
        /// Rounded rectangle that scales with Dynamic Type
        case scaledRoundRect(cornerRadius: CGFloat)
        /// Capsule
        case capsule
    }

用法 (UIKit)

如何导入？
```
import YStepper
```

创建一个步进器

// Create stepper with default values
let stepper = StepperControl()

// Add stepper to any view
view.addSubview(stepper)

自定义然后更新外观

// Create a stepper with current value text color set to green
var stepper = StepperControl(appearance: StepperControl.Appearance(textStyle: (textColor: .green, typography: .systemLabel)))

// Change the text color to red
stepper.appearance.textStyle.textColor = .red

更新步进器属性

// Set minimum value to 10 and maximum value to 101
stepper.minimumValue = 10
stepper.maximumValue = 101

// Set current value to 15
stepper.value = 15

接收更改通知

要在值更改时收到通知，只需使用与 UIDatePicker 或 YCalendarPicker 完全相同的 target-action 机制即可。
```
// Add target with action
stepper.addTarget(self, action: #selector(onValueChange), for: .valueChanged)
```

用法 (SwiftUI)

如何导入？
```
import YStepper
```
创建一个步进器视图

Stepper 符合 SwiftUI 的 View 协议，因此我们可以直接将 Stepper 与任何 SwiftUI 视图集成。
```
var body: some View {
    Stepper()
}
```

自定义然后更新外观

struct CustomStepper {
    @State var stepper: Stepper = {
        // Create a stepper with text color set to green
        var stepper = Stepper()
        stepper.appearance.textStyle.textColor = .green
        return stepper
    }()
}

extension CustomStepper: View {
    public var body: some View {
        VStack {
            stepper
            Button("Go Red") {
                // Change the text color to red
                stepper.appearance.textStyle.textColor = .red
            }
        }
    }
}

更新步进器属性

struct CustomStepper {
    @State var stepper = Stepper()
}

extension CustomCalendar: View {
    var body: some View {
        VStack {
            stepper
            Button("Set Min/Max value") {
                // set minimum value to 10 and maximum value to 101
                stepper.minimumValue = 10
                stepper.maximumValue = 101
            }
            Button("Show current value as 15") {
                // update value
                stepper.value = 15
            }
        }
    }
}

接收更改通知

要在用户更新值时收到通知，您可以使用 delegate 属性并符合 StepperDelegate 协议。

extension DemoView: StepperDelegate {
    // Value was changed
    func valueDidChange(newValue: Double) {
        print("New value: \(value)")
    }
}

依赖项

Y—Stepper 依赖于我们的 Y—CoreUI 和 Y—MatterType 框架 (两者也都是开源的，并采用 Apache 2.0 许可证)。

安装

可以通过将其作为包依赖项添加到 Xcode 项目来添加 Y—Stepper。

从“文件”菜单中，选择“添加包...”
在包存储库 URL 文本字段中输入“https://github.com/yml-org/ystepper-ios”
单击“添加包”

为 Y—Stepper 做贡献

要求

SwiftLint (linter)

brew install swiftlint

Jazzy (文档)

sudo gem install jazzy

设置

克隆存储库并在 Xcode 中打开 Package.swift。

版本控制策略

我们采用语义版本控制。

{major}.{minor}.{patch}

例如

1.0.5

分支策略

我们为我们的框架采用简化的分支策略。

main (和开发) 分支是 main
feature (和 bugfix) 分支都从 main 分支分叉
feature (和 bugfix) 分支在完成并获得批准后合并回 main。
main 被标记为每个版本的更新版本号

分支命名约定

feature/{ticket-number}-{short-description}
bugfix/{ticket-number}-{short-description}

例如

feature/CM-44-button
bugfix/CM-236-textview-color

拉取请求

在提交拉取请求之前，您应该

编译并确保没有警告和错误。
运行所有单元测试并确认一切通过。
检查单元测试覆盖率并确认所有新的/修改的代码都已完全覆盖。
从命令行运行 swiftlint 并确认没有违规行为。
从命令行运行 jazzy 并确认您具有 100% 的文档覆盖率。
考虑使用 git rebase -i HEAD~{commit-count} 将您最近的 {commit-count} 个提交合并到功能块中。
如果自您创建分支以来，父分支（通常为 main）的 HEAD 已更新，请使用 git rebase main 来变基您的分支。
- 永远不要将父分支合并到您的分支中。
- 始终根据父分支变基您的分支。

提交拉取请求时

使用提供的拉取请求模板并至少填写简介、目的和范围字段。
如果您要提交前后屏幕截图、影片或 GIF，请将它们输入到两列表中，以便可以并排查看。

合并拉取请求时

确保该分支已根据父分支的最新 HEAD 进行了变基（未合并）。这使我们的 git 历史记录易于阅读和理解。
确保在合并时删除该分支（应该是自动的）。

发布新版本

使用新版本标记相应的提交 (例如 1.0.5)
将本地标签推送到远程

生成文档 (通过 Jazzy)

您可以直接从源代码生成自己的本地文档集，方法是在终端中使用以下命令

jazzy

这会在 /docs 下生成一组文档。默认配置在默认配置文件 .jazzy.yaml 文件中设置。

要查看其他文档选项，请键入

jazzy --help

每次将提交推送到 main 时，GitHub Action 都会自动运行，该 Action 运行 Jazzy 以为我们的 GitHub 页面生成文档，网址为：https://yml-org.github.io/ystepper-ios/

许可

文档

用法

StepperControl (UIKit)

Stepper (SwiftUI)